Legacy Document

Inside Macintosh: Operating System Utilities /

Chapter 5 - Control Panel Extensions / Control Panel Extensions Reference

Control Panel Extension-Defined Routines / Managing Panel Settings

MyPanelGetSettings

A control panel extension must respond to the kPanelGetSettingsSelect request code. A control panel sends this request code to your extension to get the panel's current settings. A control panel extension typically responds to the kPanelGetSettingsSelect request code by calling an extension-defined subroutine (for example, MyPanelGetSettings) to handle the request.

FUNCTION MyPanelGetSettings (globals: Handle; VAR ud: UserData; 
                             flags: LongInt): ComponentResult;

globals

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

ud

A handle to the control panel's configuration data.

flags

Reserved. This parameter is always 0.

DESCRIPTION

Your MyPanelGetSettings function should return, through the ud parameter, a copy of the panel's current settings. This copy is maintained privately by the control panel. The control panel may subsequently restore your panel's settings by passing those settings to your MyPanelSetSettings function.

Your control panel extension is responsible for allocating storage for the configuration data to which ud is a handle. You might do that when the Component Manager passes your extension the kComponentOpenSelect parameter. Your extension should not dispose of that storage until it closes (that is, when the Component Manager passes it the kComponentCloseSelect parameter).

You can arrange the panel configuration data in any way you like. The data needs to contain whatever information is necessary for your MyPanelSetSetting function to set all relevant panel items to specified values. For example, the standard Apple sound panels save information such as the component type of the default sound output device, the current volumes levels, the current alert beep, and so forth. You might want to begin the configuration data with a version number so that you can easily change the format of the rest of the data, if necessary.

The information you return to the control panel may get stored as part of the owner's configuration information and might therefore persist across system restarts. As a result, you should not store values that might change without the control panel's knowledge (such as component ID numbers, file reference numbers, and similar volatile information).

RESULT CODES

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