Legacy Document

Inside Macintosh: Operating System Utilities /

Chapter 5 - Control Panel Extensions / Control Panel Extensions Reference

Control Panel Extension-Defined Routines / Handling Panel Events

MyPanelEvent

A control panel extension must respond to the kPanelEventSelect request code. A control panel sends this request code to your extension whenever an event occurs in your panel. A control panel extension typically responds to the kPanelEventSelect request code by calling an extension-defined subroutine (for example, MyPanelEvent) to handle the request.

FUNCTION MyPanelEvent (globals: Handle; dialog: DialogPtr; 
                      itemOffset: Integer; 
                      theEvent: eventRecord; 
                      VAR itemHit: Integer; 
                      VAR handled: Boolean): ComponentResult;

globals

A handle to the control panel extension's global data.

dialog

A pointer to the dialog record of the owning control panel. The owning control panel displays your items in the dialog box (of the control panel) referenced through this parameter.

itemOffset

An offset to the panel's first item.

theEvent

An event record describing the event being reported to your control panel extension.

itemHit

On entry, the item number of an item. This number is valid only for mouse events (on input, do not interpret this parameter for any other type of event). On exit, if the MyPanelEvent function has handled the event, it should return the item number of the associated item in this parameter.

handled

On entry, the value FALSE for mouse events; the value TRUE for all other events. On exit, the MyPanelEvent function should return a Boolean value that indicates whether it has handled the event (TRUE) or has not handled the event (FALSE).

DESCRIPTION

Your MyPanelEvent function is called whenever an event occurs in your panel. The parameter theEvent contains a complete description of the event. A control panel handles events in its own items and also gives your component a chance to handle events in its own panel.

The MyPanelEvent function is intended to operate just like an event filter function specified in calls to the ModalDialog procedure or other Dialog Manager routines. The main difference between MyPanelEvent and other event filter functions is that MyPanelEvent does not return a Boolean value as its function result. Instead, it indicates whether it handled the event in the handled parameter.

If the specified event is a mouse event, you might prefer your extension's MyPanelItem function to handle the event. In that case, you should return FALSE in the handled parameter. Otherwise, you should attempt to handle the event.

If your MyPanelEvent function does handle the event, it should update the itemHit parameter to reflect the affected item and return TRUE in the handled parameter. If you set handled to FALSE, the owning control panel sends your panel an item-select request.

RESULT CODES

Your MyPanelEvent function should return noErr if successful, or an appropriate result code otherwise.

SEE ALSO

For an example MyPanelEvent function, see Listing 5-6 on page 5-18. See the description of MyPanelItem on page 5-25 for information on handling clicks in dialog items. For a description of the fields of the event record, see the chapter "Event Manager" in Inside Macintosh: Macintosh Toolbox Essentials.