Mac Developer Library

Developer

AppKit Framework Reference NSCursor Class Reference

Options
Deployment Target:

On This Page
Language:

NSCursor

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

image: ../Art/arrow.eps

The arrow cursor (arrowCursor)

image: ../Art/ibeam.eps

The I-beam cursor for indicating insertion points (IBeamCursor)

image: ../Art/crosshair.eps

The cross-hair cursor (crosshairCursor)

image: ../Art/closed_hand.eps

The closed-hand cursor (closedHandCursor)

image: ../Art/open_hand.eps

The open-hand cursor (openHandCursor)

image: ../Art/point_hand.eps

The pointing-hand cursor (pointingHandCursor)

image: ../Art/left.eps

The resize-left cursor (resizeLeftCursor)

image: ../Art/right.eps

The resize-right cursor (resizeRightCursor)

image: ../Art/leftright.eps

The resize-left-and-right cursor (resizeLeftRightCursor)

image: ../Art/up.eps

The resize-up cursor (resizeUpCursor)

image: ../Art/down.eps

The resize-down cursor (resizeDownCursor)

image: ../Art/updown.eps

The resize-up-and-down cursor (resizeUpDownCursor)

image: ../Art/poof.eps

The disappearing item cursor (disappearingItemCursor)

image: ../Art/horizontal_cursor.png

The I-Beam text cursor for vertical layout (IBeamCursorForVerticalLayout).

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.

Inheritance


Conforms To


Import Statement


Swift

import AppKit

Objective-C

@import AppKit;

Availability


