Legacy Document

Inside Macintosh: Operating System Utilities /

Chapter 5 - Control Panel Extensions / Control Panel Extensions Reference

Control Panel Extension-Defined Routines / Handling Panel Events

MyPanelItem

A control panel extension must respond to the kPanelItemSelect request code. In general, a control panel sends this request code to your extension whenever the user clicks an item in your panel. A control panel extension typically responds to the kPanelItemSelect request code by calling an extension-defined subroutine (for example, MyPanelItem) to handle the request.

FUNCTION MyPanelItem (globals: Handle; dialog: DialogPtr; 
                      itemOffset: Integer; itemNum: Integer) 
                      : 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 panel's items in the dialog box (of the control panel) referenced through this parameter.

itemOffset

An offset to the panel's first item.

itemNum

The item number of the item selected by the user. This item number is an index into the list of items in the dialog box. To map this value to the item list you passed to the control panel (in the MyPanelGetDITL function), you need to compensate for the offset reported in the itemOffset parameter.

DESCRIPTION

Your MyPanelItem function should handle mouse clicks on specific items in your panel. The owning control panel calls your control panel extension with the kPanelItemSelect whenever your component returns FALSE in response to an event-select request. Your MyPanelItem function is therefore typically invoked each time the user clicks on some item in your panel. Your function should respond appropriately, according to the item that was clicked.

As just described, note that when a click in one of your panel's items occurs, the owning control panel first sends your component an event-select request, giving your component a chance to filter the event, if necessary. In this case, if your component returns FALSE in the handled parameter, then the control panel sends your component the item-select request code; if your component returns TRUE in the handled parameter, the control panel does not send your component the subsequent item-select request code.

RESULT CODES

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

SEE ALSO

For an example of the MyPanelItem function, see Listing 5-5 on page 5-16. For information on responding to events, see the description of the MyPanelEvent function in the next section.