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 Document

Revised by:    Dave Lyons                                      September 1990
Written by:    Matt Deatherage & Darryl Lovato                 September 1989

Files of this type contain CDevs for the Apple IIgs Control Panel New Desk 
Accessory.
Changes since January 1990:  Noted that the MachineCDEV message is not used 
and the RunCDEV message is available only once a second, and made several 
minor corrections.
_____________________________________________________________________________

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 which 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 structure behind the Control Panel is conceptually quite easy.  The 
Control Panel NDA receives events from the system which it handles through 
TaskMasterDA.  At certain times, the Control Panel calls CDev routines if the 
CDev indicates this is desirable through the CDev Flags resource.

The Control Panel takes care of nearly everything necessary, including 
tracking controls.  CDev windows are basically windows full of extended 
controls, since the only "content" message CDevs receive is that a control was 
hit.

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 a routine (if you 
like) with the control handle and ID.  This allows you to take action based 
upon the user's actions.  User interface items beyond extended controls (i.e., 
modal windows) must be handled entirely by the CDev.


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), the CDev flags 
resource (type rCDEVFlags, $8019) and the CDev's icon (type rIcon, $8001).

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, InitalLoad2 loads the code from memory.  This process gives the 
CDev code resource a maximum size of 64K.

Once the resource is loaded, the beginning of it is called tool-style with a 
stack diagram as illustrated in Figure 1.

    |
    | Result (Long)     Space for result
    |_________________
    |
    | Message (Word)    Indicator of action to take
    |_________________
    |
    | Data1 (Long)      Data passed to CDev
    |_________________
    |
    | Data2 (Long)      Data passed to CDev
    |_________________
    |
    | RTL (3 bytes)     RTL address
    |_________________

                      <-- Stack Pointer

    Figure 1--Stack Diagram Before Calling CDev

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.  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 ten 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 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.

The machine state during this call can be underestimated as "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 shut down 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.

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, 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.

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.

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:         wantEvent
                                                      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:         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.


Further Reference
_____________________________________________________________________________
  o  Apple IIgs Toolbox Reference, Volumes 1-3

