Legacy Document

Inside Macintosh: Imaging With QuickDraw /

Chapter 8 - Cursor Utilities / Cursor Utilities Reference

Data Structures /

Cursor

Your application typically does not create Cursor records, which are data structures of type Cursor. Although you can create a Cursor record and its associated Bits16 array in your program code, it is usually easier to create a black-and-white cursor in a cursor resource, which is described on page 8-31.

A cursor is a 256-pixel, black-and-white image in a 16-by-16 pixel square usually defined by an application in a cursor ('CURS') resource. When your application uses the GetCursor function (described on page 8-22) to get a cursor from a 'CURS' resource, GetCursor uses the Resource Manager to load the resource into memory as a Cursor record. Your application can then display the color cursor by using the SetCursor procedure, which is described on page 8-23.

A Cursor record is defined as follows:

TYPE CursPtr   = ^Cursor;
CursHandle     = ^CursPtr;
Cursor =
   RECORD
      data:    Bits16;  {cursor image}
      mask:    Bits16;  {cursor mask}
      hotSpot: Point;   {point aligned with mouse}
   END;

Field Description

data

Cursor image data, which must begin on a word boundary. The Bits16 data type for this field is described in the preceding section.

mask

The cursor's mask, whose effects are shown in Table 8-1. QuickDraw uses the mask to crop the cursor's outline into a background color or pattern. QuickDraw then draws the cursor into this shape. The Bits16 data type for this field is described in the preceding section.

hotSpot

A point in the image that aligns with the mouse location.This field aligns a point (not a bit) in the image with the mouse location on the screen. Whenever the user moves the mouse, the low-level interrupt-driven mouse routines move the cursor. When the user clicks, the Event Manager function WaitNextEvent reports the location of the cursor's hot spot in global coordinates.

The cursor appears on the screen as a 16-by-16 pixel square. The appearance of each bit of the square is determined by the corresponding bits in the data and mask and, if the mask bit is 0, by the pixel under the cursor, as shown in Table 8-1.

Table 8-1 Cursor appearance

Data	Mask	Resulting pixel on screen
0	1	White
1	1	Black
0	0	Same as pixel under cursor
1	0	Inverse of pixel under cursor

Notice that if all mask bits are 0, the cursor is completely transparent, in that the image under the cursor can still be viewed. Pixels under the white part of the cursor appear unchanged; under the black part of the cursor, black pixels show through as white.

Basic QuickDraw supplies a predefined cursor in the global variable named arrow; this is the standard arrow cursor.