DISCUSSION

You should call the FindControlUnderMouse function instead of FindControl to determine whether a mouse-down event occurred in a control, particularly if an embedding hierarchy is present. FindControlUnderMouse will return a handle to the control even if no part was hit and can determine whether a mouse-down event has occurred even if the control is deactivated, while FindControl does not.

When a mouse-down event occurs, your application should call FindControlUnderMouse 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.

VERSION NOTES

Available with Appearance Manager 1.0 and later.

SEE ALSO

Embedding Controls .

FindControl

Obtains the location of a mouse-down event in a control.

When the Appearance Manager is available, you should call FindControlUnderMouse to determine the location of a mouse-down event in a control. FindControlUnderMouse will return a handle to the control even if no part was hit and can determine whether a mouse-down event has occurred even if the control is deactivated, while FindControl does not.

VERSION NOTES

Not recommended with Appearance Manager 1.0 and later.

HandleControlKey

Sends a keyboard event to a control with keyboard focus.

pascal SInt16 HandleControlKey (
                     ControlHandle inControl,
                     SInt16 inKeyCode,
                     SInt16 inCharCode,
                     SInt16 inModifiers);

inControl

A handle to the control that currently has keyboard focus.

inKeyCode

The virtual key code, derived from the event structure. This value represents the key pressed or released by the user. It is always the same for a specific physical key on a particular keyboard regardless of which modifier keys were also pressed.

inCharCode

A character, derived from the event structure. The value that is generated depends on the virtual key code, the state of the modifier keys, and the current 'KCHR' resource.

inModifiers

Information from the modifiers field of the event structure specifying the state of the modifier keys and the mouse button at the time the event was posted.

function result

Returns the part code that was hit during the keyboard event; see Control Part Code Constants .

DISCUSSION

If you have determined that a keyboard event has occurred in a given window, before calling the HandleControlKey function, call GetKeyboardFocus to get the handle to the control that currently has keyboard focus. The HandleControlKey function passes the values specified in its inKeyCode , inCharCode , and inModifiers parameters to control definition functions that set the kControlSupportsFocus feature bit.

VERSION NOTES

Available with Appearance Manager 1.0 and later.

IdleControls

Performs idle event processing.

pascal void IdleControls (WindowPtr inWindow);

inWindow

A pointer to a window containing controls that support idle events.

DISCUSSION

Your application should call the IdleControls function to give idle time to any controls that want the kControlMsgIdle message. IdleControls calls the control with an idle event so the control can do idle-time processing. You should call IdleControls at least once in your event loop. see Performing Idle Processing for more details on how a control definition function should handle idle processing.

VERSION NOTES

Available with Appearance Manager 1.0 and later.

HandleControlClick

Responds to cursor movements in a control while the mouse button is down and returns the location of the next mouse-up event.

pascal ControlPartCode HandleControlClick (
                     ControlHandle inControl,
                     Point inWhere,
                     SInt16 inModifiers,
                     ControlActionUPP inAction);

inControl

A handle to the control in which the mouse-down event occurred. Pass the control handle returned by FindControl or FindControlUnderMouse .

inWhere

A point, specified in local coordinates, where the mouse-down event occurred. Supply the same point you passed to FindControl or FindControlUnderMouse .

inModifiers

Information from the modifiers field of the event structure specifying the state of the modifier keys and the mouse button at the time the event was posted.

inAction

A universal procedure pointer to an action function defining what action your application takes while the user holds down the mouse button. The value of the inAction parameter can be a valid procPtr , nil , or -1. A value of -1 indicates that the control should either perform auto tracking, or if it is incapable of doing so, do nothing (like nil ). For custom controls, what you pass in this parameter depends on how you define the control. If the part index is greater than 128, the pointer must be of type DragGrayRegionUPP unless the control supports live feedback, in which case it should be a ControlActionUPP .

function result

Returns a value of type ControlPartCode identifying the control's part; see Control Part Code Constants .

DISCUSSION

Call the HandleControlClick function after a call to FindControl or FindControlUnderMouse . The HandleControlClick function should be called instead of TrackControl to follow the user's cursor movements in a control and provide visual feedback until the user releases the mouse button. Unlike TrackControl , HandleControlClick allows modifier keys to be passed in so that the control may use these if the control (such as a list box or editable text field) is set up to handle its own tracking.

The visual feedback given by HandleControlClick depends on the control part in which the mouse-down event occurs. When highlighting is appropriate, for example, HandleControlClick 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, HandleControlClick responds by dragging a dotted outline or a ghost image of the indicator. If the user releases the mouse button when the cursor is in an indicator such as the scroll box, HandleControlClick calls the control definition function to reposition the indicator.

While the user holds down the mouse button with the cursor in one of the standard controls, HandleControlClick performs the following actions, depending on the value you pass in the parameter inAction .

• If you pass nil in the inAction parameter, HandleControlClick uses no action function and therefore performs no additional actions beyond highlighting the control or dragging the indicator. This is appropriate for push buttons, checkboxes, radio buttons, and the scroll box of a scroll bar.
• If you pass a pointer to an action function in the inAction parameter, 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 (ControlActionUPP)-1L in the inAction parameter, HandleControlClick looks in the contrlAction field of the control structure for a pointer to the control's action function. This is appropriate when you are tracking the cursor in a pop-up menu. You can call GetControlAction to determine the value of this field, and you can call SetControlAction to change this value. If the contrlAction field of the control structure contains a function pointer, HandleControlClick uses the action function it points to; if the field of the control structure also contains the value (ControlActionUPP)-1L , HandleControlClick calls the 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 structure contains the value nil , HandleControlClick performs no action.

Note

For 'CDEF' resources that implement custom dragging, you usually call HandleControlClick , which returns 0 regardless of the user's changes of the control setting. To avoid this, you should use another method to determine whether the user has changed the control setting, for instance, comparing the control's value before and after your call to HandleControlClick .

---

\xA9 1998 Apple Computer, Inc. – (Last Updated 19 Nov 98)