NSCursor

Authors

Scott Christley (scottc@net-community.com)
Adam Fedor (fedor@gnu.org)

Date: Generated at 2025-12-03

Holds an image to use as a cursor

Software documentation for the NSCursor class

NSCursor : NSObject

Declared in:

AppKit/NSCursor.h

Conforms to:

NSCoding

Availability: OpenStep

NSCursor represents the visual appearance and behavior of the mouse cursor. It combines an image with a hot spot that defines the precise location within the image that corresponds to the cursor's position. NSCursor manages a stack of active cursors and provides methods for showing, hiding, and tracking cursor changes throughout the application. Key features include: - Custom cursor creation from images with specified hot spots - Predefined system cursors for common operations - Cursor stack management with push/pop operations - Automatic cursor changes on mouse enter/exit events - System-wide cursor hiding and visibility control - Support for foreground and background color hints NSCursor maintains a cursor stack where cursors can be pushed and popped, allowing temporary cursor changes that automatically revert to previous cursors. The class also provides numerous predefined cursors for standard operations like text selection, resizing, and drag-and-drop operations. Cursor changes can be tied to mouse tracking events, automatically switching cursors when the mouse enters or exits specific regions. The system can also hide the cursor until the mouse moves, useful for fullscreen applications or media players.

NSCursor declares 4 Instance Variables

Method summary

IBeamCursor

+ (NSCursor*) IBeamCursor;

Availability: OpenStep

Returns the I-beam cursor used for text editing. This cursor indicates that the user can click to place a text insertion point or drag to select text. Returns: The I-beam text editing cursor

Returns an I-beam cursor.

arrowCursor

+ (NSCursor*) arrowCursor;

Availability: OpenStep

Returns the standard arrow cursor. This is the default cursor used throughout the system for normal pointer operations and general user interface interaction. Returns: The standard arrow cursor

Returns an arrow cursor.

closedHandCursor

+ (NSCursor*) closedHandCursor;

Availability: MacOS-X 10.3.0

Returns the closed hand cursor used for dragging operations. This cursor indicates that the user is actively dragging an item. Returns: The closed hand cursor

contextualMenuCursor

+ (NSCursor*) contextualMenuCursor;

Availability: MacOS-X 10.6.0

Returns the contextual menu cursor. This cursor indicates that a contextual menu is available at the current location, typically shown during right-click operations. Returns: The contextual menu cursor

count

+ (NSUInteger) count;

Availability: OpenStep

Returns the count of cursor instances (Windows only). This method is used internally on Windows platforms for cursor management. Returns: The number of active cursor instances

crosshairCursor

+ (NSCursor*) crosshairCursor;

Availability: MacOS-X 10.3.0

Returns the crosshair cursor used for precise selection. This cursor is typically used in graphics applications for precise positioning or selection operations. Returns: The crosshair cursor

currentCursor

+ (NSCursor*) currentCursor;

Availability: OpenStep

Returns the currently active cursor. This method returns whichever cursor is currently being displayed, whether it's a system cursor or a custom cursor. Returns: The currently active NSCursor object

Returns the current cursor.

currentSystemCursor

+ (NSCursor*) currentSystemCursor;

Availability: MacOS-X 10.6.0

Returns the current system cursor. This method returns the cursor that the system would normally display based on the current context and application state. Returns: The current system cursor

disappearingItemCursor

+ (NSCursor*) disappearingItemCursor;

Availability: MacOS-X 10.3.0

Returns the disappearing item cursor used for item deletion. This cursor indicates that an item will be deleted or removed if dropped at the current location. Returns: The disappearing item cursor

dragCopyCursor

+ (NSCursor*) dragCopyCursor;

Availability: MacOS-X 10.6.0

Returns the drag copy cursor used for copy operations. This cursor indicates that dragging will result in copying the item to the destination location. Returns: The drag copy cursor

dragLinkCursor

+ (NSCursor*) dragLinkCursor;

Availability: MacOS-X 10.6.0

Returns the drag link cursor used for link creation. This cursor indicates that dragging will create a link to the item at the destination location. Returns: The drag link cursor

greenArrowCursor

+ (NSCursor*) greenArrowCursor;

Availability: Not in OpenStep/MacOS-X

Returns a green arrow cursor (GNUstep extension). This is a GNUstep-specific cursor variant not available in other systems. Returns: A green-colored arrow cursor

hide

+ (void) hide;

Availability: OpenStep

Hides the cursor system-wide. The cursor becomes invisible but continues to function normally. Use unhide to make the cursor visible again. Hide/unhide calls are balanced, so multiple hide calls require multiple unhide calls.

Hides the current cursor.

isHiddenUntilMouseMoves

+ (BOOL) isHiddenUntilMouseMoves;

Availability: OpenStep

Returns whether the cursor is hidden until the mouse moves. Returns: YES if cursor is hidden until mouse movement, NO otherwise

Returns whther the cursor is hidden until mouse moves

