CDEV Control Panel Files Revisited

By Steven C. Sheets, Contributing Editor, Apple Computer, Il.

ApplFont - Control Panel Files

This months article will discuss the most obvious, and perhaps important, feature of the new System/Finder (not the bulging trash can or the spinning watch hands), the expandable Control Panel.

The new Control Panel is no longer a fixed Desk Accessory with only a single appearance/function. Similar to the Chooser, the new Control Panel now refers to special files in the System Folder. Each of these special Control Panel Files or cdev files appears as an Icon on the left side of the Control Panel. When one is selected, the corresponding cdev file tells the Control Panel how to draw the right side of the Control Panel. The cdev file also has code inside it that that tells the Control Panel what to do when a User selects something on the left side of the Control Panel. Now the User can pick and chose his cdev files, like he does his Desk Accessories, Fonts or FKEYs. Each new cdev gives the User a new way to change and “Control” his Macintosh.

While Apple has released some cdev files (General, Keyboard, Mouse, Monitor, Sound, Startup Device), a number of other ones have appeared. This article will explain how to create such a cdev file.

The new Control Panel and cdev files are of special importance to Mac // users. While the Chooser is the standard way to contact peripherals (like Printers or File Servers), the Control Panel is the method used to control the internals of the Machine, including expansion cards. A cdev can be created that will only function on a specific machine (one that has Color Quickdraw) or even only one that has a particular expansion card installed.

cdev File Format

A Control Panel File contains several set of resources. Each group is used for a different purpose. A cdev files has no information in it’s data fork. Besides the resources, a cdev file has the File Signature of ‘cdev’ and a specific File Creator (matching the BNDL resource, see below). It’s bundle and init bits must be set.

The first resource that is checked when the Control Panel is open is the ‘mach’ resource of ID -4064. This resource tells the Control Panel if this cdev can be used on this machine. The resource contains 2 word values, the SoftMask followed by the Hardmask. The Softmask is compared to the global variable ROM85 to check for software features, while the HardMask is compared to HwCgfFlg to determine the Hardware features. The cdev will appear in the Control Panel if every bit that is 0 in the Softmask is 0 in ROM85 and every bit that is 1 in the Hardmask is 1 in HwCgfFlg. For example, the Softmask of $FFFF and Hardmaks of $0000 would go with a cdev that would appear on any machine. Softmask of $3FFF and Hardmaks of $0000 would go with a cdev that would appear on a Mac // only. Finally there is the special case of a Softmask of $0000 and a Hardmaks of $FFFF. This is for a cdev that needs to check for more information than is stored in ROM85 and HwCgfFlg. In that case, the Control Panel calls the ‘cdev’ resource code to ask if the machine is correct (more about this below). This case would be used for a cdev that needs to have a certain expansion card be installed.

Fig. 1 Selecting our CDEV in the Control Panel

Second a cdev file must have its own icon. Not only will this Icon appear in the Finder, the Icon appears on the left side of the Control Panel. The Icon must be stored as a ICN# resource of ID number -4064. The associating resources BNDL and FREF (ie. ones that make the Finder know ICN# -4064 is to be used) must be set correctly and have the ID number -4064. The BNDL resource will have the File Creator that the cdev file must have. Finally there must be a owner resource of the same matching type as the File Creator (ID 0) in the file. Just remember that the ICN#, BNDL and FREF must be ID -4064 (normally they can be anything).

Next the cdev file must contain information on how the right side of the Control Panel will be displayed. When an Icon is pressed on the left side of the Control Panel, the Control Panel check the matching cdev file. It is looking for a resource of type DITL, ID -4064. It adds this DITL to the DITL it is using to display the entire Control Panel (left and right side). Thus all the various Buttons, Icons and Text seen on the Panel are stored in various DITL files. If a certain cdev wants to display a unusual feature, it’s DITL resource may have a number of userItems. This is how the General cdev has such an unusual appearance. The Control Panel also checks a ‘nrct’ resource of ID -4064 when it draws itself. A ‘nrct’ resource contains a number of rectangles on the right side of the Control Panel. The exact format of the resource is a word value containing the number of rectangles in the resource, followed by the 4 word values (top, left, bottom, right) per rectangle (if any). The latest version of ResEdit has a TMPL for the correct format of ‘nrct’. On the right side of the Control Panel, each rectangle is filled in with white and framed before the DITL is drawn. Any area not in a rectangle is filled in with gray. The rectangles are set to overlap so that the lines between the boxes are thicker than 1 pixel. Examine the Mouse and Keyboard cdev files for examples of this.

