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