Legacy Document

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)

Constant	Value	Description
initDev	0	Your control device function should perform any initialization, set default values for controls, and create a handle to any memory that it needs.
hitDev	1	The user clicked an enabled item, and your control device function should handle the click.
closeDev	2	The 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.)
nulDev	3	A null event occurred. Your control device function should perform idle processing. Do not assume any particular timing for this message.
updateDev	4	An 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.
activDev	5	Your 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.
deActivDev	6	Your 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.
keyEvtDev	7	A key-down or an auto-key event occurred. Your control device function should process the keyboard event.
macDev	8	Your 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.
undoDev	9	The user chose the Undo command from the Finder's Edit menu. Your control device function should handle the command.
cutDev	10	The user chose the Cut command from the Finder's Edit menu. Your control device function should handle the command.
copyDev	11	The user chose the Copy command from the Finder's Edit menu. Your control device function should handle the command.
pasteDev	12	The user chose the Paste command from the Finder's Edit menu. Your control device function should handle the command.
clearDev	13	The 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.