widget/src/cocoa/nsMacCursor.h

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