openHandCursor

+ (NSCursor*) openHandCursor;

Availability: MacOS-X 10.3.0

Returns the open hand cursor used for draggable items. This cursor indicates that an item can be grabbed and dragged. Returns: The open hand cursor

operationNotAllowedCursor

+ (NSCursor*) operationNotAllowedCursor;

Availability: MacOS-X 10.6.0

Returns the operation not allowed cursor. This cursor indicates that the current operation cannot be performed at the current location, typically shown during invalid drag operations. Returns: The operation not allowed cursor

pointingHandCursor

+ (NSCursor*) pointingHandCursor;

Availability: MacOS-X 10.3.0

Returns the pointing hand cursor used for clickable items. This cursor indicates that an item is clickable, typically used for hyperlinks or buttons. Returns: The pointing hand cursor

pop

+ (void) pop;

Availability: OpenStep

Removes the current cursor from the cursor stack. This restores the previous cursor that was active before the current cursor was pushed onto the stack.

Pops the cursor off the top of the stack and makes the previous one as the current cursor.

resizeDownCursor

+ (NSCursor*) resizeDownCursor;

Availability: MacOS-X 10.3.0

Returns the resize down cursor used for vertical resizing. This cursor indicates that the user can resize an element downward. Returns: The resize down cursor

resizeLeftCursor

+ (NSCursor*) resizeLeftCursor;

Availability: MacOS-X 10.3.0

Returns the resize left cursor used for horizontal resizing. This cursor indicates that the user can resize an element leftward. Returns: The resize left cursor

resizeLeftRightCursor

+ (NSCursor*) resizeLeftRightCursor;

Availability: MacOS-X 10.3.0

Returns the resize left-right cursor used for horizontal resizing. This cursor indicates that the user can resize an element horizontally in either direction. Returns: The resize left-right cursor

resizeRightCursor

+ (NSCursor*) resizeRightCursor;

Availability: MacOS-X 10.3.0

Returns the resize right cursor used for horizontal resizing. This cursor indicates that the user can resize an element rightward. Returns: The resize right cursor

resizeUpCursor

+ (NSCursor*) resizeUpCursor;

Availability: MacOS-X 10.3.0

Returns the resize up cursor used for vertical resizing. This cursor indicates that the user can resize an element upward. Returns: The resize up cursor

resizeUpDownCursor

+ (NSCursor*) resizeUpDownCursor;

Availability: MacOS-X 10.3.0

Returns the resize up-down cursor used for vertical resizing. This cursor indicates that the user can resize an element vertically in either direction. Returns: The resize up-down cursor

setHiddenUntilMouseMoves:

+ (void) setHiddenUntilMouseMoves: (BOOL)flag;

Availability: OpenStep

Sets whether the cursor should remain hidden until the mouse moves. This is useful for applications that want to hide the cursor during periods of inactivity, such as media players or fullscreen applications. flag: YES to hide cursor until mouse moves, NO for normal visibility

Hides the cursor if flag is YES. Unhides it if NO

unhide

+ (void) unhide;

Availability: OpenStep

Makes the cursor visible system-wide. This counteracts a previous hide operation. Hide/unhide calls are balanced, so the cursor becomes visible only when all hide operations have been matched with unhide operations.

Shows the NSCursor.

hotSpot

- (NSPoint) hotSpot;

Availability: OpenStep

Returns the hot spot point of the cursor. The hot spot defines the precise pixel within the cursor image that corresponds to the cursor's position on screen. This is typically the tip of an arrow or the center of a crosshair. Returns: The hot spot point within the cursor image

Returns the hot spot point of the NSCursor. This is in the cursor's coordinate system which is a flipped on (origin at the top left of the cursor).

image

- (NSImage*) image;

Availability: OpenStep

Returns the image used for the cursor. Returns: The NSImage object that defines the cursor's appearance

Returns the image of the NSCursor

initWithImage:

- (id) initWithImage: (NSImage*)newImage;

Availability: Not in OpenStep/MacOS-X

Initializes a cursor with the specified image using default hot spot. The hot spot is automatically set to the center of the image. newImage: The image to use for the cursor appearance Returns: An initialized NSCursor object

Initializes and returns a new NSCursor with a NSImage newImage and a hot spot point with x=0 and y=0 (top left corner).

initWithImage: foregroundColorHint: backgroundColorHint: hotSpot:

- (id) initWithImage: (NSImage*)newImage foregroundColorHint: (NSColor*)fg backgroundColorHint: (NSColor*)bg hotSpot: (NSPoint)hotSpot;

Availability: MacOS-X 10.0.0

Initializes a cursor with image, color hints, and hot spot. This method allows for creation of cursors with color hints that may be used by the underlying system to optimize cursor appearance on different backgrounds or display modes. The color hints are advisory and may be ignored by some systems. newImage: The image to use for the cursor appearance fg: Foreground color hint for the cursor bg: Background color hint for the cursor hotSpot: The point within the image that represents the cursor position Returns: An initialized NSCursor object

