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.

!codeexamplestart*
*
* shell.r
* resource file
* resource id = 30
*
shell.rsrc

Type MENU
 ,-15424
Shell
 Hide Window
 (-
 Close




/*
shell.c
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 */
 drawmenubar();
 setrect(&wr, 100, 50, 400, 250);  
 /* creating the window */
 mywindow = newwindow(NULL, &wr, "Window", 0, rdocproc, -1L, -1, 0L);
 setport(mywindow);
 textmode(srccopy);
 
 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;
 disposewindow(mywindow);
 deletemenu(dctl->dctlmenu);
 releaseresource(mymenu); /* disposing of the menu  rsrc*/
 drawmenubar();
 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:
 setport(dctl->dctlwindow);
 getdatetime(&datetime);  /* getting the time for this moment */
 iutimestring(datetime, -1, timestr);
 moveto((100-stringwidth(timestr))>>1,15);   /* moving the pen to draw 
with */
 drawstring(timestr);
 break;
 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); 
 switch(wherepressed)
 case insyswindow: /* in my desk accessory window */
 closedeskacc(dctl->dctlrefnum);
 break;
 }
 case keydown:
 sysbeep(3);
 break;
 }
 case accmenu:
 switch (pb->paramunion.cntrlparam.csparam.menustatus.itemnumber) 
 {
 case 1:/* selected 'Hide' or 'Show' */
 if (menuflag)
 {
 selectwindow(mywindow);  /* window is now visible */
 showwindow(mywindow);
 setitem(mymenu,1,"Hide Window");  /* inserting new menu item */
 /* user will see the 'Hide' option in the menu */ 
 menuflag = FALSE;
 }
 else
 {
 hidewindow(mywindow);
 setitem(mymenu, 1, "Show Window");/* inserting new menu item */
 /* user will see the 'Display' option in the menu */ 
 menuflag = TRUE;
 }
 break;
 case 3:
 closedeskacc(dctl->dctlrefnum);
 break;
 }
 }
 return 0;
}

accprime()
{
}

