Legacy Document

Inside Macintosh: Operating System Utilities /

Chapter 5 - Control Panel Extensions / Control Panel Extensions Reference

Control Panel Extension-Defined Routines / Managing Panel Components

MyPanelGetDITL

A control panel extension must respond to the kPanelGetDitlSelect request code. A control panel sends this request code to an extension to obtain a list of the panel's items. A control panel extension typically responds to the kPanelGetDitlSelect request code by calling an extension-defined subroutine (for example, MyPanelGetDITL) to handle the request.

FUNCTION MyPanelGetDITL (globals: Handle; VAR ditl: Handle)
                        : ComponentResult;

globals

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

ditl

On entry, a handle to a block of memory in your application heap. On exit, a handle to an item list.

DESCRIPTION

Your MyPanelGetDITL function should return, through the ditl parameter, an item list of the items supported by your extension. The control panel then places those items into the control panel and, after installing the panel, displays the panel to the user. When the control panel creates the panel, it places the items at the locations specified in the item list.

On entry to your MyPanelGetDITL function, the ditl parameter contains a handle to a block of memory in your application heap. You should resize the handle as necessary to hold the item list you return to the control panel. (If you use a Resource Manager routine such as Get1Resource, the Resource Manager automatically resizes the handle for you.)

In general, the owning control panel disposes of the handle you pass it once it's finished constructing the panel. As a result, you must make sure that the handle you pass to the control panel is not a resource handle. If you obtain your item list by reading it into memory from a resource, you should call the Resource Manager's DetachResource procedure to convert that resource handle into one that is suitable for use with the MyPanelGetDITL function.

The componentFlags field of the component description record for a control panel extension contains a bit flag, channelFlagDontOpenResFile, that indicates whether the control panel should open your extension's resource file before calling your extension.

Set the channelFlagDontOpenResFile component flag to 0 if you want the control panel to open your extension's resource file before calling your extension. Set the channelFlagDontOpenResFile component flag to 1 to specify that the control panel should not open your extension's resource file before calling your extension.

RESULT CODES

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

SEE ALSO

For an example of the MyPanelGetDITL function, see Listing 5-3 on page 5-14.