Legacy Document

Inside Macintosh: Imaging With QuickDraw /

Chapter 8 - Cursor Utilities / Cursor Utilities Reference

Routines / Initializing Cursors

InitCursorCtl

To load the resources necessary for displaying an animated cursor, use the InitCursorCtl procedure.

PROCEDURE InitCursorCtl (newCursors: UNIV acurHandle);

newCursors

A handle to an Acur record (described on page 8-18) that specifies the cursor resources you want to use in your animation. If you specify NIL in this parameter, InitCursorCtl loads the animated cursor resource (described on page 8-33) with resource ID 0--as well as the cursor resources (described on page 8-31) specified therein--from your application's resource file.

DESCRIPTION

The InitCursorCtl procedure loads the cursor resources for an animated cursor sequence into memory. Your application should call the InitCursorCtl procedure once prior to calling the RotateCursor procedure (described on page 8-30) or the SpinCursor procedure (described on page 8-30).

If your application passes NIL in the newCursors parameter, InitCursorCtl loads the 'acur' resource with resource ID 0, as well as the 'CURS' resources whose resource IDs are specified in the 'acur' resource. If any of the resources cannot be loaded, the cursor does not change when you call RotateCursor or SpinCursor. Otherwise, the RotateCursor procedure and the SpinCursor procedure display in sequence the cursors specified in these resources.

If your application does not pass NIL in the newCursors parameter, it must pass a handle to an Acur record. Your application can use the Resource Manager function GetResource to obtain a handle to an 'acur' resource, which your application should then coerce to a handle of type acurHandle when passing it to InitCursorCtl.

If your application calls the RotateCursor or SpinCursor procedure without calling InitCursorCtl, RotateCursor and SpinCursor automatically call InitCursorCtl. However, since you won't know the state of memory, any memory allocated by the Resource Manager for animating cursors may load into an undesirable location, possibly causing fragmentation. Calling the InitCursorCtl procedure during your initialization process has the advantage of causing the memory allocation when you can control its location. For information on using the InitCursorCtl procedure during your initialization process, see "Initializing the Cursor" on page 8-6.

SPECIAL CONSIDERATION

If you want to use multiple 'acur' resources repeatedly during the execution of your application, be aware that the InitCursorCtl procedure changes each frameN and fillN integer pair within the Acur record in memory to a handle to the corresponding 'CURS' resource, which is also in memory. Thus, if the newCursors parameter is not NIL when your application calls the InitCursorCtl procedure, your application must guarantee that newCursors always points to a fresh copy of an 'acur' resource.

SEE ALSO

Listing 8-1 on page 8-6 illustrates how to initialize an animated cursor by using the InitCursorCtl procedure. Listing 8-3 on page 8-13 shows how to animate the cursor with the RotateCursor procedure, and Listing 8-4 on page 8-13 shows how to animate the cursor with the SpinCursor procedure.