NXCursor

NXCursor

Inherits From: Object

Declared In: appkit/NXCursor.h

Class Description

An NXCursor holds an image that can become the image that the Window Server can display for the cursor. A set message makes the receiver the current cursor:

[myNXCursor set];

For automatic cursor management, an NXCursor 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 NXCursor is automatically set to be the current cursor. It ceases to be the current cursor when the cursor leaves the rectangle. The assignment is made using View's addCursorRect:cursor: method, usually inside a resetCursorRects method:

- resetCursorRects
{
[self addCursorRect:&someRect cursor:theNXCursorObject];
return self;
}

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

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

An NXCursor 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 NXCursor instances and assigns them to global variables:

NXArrow The standard arrow cursor

NXIBeam The cursor that's displayed over editable or selectable text

There's no NXCursor instance for the wait cursor. The wait cursor is displayed automatically by the system, without any required program intervention.

Instance Variables

NXPoint hotSpot;
struct _csrFlags {
unsigned int onMouseExited:1;
unsigned int onMouseEntered:1;
} cFlags;
id image;

hotSpot The point in the cursor image whose location on the screen is reported as the cursor's location.

cFlags.onMouseExited A flag indicating whether to set the cursor when the NXCursor object receives a mouse-exited event.

cFlags.onMouseEntered A flag indicating whether to set the cursor when the NXCursor object receives a mouse-entered event.

image The cursor image, an NXImage object.

Method Types

Initializing a new NXCursor object

init

initFromImage:

Defining the cursor setImage:

image
setHotSpot:

Setting the cursor push

pop
+ pop
set
setOnMouseEntered:
setOnMouseExited:
mouseEntered:
mouseExited:
+ currentCursor

Archiving read:

write:

Class Methods

currentCursor

+ currentCursor

Returns the last NXCursor that received a set message.
See also: set, push, + pop, mouseEntered:, mouseExited:,

pop

+ pop

Removes the NXCursor at the top of the cursor stack, and sets the NXCursor that was beneath it to be the current cursor. Returns self (the class object).
This method can be used in conjunction with the push method to manage a group of cursors within a local context. Every push should be balanced by a subsequent pop. When the last remaining cursor is popped from the stack, the Application Kit restores a cursor appropriate for the larger context.
The pop instance method provides the same functionality as this class method.
See also: push

Instance Methods

image

image

Returns the NXImage object that supplies the cursor image for the receiving NXCursor, or nil if no image has been set.
See also: initFromImage:, setImage:

init

init

Initializes the receiver, a newly allocated NXCursor instance, by sending it an initFromImage: message with nil as the argument. This doesn't assign an image to the object. An image must then be set (with the setImage: method) before the cursor can be used. Returns self.
See also: setImage:, initFromImage:

initFromImage:

initFromImage:image

Initializes the receiver, a newly allocated NXCursor instance, by setting the image it will use to image, an NXImage object. The image must be at least 16 pixels wide by 16 pixels high. If the image is smaller than 16-by-16, an error is generated when the application tries to use the cursor, and the previous cursor remains in use. If the image is larger than 16-by-16, only the lower-left 16-by-16 pixels of the image will be displayed. The default hot spot is at the upper left corner of the 16-by-16 square.
This method is the designated initializer for the class. Returns self.
See also: setHotSpot:, setImage:

mouseEntered:

mouseEntered:(NXEvent *)theEvent

Responds to a mouse-entered event by setting the receiver to be the current cursor, but only if enabled to do so by a previous setOnMouseEntered: message. This method does not push the receiver on the cursor stack. Returns self.
See also: setOnMouseEntered:

mouseExited:

mouseExited:(NXEvent *)theEvent

Responds to a mouse-exited event by setting the receiver to be the current cursor, but only if enabled to do so by a previous setOnMouseExited: message. This method does not push the receiver on the cursor stack. Returns self.
See also: setOnMouseExited:

pop

pop

Removes the topmost NXCursor object, not necessarily the receiver, from the cursor stack, and makes the next NXCursor down the current cursor. Returns self.
This method is a cover for the class method of the same name.
See also: + pop, push

push

push

Puts the receiving NXCursor on the cursor stack and sets it to be the Window Server's cursor. Returns self.
This method can be used in conjunction with the pop method to manage a group of cursors within a local context. Every push should be matched by a subsequent pop.
See also: + pop

read:

read:(NXTypedStream *)stream

Writes the NXCursor, including the image, to stream. Returns self.
See also: write:

set

set

Makes the NXCursor the cursor displayed by the Window Server, and returns self. This method doesn't push the receiver on the cursor stack.

setHotSpot:

setHotSpot:(const NXPoint *)aPoint

Sets the point on the cursor that will be used to report its location. The point is specified relative to a flipped coordinate system with an origin at the upper left corner of the cursor image and coordinate units equal to those of the base coordinate system. The point should not have any fractional coordinates, meaning that it should lie at the corner of four pixels. The point selects the pixel below it and to its right. This pixel is the one part of the cursor image that's guaranteed never to be off-screen.
When the pixel selected by the hot spot lies inside a rectangle (say a button), the cursor is said to be over the rectangle. When the pixel is outside the rectangle, the cursor is taken to be outside the rectangle, even if other parts of the image are inside.
The default hot spot is at the upper left corner of the image--(0,0) in its flipped coordinate system. Returns self.

setImage:

setImage:image

Assigns a new cursor image to the receiving NXCursor, and returns self. image should be an NXImage object for an image that's 16 pixels wide by 16 pixels high. If the image is smaller than 16-by-16, an error is generated when the application tries to use the cursor, and the previous cursor remains in use. If the image is larger than 16-by-16, only the lower-left 16-by-16 pixels of the image will be displayed.
Resetting the image of an NXCursor while it is the current cursor may have unpredictable results.
See also: image, initFromImage:

setOnMouseEntered:

setOnMouseEntered:(BOOL)flag

Determines whether the NXCursor should set itself to be the current cursor when it receives a mouseEntered: event message. To be able to receive the event message, an NXCursor must first be made the owner of a tracking rectangle by Window's setTrackingRect:inside:owner:tag:left:right: method.
Cursor rectangles are a more convenient way of associating cursors with particular areas within a window.
Returns self.
See also: mouseEntered:, setTrackingRect:inside:owner:tag:left:right: (Window)

setOnMouseExited:

setOnMouseExited:(BOOL)flag

Determines whether the NXCursor should set itself to be the current cursor when it receives a mouseExited: event message. To be able to receive the event message, an NXCursor must first be made the owner of a tracking rectangle by Window's setTrackingRect:inside:owner:tag:left:right: method.
Cursor rectangles are a more convenient way of associating cursors with particular areas within windows.
Returns self.
See also: mouseExited:, setTrackingRect:inside:owner:tag:left:right: (Window)

write:

write:(NXTypedStream *)stream

Writes the NXCursor and its image to stream. Returns self.
See also: read:

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

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

	NXArrow	The standard arrow cursor
	NXIBeam	The cursor that's displayed over editable or selectable text

	hotSpot	The point in the cursor image whose location on the screen is reported as the cursor's location.

	cFlags.onMouseExited	A flag indicating whether to set the cursor when the NXCursor object receives a mouse-exited event.

	cFlags.onMouseEntered	A flag indicating whether to set the cursor when the NXCursor object receives a mouse-entered event.

	image	The cursor image, an NXImage object.