Legacy Document

Important: The information in this document is obsolete and should not be used for new development.

Inside Macintosh: Programmer's Guide to MacApp / Part 1 - MacApp Theory and Architecture: Chapter 8 - Displaying, Manipulating, and Printing Data

Cursor Handling
MacApp's cursor-handling capabilities are provided as part of the application, window, and view classes. Using only MacApp's default behavior, your application can

associate a cursor resource ID with a view and display the specified image when the cursor is over the view
display an arrow cursor if no other cursor image is specified
display a special cursor when the cursor image is over draggable data, switch the cursor when the user starts a drag, and switch back to the previous cursor when the drag is complete
display the watch cursor when the application is busy for an extended period

MacApp handles each of these operations automatically--all your application has to do is supply a cursor resource ID at the appropriate time.

Note
A mouse is a hardware device and a cursor is an image displayed on the screen, but Macintosh users tend to use the terms interchangeably. This chapter will use whichever term seems appropriate to a particular discussion.
The following sections describe MacApp's basic cursor operations. For more information on general cursor operations, see Chapter 21, "Working With the Cursor." For information on working with the cursor for drag-and-drop operations, see Chapter 9, "Drag and Drop," and Chapter 28, "Working With Drag and Drop."

The Cursor Region
Since your application can change the cursor image at any time, MacApp must constantly check which image to display while the mouse is moving. To optimize the checking MacApp must do, your views that handle the cursor compute the region for which the current cursor image is valid. While the cursor remains in this region, MacApp will not change the cursor image.

IMPORTANT
Any method that changes the cursor image or the current cursor region is responsible for setting a new cursor region.
Whenever the application object receives an event indicating that the mouse has moved outside the current cursor region, it invalidates the cursor region. This results in a call to the application object's TrackCursor method.

Tracking the Cursor
When the application object tracks the cursor, it looks for an application window that can handle the cursor. If it doesn't find one, it computes the largest possible default cursor region and sets the cursor to the arrow cursor.
If the application object does find a window that can handle the cursor, it calls the window object's HandleCursor method (a method of the TView class), which does the following:

If the view allows its subviews to handle the cursor, HandleCursor gives each interested subview that contains the mouse a chance to handle the cursor.
If no subview handles the cursor, it gives each enabled behavior a chance to handle the cursor.
If no subview or behavior handles the cursor, it sets the cursor region to the window's extent and calls DoSetCursor to set the cursor for the window.

Setting the Cursor Image for a View
When a user moves the cursor over a view, MacApp calls the view's DoSetCursor method. If no drag operation is involved, MacApp automatically sets the cursor image according to the view's fCursorID field. If fCursorID is set to kNoResource, the arrow cursor is shown.
If drag-and-drop support is included in the application, the DoSetCursor method calls the view method DoSetDragCursor to determine whether a mouse click would initiate a drag. Setting the cursor for a drag operation is described in "Setting the Drag Cursor," beginning on page 257.

Busy Cursor Handling
Your application should display a progress dialog box when it is busy with a long task. For shorter tasks, or when you don't know how long a task will take, you can display a busy cursor instead. The most common busy cursor is the watch cursor, a cursor that looks like a wristwatch. The watch cursor is called "animated" when the hands spin around the watch face.

Default Busy Cursor Behavior
MacApp's UBusyCursor unit implements a mechanism for automatically setting the cursor to an animated watch cursor whenever the application is busy. An application is considered busy if it hasn't called any of the Toolbox routines WaitNextEvent, GetNextEvent, or EventAvail for a given number of ticks, where 60 ticks equals 1 second.
The busy cursor mechanism is implemented by a global object gBusyCursor, of type TBusyCursor. This object is created in InitUBusyCursor, which is called from DoInitUMacApp. The cursor is changed to a watch cursor by a vertical blanking (or VBL) task, a task that is executed during the vertical blanking interrupt. For more information on VBL tasks, see the Technical Introduction to the Macintosh Family, second edition.
MacApp's busy cursor has the following default behavior:

The delay before changing to the busy cursor is 120 ticks, or 2 seconds.
The busy cursor is always animated, at least for the first 231 - 1 (2,147,483,647) seconds (or roughly 68 years).

Modifying Busy Cursor Behavior
You can modify the behavior of the busy cursor object in the following ways:

You can turn off automatic display of the busy cursor.
You can set the delay time before the busy cursor is displayed.
You can tell the busy cursor not to stay animated if your application stops responding. This ensures that the busy cursor won't spin forever if your application never returns from a task.

For specific details on how to modify busy cursor behavior, see "Recipe--Modifying Busy Cursor Behavior," beginning on page 497 in Chapter 21, "Working With the Cursor."