accstatus()
{
}
/* 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

Cocktail 8.4 - General maintenance and o...
Cocktail is a general purpose utility for OS X that lets you clean, repair and optimize your Mac. It is a powerful digital toolset that helps hundreds of thousands of Mac users around the world get... Read more
PDFKey Pro 4.3 - Edit and print password...
PDFKey Pro can unlock PDF documents protected for printing and copying when you've forgotten your password. It can now also protect your PDF files with a password to prevent unauthorized access and/... Read more
Kodi 15.0.beta1 - Powerful media center...
Kodi (was XBMC) is an award-winning free and open-source (GPL) software media player and entertainment hub that can be installed on Linux, OS X, Windows, iOS, and Android, featuring a 10-foot user... Read more
DiskCatalogMaker 6.4.12 - Catalog your d...
DiskCatalogMaker is a simple disk management tool which catalogs disks. Simple, light-weight, and fast. Finder-like intuitive look and feel. Super-fast search algorithm. Can compress catalog data... Read more
Macs Fan Control 1.3.0.0 - Monitor and c...
Macs Fan Control allows you to monitor and control almost any aspect of your computer's fans, with support for controlling fan speed, temperature sensors pane, menu-bar icon, and autostart with... Read more
Lyn 1.5.11 - Lightweight image browser a...
Lyn is a lightweight and fast image browser and viewer designed for photographers, graphic artists and Web designers. Featuring an extremely versatile and aesthetically pleasing interface, it... Read more
NeoOffice 2014.11 - Mac-tailored, OpenOf...
NeoOffice is a complete office suite for OS X. With NeoOffice, users can view, edit, and save OpenOffice documents, PDF files, and most Microsoft Word, Excel, and PowerPoint documents. NeoOffice 3.x... Read more
LaunchBar 6.4 - Powerful file/URL/email...
LaunchBar is an award-winning productivity utility that offers an amazingly intuitive and efficient way to search and access any kind of information stored on your computer or on the Web. It provides... Read more
Remotix 3.1.4 - Access all your computer...
Remotix is a fast and powerful application to easily access multiple Macs (and PCs) from your own Mac. Features Complete Apple Screen Sharing support - including Mac OS X login, clipboard... Read more
DesktopLyrics 2.6.6 - Displays current i...
DesktopLyrics is an application that displays the lyrics of the song currently playing in "iTunes" right on your desktop. The lyrics for the song have to be set in iTunes; DesktopLyrics does nothing... Read more

What the Apple Watch Gets Right, and Wha...
| Read more »
Celebrate PAC-MAN's 35th Birthday W...
BANDAI NAMCO Entertainment America is celebrating PAC-MAN's 35th anniversary by releasing updates for PAC-MAN and PAC-MAN Lite for iOS. [Read more] | Read more »
Strike Wing Episode 2 has Landed on the...
Strike Wing: Raptor Rising is an exciting space combat simulator by Crescent Moon Games, which was recently updated to continue the story with Episode 2. [Read more] | Read more »
This Week at 148Apps: May 18-22, 2015
May Days at 148Apps How do you know what apps are worth your time and money? Just look to the review team at 148Apps. We sort through the chaos and find the apps you're looking for. The ones we love become Editor’s Choice, standing out above the... | Read more »
Biz Builder Delux (Games)
Biz Builder Delux 1.0.0 Device: iOS Universal Category: Games Price: $4.99, Version: 1.0.0 (iTunes) Description: Ah, there's nothing like the rhythmic bustle of a burgeoning business burg... especially when you're the one building it... | Read more »
Auroch Digital is Bringing Back Games Wo...
| Read more »
Blades of Brim is a New Endless Runner f...
SYBO Games, the minds behind the ever-popular Subway Surfers, have announced their latest project: Blades of Brim. [Read more] | Read more »
Carbo - Handwriting in the Digital Age...
Carbo - Handwriting in the Digital Age 1.0 Device: iOS Universal Category: Productivity Price: $3.99, Version: 1.0 (iTunes) Description: | Read more »
Draggy Dead (Games)
Draggy Dead 1.1 Device: iOS Universal Category: Games Price: $.99, Version: 1.1 (iTunes) Description: Ditch your dead end job and take up a rewarding career in Grave Robbing today!Guide the recently deceased to a fun filled life of... | Read more »
Bad Dinos (Games)
Bad Dinos 1.0.0 Device: iOS Universal Category: Games Price: $2.99, Version: 1.0.0 (iTunes) Description: | Read more »

Price Scanner via MacPrices.net

New 13-inch 2.9GHz Retina MacBook Pro on sale...
B&H Photo has the 13″ 2.9GHz/512GB Retina MacBook Pro on sale for $1699.99 including free shipping plus NY tax only. Their price is $100 off MSRP, and it’s the lowest price for this model from... Read more
12-inch MacBook stock status for Monday, May...
The new 12″ Retina MacBooks are still on backorder at The Apple Store with a 3-5 week waiting period. However, a few models are in stock today at Apple resellers. Stock is limited, so act now if you’... Read more
New 27-inch 3.3GHz 5K iMac in stock with free...
Adorama has the new 27″ 3.3GHz 5K iMac in stock today for $1999 including free shipping plus NY & NJ sales tax only. Adorama will include a free copy of Apple’s 3-year AppleCare Protection Plan. Read more
Memorial Day Weekend Sale: New 27-inch 3.3GHz...
Best Buy has the new 27″ 3.3GHz 5K iMac on sale for $1899.99 this weekend. Choose free shipping or free local store pickup (if available). Sale price for online orders only, in-store prices may vary... Read more
OtterBox Maximizes Portability, Productivity...
From the kitchen recipe book to the boarsroom presentation, the OtterBox Agility Tablet System turns tablets into one of the most versatile pieces of handheld technology available. Available now, the... Read more
Launch of New Car App Gallery and Open Develo...
Automatic, a company on a mission to bring the power of the Internet into every car, has announced the launch of the Automatic App Gallery, an app store for nearly every car or truck on the road... Read more
Memorial Day Weekend Sale: 13-inch 1.6GHz Mac...
Best Buy has the new 13″ 1.6GHz/128GB MacBook Air on sale for $849 on their online store this weekend. Choose free shipping or free local store pickup (if available). Sale price for online orders... Read more
Memorial Day Weekend Sale: 27-inch 3.5GHz 5K...
Best Buy has the 27″ 3.5GHz 5K iMac on sale for $2099.99 this weekend. Choose free shipping or free local store pickup (if available). Sale price for online orders only, in-store prices may vary.... Read more
Sale! 16GB iPad mini 3 for $349, save $50
B&H Photo has the 16GB iPad mini 3 WiFi on sale for $349 including free shipping plus NY sales tax only. Their price is $50 off MSRP, and it’s the lowest price available for this model. Read more
Price drop on 2014 15-inch Retina MacBook Pro...
B&H Photo has dropped prices on 2014 15″ Retina MacBook Pros by $200. Shipping is free, and B&H charges NY sales tax only: - 15″ 2.2GHz Retina MacBook Pro: $1799.99 save $200 - 15″ 2.5GHz... Read more

Jobs Board

Architect / Senior Software Engineer, *Apple...
Changing the world is all in a day039s work at Apple . If you love innovation, here039s your chance to make a career of it. You039ll work hard. But the job comes with Read more
*Apple* Pay Support Readiness Project Manage...
Changing the world is all in a day039s work at Apple . If you love innovation, here039s your chance to make a career of it. You039ll work hard. But the job comes with Read more
Hardware Design Validation Engineer - *Apple...
**Job Summary** The Apple Watch team is looking for a Hardware Design Validation Engineer. This person will be part of the Apple Watch hardware team with Read more
Sr. Payment Program Manager, *Apple* Pay -...
**Job Summary** Apple Pay is an exciting environment and a…devices in a simple, private and secure way. The Apple Pay Team is looking for an experienced Senior Read more
Project Manager / Business Analyst, WW *Appl...
…a senior project manager / business analyst to work within our Worldwide Apple Fulfillment Operations and the Business Process Re-engineering team. This role will work Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.