Legacy Document

Inside Macintosh: Macintosh Toolbox Essentials /

Chapter 5 - Control Manager / Control Manager Reference

Control Manager Routines / Handling Mouse Events in Controls

TrackControl

To follow and respond to cursor movements in a control and then to determine the control part in which the mouse-up event occurs, use the TrackControl function.

FUNCTION TrackControl (theControl: ControlHandle; 
                       thePoint: Point; actionProc: ProcPtr)
                       : Integer;

theControl

A handle to the control in which a mouse-down event occurred.

thePoint

A point, specified in coordinates local to the window, where the mouse-down event occurred.

actionProc

The action procedure. Typically, you should set this parameter to NIL
for buttons, checkboxes, radio buttons, and the scroll box of a scroll bar; set this parameter to Pointer(-1) for pop-up menus; and set this parameter to the pointer to an action procedure for scroll arrows and
gray areas of scroll bars, as well as for any other controls that require
you to define additional actions to take while the user holds down the mouse button.

DESCRIPTION

The TrackControl function follows the user's cursor movements in a control and provides visual feedback until the user releases the mouse button. The visual feedback given by TrackControl depends on the control part in which the mouse-down event occurs. When highlighting is appropriate, for example, TrackControl highlights the control part (and removes the highlighting when the user releases the mouse button). When the user holds down the mouse button while the cursor is in an indicator (such as the scroll box of a scroll bar) and moves the mouse, TrackControl responds by dragging a dotted outline of the indicator.

The TrackControl function returns as its function result the control's part code if the user releases the mouse button while the cursor is inside the control part, or 0 if the user releases the mouse button while the cursor is outside the control part. For control parts, the TrackControl function returns the same values (represented by the constants inButton, inCheckBox, inUpButton, inDownButton, inPageUp, inPageDown, and inThumb) returned by the FindControl function, as described on page 5-82.

When TrackControl returns a value other than 0 as its function result, your application should respond as appropriate to a mouse-up event in that control part. When TrackControl returns 0 as its function result, your application should do nothing.

If the user releases the mouse button when the cursor is in an indicator such as a scroll box, TrackControl calls the control's control definition function to reposition the indicator. The control definition function for scroll bars, for example, responds to the user dragging a scroll box by redrawing the scroll box, calculating the control's current setting according to the new relative position of the scroll box, and storing the current setting in the control record. Thus, if the minimum and maximum settings are 0 and 10, and the scroll box is in the middle of the scroll bar, 5 is stored as the current setting. For a scroll bar, your application must then respond by scrolling to the corresponding relative position in the document.

Generally, you use TrackControl after using the FindControl function. In the parameter theControl of TrackControl, pass the control handle returned by the FindControl function, and in the parameter thePoint, supply the same point you passed to FindControl (that is, a point in coordinates local to the window).

While the user holds down the mouse button with the cursor in one of the standard controls, TrackControl performs the following actions, depending on the value you pass in the parameter actionProc. (For other controls, what you pass in this parameter depends on how you define the control.)

• If you pass NIL in the actionProc parameter, TrackControl uses no action procedure and therefore performs no additional actions beyond highlighting the control or dragging the indicator. This is appropriate for buttons, checkboxes, radio buttons, and the scroll box of a scroll bar.
• If you pass a pointer to an action procedure in the actionProc parameter, you must provide the procedure, and it must define some action that your application repeats as long as the user holds down the mouse button. This is appropriate for the scroll arrows and gray areas of a scroll bar.
• If you pass Pointer(-1) in the actionProc parameter, TrackControl looks in the contrlAction field of the control record for a pointer to the control's action procedure. This is appropriate when you are tracking the cursor in a pop-up menu. (You can use the GetControlAction function to determine the value of this field, and you can use the SetControlAction procedure to change this value.) If the contrlAction field of the control record contains a procedure pointer, TrackControl uses the action procedure it points to; if the field of the control record also contains the value Pointer(-1), TrackControl calls the control's control definition function to perform the necessary action; you may wish to do this if you define your own control definition function for a custom control. If the field of the control record contains the value NIL, TrackControl performs no action.

SPECIAL CONSIDERATIONS

When you need to handle events in alert and dialog boxes, Dialog Manager routines automatically call FindControl and TrackControl.

ASSEMBLY-LANGUAGE INFORMATION

The TrackControl function invokes the Window Manager function DragGrayRgn, so you can use the global variables DragHook and DragPattern.

SEE ALSO

See "Defining Your Own Action Procedures" beginning on page 5-109 for information about an action procedure to specify in the actionProc parameter. See "Defining Your Own Control Definition Function" beginning on page 5-102 for information about creating a control definition function.

Listing 5-11 on page 5-32, Listing 5-12 on page 5-33, Listing 5-13 on page 5-35,
and Listing 5-18 on page 5-48 illustrate the use of TrackControl for responding to mouse-down events in, respectively, a button, a pop-up menu, a checkbox, and a
scroll bar.

See the chapter "Dialog Manager" in this book for more information about including controls in alert boxes and dialog boxes.