TweetFollow Us on Twitter

DAs in C
Volume Number:1
Issue Number:11
Column Tag:Programmer's Forum

Desk Accessories in C

By Wesley Swannack, Computer Engineer, Richland, WA.

Creating a tools and mini-applications

A feature of the Macintosh that sets it apart from other computers is it's ability to have Desk Accessories. Desk Accessories can be considered a 'mini-application' that can be executed while using a program such as MacDraw or writing a Macintosh application program. Desk accessories are small programs that help you achieve a main goal, and is a part of the Desktop Concept that Apple has envisioned. In short, while creating programs or documents there are tools that we use intermittently, such as the Scrapbook, or a Hex Calculator. This is analogous to activities before the advent of personnel computers, tools physically sat on the desk, now the tools are more powerful electronic versions.

Can useful Desk Accessories be Written?

Desk Accessories can be very powerful; enhancing the functionality of the Macintosh. My favorite example, is Click-On Worksheet from T/Maker Graphics. Click-On Worksheet is a very powerful spreadsheet and chart program, that allows the creation of a small spreadsheet or chart while using a word processing or database program. Another example is the dCad Calculator from Desktop, a scientific and programing calculator.

Some Background Information

When writing that first desk accessory, there are two very important chapters in Inside Macintosh, to familiarize yourself with. The Chapters are the Desk Manager and the Device Manager. Briefly, the sole purpose of the Desk Manager is to coordinate activities between the executing desk accessory and the application program. The Device Manager handles the I/O of information to and from the desk accessory.

When writing a desk accessory, the program content is considered a 'DRVR' (driver) resource type, from a Macintosh viewpoint. 'DRVR' resources are kept in the System file and are read into memory by the Device Manager as needed. At this time the resource ID's of the DRVR's can range from 0 to 31, however remember that the first 11 are reserved by Apple. These reserved ID's are for things like the Disk, Sound, AppleTalk, and Printer drivers.

Open, Close, Control, Prime, and Status

A 'DRVR' routine is made up of 5 routines that dictate actions. They are Open, Close, Control, Prime, and Status. The Open routine reads all the 'DRVR' code and resources into memory, creates data structures and variables when the desk accessory is executed for the first time. The Close routine deletes and removes from memory, structures and resources that the desk accessory used. The Control routine is the most important of all five routines. This routine is executed everytime the procedure SystemTask() is called within the event loop of the application program currently running. Think of the procedure as giving control of the Mac over to the desk accessory; then, when the desk accessory is closed, control is handed back to the main application program. The Prime and Status routines deal with the reading and writing of information to the 'DRVR' and at this time are not important to us. One neat feature of Desk Accessories is the ability to attach and use resources such as WIND's and MENU's.

Getting Started on the Desk Accessory

Ok, Let us get started on the Desk Accessory. This desk accessory has been written using 'C' as the language and most C compilers support the creating of desk accessories. Even if you don't program in C, most programs are easy to follow because of all the toolbox calls that programs use. The type of desk accessory that we will be writing is called a Shell. Shells allow a person to start from a point that works. Then in a modular fashion new routines and functions, can be added. This allows you to track down errors and debug the program much easier. So once you have finished with this shell program, you will have a base to work from as you try out your own desk accessories.

Looking at the beginning of the program listing, the necessary header files have been included, that represent predefined constants and variable structures. Next is a procedure called ACC(). This is a MegaMax dependent item since the Linker supports the creation of desk accessories. What is important is the arguments of the ACC procedure.