Lastly the cdev file must have a resource of type ‘cdev’, ID -4064. This resource is a code resource similar to a FKEY or a Window Proc. This code takes care of the event handling for the right side of the Control Panel. As mention above, it also takes care of special checks to see if this cdev should appear on this machine at all. The exact format of the ‘cdev’ resource is explained below.

The cdev file can contain additional resources that the ‘cdev’ code can use. These resources must be in the range of ID -4048 to -4033. Whenever the cdev’ code resource is called, the cdev file resource fork will be open. Thus all the additional resources can be used. They can even be changed, and this changed value can be written back to the resource file by changing the value of the handle, calling ChangedResource, then calling WriteResource. As explained below, this is a convenient way to save information between system resets.

cdev Call

An ‘cdev’ resource is a code resource similar to a FKEY or Window Proc. Whenever cdev is called, the current Grafport will always be set to the Grafport holding the right side of the Control Panel. The entry point of the resource has this format:

FUNCTION  cdev(  message, item, numItems, CPanelID: INTEGER;
 theEvenT:EventRecord;
 cdevStorage: Handle;
 CPDialog: DialogPtr): Handle;

Remember that the Control Panel draws most of the right side of the desk accessory by adding the DITL in the cdev file to the Control Panels own DITL. Thus the first item in the cdev files DITL may be the 7th item in the Control Panel DITL (after the cdev DITL is added) if were 6 items to begin with.

The CPDialog parameter is the DialogPtr that contains the Control Panels DITL. CPanelID is the base resource ID of the Control Panel DialogPtr. The parameter numItems is the actual number of items in the Control Panel DITL before the cdev DITL was added. The parameter theEvenT is the EventRecord of some action that cdev has to take care of, while item is the number of some item in the DITL that has been just been pressed. The cdevStorage parameter normally contains the value that was last returned by the last cdev call. This parameter can be used to store internal data or pass error messages.

The key parameter to the cdev function is message. It value tells the function exactly what is should do for this call. It can be passed the following values:

CONTS initDev  = 0;
 hitDev = 1;
 closeDev = 2;
 nulDev = 3;
 updateDev= 4;
 activDev = 5;
 deActivDev = 6;
 keyEvtDev= 7;
 macDev = 8;

The messages updateDev, activDev, deActivDev and keyEvtDev are fairly simple. Each of these messages handles a praticular type of event passed by the theEvenT parameter. In many case, such a call would do nothing since the Control Panel is doing most of their work. The nulDev message is sent to the cdev on every desk accessory run event. An clock cdev could use this message to change the time of the clock.

Fig. 2 Our CDEV in operation

The initDev and closeDev calls are called when the cdev is opened or closed. The calls with these messages should create or delete any private storage. The initDev call may also make any changes to the cdev portion of the Control Panel (ex. hiliting the buttons, checking boxes, setting text, setting userItems). When InitDev is first passed, cdevStorage does not contain a real handle. It actually contains a longint value of 3. If the cdev does not want internal data, the cdev can return the cdevStorage handle and everything will work. If the cdev does want internal storage, the cdev should create the handle, initialize the data, and return it as the function’s results. The next call to cdev will have cdevStorage contain this handle. As long as all future call pass the cdevStorage handle as the function’s results, the handle can be used as storage safely. When a closeDev message is sent, the cdev must release the storage handle (if there is one). Remember that this internal data structure is strictly alive while the cdev is being displayed in the Control Panel. If another cdev is picked or the Control Panel is closed, the closeDev message is sent and the cdev is closed.

If at anytime, the cdevStorage parameter contains the values -1, 0 or 1, the cdev call must do nothing but return the parameter as the function result. These values are error codes and indicate that the Control Panel is having some problem. If the cdev itself ever has an error, it can return these values. The Control Panel then will gray out the right side of the Control Panel. Error 0 indicates a memory error, and the Control Panel will display a message to that effect. Error 1 indicates a resource error (resource not found), and will display a message to that effect. Error -1 indicates some cdev specific error. In that case, the cdev should briefly put up it’s own message.

The hitDev call is fairly obvious. The user has just pressed an item. The item number is in the parameter Item. Remember that this number is not based on the cdev DITL, but on the DITL created by the Control Panel by adding DITLs. The cdev call usually does something at this point to change the operation of the Macintosh. The call may also want to change the DITL to explain the change (ex. check a new box and uncheck the old one).

The macDev is only passed when the ‘mach’ resource of the cdev file contains $0000 and $FFFF. Then the cdev must decide if it should be shown on this machine. If so, the function should return 1. If not, it should return 0. These 0 and 1 values have no relationship to the 0 and 1 error codes describe above. This call is done before the cdev is formally opened.

