NSCursor

Inherits From: NSObject

Conforms To: NSCoding NSObject (NSObject)

Inherits From: AppKit/NSCursor.h

Class Description

An NSCursor holds an image that the window system can display for the cursor. An NSCursor is initialized with an NSImage object (which can subsequently be replaced by sending the NSCursor a setImage: message). To make the window system display a particular image as the current cursor, simply send a set message to the NSCursor instance associated with that image.

For automatic cursor management, an NSCursor can be assigned to a cursor rectangle within a window. When the window is key and the user moves the cursor into the rectangle, the NSCursor becomes the current cursor. It ceases to be the current cursor when the cursor leaves the rectangle. The assignment is made using NSView's addCursorRect:cursor: method, usually inside a resetCursorRects method:

- (void)resetCursorRects

{

[self addCursorRect:someRect cursor:theNSCursorObject];

}

This is the recommended way of associating a cursor with a particular region inside a window. However, the NSCursor class provides two other ways of setting the cursor:

. The class maintains its own stack of cursors. Pushing an NSCursor instance on the stack sets it to be the current cursor. Popping an NSCursor from the stack sets the next NSCursor in line, the one that's then at the top of the stack, to be the current cursor.

. An NSCursor can be made the owner of a tracking rectangle and told to set itself when it receives a mouse-entered or mouse-exited event.

The Application Kit provides two ready-made NSCursor instances: the standard arrow cursor, and the I-beam cursor that's displayed over editable or selectable text. These can be retrieved with the class methods arrowCursor and IBeamCursor, respectively. There's no NSCursor instance for the wait cursor. The wait cursor is displayed automatically by the system, without any required program intervention.

Initializing a New NSCursor Object

• - (id)initWithImage:(NSImage *)newImage Initializes a new NSCursor object with newImage.

• - (NSPoint)hotSpot Returns the point on the cursor that's aligned with the mouse.
• - (NSImage *)image Returns the NSImage object that has the cursor image.
• - (void)setHotSpot:(NSPoint)spot Sets the point on the cursor that's aligned with the mouse.
• - (void)setImage:(NSImage *)newImage Makes newImage the NSImage object that supplies the cursor image.

• + (void)hide Hides the cursor.
• + (void)pop Restores the previous cursor.
• + (void)setHiddenUntilMouseMoves:(BOOL)flag; Hides cursor when flag is YES; reveals it otherwise.
• + (void)unhide Shows the cursor.
• - (BOOL)isSetOnMouseEntered Returns YES if mouseEntered: sets cursor.
• - (BOOL)isSetOnMouseExited Returns YES if mouseExited: sets cursor.
• - (void)mouseEntered:(NSEvent *)theEvent Responds to a mouse-entered event by setting the cursor if setOnMouseEntered was sent.
• - (void)mouseExited:(NSEvent *)theEvent Responds to a mouse-exited event by setting the cursor if setOnMouseExited was sent.
• - (void)pop Removes the topmost NSCursor object from the cursor stack, and makes the next NSCursor down the current cursor.
• - (void)push Puts the receiving NSCursor on the cursor stack and sets it to be the current cursor.
• - (void)set Sets the NSCursor to be the current cursor.
• - (void)setOnMouseEntered:(BOOL)flag Determines whether mouseEntered: sets cursor.
• - (void)setOnMouseExited:(BOOL)flag Determines whether mouseExited: sets cursor.

• + (NSCursor *)arrowCursor Returns an arrow cursor.
• + (NSCursor *)currentCursor Returns the current cursor.
• + (NSCursor *)IBeamCursor Returns an I-beam cursor.