The Control routine can respond to certain device routines, which are determined by the argument drvrFlags. Explanation of the flags can be found on pages 19 and 20 of the Device Manager Guide. How one determines the drvrFlags is tersely explained in Inside Macintosh, so after much thinking the light came on!! At the top of page 20 is a set of predefined constants such as dNeedTime. Looking at the equates one sees that the constants range from 0 to 6. These numbers represent which bit in the high word byte of the drvrFlags to set to a one. So the program example $2400 in binary form represents a 00100100 00000000. This binary number, (using page 20 as a guide), shows that the driver can respond to control events and that the driver needs time to perform periodic action. [Hence bit settings in the drvrFlags argument determine characteristics of the driver. --Ed.] The next argument drvrDelay contains a tick count indicating how often the control routine should be called. A tick count of 0 means that the control routine will be called as often as possible. A 1 means that the action should be called every 60th of a second, 2 means every 30th of a second. Using a value of 60 in the program, our control routine will be called every full second. Remember whether this action occurs, is dependent on how long it takes the application program to call SystemTasks(). DrvrEvmask is a mask that filters what type of events the desk accessory will responded to; these are explained on page 16 of the Event Manager. Basically, just add up all the numbers that represent those events you want to respond to. The argument drvrMenu represents the resource ID number of a menu that your desk accessory uses. You have seen many desk accessories that have a menu appear on the menubar such as Extras. To attach resources such as menus and windows, a special formula is used in determining the resource ID number. This formula is discussed on page 10 of the Resource Manger. In our example program, a resource number of -15424 is used. Looking at the chart on page 10 we know that bits 15 and 14 are set to a 1. This means that all resources of desk accessories will be negative value, such as the above example. Next bits 13, 12, and 11 are set to 0. This specifies that a DRVR resource own's the attached resources. Bits 5 thru 10 contain the resource id number of the DRVR. As mention in the very beginning of the program listing, we are using a resource id = 30. Bits 4 thru 0 are variable and allow us to have several menus attached to the same desk accessory. So the value -15424 = 11000011 11000000 in binary form. We used a variable of 0 in this MENU resource however if you want to add another menu you can use a 1, then 2, and so on. Length and Window title are arguments that are used for the title of the window and the length of the window title.

Format of the Desk Accessory File

The internal format of the desk accessory file can be found on page 12 of the Desk Manager. This is the final form that all desk accessories look like when finally compiled into machine code. If you have a compiler that creates Desk Accessories then this information is just for interest only.

Opening the DRVR routine

When a desk accessory is used for the first time, information about the desk accessory is read into a structure in memory called a Device Control Entry block. An illustrated version of this can be found on page 21 of the Device Manager. Looking at it, we notice that it has information about the window, menu, number of ticks, etc. This is very important, for this is how data can be accessed from one routine to the other. The first thing that is declared is a *dctl and a *pb pointers after the accopen(dctl,pb) function. The pointers allows access to the Device Control Block, and since this is a RAM driver (i.e. loaded from disk into memory), a paramunion block must be used to gain access to events and other information. Next a menu structure and a window pointer is created since this desk accessory will have a window and a menu associated with it. Then we check to make sure that that this desk accessory has not been already executed by checking for the presence of the window. Once the IF statement is true, use the function getmenu to get the menu resource that is already in the system file. Since the device control entry block already contains the menu resource id, just pass the value to the function getmenu. Next create the window, set the port, and assign the text mode. Now we get the device reference number (dctlrefnum) and insert into the windowkind field of my window structure. This reference number is what the Device Manager uses internally, instead of using the name of the Desk Accessory. Now assign the dcltwindow field in the device entry block, a pointer that points to my window. At this point we have created all the menus and windows and the Open routine is finished.

Controlling the DRVR routine

The Control routine represents the heart of the desk accessory. This routine is executed everytime a SystemTask is called from the application program. This desk accessory creates a window, menu, and prints the time of day in the window.

Following the program, create *dctl and *pb pointers to the various information structures of the driver (i.e. desk accessory.) Then we create a new menu structure and window pointer. Using the dclt (device control block) we can extract the menuhandle and the pointer to my desk accessory's window, that are somewhere, floating out in memory. Next is the event structure that determines what the desk accessory will do every time the procedure SystemTask is called from the application program.

The action taken by the Control routine is determined by a message that is stored in .cscode field of the paramunion.cntrlparam structure. This field is accessed by the pb pointer that was created when the Control routine was just executing. The messages that we can expect to receive can be found on page 14 of the Desk Manager. These messages simply tell the Control routine what kind of action to take. In our example we used the accrun, accevent, and the accmenu messages. As outlined in the page 14, accrun handles periodic actions such as getting the time for a clock. Handling events such as keyboard and mouse events the accevent message is used. When using menus the Desk Manager uses the accmenu message.

Looking at the accrun portion of the switch statement, in the program listing, we can see that the time of day is inserted into the datetime variable, then printed onto the window that is associated with the desk accessory. This is done as long as the switch condition finds the accrun message in the .cscode field.

The accevent portion of the switch statement is a little more complicated since we must determine what type of event has occurred. Besides the accevent message, the control routine receives in the csparam field of the paramunion structure, a pointer to an event record. This event record is needed to tell us the what and where of the event. To get the what of the event record, we do a 'C' type cast of the pointer, casting the pointer as an event record. One note, that in the header file of the paramunion structure that we must use a long that is a field of the csparam structure. This will allow us to conveniently get the address when type casting the pointer. It may seem somewhat complicated but it works quite well. Back to the program. Now that we know what type of event occurred, we can find out where it occurred such as in a mousedown event. Using the same technique as above, we can pass to the findwindow routine where the mousedown event occurred.

