PATH  Documentation > Mac OS X > Application Kit Reference: Objective-C

Table of Contents

NSCursor


Inherits from:
NSObject
Conforms to:
NSCoding
NSObject (NSObject)
Declared in:
AppKit/NSCursor.h




Class Description


Instances of the NSCursor class manage the appearance of the cursor. When you initialize a cursor-the designated initializer is initWithImage:hotSpot:-you assign it a 16-by-16 pixel NSImage and a point to be the hot spot. The image is usually a small, opaque icon-for example, a pair of cross-hairs-surrounded by transparent pixels. The pixels in the cursor image are mapped on a flipped coordinate system: the upper left pixel is (0,0); the lower right is (15,15).

To determine exactly when the mouse is inside a particular cursor rectangle, the Application Kit tracks a single pixel in the cursor image. This pixel is known as the hot spot, and you can reference it using the hotSpot method. By definition, the location of the current cursor's hot spot is the location of the mouse; when the hot spot is inside a cursor rectangle, so is the mouse. The hot spot is useful not only for determining which cursor is current, but for determining where a mouse click should have its effect.

An NSCursor object is immutable: you cannot change its hot spot or image after it's created. Instead, use initWithImage:hotSpot: to create a new one with the new settings.

An application may use several cursor instances-for example, one that looks like an arrow and one that looks like an I-beam. The instance that currently appears on the screen is called the "current cursor," and is referenced by the currentCursor class method. You can set the current cursor in several ways:

The cursor rectangle is a region inside an NSView that triggers a change in the current cursor. To create a cursor rectangle, use the addCursorRect:cursor: method of NSView to associate a region of the view with the cursor, as shown in the following example:

[aView addCursorRect:aRect cursor:aCursor];
[aCursor setOnMouseEntered:YES];

This assignment means that when the mouse enters aRect, aCursor will receive a mouseEntered: event message, which the cursor uses to make itself the current cursor. However, before the cursor can acknowledge the mouseEntered: message, you must invoke the cursor's setOnMouseEntered: method. Alternatively, you can set the cursor when the mouse leaves the cursor rectangle by invoking the setOnMouseExited: method instead of setOnMouseEntered:. A cursor that sets itself upon leaving the cursor rectangle receives a mouseExited: event message to instigate the change.

The Application Kit provides two ready-made cursors for commonly used cursor images. You can retrieve these cursors by using the arrowCursor and IBeamCursor class methods. There is no NSCursor instance for the wait cursor, because the system automatically displays it at the appropriate times.




Adopted Protocols


NSCoding
- encodeWithCoder:
- initWithCoder:


Method Types


Initializing a new cursor
- initWithImage:hotSpot:
- initWithImage:foregroundColorHint:backgroundColorHint:hotSpot:
Setting cursor attributes
- image
- hotSpot
+ hide
+ unhide
+ setHiddenUntilMouseMoves:
Controlling which cursor is current
+ pop
- pop
- push
- set
- mouseEntered:
- setOnMouseEntered:
- isSetOnMouseEntered
- mouseExited:
- setOnMouseExited:
- isSetOnMouseExited
Retrieving cursor instances
+ arrowCursor
+ currentCursor
+ IBeamCursor


Class Methods



arrowCursor

+ (NSCursor *)arrowCursor

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

See Also: + IBeamCursor, + currentCursor, - hotSpot



currentCursor

+ (NSCursor *)currentCursor

Returns the cursor currently displayed on the screen.

See Also: - set, - push, + pop, - mouseEntered:, - mouseExited:



hide

+ (void)hide

Makes the current cursor invisible. If another cursor becomes current, that cursor will be invisible, too. It will remain invisible until you invoke the unhide method.

hide overrides setHiddenUntilMouseMoves:.



IBeamCursor

+ (NSCursor *)IBeamCursor

Returns a cursor that looks like a capital I with a tiny crossbeam at its middle. 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.

See Also: + arrowCursor, + currentCursor



pop

+ (void)pop

Pops the current cursor off the top of the stack. 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.

See Also: - push



setHiddenUntilMouseMoves:

+ (void)setHiddenUntilMouseMoves:(BOOL)flag

If flag is trueYES, hides the cursor. The cursor remains invisible until:

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

See Also: + hide



unhide

+ (void)unhide

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

See Also: + setHiddenUntilMouseMoves:, + hide




Instance Methods



hotSpot

- (NSPoint)hotSpot

Returns the position of the hot spot, specified according to the cursor's flipped 16-by-16 coordinate system. 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.

See Also: - initWithImage:hotSpot:



image

- (NSImage *)image

Returns the image for the receiving cursor, or nil if none exists.

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.

See Also: - initWithImage:hotSpot:



initWithImage:foregroundColorHint:backgroundColorHint:hotSpot:

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

Initializes the receiver, assigns it newImage (which must be 16-by-16 pixels) and sets its hot spot to hotSpot. The foreground and background colors are currently ignored. Returns self.

See Also: - initWithImage:hotSpot:



initWithImage:hotSpot:

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

This method is the designated initializer for the class. It initializes the receiver, assigns it newImage (which must be 16-by-16 pixels) and sets its hot spot to aPoint. Returns self.

See Also: - hotSpot, - image, - initWithImage:foregroundColorHint:backgroundColorHint:hotSpot:



isSetOnMouseEntered

- (BOOL)isSetOnMouseEntered

Returns YES if the receiving cursor will become current when it receives a mouseEntered: message; otherwise, returns NO.

To receive such a message, the receiver must first be assigned a cursor rectangle. This assignment can be made using NSView's addCursorRect:cursor: method. For a more complete explanation, see the class description.

See Also: - setOnMouseEntered:, - isSetOnMouseExited



isSetOnMouseExited

- (BOOL)isSetOnMouseExited

Returns YES if the receiving cursor becomes current when it receives a mouseExited: message; otherwise, returns NO.

To receive such a message, the receiver must first be assigned a cursor rectangle. This assignment can be made using NSView's addCursorRect:cursor: method. For a more complete explanation, see the class description.

See Also: - setOnMouseExited:



mouseEntered:

- (void)mouseEntered:(NSEvent *)anEvent

This message is automatically sent to the receiver when the mouse enters the receiver's cursor rectangle. 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 the class description.

See Also: - isSetOnMouseEntered, - mouseExited:



mouseExited:

- (void)mouseExited:(NSEvent *)anEvent

This message is automatically sent to the receiver when the mouse exits the receiver's cursor rectangle. Like mouseEntered:, it is part of the class interface only so you can override it.

See Also: - setOnMouseExited:, - isSetOnMouseExited



pop

- (void)pop

Sends a pop message to the instance's class.

See Also: - push, + pop



push

- (void)push

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

See Also: - pop, + pop



set

- (void)set

Makes the receiver the current cursor.

See Also: + currentCursor



setOnMouseEntered:

- (void)setOnMouseEntered:(BOOL)flag

If flag is YES, the cursor accepts future mouseEntered: event messages, otherwise it ignores them. Accepting mouseEntered: event messages allows the cursor to be made the current cursor when the mouse enters a view's cursor rectangle.

See Also: - mouseEntered:



setOnMouseExited:

- (void)setOnMouseExited:(BOOL)flag

If flag is YES, the cursor accepts future mouseExited: event messages, otherwise it ignores them. Accepting mouseExited: event messages allows the cursor to be made the current cursor when the mouse exits a view's cursor rectangle.


Table of Contents