initWithImage: hotSpot:

- (id) initWithImage: (NSImage*)newImage hotSpot: (NSPoint)hotSpot;

Availability: OpenStep

Initializes a cursor with the specified image and hot spot. This is the designated initializer for creating custom cursors. The hot spot defines the precise pixel within the image that corresponds to the cursor's position on screen. newImage: The image to use for the cursor appearance hotSpot: The point within the image that represents the cursor position Returns: An initialized NSCursor object

Initializes and returns a new NSCursor with a NSImage newImage and the hot spot to hotSpot.

NB. The coordinate system of an NSCursor is flipped, so a hotSpot at 0,0 is in the top left corner of the cursor.

isSetOnMouseEntered

- (BOOL) isSetOnMouseEntered;

Availability: OpenStep

Returns whether this cursor is automatically set on mouse entered events. Returns: YES if cursor is set on mouse entered events, NO otherwise

Returns whether if the cursor is set on -mouseEntered: .

isSetOnMouseExited

- (BOOL) isSetOnMouseExited;

Availability: OpenStep

Returns whether this cursor is automatically set on mouse exited events. Returns: YES if cursor is set on mouse exited events, NO otherwise

Returns whether if the cursor is push on -mouseExited: .

mouseEntered:

- (void) mouseEntered: (NSEvent*)theEvent;

Availability: OpenStep

Handles mouse entered events for automatic cursor switching. This method is called automatically when the mouse enters a tracking area that has this cursor associated with it. theEvent: The mouse entered event

Sets the cursor if -isSetOnMouseEntered is YES or pushs the cursor if -isSetOnMouseExited is NO

mouseExited:

- (void) mouseExited: (NSEvent*)theEvent;

Availability: OpenStep

Handles mouse exited events for automatic cursor switching. This method is called automatically when the mouse exits a tracking area that has this cursor associated with it. theEvent: The mouse exited event

Sets the cursor if -isSetOnMouseExited is YES or pops the cursor if -isSetOnMouseEntered is NO

pop

- (void) pop;

Availability: OpenStep

Removes this cursor from the cursor stack. This restores the previous cursor that was active before this cursor was pushed onto the stack.

Pops the cursor off the top of the stack and makes the previous the current cursor.

push

- (void) push;

Availability: OpenStep

Pushes this cursor onto the cursor stack and makes it current. The previous cursor is preserved and can be restored by calling pop on this cursor or the class method pop.

Adds the NSCursor into the cursor stack and makes it the current cursor.

set

- (void) set;

Availability: OpenStep

Sets this cursor as the current cursor. Unlike push, this method does not preserve the previous cursor on a stack. The cursor remains active until another cursor is set.

Sets the NSCursor as the current cursor.

setHotSpot:

- (void) setHotSpot: (NSPoint)spot;

Availability: Not in OpenStep/MacOS-X

Sets the hot spot point of the cursor. This method is used internally and should not be called directly. spot: The new hot spot point within the cursor image

Sets the hot spot point of the NSCursor to spot

setImage:

- (void) setImage: (NSImage*)newImage;

Availability: Not in OpenStep/MacOS-X

Sets the image used for the cursor. This method is used internally and should not be called directly. newImage: The new image to use for the cursor

Sets newImage the image of the NSCursor

setOnMouseEntered:

- (void) setOnMouseEntered: (BOOL)flag;

Availability: OpenStep

Sets whether this cursor should be automatically set on mouse entered events. When enabled, this cursor will automatically become active when the mouse enters tracking areas associated with this cursor. flag: YES to enable automatic setting on mouse entered, NO to disable

Sets whether if the cursor is set on -mouseEntered: .

setOnMouseExited:

- (void) setOnMouseExited: (BOOL)flag;

Availability: OpenStep

Sets whether this cursor should be automatically set on mouse exited events. When enabled, this cursor will automatically become active when the mouse exits tracking areas associated with this cursor. flag: YES to enable automatic setting on mouse exited, NO to disable

Sets whether if the cursor is push on -mouseExited: .

Instance Variables for NSCursor Class

_cid

@protected void* _cid;

Availability: OpenStep

Platform-specific cursor identifier used by the underlying windowing system.
Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.

_cursor_image

@protected NSImage* _cursor_image;

Availability: OpenStep

The image that defines the visual appearance of the cursor.
Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.

_hot_spot

@protected NSPoint _hot_spot;

Availability: OpenStep

The hot spot point within the cursor image that corresponds to the actual cursor position.
Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.

struct GSCursorFlagsType

@protected struct GSCursorFlagsType struct GSCursorFlagsType;

Availability: OpenStep

Internal flags structure containing cursor state information.
Whether this cursor is automatically set when mouse enters a tracking area.
Whether this cursor is automatically set when mouse exits a tracking area.
The cursor type identifier for predefined system cursors.
Reserved bits for future use.