Init Resource

The General and the ApplFont files allows the user to set the Parameter RAM of the Macintosh. The Parameter RAM settings will stay effect until changed. Even when the Mac is turned off, the Parameter RAM stays active, thus saving the values between sessions. However, there are some effects that can only go into effect after certain code is executed. Such cdev files can use a INIT resource to do want they want. An INIT resource is a code resource like FKEY or cdev that is executed at startup by the system. It is a procedure call with no parameters. Normally an INIT resource must be in the System file. However one of the INIT resources that is in the System file checks other files in the System Folder for INIT resources. Files of various Types (including ‘INIT’ type and, as of the latest System, ‘cdev’ type) are checked for any resources of type INIT. If one is found, it is executed. This is an extremely powerful feature.

The best way to explain this idea is to give an example. Say someone wants to create a cdev that turns on or off some specific function. The cdev file for such an example would consist of several parts. First there would be the normal cdev file format containing the DITL, ICN#, cdev and other resource. There would also be a special resource (name and type is unimportant) that would contain a single boolean variable. Inside the cdev resource is the code that turns on or off the specific function. Everytime the user would press the correct on or off button in the Control Panel, the cdev code would turn the function on or off. It would also store the latest on or off value inside the special boolean resource (by changing the value of the handle, calling ChangedResource, then calling WriteResource). Remember that the cdev file resource fork is always open whenever the cdev code resource is itself being called.

So far the example would work until Mac power is turned off. When the machine is turned back on, the user may want the special function to be in effect. This would not occur until the cdev file is selected in the Control Panel. Then the cdev code would have a chance to see if the special feature should be turned on. To solve this problem, the INIT resource comes to the rescue. On system startup, the resource would be executed. It would check the special boolean resource (INITs, like cdevs, always are called with the resource fork of the file containing them open). If the boolean value is on (from the last time someone set it with the Control Panel), the INIT resource would turn on the special function. Thus the entire cdev file would always make sure the special blanking is set the way the user wants it.

Consider the example of an auto-screen blanking cdev. Such a function makes the screen go dark if no one has used the Macintosh after some set time period so that the Macintosh screen does not get a burned image. An auto-screen blanking function usually works by inserting a checking routine (check how long it’s been since someone has use the Mac) in the system heap (where it would not be destroyed when the applications are switched). To turn the routine on or off, the memory location of the routine needs to be installed into or removed from one of the various Macintosh timers. Thus the memory location must be saved between various times the Control Panel is accessed. To do this another special resource would probably be used that contains the longint memory address. The INIT resource would initially install the blanking routine and save the memory location into this special resource. The INIT would may or may not turn on the install the routine in a time queue depending on the last setting of the Control Panel. The later calls to the cdev would use the memory location to turn the blanking on or off.

The Code

ApplFont is a sample cdev file that allows the users to set the Application Font value. This value is one of the few Parameter RAM settings that is not changed by the General, Mouse or Keyboard cdev Files. Since it is a Parameter RAM that is being changed, no INIT resource is needed.

The Application Font is a special reference Font. It is not a true Font like the other Font ID numbers. Normally when a program sets the txFont field of a Quickdraw Grafport to some number (using the TextFont procedure), all Text drawing would be done in the Font that has the matching ID number. However when the txFont field is set to one (1), the Font used is the one that matches the Application Font ID number. Many programs and Desk Accessories draw using the Application Font, thus allowing the user to select the Font.

The actual value of the Application Font portion of the Parameter RAM (font field of the SysParmType data structure) must be the Application Font number minus 1. Since Quickdraw only refers to the Parameter RAM at system boot to retrieve the Application Font number, changing this number will not effect the system until the next reboot. While it is not dangerous to change the number (using the GetSysPPtr and WriteParam calls), a simple rule needs to be observed. Never change the Application Font to a Font that is not installed on the System, or the System will not function.

The original ApplFont file was created using ResEdit while the cdev resource was created using Lightspeed Pascal. The Resource file (MPW format) enclosed here could have just as easily created all the resources save the cdev resource. It is still easiest to use ResEdit to paste the compiled cdev resource into the finished cdev file. Use ResEdit to change the File Signature and Creator (in this case, ‘cdev’ and ‘apft’). Do not forget to set the bundle and init bit so the Icon will be displayed.

{ AppFont - Application Font Control }
{ by Steve Sheets}
{ Control Panel Proc to change Application Font }

UNIT AFunit;

INTERFACE

FUNCTION Main (message, item, numitems, 
 CPanel : integer;
 theEvent : EventRecord;
 cdevStorage : longint;
 CPDialog : DialogPtr) : longint;