Remember that all windows created by desk accessories are considered system windows, as talked about on page 4 of the Window Manager. The insyswindow constant is what findwindow will return, if the mousedown event occurred inside of our desk accessory window, so beware. If the person clicked inside of a application window, the desk manager will handle it and does not have to be addressed by the desk accessory. In our program when clicking inside of the system window the procedure closedeskacc is called. The only argument that is passed is the reference number of the desk accessory. This can be accessed thru dctlrefnum field of the device control block. The procedure closedeskacc terminates the Control routine of the desk accessory and starts the execution of the Close routine.

When selecting a desk accessory's menu the Desk manager generates an accmenu message. Once again we can extract the data using the csparam field. This allows us to get the item number of which item was choosen in the desk accessories menu. If we selected the first item we can hide or show the window on the desktop. Notice this also toggles the menu from show to hide and back again. If we select close then the closedeskacc procedure is called and the desk accessory is terminated.

Closing the DRVR routine

When the Closing the desk accessory the windows, menus and any other data structures must be disposed of. Then the dctlwindow pointer field of the device control block must have a nil inserted. Looking at our Close routine example we once again access the pb and dctl thru the use of pointers. This allows us to dispose of the window structures and menu resources. We redraw and update the menubar, then do a sysbeep just to let us know that the routine is complete and the desk accessory is no more.

Some Closing Comments

Once you have compiled the desk accessory and the resource file, using REdit is useful for cutting and pasting the DRVR and MENU into the System file. Remember that the ID's of the DRVR and MENU are equal to 30. If you wish to change the DRVR id number, then remember to change the resource id's of the attached resources.

After looking over the code for this desk accessory you may decide that this is a trivial program. The idea here is to create a shell version that is understandable and most importantly works. In later issues we can approach the cutting and pasting between applications and desk accessories, and how to create a calculator.

Remember that desk accessories can be as powerful as application programs. It is not unlikely that a terminal program or text editor couldn't be written as a desk accessory. I write desk accessories because they can give the Macintosh a state of 'pseudo-concurrency' and the Mac is an interesting machine to program.

* shell.r
* resource file
* resource id = 30

 Hide Window

Wesley C. Swannack
shell for most desk accessories
written in Megamax C.
id number of the 'DRVR' = 30
#include <global.h>
#include <acc.h>
#include <desk.h>
#include <qd.h>
#include <event.h>
#include <res.h>
#include <misc.h>
#include <mem.h>
#include <menu.h>
#include <te.h>
#include <font.h>
#include <file.h>
#include <win.h>
#include <control.h>
#include <device.h>

/* drvrFlags, drvrDelay,drvrEvmask, drvrMenu , Length and window title 
ACC(0x2400,60, 0x014A,-15424,5, "Shell")
int menuflag = FALSE;

accopen(dctl, pb)
dctlentry *dctl; /* pointer to device control block */
paramblockrec *pb; /* handle to parameter block */
 menuhandle mymenu;  /* creating my menu structure */
 windowpeek mywindow;/* pointer to the window record */
 rect wr; /* starting size for the window */
 if (dctl->dctlwindow == NULL)/* No window  created*/
 mymenu = getmenu(dctl->dctlmenu);
 insertmenu(mymenu, 0); /* appending the menu to the menubar */
 setrect(&wr, 100, 50, 400, 250);  
 /* creating the window */
 mywindow = newwindow(NULL, &wr, "Window", 0, rdocproc, -1L, -1, 0L);
 mywindow->windowkind = dctl->dctlrefnum;    /* getting neg number for 
my sys window */ 
 dctl->dctlwindow = mywindow; /* device window now my window ptr */
 return 0;

accclose(dctl, pb)
dctlentry *dctl;
paramblockrec *pb;
 menuhandle mymenu;  /* declaring menu */
 windowptr mywindow; /* declaring window */
 mymenu = getmhandle(dctl->dctlmenu);  /* getting handle to desk menu 
 mywindow = dctl->dctlwindow;      /* getting desk window */
 dctl->dctlwindow = NULL;
 releaseresource(mymenu); /* disposing of the menu  rsrc*/
 sysbeep(2);/* just to let me know when closed */
 return 0;

