widget/cocoa/nsMacCursor.h

   1 /* This Source Code Form is subject to the terms of the Mozilla Public
   2  * License, v. 2.0. If a copy of the MPL was not distributed with this
   3  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
   4
   5 #ifndef nsMacCursor_h_
   6 #define nsMacCursor_h_
   7
   8 #import <Cocoa/Cocoa.h>
   9 #import "nsIWidget.h"
  10
  11 /*! @class      nsMacCursor
  12     @abstract   Represents a native Mac cursor.
  13     @discussion <code>nsMacCursor</code> provides a simple API for creating and
  14                 working with native Macintosh cursors.  Cursors can be created
  15                 used without needing to be aware of the way different cursors
  16                 are implemented, in particular the details of managing an
  17                 animated cursor are hidden.
  18 */
  19 @interface nsMacCursor : NSObject {
  20  @private
  21   NSTimer* mTimer;
  22  @protected
  23   nsCursor mType;
  24   int mFrameCounter;
  25 }
  26
  27 /*! @method     cursorWithCursor:
  28     @abstract   Create a cursor by specifying a Cocoa <code>NSCursor</code>.
  29     @discussion Creates a cursor representing the given Cocoa built-in cursor.
  30     @param      aCursor the <code>NSCursor</code> to use
  31     @param      aType the corresponding <code>nsCursor</code> constant
  32     @result     an autoreleased instance of <code>nsMacCursor</code>
  33                 representing the given <code>NSCursor</code>
  34  */
  35 + (nsMacCursor*)cursorWithCursor:(NSCursor*)aCursor type:(nsCursor)aType;
  36
  37 /*! @method     cursorWithImageNamed:hotSpot:type:
  38     @abstract   Create a cursor by specifying the name of an image resource to
  39                 use for the cursor and a hotspot.
  40     @discussion Creates a cursor by loading the named image using the
  41                 <code>+[NSImage imageNamed:]</code> method.
  42                 <p>The image must be compatible with any restrictions laid down
  43                 by <code>NSCursor</code>. These vary by operating system
  44                 version.</p>
  45                 <p>The hotspot precisely determines the point where the user
  46                 clicks when using the cursor.</p>
  47     @param      aCursor the name of the image to use for the cursor
  48     @param      aPoint the point within the cursor to use as the hotspot
  49     @param      aType the corresponding <code>nsCursor</code> constant
  50     @result     an autoreleased instance of <code>nsMacCursor</code> that uses the given image and
  51    hotspot
  52  */
  53 + (nsMacCursor*)cursorWithImageNamed:(NSString*)aCursorImage
  54                              hotSpot:(NSPoint)aPoint
  55                                 type:(nsCursor)aType;
  56
  57 /*! @method     cursorWithFrames:type:
  58     @abstract   Create an animated cursor by specifying the frames to use for
  59                 the animation.
  60     @discussion Creates a cursor that will animate by cycling through the given
  61                 frames. Each element of the array must be an instance of
  62                 <code>NSCursor</code>
  63     @param      aCursorFrames an array of <code>NSCursor</code>, representing
  64                 the frames of an animated cursor, in the order they should be
  65                 played.
  66     @param      aType the corresponding <code>nsCursor</code> constant
  67     @result     an autoreleased instance of <code>nsMacCursor</code> that will
  68                 animate the given cursor frames
  69  */
  70 + (nsMacCursor*)cursorWithFrames:(NSArray*)aCursorFrames type:(nsCursor)aType;
  71
  72 /*! @method     cocoaCursorWithImageNamed:hotSpot:
  73     @abstract   Create a Cocoa NSCursor object with a Gecko image resource name
  74                 and a hotspot point.
  75     @discussion Create a Cocoa NSCursor object with a Gecko image resource name
  76                 and a hotspot point.
  77     @param      imageName the name of the gecko image resource, "tiff"
  78                 extension is assumed, do not append.
  79     @param      aPoint the point within the cursor to use as the hotspot
  80     @result     an autoreleased instance of <code>nsMacCursor</code> that will
  81                 animate the given cursor frames
  82  */
  83 + (NSCursor*)cocoaCursorWithImageNamed:(NSString*)imageName hotSpot:(NSPoint)aPoint;
  84
  85 /*! @method     isSet
  86     @abstract   Determines whether this cursor is currently active.
  87     @discussion This can be helpful when the Cocoa NSCursor state can be
  88                 influenced without going through nsCursorManager.
  89     @result     whether the cursor is currently set
  90  */
  91 - (BOOL)isSet;
  92
  93 /*! @method     set
  94     @abstract   Set the cursor.
  95     @discussion Makes this cursor the current cursor. If the cursor is
  96                 animated, the animation is started.
  97  */
  98 - (void)set;
  99
 100 /*! @method     unset
 101     @abstract   Unset the cursor. The cursor will return to the default
 102                 (usually the arrow cursor).
 103     @discussion Unsets the cursor. If the cursor is animated, the animation is
 104                 stopped.
 105  */
 106 - (void)unset;
 107
 108 /*! @method     isAnimated
 109     @abstract   Tests whether this cursor is animated.
 110     @discussion Use this method to determine whether a cursor is animated
 111     @result     YES if the cursor is animated (has more than one frame), NO if
 112                 it is a simple static cursor.
 113  */
 114 - (BOOL)isAnimated;
 115
 116 /** @method     cursorType
 117     @abstract   Get the cursor type for this cursor
 118     @discussion This method returns the <code>nsCursor</code> constant that
 119                 corresponds to this cursor, which is  equivalent to the CSS
 120                 name for the cursor.
 121     @result     The nsCursor constant corresponding to this cursor, or
 122                 nsCursor's 'eCursorCount' if the cursor is a custom cursor
 123                 loaded from a URI
 124  */
 125 - (nsCursor)type;
 126 @end
 127
 128 #endif  // nsMacCursor_h_