Important: The information in this document is obsolete and should not be used for new development.
MyCdev
You provide a control device function to implement your control panel. In themessage
parameter, the Finder passes a value indicating which action your control device function should perform. Here's how you declare a control device function calledMyCdev
:
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 subtractnumItems
fromitem
.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
fromitem
.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
, orkeyEvtDev
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 aninitDev
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 ofcdevStorageValue
, 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 aninitDev
message. Apart from amacDev
message, your control device function should ignore
any messages that it receives before aninitDev
message. Your function should also ignore any messages it receives after acloseDev
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 theinitDev
and thecloseDev
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 themessage
parameter and provides a description of the action your function should perform.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.