IMPLEMENTATION

{ Given the DialogPtr to the Control Panel, and the number of items in 
the original Control Panel DITL and the Number of the Font Button to 
be selected, selects that Font Button and unselects all the other Buttons. 
}

PROCEDURE DoHit (N, X : integer;
 CP : DialogPtr);
VAR
 count : integer;
 myT : integer;
 myH : handle;
 myR : rect;
BEGIN
 FOR count := X + 1 TO X + 16 DO
 BEGIN
 GetDItem(CP, count, myT, myH, MyR);
 IF count = N THEN
 SetCtlValue(Controlhandle(myH), 1)
 ELSE
 SetCtlValue(Controlhandle(myH), 0);
 END;
END;

{ First finds the current Application Font ID number, converts that ID 
number into corresponding Font Button number and returns that number. 
}

FUNCTION CurNum : integer;
VAR
 SP : SysPPtr;
 V : integer;
BEGIN
 SP := GetSysPPtr;
 V := SP^.Font + 1;
 CASE V OF
 0 : 
 CurNum := 1;
 2, 3, 4, 5, 6, 7, 8, 9 : 
 CurNum := V;
 11, 12 : 
 CurNum := V - 1;
 20, 21, 22, 23, 24 : 
 CurNum := V - 8;
 OTHERWISE
 CurNum := 0;
 END;
END;

{ Given the Font Button number, converts it into the Application Font 
ID number, then sets the current Application Font to that number. }

PROCEDURE SetNum (N : integer);
VAR
 SP : SysPPtr;
 E : OSErr;
 V : integer;
BEGIN
 CASE N OF
 1 : 
 V := 0;
 2, 3, 4, 5, 6, 7, 8, 9 : 
 V := N;
 10, 11 : 
 V := N + 1;
 12, 13, 14, 15, 16 : 
 V := N + 8;
 OTHERWISE
 V := Geneva;
 END;
 SP := GetSysPPtr;
 SP^.Font := V - 1;
 E := WriteParam;
END;

{ For all the Font Buttons, checks to see if that Font is installed in 
the system. If it is not installed, unhilites the corresponding button 
so it can not be selected. }

PROCEDURE ZapFonts (CP : DialogPtr;
 N : integer);
VAR
 count, F : integer;
 S : str255;
 myT : integer;
 myH : handle;
 myR : rect;
BEGIN
 FOR count := 1 TO 16 DO
 BEGIN
 CASE count OF
 1 : 
 F := 0;
 2, 3, 4, 5, 6, 7, 8, 9 : 
 F := count;
 10, 11 : 
 F := count + 1;
 12, 13, 14, 15, 16 : 
 F := count + 8;
 OTHERWISE
 END;
 GetFontName(F, S);
 GetDItem(CP, N + count, myT, myH, MyR);
 IF S = ‘’ THEN
 HiliteControl(ControlHandle(myH), 255)
 ELSE
 HiliteControl(ControlHandle(myH), 0);
 END;
END;

