Legacy Document

Inside Macintosh: Operating System Utilities /

Chapter 5 - Control Panel Extensions / Control Panel Extensions Reference

Control Panel Extension-Defined Routines / Managing Panel Components

MyPanelInstall

A control panel extension must respond to the kPanelInstallSelect request code. A control panel sends this request code to an extension immediately after sending the kPanelGetDitlSelect request code (which initially adds your panels's items to the control panel) and just before displaying the panel to the user. A control panel extension typically responds to the kPanelInstallSelect request code by calling an extension-defined subroutine (for example, MyPanelInstall) to handle the request.

FUNCTION MyPanelInstall (globals: Handle; dialog: DialogPtr; 
                         itemOffset: 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 referenced through this parameter.

itemOffset

An offset to the panel's first item.

DESCRIPTION

Your MyPanelInstall function should perform any processing that must occur after the panel is created but before it is displayed to the user. For example, your MyPanelInstall function can set or restore default values of various items in the panel. You can also use this opportunity to create user items (such as lists) in the panel.

The itemOffset parameter specifies the offset from 1 to the first item in your panel. The items installed by your control panel extension are contained in a larger dialog box containing other items; as a result, if you call the GetDialogItem procedure to obtain a handle to an item, you need to increment the itemNo parameter passed to GetDialogItem by the value of itemOffset.

In most cases, you'll need to save the value passed in the itemOffset parameter in your extension's global storage for later use. For example, you usually need this value to determine which panel item the user selected when your extension responds to the kPanelItemSelect request code.

The value passed to your MyPanelInstall function in the itemOffset parameter may be different each time MyPanelInstall is called. You should not assume it is always the same value.

RESULT CODES

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

SEE ALSO

For an example of the MyPanelInstall function, see Listing 5-4 on page 5-15.