Apple II File Type Notes _____________________________________________________________________________ Developer Technical Support File Type: $C7 (199) Auxiliary Type: All Full Name: Control Panel New Desk Accessory Device (CDev) Short Name: Control Panel Revised by: Dave "Flag Bits" Lyons July 1991 Written by: Matt Deatherage & Darryl Lovato September 1989 Files of this type contain Control Panels (CDevs) for the Apple IIgs Control Panel New Desk Accessory. Changes since March 1991: Added information about opening additional resource files, hits on list control scroll bars, and hard-coding window coordinates, and Control Panel file creation dates. _____________________________________________________________________________ Files of type $C7 contain Control Panel Documents, which are a type of miniature "device," which led to their four-letter file type (cdev) on the Macintosh. The same abbreviation is used for modules that work with the Apple IIgs Control Panel New Desk Accessory (NDA). The Control Panel NDA is available with Apple IIgs System Software 5.0 and later. The Control Panel acts as a shell around modules that provide the user with additional control over aspects of the system. Auxiliary Type The auxiliary type of CDevs is defined bit by bit. Currently, only bit 15 is defined--it's the "inactive" bit. As with desk accessories, FSTs, and setup files, the CDev is not loaded or used if this bit is set. All other bits are reserved and must be set to zero. How the Control Panel Works The Control Panel NDA lets the user choose CDevs, and it communicates with open CDevs using a small collection of messages. Most events the Control Panel NDA receives from the system are handled by calling TaskMasterDA. At certain times, the Control Panel sends messages to CDevs. The Control Panel takes care of nearly everything necessary, including tracking controls. CDev windows are usually just windows full of extended controls; the CDev receives a HitCDEV message every time the user adjusts the value of one of the controls. Every control in a CDev must be an extended control. Older, non-extended controls are not allowed; all controls must be created with NewControl2. When one of these controls is "hit," the Control Panel calls the CDev with the HitCDEV message, the control handle, and the control ID. This allows the CDev to respond to user actions. User interface items beyond extended controls (for example, modal windows) must be handled entirely by the CDev (that is, the Control Panel NDA is not involved). Note: Setting the fInWindowOnly bit of Pop-up menu controls is not recommended. The Control Panel Window In version 1.x of the Control Panel NDA there is a single window, and exactly one CDev is always active in a portion of that window. To allow Apple maximum flexibility, CDevs should not assume this will always be true. Many CDev messages include "the Control Panel's window pointer" as one of the parameters. This is guaranteed to be the window containing the CDev's controls, but little else is guaranteed. For example, do not draw outside the area containing your CDev's controls; do not compute other window sizes from the size of this window; and do not assume that the Control Panel will offset your controls' coordinates by the same amount version 1.x does. Do not hard-code any window coordinates. The Control Panel shifts all your controls by some amount horizontally and vertically, but this amount will not stay the same between different versions of the Control Panel (and it could even become zero). If you draw things besides controls in the window, compute the coordinates relative to a control on the fly. Resource Fork The Control Panel opens your CDev's resource fork differently depending on whether the machine was booted from an AppleShare file server or from a local volume. When the machine was booted from AppleShare, your resource fork is opened with read-only access so that more than one user can have your CDev open at once. When the machine was booted locally, your resource fork is opened with "as allowed" access (this means you will have read/write access if the CDev file is unlocked and was not already opened read-only by some other part of the system). When your CDev receives the BootCDEV message at boot time, its resource fork is always open read-only. File Format A CDev is defined by three resources (additional resources may be present). The data fork of a CDev is reserved and must remain empty. The three required resources are the CDev code resource (type rCDEVCode=$8018, ID=$00000001), the CDev flags resource (type rCDEVFlags=$8019, ID $00000001) and the CDev's icon (type rIcon=$8001, ID=$00000001). It is a good idea to make sure each released version of your CDev file has a different creation date, since the system caches certain information about your CDev; the system can use the creation date to notice that a new version of your CDev is present. You may also want to delete the *:System:CDevs:CDev.Data file, if it exists, as part of your CDev installation process. The Icon Resource Each CDev's icon is a standard icon resource. The CDev uses this icon when displayed in the Control Panel. It is also displayed at boot time if the CDev has any initialization code (described later). Note: If the icon is to be displayed during boot time, it must be exactly 28 pixels wide. The CDEV Code Resource The CDev's code resource contains the code to do the CDev's work. A code resource has the same format as an OMF load file; the code resource converter (which is part of the system) is responsible for loading code resources. Eventually, InitialLoad2 loads the code from memory. This process gives the CDev code resource a maximum size of 64K. When the CDev code gets control, the Control Panel will have formatted the input stack as follows: |____________| Previous contents | | |- Space -| Long -- Space for result |____________| | | |- message -| Word -- Action for CDev to take |____________| | | |- data1 -| Long -- Data passed to CDev |____________| | | |- data2 -| Long -- Data passed to CDev |____________| | | |- RTLaddr -| 3 bytes -- return address |____________| | | <-- SP The CDev must remove the input parameters from the stack and perform an RTL, so the calling routine may then pull the four-byte result parameter off the stack. Just before the CDev code RTLs, the stack must be formatted as follows: |____________| Previous contents | | |- Result -| Long -- Result from CDev |____________| | | |- RTLaddr -| 3 bytes -- return address |____________| | | <-- SP This function, like nearly all toolbox functions, is a "Pascal" function, and may be declared in Pascal as follows: function MyCDEV(message: Integer; data1, data2: Longint): LongInt; It may be declared in C as follows: pascal Long MyCDEV(message, data1, data2) int message; long data1, data2; Data1 and Data2 depend on the value of message; message is the parameter that tells the CDev code what needs to be done. Higher-level language CDevs can easily be arranged as a giant switch (or case) statement. There are currently eleven defined CDev messages. Where parameters are not listed, they are undefined. Message 1: MachineCDEV The Control Panel always compares the Apple IIgs ROM version against the minimum ROM version you put in the CDev Flags resource. If the machine's ROM version is too low, the CDev does not appear. The MachineCDEV message is currently not used, but future versions of the Control Panel may call MachineCDEV, if the wantMachine bit is set in the CDev Flags resource, to let the CDev do additional checks to see if it makes sense for the CDev to be visible or not. The parameters are undefined; the CDev returns a non-zero result if it should be displayed. Message 2: BootCDEV If the wantBoot flag is set in the CDev Flags resource, this routine is called during the IIgs boot sequence. The parameters are undefined. BootCDEV is called only during a real boot--it doesn't get control on a switch back to GS/OS from ProDOS 8. The Control Panel draws the icon (from the icon resource) on the boot screen. The icon must be exactly 28 pixels wide if it is drawn at boot time. At best, the machine state during this call can be termed bad. QuickDraw II is not even available; this is called from a setup file belonging to the Control Panel. Be sure to save and restore any system resources you use, including the data bank register and the direct page register. Message 3: Reserved This message is reserved for future use as a shutdown message. Message 4: InitCDEV If the wantInit flag is set in the CDev Flags resource, this routine is called with data1 equal to the Control Panel's window pointer. When InitCDEV is called, CreateCDEV (message 7) has already been called. Controls should have been created in CreateCDEV, and this routine is an ideal place to initialize the controls before they are displayed. Message 5: CloseCDEV This routine is called if the wantClose bit is set in the CDev Flags resource. If so, CloseCDEV is called when the Control Panel is closing when your CDev is the currently selected one or when another CDev is selected. This is a good place to dispose of any memory you allocated or to save settings that need to be saved. The disposal of the CDev's controls is handled by the Control Panel. The Control Panel's window pointer is in data1. Message 6: EventsCDEV If the wantEvents bit is set in the CDev Flags resource, the Control Panel calls this routine with data1 as a pointer to the event record (this is an Event Manager event record, not a TaskMaster-style task record). The Control Panel's window pointer is in data2. The Control Panel, like all NDAs, is passed events, which the Control Panel then handles by using the TaskMasterDA call. This routine is called before TaskMasterDA is called, so the CDev can change the event record before the Control Panel handles it. Message 7: CreateCDEV This routine is only called if the wantCreate bit is set in the CDev Flags resource. When called, the Control Panel's window pointer is in data1. The CDev must create any controls it has during this call. The CDev's resource fork is open during this call, so Resource Manager calls may be made (and controls may be created from resources in the CDev file). All control rectangles are relative to the upper-left corner of the part of the Control Panel window a CDev owns while it's selected. The Control Panel handles setting the offsets of the controls to the proper place in the window. Initialization of the controls must be done in the InitCDEV call. If the wantCreate bit is not set, your CDev must contain an rControlList (type=$8003) resource with ID $00000001. The Control Panel automatically creates your controls from the resource. Message 8: AboutCDEV If the wantAbout bit is set in the CDev Flags resource, the Control Panel calls this routine when the user selects "Help" while your CDev is selected. The window pointer to the help window is in data1. The Control Panel takes care of the icon, author, version string and the "OK" button. The easiest way to handle help is simply to create a static text control with the help text in it. If the wantAbout bit is not set, your CDev must have an rControlList resource with ID $00000002. When the user selects "Help" while your CDev is selected, the Control Panel uses this resource to create your additional About controls. Message 9: RectCDEV Normally, the Control Panel uses the rectangle in the CDev Flags resource for the CDev's display rectangle. However, if the wantRect bit is set in the CDev Flags resource, this routine is called before the CDev is displayed with data1 containing a pointer to the display rectangle. The rectangle may be modified by this routine. This gives CDevs the chance to use different sized rectangles for different occasions. For example, on ROM 03, the serial port CDevs show fewer parameters when the port is set to AppleTalk (since fewer parameters are changeable). In that instance, the RectCDEV routine changes the rectangle to be smaller. Message 10: HitCDEV If the CDev wants to know when a control has been hit, it can set the wantHit bit in the CDev Flags resource. When called, the handle to the control in question is in data1 and that control's ID is in data2. The CDev may then take action based upon the control selection. If you need the window pointer, you can get it from the ctlOwner field of the control record handle in data1. Note: If your CDev contains any extended List controls, the toolbox automatically creates a scroll bar control for each list. These scroll bars are standard (not extended) controls; this is the exception to the rule that all CDev controls must be extended. When the user tracks the scroll bar, the HitCDEV data1 parameter is a valid control handle, but data2 is an unpredictable large value (because no control ID is available for a non-extended control). Message 11: RunCDEV This routine is called if the wantRun bit in the CDev flags resource is set. It enables CDevs to receive a call as often as the Control Panel NDA receives run events from SystemTask (currently once per second). The CDEV Flags resource The CDEV Flags resource tells the Control Panel NDA which messages the CDev code accepts. It also tells the Control Panel certain things about the operating environment required for the CDev. flags (+000) Word The flags word tells the Control Panel which messages (defined in the discussion of the CDev Code resource) the CDev wants: Bits 15 - 11: Reserved, must be zero. Bit 10: wantRun CDev wants run events. Bit 9: wantHit CDev wants control hits. Bit 8: wantRect CDev wants rectangle messages. Bit 7: wantAbout CDev wants "about" messages. Bit 6: wantCreate CDev wants create messages. Bit 5: wantEvents CDev wants event records. Bit 4: wantClose CDev wants close messages. Bit 3: wantInit CDev wants initialization message. Bit 2: wantShutDown Reserved, must be zero. Bit 1: wantBoot CDev wants boot messages. Bit 0: wantMachine Reserved, must be zero. enabled (+002) Byte If this value is zero, the CDev is never activated. version (+003) Byte An integer version number assigned by the author. machine (+004) Byte This byte contains a minimum ROM version required for the CDev. For most CDevs this is 1, but some (requiring, for example, hardware text page two shadowing) want 3 in this byte. reserved (+005) Byte Reserved, must be zero. data rectangle (+006) 4 Words QuickDraw II rectangle within which the CDev is displayed. The top left of this rectangle must be (0,0). name (+014) 16 Bytes A string (Pascal) giving the name of the CDev. Names longer than 15 bytes are not allowed. Note that this field requires 16 bytes regardless of the string length. author (+030) 33 Bytes A string (Pascal) giving the name of the CDev's author. Names longer than 32 bytes are not allowed. Note that this field requires 33 bytes regardless of the string length. version (+063) 9 Bytes A string (Pascal) giving the version of the CDev. Strings are typically of the format "v1.0". Version strings longer than eight bytes are not allowed. Note that this field requires nine bytes regardless of the string length. Opening Additional Resource Files The Control Panel, not any CDev, owns the Resource Manager search path that is in effect when a CDev routine gets control. While handling a CDev message, you may temporarily open additional resources files in the same search path, but you must close them and call SetCurResourceFile to its previous value before returning control to the Control Panel. There may be extra resource files in the search path that you know nothing about, so do not assume that your extra file is adjacent to your CDev resource file in the search path. Further Reference _____________________________________________________________________________ o Apple IIgs Toolbox Reference, Volumes 1-3