{ cdev Main Function.Handles InitDev call (Zaps all the unistalled Font 
Buttons and selects the current Font Button) and the HitDev calls (selects 
the pressed Font Buttons and sets the Application Font to that Font. 
}

FUNCTION Main;
VAR
 Val : longint;
BEGIN
 IF (cdevStorage <> 0) AND (cdevStorage <> 1) AND (cdevStorage <> -1) 
THEN
 BEGIN
 CASE Message OF
 0 :    {InitDev}
 BEGIN
 ZapFonts(CPDialog, numitems);
 DoHit(CurNum + numitems, numitems, CPDialog);
 END;
 1 :    {HitDev}
 BEGIN
 DoHit(item, numitems, CPDialog);
 SetNum(item - numitems);
 END;
 OTHERWISE
 END;
 END;
 Main := cdevStorage;
END;

END.




/*
 * AppFont.r - Application Font Control 
 * by Steve Sheets in MPW Format
 * Control Panel Proc changes Application Font
 *
 */

#include “Types.r”

type ‘apft’ as ‘STR ‘;

type ‘nrct’ {
 integer = $$CountOf(RectArray);
 array RectArray { rect; };
};

type ‘mach’ {
 unsigned hex integer;
 unsigned hex integer;
};

resource ‘apft’ (0) {
 “Application Font Control by Steve Sheets 3/18/87”
};

resource ‘nrct’ (-4064, purgeable) {
 { /* array RectArray: 1 elements */
 /* [1] */
 {-1,87,200,322}
 }
};

resource ‘mach’ (-4064, purgeable) {
 0xFFFF,
 0
};

resource ‘BNDL’ (-4064, purgeable) {
 ‘apft’,
 0,
 { /* array TypeArray: 2 elements */
 /* [1] */
 ‘ICN#’,
 { /* array IDArray: 1 elements */
 /* [1] */
 0, -4064
 },
 /* [2] */
 ‘FREF’,
 { /* array IDArray: 1 elements */
 /* [1] */
 0, -4064
 }
 }
};

resource ‘FREF’ (-4064, purgeable) {
 ‘cdev’,
 0,
 “”
};

resource ‘ICN#’ (-4064, purgeable, preload) {
 { /* array: 2 elements */
 /* [1] */
 $”1FFF FFF8 2000 0004 4002 0002 8006 0001"
 $”800E 0001 8016 0001 8026 0001 8046 0001"
 $”80FE 0001 8106 0001 8206 0001 8406 0001"
 $”8806 0001 BF1F 8001 8000 0001 8000 8001"
 $”8001 5001 8002 3001 8001 1001 8000 9101"
 $”8001 F281 8000 0441 8000 0821 8000 10D1"
 $”8000 2129 8000 129D 8000 091D 8000 04ED”
 $”8000 0281 4000 0102 2000 0004 1FFF FFF8",
 /* [2] */
 $”1FFF FFF8 3FFF FFFC 7FFF FFFE FFFF FFFF”
 $”FFFF FFFF FFFF FFFF FFFF FFFF FFFF FFFF”
 $”FFFF FFFF FFFF FFFF FFFF FFFF FFFF FFFF”
 $”FFFF FFFF FFFF FFFF FFFF FFFF FFFF FFFF”
 $”FFFF FFFF FFFF FFFF FFFF FFFF FFFF FFFF”
 $”FFFF FFFF FFFF FFFF FFFF FFFF FFFF FFFF”
 $”FFFF FFFF FFFF FFFF FFFF FFFF FFFF FFFF”
 $”FFFF FFFF 7FFF FFFE 3FFF FFFC 1FFF FFF8"
 }
};

resource ‘DITL’ (-4064, purgeable) {
 { /* array DITLarray: 17 elements */
 /* [1] */
 {25, 100, 44, 170},
 RadioButton {
 enabled,
 “Chicago”
 },
 /* [2] */
 {45, 100, 64, 185},
 RadioButton {
 enabled,
 “New York”
 },
 /* [3] */
 {65, 100, 84, 169},
 RadioButton {
 enabled,
 “Geneva”
 },
 /* [4] */
 {85, 100, 104, 171},
 RadioButton {
 enabled,
 “Monaco”
 },
 /* [5] */
 {105, 100, 124, 164},
 RadioButton {
 enabled,
 “Venice”
 },
 /* [6] */
 {125, 100, 144, 167},
 RadioButton {
 enabled,
 “London”
 },
 /* [7] */
 {145, 100, 164, 165},
 RadioButton {
 enabled,
 “Athens”
 },
 /* [8] */
 {165, 100, 185, 209},
 RadioButton {
 enabled,
 “San Francisco”
 },
 /* [9] */
 {25, 215, 44, 284},
 RadioButton {
 enabled,
 “Toronto”
 },
 /* [10] */
 {45, 215, 64, 270},
 RadioButton {
 enabled,
 “Cairo”
 },
 /* [11] */
 {65, 215, 84, 313},
 RadioButton {
 enabled,
 “Los Angeles”
 },
 /* [12] */
 {85, 215, 104, 272},
 RadioButton {
 enabled,
 “Times”
 },
 /* [13] */
 {105, 215, 124, 297},
 RadioButton {
 enabled,
 “Helvetica”
 },
 /* [14] */
 {125, 215, 144, 283},
 RadioButton {
 enabled,
 “Courier”
 },
 /* [15] */
 {145, 215, 164, 283},
 RadioButton {
 enabled,
 “Symbol”
 },
 /* [16] */
 {165, 215, 184, 284},
 RadioButton {
 enabled,
 “Taliesin”
 },
 /* [17] */
 {5, 129, 23, 364},
 StaticText {
 disabled,
 “Select New 
 Application Font”
 }
 }
};





PROGRAM AFTest;
 VAR
 X, F, N : integer;
 SP : SysPPtr;
 E : OSErr;
BEGIN
 SP := GetSysPPtr;
 F := SP^.Font;
 x := 2;
 CASE X OF
 2 : 
 BEGIN
 N := NewYork;
 SP^.Font := N - 1;
 E := WriteParam;
 END;
 OTHERWISE
 END;
END.