Inside Macintosh: Imaging With QuickDraw /

Chapter 8 - Cursor Utilities

Summary of Cursor Utilities

Pascal Summary

Constants

CONST
   iBeamCursor = 1;  {used in text editing}
   crossCursor = 2;  {often used for manipulating graphics}
   plusCursor  = 3;  {often used for selecting fields in an array}
   watchCursor = 4;  {used to mean a short operation is in progress}

Data Types

TYPE  Bits16 = ARRAY[0..15] OF Integer;
      CursPtr = ^Cursor;
      CursHandle = ^CursPtr;
      Cursor =
      RECORD
         data:    Bits16;  {cursor image}
         mask:    Bits16;  {cursor mask}
         hotSpot: Point;   {point aligned with mouse}
      END;
      CCrsrPtr = ^CCrsr;
      CCrsrHandle = ^CCrsrPtr;
      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 (0 if none)}
         crsrXHandle:Handle;        {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;
      Cursors =            {values to pass to Show_Cursor}
         (HIDDEN_CURSOR,   {the current cursor}
          I_BEAM_CURSOR,   {the I-beam cursor; to select text}
          CROSS_CURSOR,    {the crosshairs cursor; to draw graphics}
          PLUS_CURSOR,     {the plus sign cursor; to select cells}
          WATCH_CURSOR,    {the wristwatch cursor; to indicate a }
                           { short operation in progress}
          ARROW_CURSOR);   {the standard cursor}
      acurPtr = ^Acur;
      acurHandle = ^acurPtr;
      Acur = 
      RECORD
         n:       Integer;    {number of cursors ("frames")}
         index:   Integer;    {reserved}
         frame1:  Integer;    {'CURS' resource ID for frame #1}
         fill1:   Integer;    {reserved}
         frame2:  Integer;    {'CURS' resource ID for frame #2}
         fill2:   Integer;    {reserved}
         frameN:  Integer;    {'CURS' resource ID for frame #N}
         fillN:   Integer;    {reserved}
      END;

Routines

Initializing Cursors

PROCEDURE InitCursor;
PROCEDURE InitCursorCtl    (newCursors: UNIV acurHandle);

Changing Black-and-White Cursors

FUNCTION GetCursor         (cursorID: Integer): CursHandle;
PROCEDURE SetCursor        (crsr: Cursor);

Changing Color Cursors

{DisposeCCursor is also spelled as DisposCCursor}
FUNCTION GetCCursor        (cursorID: Integer): CCursHandle;
PROCEDURE SetCCursor       (cCrsr: CCrsrHandle);
PROCEDURE DisposeCCursor   (cCrsr: CCrsrHandle);
PROCEDURE AllocCursor;

Hiding and Showing Cursors

PROCEDURE HideCursor;
PROCEDURE Hide_Cursor;
PROCEDURE ObscureCursor;
PROCEDURE ShieldCursor     (shieldRect: Rect; offsetPt: Point);
PROCEDURE ShowCursor;
PROCEDURE Show_Cursor      (cursorKind: Cursors);

Displaying Animated Cursors

PROCEDURE RotateCursor     (counter: LongInt);
PROCEDURE SpinCursor       (increment: Integer);

C Summary

Constants

enum {
   iBeamCursor =  1,    /* used in text editing */
   crossCursor =  2,    /* often used for manipulating graphics */
   plusCursor =   3,    /* often used for selecting fields in an array */
   watchCursor =  4     /* used to mean a short operation is in progress */
};
enum {               /* values to pass to Show_Cursor */
   HIDDEN_CURSOR,    /* the current cursor */
   I_BEAM_CURSOR,    /* the I-beam cursor; to select tect */
   CROSS_CURSOR,     /* the crosshairs cursor; to draw graphics */
   PLUS_CURSOR,      /* the plus sign cursor; to select cells */
   WATCH_CURSOR,     /* the wristwatch cursor; to indicate a short 
                        operation in progress */
   ARROW_CURSOR      /* the standard cursor */
};
typedef unsigned char Cursors;

Data Types

typedef short Bits16[16];
struct Cursor {
   Bits16   data;    /* cursor image */
   Bits16   mask;    /* cursor mask */
   Point    hotSpot; /* point aligned with mouse */
};
typedef struct Cursor Cursor;
typedef Cursor *CursPtr, **CursHandle;
struct CCrsr {
   short          crsrType;      /* type of cursor */
   PixMapHandle   crsrMap;       /* the cursor's PixMap record */
   Handle         crsrData;      /* cursor's data */
   Handle         crsrXData;     /* expanded cursor data */
   short          crsrXValid;    /* depth of expanded data (0 if none) */
   Handle         crsrXHandle;   /* future use */
   Bits16         crsr1Data;     /* 1-bit cursor */
   Bits16         crsrMask;      /* cursor's mask */
   Point          crsrHotSpot;   /* cursor's hot spot */
   long           crsrXTable;    /* private */
   long           crsrID;        /* ctSeed for expanded cursor */
};
typedef struct CCrsr CCrsr;
typedef CCrsr *CCrsrPtr, **CCrsrHandle;
struct Acur {
   short    n;       /* number of cursors ("frames of film") */
   short    index;   /* reserved */
   short    frame1;  /* 'CURS' resource ID for frame #1 */
   short    fill1;   /* reserved */
   short    frame2;  /* 'CURS' resource ID for frame #2 */
   short    fill2;   /* reserved */
   short    frameN;  /* 'CURS' resource ID for frame #N */
   short    fillN;   /* reserved */
};
typedef struct Acur acur,*acurPtr,**acurHandle;

Functions

Initializing Cursors

pascal void InitCursor       (void);
pascal void InitCursorCtl    (acurHandle newCursors);

Changing Black-and-White Cursors

pascal CursHandle GetCursor  (short cursorID);
pascal void SetCursor        (const Cursor *crsr); 

Changing Color Cursors

/* DisposeCCursor is also spelled as DisposCCursor */
pascal CCrsrHandle GetCCursor
                             (short crsrID);
pascal void SetCCursor       (CCrsrHandle cCrsr);
pascal void DisposeCCursor   (CCrsrHandle cCrsr);
pascal void AllocCursor      (void);

Hiding and Showing Cursors

pascal void HideCursor       (void);
pascal void Hide_Cursor      (void);
pascal void ObscureCursor    (void);
pascal void ShieldCursor     (const Rect *shieldRect, Point offsetPt);
pascal void ShowCursor       (void);
pascal void Show_Cursor      (Cursors cursorKind);

Displaying Animated Cursors

pascal void RotateCursor     (long counter);
pascal void SpinCursor       (short increment);

Assembly-Language Summary

Data Structures

Cursor Data Structure

0	data	32 bytes	cursor image
32	mask	32 bytes	cursor mask
64	hotSpot	long	point aligned with mouse

Color Cursor Data Structure

0	crsrType	word	type of cursor
2	crsrMap	long	the cursor's PixMap record
6	crsrData	long	cursor's data
10	crsrXData	long	expanded cursor data
14	crsrXValid	word	depth of expanded data (0 if none)
16	crsrXHandle	long	handle for future use
20	crsr1Data	16 words	1-bit data
52	crsrMask	16 words	1-bit mask
84	crsrHotSpot	long	hot spot for cursor
88	crsrXTable	long	table ID for expanded data
92	crsrID	long	ID for cursor
96	crsrRec	long	size of cursor save area

Global Variables

arrow

The standard arrow cursor.