Legacy Document

Inside Macintosh: Imaging With QuickDraw /

Chapter 8 - Cursor Utilities / Cursor Utilities Reference

Data Structures /

CCrsr

Your application typically does not create CCrsr records, which are data structures of type CCrsr. Although you can create a CCrsr record, it is usually easier to create a color cursor in a color cursor resource, which is described on page 8-32.

A color cursor is a 256-pixel color image in a 16-by-16 pixel square usually defined in a color cursor ('crsr') resource. When your application uses the GetCCursor function (described on page 8-24) to get a color cursor from a 'crsr' resource, GetCCursor uses the Resource Manager to load the resource into memory as a CCrsr record. Your application can then display the color cursor by using the SetCCursor procedure, which is described on page 8-24.

The CCrsr record is substantially different from the Cursor record described in the preceding section; the fields crsr1Data, crsrMask, and crsrHotSpot in the CCrsr record are the only ones that have counterparts in the Cursor record. A CCrsr record is defined as follows:

TYPE CCrsrHandle =   ^CCrsrPtr;
CCrsrPtr =           ^CCrsr;
CCrsr = 
   RECORD
      crsrType:      Integer;       {type of cursor}
      crsrMap:       PixMapHandle;  {the cursor's PixMap record}
      crsrData:      Handle;        {cursor's data}
      crsrXData:     Handle;        {expanded cursor data}
      crsrXValid:    Integer;       {depth of expanded data}
      crsrXHandle:   Handle;        {reserved for future use}
      crsr1Data:     Bits16;        {1-bit cursor}
      crsrMask:      Bits16;        {cursor's mask}
      crsrHotSpot:   Point;         {cursor's hot spot}
      crsrXTable:    LongInt;       {private}
      crsrID:        LongInt;       {ctSeed for expanded cursor}
   END;

Field Description

crsrType

The type of cursor. Possible values are $8000 for a black-and-white cursor and $8001 for a color cursor.

crsrMap

A handle to the PixMap record defining the cursor's characteristics. PixMap records are described in the chapter "Color QuickDraw" in this book.

crsrData

A handle to the cursor's pixel data.

crsrXData

A handle to the expanded pixel image used internally by Color QuickDraw.

crsrXValid

The depth of the expanded cursor image. If you change the cursor's data or color table, you should set this field to 0 to cause the cursor to be re-expanded. You should never set it to any other values.

crsrXHandle

Reserved for future use.

crsr1Data

A 16-by-16 pixel image with a pixel depth of 1 to be displayed when the cursor is on screens with pixel depths of 1 or 2 bits.

crsrMask

The cursor's mask data. 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 same 1-bit mask is used with images specified by the crsrData and crsr1Data fields.

crsrHotSpot

The cursor's hot spot.

crsrXTable

Reserved for future use.

crsrID

The color table seed for the cursor.

The first four fields of the CCrsr record are similar to the first four fields of the PixPat record, and are used in the same manner by Color QuickDraw. See the chapter "Color QuickDraw" in this book for information about PixPat records.

The display of a cursor involves a relationship between a mask, stored in the crsrMask field with the same format used for 1-bit cursor masks, and an image. There are two possible sources for a color cursor's image. When the cursor is on a screen whose depth is 1 or 2 bits per pixel, the image for the cursor is taken from the crsr1Data field, which contains bitmap cursor data (similar to the bitmap in a 'CURS' resource).

When the screen depth is greater than 2 bits per pixel, the crsrMap field and the crsrData field define the image. The pixels within the mask replace the destination pixels. Color QuickDraw transfers the pixels outside the mask into the destination pixels using the XOR Boolean transfer mode. Therefore, if pixels outside the mask are white, the destination pixels aren't changed. If pixels outside the mask are all black, the destination pixels are inverted. All other values outside of the mask cause unpredictable results. See the discussion of Boolean transfer modes in the chapter "Color QuickDraw" in this book for more information about the XOR Boolean transfer mode.

To work properly, a color cursor's image should contain white pixels (R = G = B = $FFFF) for the transparent part of the image, and black pixels (R = G = B = $0000) for the part of the image to be inverted, in addition to the other colors in the cursor's image. Thus, to define a cursor that contains two colors, it's necessary to use a 2-bit cursor image (that is, a four-color image).

If your application changes the value of your color cursor data or its color table, it should set the crsrXValid field to 0 to indicate that the color cursor's data needs to be re-expanded, and it should assign a new unique value to the crsrID field (unique values can be obtained using the Color Manager function GetCTSeed, which is described in Advanced Color Imaging on the Mac OS. Then your application should call SetCCursor to display the changed color cursor.