Legacy Document

Inside Macintosh: Macintosh Toolbox Essentials /

Chapter 5 - Control Manager / Control Manager Reference

Control Manager Routines / Handling Mouse Events in Controls

FindControl

To determine whether a mouse-down event has occurred in a control and, if so, in which part of that control, use the FindControl function.

FUNCTION FindControl (thePoint: Point; theWindow: WindowPtr;
                      VAR theControl: ControlHandle): Integer;

thePoint

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

theWindow

A pointer to the window in which the mouse-down event occurred.

theControl

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

DESCRIPTION

When the user presses the mouse button while the cursor is in a visible, active control, FindControl returns as its function result a part code identifying the control's part; the function also returns a handle to the control in the parameter theControl. The part codes that FindControl returns, and the constants you can use to represent them, are listed here:

CONST inButton       = 10;    {button}
      inCheckBox     = 11;    {checkbox or radio button}
      inUpButton     = 20;    {up arrow for a vertical scroll }
                              { bar, left arrow for a horizontal }
                              { scroll bar}
      inDownButton   = 21;    {down arrow for a vertical scroll }
                              { bar, right arrow for a }
                              { horizontal scroll bar}
      inPageUp       = 22;    {gray area above scroll box for a }
                              { vertical scroll bar, gray area }
                              { to left of scroll box for a }
                              { horizontal scroll bar}
      inPageDown     = 23;    {gray area below scroll box for a }
                              { vertical scroll bar, gray area }
                              { to right of scroll box for a }
                              { horizontal scroll bar}
      inThumb        = 129;   {scroll box}

The pop-up control definition function does not define part codes for pop-up menus. Instead, your application should store the handles for your pop-up menus when you create them. Your application should then test the handles you store against the handles returned by FindControl before responding to users' choices in pop-up menus.

If the mouse-down event occurs in an invisible or inactive control, or if it occurs outside a control, FindControl sets theControl to NIL and returns 0 as its function result.

When a mouse-down event occurs, your application should call FindControl after using the Window Manager function FindWindow to ascertain that a mouse-down event has occurred in the content region of a window containing controls.

Before calling FindControl, use the GlobalToLocal procedure to convert the point stored in the where field (which describes the location of the mouse-down event) of the event record to coordinates local to the window. Then, when using FindControl, pass this point in the parameter thePoint.

In the parameter theWindow, pass the window pointer returned by the FindWindow function.

After using FindControl to determine that a mouse-down event has occurred in
a control, you generally use the TrackControl function, which automatically
follows the movements of the cursor and responds as appropriate until the user releases the mouse button.

SPECIAL CONSIDERATIONS

The Dialog Manager automatically calls FindControl and TrackControl for mouse-down events inside controls of alert boxes and dialog boxes.

The FindControl function also returns NIL in the parameter theControl and 0 as
its function result if the window is invisible or if it doesn't contain the given point. (However, FindWindow won't return a window pointer to an invisible window or to one that doesn't contain the point where the mouse-down event occurred. As long as you call FindWindow before FindControl, this situation won't arise.)

SEE ALSO

Listing 5-10 on page 5-30 illustrates the use of FindControl for detecting mouse-down events in a pop-up menu and a button; Listing 5-18 on page 5-48 illustrates its use for detecting mouse-down events in scroll bars.

The FindWindow function is described in the chapter "Window Manager" in this book. The GlobalToLocal procedure is described in Inside Macintosh: Imaging.

The event record is described in the chapter "Event Manager" in this book. See the chapter "Dialog Manager" in this book for more information about including controls in alert boxes and dialog boxes.