Available in OS X v10.0 and later.
  • Returns the receiver's image.

    Declaration

    Swift

    var image: NSImage { get }

    Objective-C

    @property(readonly, strong) NSImage *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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Returns the position of the cursor's hot spot.

    Declaration

    Swift

    var hotSpot: NSPoint { get }

    Objective-C

    @property(readonly) NSPoint hotSpot

    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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Makes the current cursor invisible.

    Declaration

    Swift

    class func hide()

    Objective-C

    + (void)hide

    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:.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Negates an earlier call to hide by showing the current cursor.

    Declaration

    Swift

    class func unhide()

    Objective-C

    + (void)unhide

    Discussion

    Each invocation of unhide must be balanced by an invocation of hide in order for the cursor display to be correct.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Sets whether the cursor is hidden until the mouse moves.

    Declaration

    Swift

    class func setHiddenUntilMouseMoves(_ flag: Bool)

    Objective-C

    + (void)setHiddenUntilMouseMoves:(BOOL)flag

    Parameters

    flag

    YEStrue to hide the cursor until one of the following occurs:

    • The mouse moves.

    • You invoke the method again, with flag set to NOfalse.

    Discussion

    Do not try to counter this method by invoking unhide. The results are undefined.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

    See Also

    + hide

  • Pops the current cursor off the top of the stack.

    Declaration

    Swift

    class func pop()

    Objective-C

    + (void)pop

    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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

    See Also

    – push

  • Sends a pop message to the receiver’s class.

    Declaration

    Swift

    func pop()

    Objective-C

    - (void)pop

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Puts the receiver on top of the cursor stack and makes it the current cursor.

    Declaration

    Swift

    func push()

    Objective-C

    - (void)push

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

    See Also

    – pop
    – pop

  • Makes the receiver the current cursor.

    Declaration

    Swift

    func set()

    Objective-C

    - (void)set

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

    See Also

    + currentCursor

  • Automatically sent to the receiver when the cursor enters a cursor rectangle owned by the receiver.

    Declaration

    Swift

    func mouseEntered(_ anEvent: NSEvent)

    Objective-C

    - (void)mouseEntered:(NSEvent *)anEvent

    Parameters

    anEvent

    The event generated when the cursor enters the cursor rectangle.

    Discussion

    If used after setOnMouseEntered: has been called with an argument of YEStrue, 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:.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Specifies whether the receiver accepts mouseEntered: events.

    Declaration

    Swift

    func setOnMouseEntered(_ flag: Bool)

    Objective-C

    - (void)setOnMouseEntered:(BOOL)flag

    Parameters

    flag

    YEStrue if the receiver accepts future mouseEntered: 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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • isSetOnMouseEntered - isSetOnMouseEntered Available in OS X v10.0 through OS X v10.9

    Returns a Boolean value indicating whether the receiver becomes current on receiving a mouseEntered: message.

    Declaration

    Objective-C

    - (BOOL)isSetOnMouseEntered

    Return Value

    YEStrue if the receiver will become current when it receives a mouseEntered: message; otherwise, NOfalse.

    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.

    Import Statement

    Objective-C

    @import AppKit;

    Availability

    Available in OS X v10.0 through OS X v10.9.

  • Automatically sent to the receiver when the cursor exits a cursor rectangle owned by the receiver.

    Declaration

    Swift

    func mouseExited(_ anEvent: NSEvent)

    Objective-C

    - (void)mouseExited:(NSEvent *)anEvent

    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:.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Sets whether the receiver accepts mouseExited: events.

    Declaration

    Swift

    func setOnMouseExited(_ flag: Bool)

    Objective-C

    - (void)setOnMouseExited:(BOOL)flag

    Parameters

    flag

    YEStrue if the receiver accepts future mouseExited: 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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • isSetOnMouseExited - isSetOnMouseExited Available in OS X v10.0 through OS X v10.9

    Returns a Boolean value indicating whether the receiver becomes current when it receives a mouseExited: message.

    Declaration

    Objective-C

    - (BOOL)isSetOnMouseExited

    Return Value

    YEStrue if the receiver becomes current when it receives a mouseExited: message; otherwise, NOfalse.

    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.

    Import Statement

    Objective-C

    @import AppKit;

    Availability

    Available in OS X v10.0 through OS X v10.9.

  • Returns the application’s current cursor.

    Declaration

    Swift

    class func currentCursor() -> NSCursor

    Objective-C

    + (NSCursor *)currentCursor

    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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Returns the current system cursor.

    Declaration

    Swift

    class func currentSystemCursor() -> NSCursor?

    Objective-C

    + (NSCursor *)currentSystemCursor

    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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.6 and later.

  • Returns the default cursor, the arrow cursor.

    Declaration

    Swift

    class func arrowCursor() -> NSCursor

    Objective-C

    + (NSCursor *)arrowCursor

    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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Returns the contextual menu system cursor.

    Declaration

    Swift

    class func contextualMenuCursor() -> NSCursor

    Objective-C

    + (NSCursor *)contextualMenuCursor

    Return Value

    The contextual menu cursor

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.6 and later.

  • Returns the closed-hand system cursor.

    Declaration

    Swift

    class func closedHandCursor() -> NSCursor

    Objective-C

    + (NSCursor *)closedHandCursor

    Return Value

    The closed-hand cursor.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.3 and later.

  • Returns the cross-hair system cursor.

    Declaration

    Swift

    class func crosshairCursor() -> NSCursor

    Objective-C

    + (NSCursor *)crosshairCursor

    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).

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.3 and later.

  • Returns a cursor indicating that the current operation will result in a disappearing item.

    Declaration

    Swift

    class func disappearingItemCursor() -> NSCursor

    Objective-C

    + (NSCursor *)disappearingItemCursor

    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).

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.3 and later.

  • Returns a cursor indicating that the current operation will result in a copy action.

    Declaration

    Swift

    class func dragCopyCursor() -> NSCursor

    Objective-C

    + (NSCursor *)dragCopyCursor

    Return Value

    The drag copy cursor.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.6 and later.

  • Returns a cursor indicating that the current operation will result in a link action.

    Declaration

    Swift

    class func dragLinkCursor() -> NSCursor

    Objective-C

    + (NSCursor *)dragLinkCursor

    Return Value

    The drag link cursor.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.6 and later.

  • Returns a cursor that looks like a capital I with a tiny crossbeam at its middle.

    Declaration

    Swift

    class func IBeamCursor() -> NSCursor

    Objective-C

    + (NSCursor *)IBeamCursor

    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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Returns the open-hand system cursor.

    Declaration

    Swift

    class func openHandCursor() -> NSCursor

    Objective-C

    + (NSCursor *)openHandCursor

    Return Value

    The open-hand cursor.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.3 and later.

  • Returns the operation not allowed cursor.

    Declaration

    Swift

    class func operationNotAllowedCursor() -> NSCursor

    Objective-C

    + (NSCursor *)operationNotAllowedCursor

    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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.5 and later.

  • Returns the pointing-hand system cursor.

    Declaration

    Swift

    class func pointingHandCursor() -> NSCursor

    Objective-C

    + (NSCursor *)pointingHandCursor

    Return Value

    The pointing-hand cursor. The tip of the pointing finger is the hot spot.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.3 and later.

  • Returns the resize-down system cursor.

    Declaration

    Swift

    class func resizeDownCursor() -> NSCursor

    Objective-C

    + (NSCursor *)resizeDownCursor

    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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.3 and later.

  • Returns the resize-left system cursor.

    Declaration

    Swift

    class func resizeLeftCursor() -> NSCursor

    Objective-C

    + (NSCursor *)resizeLeftCursor

    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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.3 and later.

  • Returns the resize-left-and-right system cursor.

    Declaration

    Swift

    class func resizeLeftRightCursor() -> NSCursor

    Objective-C

    + (NSCursor *)resizeLeftRightCursor

    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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.3 and later.

  • Returns the resize-right system cursor.

    Declaration

    Swift

    class func resizeRightCursor() -> NSCursor

    Objective-C

    + (NSCursor *)resizeRightCursor

    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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.3 and later.

  • Returns the resize-up system cursor.

    Declaration

    Swift

    class func resizeUpCursor() -> NSCursor

    Objective-C

    + (NSCursor *)resizeUpCursor

    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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.3 and later.

  • Returns the resize-up-and-down system cursor.

    Declaration

    Swift

    class func resizeUpDownCursor() -> NSCursor

    Objective-C

    + (NSCursor *)resizeUpDownCursor

    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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.3 and later.

  • Returns the cursor for editing vertical layout text.

    Declaration

    Swift

    class func IBeamCursorForVerticalLayout() -> NSCursor

    Objective-C

    + (NSCursor *)IBeamCursorForVerticalLayout

    Return Value

    The vertical layout text cursor. This cursor is used when editing vertical layout text.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.7 and later.

  • The version of the AppKit framework containing a specific bug fix.

    Declaration

    Swift

    var NSAppKitVersionNumberWithCursorSizeSupport: Double { get }

    Objective-C

    #define NSAppKitVersionNumberWithCursorSizeSupport 682.0

    Constants

    • NSAppKitVersionNumberWithCursorSizeSupport

      NSAppKitVersionNumberWithCursorSizeSupport

      The 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.