Inside Macintosh: Programmer's Guide to MacApp / Part 2 - Working With MacApp

Chapter 21 - Working With the Cursor

Overview

MacApp provides support to help your application

• change the cursor image for a view or change the image whenever the cursor is over an object in your view
• show an animated watch cursor during completion of a long task
• show the grabber hand or arrow cursor when a mouse-down action is initiating a drag operation, or show a drag cursor specified by your application

Whenever the user moves the mouse, MacApp determines whether the cursor image is over the content area of an application window. If it is, the window object and the views in the window's content area are given the opportunity to track the cursor and to change the cursor image.

Figure 21-1 shows some commonly used cursor images. The I-beam cursor is typically used as a text insertion point, the crosshairs cursor for drawing, the plus sign for selecting or dragging, the wristwatch to show that the application is busy, the grabber hand for dragging, and the arrow for clicking, selecting, or dragging.

Figure 21-1 Commonly used cursor images

MacApp's Cursor-Handling Support

Some important MacApp classes, methods, and fields for working with the cursor are show in Figure 21-2.

Figure 21-2 Classes, methods, and fields for working with the cursor

Cursor handling starts with the application object, which uses the fCursorRegion field to specify a region for which the current cursor image is valid. When the application receives a mouse-moved event that occurred outside the current cursor region, it invalidates the cursor region. The application's MainEventLoop method sets in motion a series of actions that cause the cursor region to be checked regularly and recomputed when necessary.

An application, window, view, or behavior object can handle the cursor by setting the cursor image and computing a region for which that image is valid. If no other object handles the cursor, the application object sets the cursor to the arrow cursor.

Application Fields and Methods

These fields and methods of TApplication are used in cursor handling:

fAlwaysTrackCursor

When the fAlwaysTrackCursor field has the value TRUE, MacApp ignores the current cursor region and always tracks the cursor; otherwise, it only tracks the cursor when the cursor moves outside the current cursor region. The default value is FALSE.

fCursorRegion

The fCursorRegion field specifies the area in which the current cursor image is valid.

DoSetCursor

The DoSetCursor method calls GetDefaultCursorRegion, then calls the Toolbox routine SetCursor to set the cursor image to the arrow cursor.

GetDefaultCursorRegion

The GetDefaultCursorRegion method computes the cursor region for the case when no window has handled the cursor. It starts with the desktop region, then subtracts the cursor region of any window that handles the cursor.

HandleCursor

The HandleCursor method looks for a window that contains the mouse and can handle the cursor. If it finds one, it calls the window object's HandleCursor method, then adjusts the cursor region.

TrackCursor

The TrackCursor method calls HandleCursor to give the application's windows and views a chance to handle the cursor. If none does, it calls DoSetCursor.

View Fields and Methods

These fields and methods of TView are used in cursor handling:

fCursorID

The fCursorID field stores a resource ID number for a cursor resource. The default value is kNoResource (indicating the arrow cursor should be displayed).

fHandlesCursor

When the fHandlesCursor field has the value TRUE, the view can handle the cursor; otherwise, it can't. The default value is TRUE.

fHandlesFirstClicks

When the fHandlesFirstClicks field has the value TRUE, the view responds to a first click in the view; otherwise, it doesn't. The default value is TRUE. (See also fDoFirstClick in "Window Fields and Methods" on page 488. If, for example, you want a user to be able start drawing in a window that isn't the frontmost window by clicking in that window and dragging, you set fDoFirstClick to TRUE for the window and set fHandlesFirstClicks to TRUE for the view that handles the drawing.)

fLetsSubViewsHandleCursor

When the fLetsSubViewsHandleCursor field has the value TRUE, the view lets its subviews handle the cursor; otherwise, it doesn't. The default value is TRUE.

DoMakeDragCursorRegion

The DoMakeDragCursorRegion method creates and returns a region, in local coordinates, that can be used to test whether the mouse is in a location that would initiate a drag operation (and over which the cursor image should be set to a drag cursor).

DoSetCursor

The DoSetCursor method first calls DoSetDragCursor. If DoSetDragCursor doesn't set the cursor, then DoSetCursor uses fCursorID to retrieve a cursor resource. (If fCursorID is set to kNoResource, it uses the arrow cursor.) DoSetCursor calls the Toolbox routine SetCursor to set the cursor image.

DoSetDragCursor

The DoSetDragCursor method determines whether a mouse click would initiate a drag operation. If so, it sets the cursor to the open-hand cursor; if not, it does nothing. (See "Setting the Drag Cursor" on page 257.)

GetDefaultCursorRegion

The GetDefaultCursorRegion method computes the largest possible cursor region. It starts with the view's extent, then subtracts the region of any subview that handles the cursor.

HandleCursor

If the fLetsSubViewsHandleCursor field has the value TRUE, HandleCursor looks for a subview that contains the mouse and handles the cursor. If no subview handles the cursor, it lets behaviors have a chance. If no subview or behavior handles the cursor, it calls DoSetCursor.

HandleDragCursor

If a subview contains the mouse, allows dragging, and has subviews of its own, the HandleDragCursor method calls the subview's HandleDragCursor method. If no such subview handles the drag cursor, but the current view does have at least one subview, HandleDragCursor computes a cursor region that contains the extent of all subviews that allow dragging. Finally, HandleDragCursor calls DoSetDragCursor. If DoSetDragCursor doesn't return a cursor region, HandleDragCursor sets the cursor region to the one it computed and sets the cursor to the arrow cursor.

WillDrag

The WillDrag method is passed the cursor region computed by DoMakeDragCursorRegion. It determines whether the view contains draggable data and whether the cursor is currently in a location that would initiate a drag.

Window Fields and Methods

These fields and methods of TWindow are used in cursor handling:

fDoFirstClick

When the fDoFirstClick field has the value TRUE, a mouse-down event in this window activates the window and is passed on to the content region; otherwise, a mouse-down event only activates the window. The default value is FALSE. (See also "Floating Windows," beginning on page 448.)

fIsActive

When the fIsActive field has the value TRUE, this window is active; otherwise, it is not active.

HandlesCursor

The HandlesCursor method returns TRUE if fHandlesCursor is TRUE and the window is active, or if fDoFirstClick is TRUE.

Setting the Cursor Image for a View

You can associate a cursor image with each of your views by specifying a cursor ID in your view resource and setting the fHandlesCursor field to TRUE. 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.

To change the view's cursor image as the mouse moves within a view, you override the DoSetCursor method, as described in "Recipe--Setting the Cursor Image Over a View" on page 491.

For information on setting the cursor for a drag operation, see Chapter 9, "Drag and Drop," and Chapter 28, "Working With Drag and Drop."

Color Cursors

MacApp's default cursor handling for view and window objects is not set up to handle color cursor resources. Unless you modify MacApp's behavior, the ID specified in the fCursorID field must refer to a standard cursor of type 'CURS'. To work with a color cursor (resource type 'crsr'), you use the Toolbox routine GetCCursor to get the cursor, and the routine SetCCursor to set it. For more information, see "Recipe--Displaying a Color Cursor" on page 495.