accctl(dctl, pb)
dctlentry *dctl;
paramblockrec *pb;
 long datetime;
 char timestr[100];

 menuhandle mymenu;  /* declaring menu */
 windowptr mywindow; /* declaring window */
 mywindow = dctl->dctlwindow; /* getting my window stuff */
 mymenu = getmhandle(dctl->dctlmenu);/* getting my menu stuff */

 switch (pb->paramunion.cntrlparam.cscode) 
 case accrun:
 getdatetime(&datetime);  /* getting the time for this moment */
 iutimestring(datetime, -1, timestr);
 moveto((100-stringwidth(timestr))>>1,15);   /* moving the pen to draw 
with */
 case accevent:
 /* getting the event */ 
 switch (((eventrecord *)pb->paramunion.cntrlparam.csparam.eventaddress)->what)
 case mousedown:
 int wherepressed;
 /* Only because it is a really long statement to print,notice that the 
next to lines are really one line */ wherepressed=findwindow(&(((eventrecord*)pb->paramunion.cntrlparam.csparam.eventaddress)-> 
where), &mywindow); 
 case insyswindow: /* in my desk accessory window */
 case keydown:
 case accmenu:
 switch (pb->paramunion.cntrlparam.csparam.menustatus.itemnumber) 
 case 1:/* selected 'Hide' or 'Show' */
 if (menuflag)
 selectwindow(mywindow);  /* window is now visible */
 setitem(mymenu,1,"Hide Window");  /* inserting new menu item */
 /* user will see the 'Hide' option in the menu */ 
 menuflag = FALSE;
 setitem(mymenu, 1, "Show Window");/* inserting new menu item */
 /* user will see the 'Display' option in the menu */ 
 menuflag = TRUE;
 case 3:
 return 0;


/* I have included the appropriate data structures so that you can tell
 whether or not your files have the appropriate variables.
 The variables talked about are in boldface type

 This is for refernence only

typedef union {    /* control information */
 int sndval;
 int asncconfig;
 struct { ....  } asyncinbuff;
 struct { ....  } asyncshk;
 struct { ....  } printer;
 struct { ....  } fontmgr;
 ptr diskbuff;
 long eventaddress;/* address for desk events */
 long asyncnbytes;
 struct { ....  } asyncstatus;
 struct { ....  } diskstat;
 struct { /* menu manager */
 int menuident;
 int itemnumber;
        } menustatus;
   } opparamtype;

typedef opparamtype *opparamptr;

typedef struct {
     ptr iolink;
     int iotype;
     int iotrap;
     ptr iocmdaddr;
     procptr iocompletion;
     int ioresult;
     char *ionameptr;
     int iovrefnum;
     union {
 struct { .... } ioparam;
 struct { .... } fileparam;
 struct { .... } volumeparam;
 struct {
        int filler3;
        int cscode;
        opparamtype csparam;
   } cntrlparam;
        } paramunion;
   } paramblockrec;


Community Search:
MacTech Search:

Software Updates via MacUpdate

