Legacy Documentclose button

Important: The information in this document is obsolete and should not be used for new development.

Previous Book Contents Book Index Next

Inside Macintosh: More Macintosh Toolbox /
Chapter 8 - Control Panels / Control Panels Reference
Application-Defined Routines / Control Device Functions


MyCdev

You provide a control device function to implement your control panel. In the message parameter, the Finder passes a value indicating which action your control device function should perform. Here's how you declare a control device function called MyCdev:

FUNCTION MyCdev(message, item, numItems, CPrivateValue: Integer;
                VAR theEvent: EventRecord; 
                cdevStorageValue: LongInt; CPDialog: DialogPtr)
                : LongInt; 
message
A value that identifies the event or action to which your control
device function should respond. See Table 8-3 on page 8-77 for the constants your function can receive in this parameter.
item
The number of the item that the user clicked. In System 7, this is always the actual number of the item in your item list. In System 6, the Control Panel desk accessory appends your item list to its own. Although you begin numbering your item list with 1, the Control Panel adds the number of items in its item list to your item. Therefore, to get the
actual number of the clicked item, and to provide for backward compatibility, your control device function should always subtract numItems from item.
numItems
In System 7, the Finder passes a value of 0 for this parameter. This parameter is provided for backward compatibility with the Control Panel desk accessory. In System 6, this parameter contains the number of items in the item list belonging to the Control Panel desk accessory. To get the actual number of the item that the user clicked, subtract numItems from item.
CPrivateValue
Reserved for use by the Finder or the Control Panel desk accessory.
theEvent
The event record for the event that caused the Finder to send a hitDev, nulDev, activDev, deActivDev, updateDev, or keyEvtDev message to your control device function. See the chapter "Event Manager" in Inside Macintosh: Macintosh Toolbox Essentials for a description of events and event records.
cdevStorageValue
The first time the Finder calls your control device function, this parameter is set to the constant cdevUnset. After the first call, this parameter contains the function result last returned by your control device function. Typically, in response to an initDev message, a control device function allocates a handle to memory and returns this handle as its function result. It does this so that it can store values between calls from the Finder. On all subsequent calls, the Finder passes the handle back to your function as the value of cdevStorageValue, and your function returns this value as its function result until an error condition occurs or the user closes the control panel.
If your function does not create a handle, your function and the Finder pass cdevUnset back and forth, instead of the handle, until an error condition occurs or the user closes the control panel.
CPDialog
The dialog pointer for your control panel's dialog box. The dialog can be a color dialog on systems that support color windows. See the chapter "Dialog Manager" in Inside Macintosh: Macintosh Toolbox Essentials for a description of dialog pointers.
DESCRIPTION
The Finder calls your control device function repeatedly with various messages in response to user actions and events from the time the user opens your control panel until the user closes the control panel or your function reports an error condition from which it cannot recover. Before attempting to handle messages from the Finder, your control device function should determine whether enough memory is available to perform the requested action.

Depending on how you define your control panel's machine resource, the Finder calls your control device function for the first time with a macDev message or an initDev message. Apart from a macDev message, your control device function should ignore
any messages that it receives before an initDev message. Your function should also ignore any messages it receives after a closeDev message, which the Finder sends under normal conditions free of error as a signal that your function should begin its termination process: releasing any allocated memory, handles, pointers, and so on. Between the initDev and the closeDev calls, the Finder calls your control device function to direct it to handle activate, update, keyboard-related, mouse-related, and null events. When the user chooses a command from the Finder's Edit menu, the Finder passes the command to your function as an edit message. Table 8-3 lists the constant names for the values that the Finder passes in the message parameter and provides a description of the action your function should perform.
Table 8-3 Messages from the Finder (Continued)
ConstantValueDescription
initDev0Your control device function should perform any initialization, set default values for controls, and create a handle to any memory that it needs.
hitDev1The user clicked an enabled item, and your control device function should handle the click.
closeDev2The user closed the control panel; your function should terminate after disposing of any handles and pointers it created. (In System 6 and earlier, the user could have also selected another control panel.)
nulDev3A null event occurred. Your control device function should perform idle processing. Do not assume any particular timing for this message.
updateDev4An update event occurred. Your control device function should update any user items and redraw any controls that are not standard dialog items handled by the Dialog Manager.
activDev5Your control panel is becoming active as the result of an activate event. Your control device function should make the default button and any other controls in your control panel active.
deActivDev6Your control panel is becoming inactive as the result of an activate event. Your control device function should make the default button and any other controls in your control panel inactive.
keyEvtDev7A key-down or an auto-key event occurred. Your control device function should process the keyboard event.
macDev8Your control device function should check the hardware and software configuration to determine whether the control panel can run on it. Your function should return a function result of 1 if it can run and 0 if it cannot.
undoDev9The user chose the Undo command from the Finder's Edit menu. Your control device function should handle the command.
cutDev10The user chose the Cut command from the Finder's Edit menu. Your control device function should handle the command.
copyDev11The user chose the Copy command from the Finder's Edit menu. Your control device function should handle the command.
pasteDev12The user chose the Paste command from the Finder's Edit menu. Your control device function should handle the command.
clearDev13The user chose the Clear command from the Finder's Edit menu. Your control device function should handle the command.

In System 7, the Finder processes all Command-key equivalents on behalf of your control panel, except those that it maps to its own Edit menu commands. The Finder converts these Command-key equivalents to edit messages, which it then passes to your control panel for processing. In System 6, the Control Panel passes both commands from the Edit menu and their Command-key equivalents to your control device function for processing. See the sections "Responding to Keyboard Events" on page 8-37 and "Handling Edit Menu Commands" on page 8-46 for more information on how to handle Command-key equivalents.

If your function cannot recover from an error condition, it must return one of three error codes to the Finder after disposing of any memory, handles, and pointers that it created and restoring the system stack to the state it would be in after successful execution. See Table 8-2 on page 8-47 for the error codes that your control device function can return.

SEE ALSO
For information on how to write a control device function, see "Writing a Control Panel Function" beginning on page 8-25. For information on the required and optional resources for your control panel, see "Creating a Control Panel's Resources" beginning on page 8-14.


Previous Book Contents Book Index Next

© Apple Computer, Inc.
6 JUL 1996