NSCursor Class Reference
| Inherits from | |
| Conforms to | |
| Framework | /System/Library/Frameworks/AppKit.framework |
| Availability | Available in OS X v10.0 and later. |
| Companion guide | |
| Declared in | NSCursor.h |
Overview
Instances of the NSCursor class manage the appearance of the cursor.
The following table shows and describes the system cursors, and indicates the class method for obtaining them:
Cursor |
Description |
|---|---|
|
The arrow cursor ( |
|
The I-beam cursor for indicating insertion points ( |
|
The cross-hair cursor ( |
|
The closed-hand cursor ( |
|
The open-hand cursor ( |
|
The pointing-hand cursor ( |
|
The resize-left cursor ( |
|
The resize-right cursor ( |
|
The resize-left-and-right cursor ( |
|
The resize-up cursor ( |
|
The resize-down cursor ( |
|
The resize-up-and-down cursor ( |
|
The disappearing item cursor ( |
| The I-Beam text cursor for vertical layout ( |
In OS X version 10.3 and later, cursor size is no longer limited to 16 by 16 pixels.
Cursor Rectangles
In Cocoa, you can change the currently displayed cursor based on the position of the mouse over one of your views. You might use this technique to provide visual feedback about what actions the user can take with the mouse. For example, you might display one of the resize cursors whenever the mouse moves over a portion of your view that acts as a custom resizing handle. To set this up, you associate a cursor object with one or more cursor rectangles in the view.
Cursor rectangles are a specialized type of tracking rectangles, which are used to monitor the mouse location in a view. Views implement cursor rectangles using tracking rectangles but provide methods for setting and refreshing cursor rectangles that are distinct from the generic tracking rectangle interface. For information on how to set up cursor rectangles, see “Mouse-Tracking and Cursor-Update Events”.
Balancing Cursor Hiding and Unhiding
Each call to hide cursor must have a corresponding unhide call. For example,
[NSCursor hide]; |
[NSCursor hide]; |
…. |
[NSCursor unhide]; |
Will result in the cursor still being hidden because the hide and unhide method invocations are not balanced. Instead you must balance the method calls, such as in the following example:
[NSCursor hide]; |
[NSCursor hide]; |
…. |
[NSCursor unhide]; |
[NSCursor unhide]; |
There are corresponding cursor hide and unhide calls, thus the cursor will become visible.
Tasks
Initializing a New Cursor
Setting Cursor Attributes
Controlling Which Cursor Is Current
-
+ pop -
– pop -
– push -
– set -
– mouseEntered: -
– setOnMouseEntered: -
– isSetOnMouseEntered -
– mouseExited: -
– setOnMouseExited: -
– isSetOnMouseExited
Retrieving Cursor Instances
-
+ currentCursor -
+ currentSystemCursor -
+ arrowCursor -
+ contextualMenuCursor -
+ closedHandCursor -
+ crosshairCursor -
+ disappearingItemCursor -
+ dragCopyCursor -
+ dragLinkCursor -
+ IBeamCursor -
+ openHandCursor -
+ operationNotAllowedCursor -
+ pointingHandCursor -
+ resizeDownCursor -
+ resizeLeftCursor -
+ resizeLeftRightCursor -
+ resizeRightCursor -
+ resizeUpCursor -
+ resizeUpDownCursor -
+ IBeamCursorForVerticalLayout
Class Methods
arrowCursor
Returns the default cursor, the arrow cursor.
Return Value
The default cursor, a slanted arrow with its hot spot at the tip. The arrow cursor is the one you’re used to seeing over buttons, scrollers, and many other objects in the window system.
Availability
- Available in OS X v10.0 and later.
See Also
Declared In
NSCursor.hclosedHandCursor
Returns the closed-hand system cursor.
Return Value
The closed-hand cursor.
Availability
- Available in OS X v10.3 and later.
Declared In
NSCursor.hcontextualMenuCursor
Returns the contextual menu system cursor.
Return Value
The contextual menu cursor
Availability
- Available in OS X v10.6 and later.
Declared In
NSCursor.hcrosshairCursor
Returns the cross-hair system cursor.
Return Value
The cross-hair cursor. This cursor is used for situations when precise location is required (where the lines cross is the hot spot).
Availability
- Available in OS X v10.3 and later.
Declared In
NSCursor.hcurrentCursor
Returns the application’s current cursor.
Return Value
The top cursor on the application’s cursor stack. This cursor may not be the visible cursor on the screen if a different application is currently active.
Discussion
The method only returns the cursor set by your application using NSCursor methods. It does return not cursors set by other applications or cursors set by your application using Carbon API.
Availability
- Available in OS X v10.0 and later.
See Also
Declared In
NSCursor.hcurrentSystemCursor
Returns the current system cursor.
Return Value
A cursor whose image and hot spot match those of the currently-displayed cursor on the system
Discussion
This method returns the current system cursor regardless of which application set the cursor, and whether Cocoa or Carbon APIs were used to set it.
This method replaces the now deprecated QDGetCursorData function.
Availability
- Available in OS X v10.6 and later.
Declared In
NSCursor.hdisappearingItemCursor
Returns a cursor indicating that the current operation will result in a disappearing item.
Return Value
The system cursor that indicates that the current operation will result in a disappearing item (for example, when dragging an item from the dock or a toolbar).
Availability
- Available in OS X v10.3 and later.
Declared In
NSCursor.hdragCopyCursor
Returns a cursor indicating that the current operation will result in a copy action.
Return Value
The drag copy cursor.
Availability
- Available in OS X v10.6 and later.
Declared In
NSCursor.hdragLinkCursor
Returns a cursor indicating that the current operation will result in a link action.
Return Value
The drag link cursor.
Availability
- Available in OS X v10.6 and later.
Declared In
NSCursor.hhide
Makes the current cursor invisible.
Discussion
If another cursor becomes current, that cursor will be invisible, too. It will remain invisible until you invoke the unhide method.
Each invocation of hide must be balanced by an invocation of unhide in order for the cursor to be displayed.
The hide method overrides setHiddenUntilMouseMoves:.
Availability
- Available in OS X v10.0 and later.
Declared In
NSCursor.hIBeamCursor
Returns a cursor that looks like a capital I with a tiny crossbeam at its middle.
Return Value
The I-beam cursor. This is the cursor that you’re used to seeing over editable or selectable text. The I-beam cursor’s default hot spot is where the crossbeam intersects the I.
Availability
- Available in OS X v10.0 and later.
See Also
Declared In
NSCursor.hIBeamCursorForVerticalLayout
Returns the cursor for editing vertical layout text.
Return Value
The vertical layout text cursor. This cursor is used when editing vertical layout text.
Availability
- Available in OS X v10.7 and later.
Declared In
NSCursor.hopenHandCursor
Returns the open-hand system cursor.
Return Value
The open-hand cursor.
Availability
- Available in OS X v10.3 and later.
Declared In
NSCursor.hoperationNotAllowedCursor
Returns the operation not allowed cursor.
Return Value
The operation not allowed cursor.
Discussion
This cursor indicates that the operation that is being attempted, perhaps dragging to an item that can’t accept the drag type, is being denied.
Availability
- Available in OS X v10.6 and later.
Declared In
NSCursor.hpointingHandCursor
Returns the pointing-hand system cursor.
Return Value
The pointing-hand cursor. The tip of the pointing finger is the hot spot.
Availability
- Available in OS X v10.3 and later.
Declared In
NSCursor.hpop
Pops the current cursor off the top of the stack.
Discussion
The new object on the top of the stack becomes the current cursor. If the current cursor is the only cursor on the stack, this method does nothing.
Availability
- Available in OS X v10.0 and later.
See Also
Declared In
NSCursor.hresizeDownCursor
Returns the resize-down system cursor.
Return Value
The resize-down cursor. This cursor is used when moving or resizing an object to indicate that the user can move only in the indicated direction.
Availability
- Available in OS X v10.3 and later.
Declared In
NSCursor.hresizeLeftCursor
Returns the resize-left system cursor.
Return Value
The resize-left cursor. This cursor is used when moving or resizing an object to indicate that the user can move only in the indicated direction.
Availability
- Available in OS X v10.3 and later.
Declared In
NSCursor.hresizeLeftRightCursor
Returns the resize-left-and-right system cursor.
Return Value
The resize-left-and-right cursor. This cursor is used when moving or resizing an object and the object can be moved left or right.
Availability
- Available in OS X v10.3 and later.
Declared In
NSCursor.hresizeRightCursor
Returns the resize-right system cursor.
Return Value
The resize-right cursor. This cursor is used when moving or resizing an object to indicate that the user can move only in the indicated direction.
Availability
- Available in OS X v10.3 and later.
Declared In
NSCursor.hresizeUpCursor
Returns the resize-up system cursor.
Return Value
The resize-up cursor. This cursor is used when moving or resizing an object to indicate that the user can move only in the indicated direction.
Availability
- Available in OS X v10.3 and later.
Declared In
NSCursor.hresizeUpDownCursor
Returns the resize-up-and-down system cursor.
Return Value
The resize-up-and-down cursor. This cursor is used when moving or resizing an object and the object can be moved up or down.
Availability
- Available in OS X v10.3 and later.
Declared In
NSCursor.hsetHiddenUntilMouseMoves:
Sets whether the cursor is hidden until the mouse moves.
Parameters
- flag
YESto hide the cursor until one of the following occurs:The mouse moves.
You invoke the method again, with flag set to
NO.
Discussion
Do not try to counter this method by invoking unhide. The results are undefined.
Availability
- Available in OS X v10.0 and later.
See Also
Declared In
NSCursor.hunhide
Negates an earlier call to hide by showing the current cursor.
Discussion
Each invocation of unhide must be balanced by an invocation of hide in order for the cursor display to be correct.
Availability
- Available in OS X v10.0 and later.
See Also
Declared In
NSCursor.hInstance Methods
hotSpot
Returns the position of the cursor's hot spot.
Return Value
The point describing the position of the hot spot, specified according to the cursor’s flipped coordinate system.
Discussion
For a more complete explanation, see the class description.
Note that an NSCursor object is immutable: you cannot change its hot spot after it’s created. Instead, use initWithImage:hotSpot: to create a new cursor with the new settings.
Availability
- Available in OS X v10.0 and later.
See Also
Declared In
NSCursor.himage
Returns the receiver's image.
Return Value
The cursor image or nil if none exists
Discussion
Note that an NSCursor object is immutable: you cannot change its image after it’s created. Instead, use initWithImage:hotSpot: to create a new cursor with the new settings.
Availability
- Available in OS X v10.0 and later.
See Also
Declared In
NSCursor.hinitWithImage:foregroundColorHint:backgroundColorHint:hotSpot:
Initializes the cursor with the specified image and hot spot.
Parameters
- newImage
The image to assign to the cursor.
- fg
The foreground color. This is currently ignored.
- bg
The background color. This is currently ignored.
- hotSpot
The point to assign as the cursor's hot spot.
Return Value
The initialized cursor object.
Availability
- Available in OS X v10.0 and later.
See Also
Declared In
NSCursor.hinitWithImage:hotSpot:
Initializes a cursor with the given image and hot spot.
Parameters
- newImage
The image to assign to the cursor.
- aPoint
The point to set as the cursor's hot spot.
Return Value
An initialized cursor object.
Discussion
This method is the designated initializer for the class.
Availability
- Available in OS X v10.0 and later.
Declared In
NSCursor.hisSetOnMouseEntered
Returns a Boolean value indicating whether the receiver becomes current on receiving a mouseEntered: message.
Return Value
YES if the receiver will become current when it receives a mouseEntered: message; otherwise, NO.
Discussion
To receive such a message, the receiver must first be assigned a cursor rectangle. This assignment can be made using the NSView method addCursorRect:cursor:. For a more complete explanation, see the class description.
Availability
- Available in OS X v10.0 and later.
See Also
Declared In
NSCursor.hisSetOnMouseExited
Returns a Boolean value indicating whether the receiver becomes current when it receives a mouseExited: message.
Return Value
YES if the receiver becomes current when it receives a mouseExited: message; otherwise, NO.
Discussion
To receive such a message, the receiver must first be assigned a cursor rectangle. This assignment can be made using the NSView method addCursorRect:cursor:. For a more complete explanation, see the class description.
Availability
- Available in OS X v10.0 and later.
See Also
Declared In
NSCursor.hmouseEntered:
Automatically sent to the receiver when the cursor enters a cursor rectangle owned by the receiver.
Parameters
- anEvent
The event generated when the cursor enters the cursor rectangle.
Discussion
If used after setOnMouseEntered: has been called with an argument of YES, mouseEntered: can make the receiver the current cursor.
In your programs, you won’t invoke mouseEntered: explicitly. It’s only included in the class interface so you can override it.
For a more complete explanation, see “Mouse-Tracking and Cursor-Update Events” and the NSView method addTrackingRect:owner:userData:assumeInside:.
Availability
- Available in OS X v10.0 and later.
See Also
Declared In
NSCursor.hmouseExited:
Automatically sent to the receiver when the cursor exits a cursor rectangle owned by the receiver.
Parameters
- anEvent
The event generated when the cursor exits the cursor rectangle.
Discussion
Like mouseEntered:, this message is part of the class interface only so you can override it.
For a more complete explanation, see “Mouse-Tracking and Cursor-Update Events” and the NSView method addTrackingRect:owner:userData:assumeInside:.
Availability
- Available in OS X v10.0 and later.
See Also
Declared In
NSCursor.hpop
Sends a pop message to the receiver’s class.
Availability
- Available in OS X v10.0 and later.
Declared In
NSCursor.hpush
Puts the receiver on top of the cursor stack and makes it the current cursor.
Availability
- Available in OS X v10.0 and later.
Declared In
NSCursor.hset
Makes the receiver the current cursor.
Availability
- Available in OS X v10.0 and later.
See Also
Declared In
NSCursor.hsetOnMouseEntered:
Specifies whether the receiver accepts mouseEntered: events.
Parameters
- flag
YESif the receiver accepts futuremouseEntered:event messages; otherwise it ignores them.
Discussion
Accepting mouseEntered: event messages allows the cursor to be made the current cursor when the cursor enters a view’s cursor rectangle.
Availability
- Available in OS X v10.0 and later.
See Also
Declared In
NSCursor.hsetOnMouseExited:
Sets whether the receiver accepts mouseExited: events.
Parameters
- flag
YESif the receiver accepts futuremouseExited:event messages; otherwise it ignores them.
Discussion
Accepting mouseExited: event messages allows the cursor to be made the current cursor when the cursor exits a view’s cursor rectangle.
Availability
- Available in OS X v10.0 and later.
Declared In
NSCursor.hConstants
AppKit Versions for NSCursor Bug Fixes
The version of the AppKit framework containing a specific bug fix.
#define NSAppKitVersionNumberWithCursorSizeSupport 682.0
Constants
NSAppKitVersionNumberWithCursorSizeSupportThe specific version of the AppKit framework that introduced support for cursors larger than 16 x 16 pixels in size. Developers should not need to use this constant unless they are writing applications for OS X v10.2 and earlier.
Available in OS X v10.3 and later.
Declared in
NSCursor.h.
© 2012 Apple Inc. All Rights Reserved. (Last updated: 2012-05-14)