Splash Cars guide - How to paint the tow...
Splash Cars is an arcade driving game that feels like a hybrid between Dawn of the Plow and Splatoon. In it, you'll need to drive a car around to repaint areas of a town that have lost all of their color. Check out these tips to help you perform... | Read more »
The best video player on mobile
We all know the stock video player on iOS is not particularly convenient, primarily because it asks us to hook a device up to iTunes to sync video in a world that has things like Netflix. [Read more] | Read more »
Four apps to help improve your Super Bow...
Super Bowl Sunday is upon us, and whether you’re a Panthers or a Broncos fan you’re no doubt gearing up for it. [Read more] | Read more »
LooperSonic (Music)
LooperSonic 1.0 Device: iOS Universal Category: Music Price: $4.99, Version: 1.0 (iTunes) Description: LooperSonic is a multi-track audio looper and recorder that will take your loops to the next level. Use it like a loop pedal to... | Read more »
Space Grunts guide - How to survive
Space Grunts is a fast-paced roguelike from popular iOS developer, Orange Pixel. While it taps into many of the typical roguelike sensibilities, you might still find yourself caught out by a few things. We delved further to find you some helpful... | Read more »
Dreii guide - How to play well with othe...
Dreii is a rather stylish and wonderful puzzle game that’s reminiscent of cooperative games like Journey. If that sounds immensely appealing, then you should immediately get cracking and give it a whirl. We can offer you some tips and tricks on... | Read more »
Kill the Plumber World guide - How to ou...
You already know how to hop around like Mario, but do you know how to defeat him? Those are your marching orders in Kill the Plumber, and it's not always as easy as it looks. Here are some tips to get you started. This is not a seasoned platform... | Read more »
Planar Conquest (Games)
Planar Conquest 1.0 Device: iOS Universal Category: Games Price: $12.99, Version: 1.0 (iTunes) Description: IMPORTANT: Planar Conquest is compatible only with iPad 3 & newer devices, iPhone 5 & newer. It’s NOT compatible with... | Read more »
We talk to Cheetah Mobile about its plan...
Piano Tiles 2 is a fast-paced rhythm action high score chaser out now on iOS and Android. You have to tap a series of black tiles that appear on the screen in time to the music, being careful not to accidentally hit anywhere else. Do that and it's... | Read more »
Ultimate Briefcase guide - How to dodge...
Ultimate Briefcase is a simple but tricky game that’s highly dependent on how fast you can react. We can still offer you a few tips and tricks on how to survive though. Guess what? That’s exactly what we’re going to do now. Take it easy [Read more... | Read more »

Price Scanner via

12-inch 1.2GHz Silver Retina MacBook on sale...
B&H Photo has the 12″ 1.2GHz Silver Retina MacBook on sale for $1399 including free shipping plus NY sales tax only. Their price is $200 off MSRP, and it’s the lowest price for this model from... Read more
iPads on sale at Target: $100 off iPad Air 2,...
Target has WiFi iPad Air 2s and iPad mini 4s on sale for up to $100 off MSRP on their online store for a limited time. Choose free shipping or free local store pickup (if available). Sale prices for... Read more
Target offers Apple Watch for $100 off MSRP
Target has Apple Watches on sale for $100 for a limited time. Choose free shipping or free local store pickup (if available). Sale prices for online orders only, in-store prices may vary: - Apple... Read more
Apple refurbished 2014 13-inch Retina MacBook...
Apple has Certified Refurbished 2014 13″ Retina MacBook Pros available for up to $400 off original MSRP, starting at $979. An Apple one-year warranty is included with each model, and shipping is free... Read more
Macs available for up to $300 off MSRP, $20 o...
Purchase a new Mac or iPad using Apple’s Education Store and take up to $300 off MSRP. All teachers, students, and staff of any educational institution qualify for the discount. Shipping is free, and... Read more
Watch Super Bowl 50 Live On Your iPad For Fre...
Watch Super Bowl 50 LIVE on the CBS Sports app for iPad and Apple TV. Get the app and then tune in Sunday, February 7, 2016 at 6:30 PM ET to catch every moment of the big game. The CBS Sports app is... Read more
Two-thirds Of All Smart Watches Shipped In 20...
Apple dominated the smart watch market in 2015, accounting for over 12 million units and two-thirds of all shipments according to Canalys market research analysts’ estimates. Samsung returned to... Read more
12-inch 1.2GHz Retina MacBooks on sale for up...
B&H Photo has 12″ 1.2GHz Retina MacBooks on sale for $180 off MSRP. Shipping is free, and B&H charges NY tax only: - 12″ 1.2GHz Gray Retina MacBook: $1499 $100 off MSRP - 12″ 1.2GHz Silver... Read more
12-inch 1.1GHz Gray Retina MacBook on sale fo...
B&H Photo has the 12″ 1.1GHz Gray Retina MacBook on sale for $1199 including free shipping plus NY sales tax only. Their price is $100 off MSRP, and it’s the lowest price available for this model... Read more
Apple now offering full line of Certified Ref...
Apple now has a full line of Certified Refurbished 2015 21″ & 27″ iMacs available for up to $350 off MSRP. Apple’s one-year warranty is standard, and shipping is free. The following models are... Read more

Jobs Board

*Apple* Retail - Multiple Positions (US) - A...
Job Description: Sales Specialist - Retail Customer Service and Sales Transform Apple Store visitors into loyal Apple customers. When customers enter the store, Read more
*Apple* Subject Matter Expert - Experis (Uni...
This position is for an Apple Subject Matter Expert to assist in developing the architecture, support and services for integration of Apple devices into the domain. Read more
*Apple* Macintosh OSX - Net2Source Inc. (Uni...
…: * Work Authorization : * Contact Number(Best time to reach you) : Skills : Apple Macintosh OSX Location : New York, New York. Duartion : 6+ Months The associate would Read more
Computer Operations Technician ll - *Apple*...
# Web Announcement** Apple Technical Liaison**The George Mason University, Information Technology Services (ITS), Technology Support Services, Desktop Support Read more
Restaurant Manager - Apple Gilroy Inc./Apple...
…in every aspect of daily operation. WHY YOU'LL LIKE IT: You'll be the Big Apple . You'll solve problems. You'll get to show your ability to handle the stress and Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.