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

jAlbum Pro 12.6.4 - Organize your digita...
jAlbum Pro has all the features you love in jAlbum, but comes with a commercial license. With jAlbum, you can create gorgeous custom photo galleries for the Web without writing a line of code!... Read more
jAlbum 12.6.4 - Create custom photo gall...
With jAlbum, you can create gorgeous custom photo galleries for the Web without writing a line of code! Beginner-friendly, with pro results Simply drag and drop photos into groups, choose a design... Read more
Microsoft Remote Desktop 8.0.16 - Connec...
With Microsoft Remote Desktop, you can connect to a remote PC and your work resources from almost anywhere. Experience the power of Windows with RemoteFX in a Remote Desktop client designed to help... Read more
Spotify 1.0.4.90. - Stream music, create...
Spotify is a streaming music service that gives you on-demand access to millions of songs. Whether you like driving rock, silky R&B, or grandiose classical music, Spotify's massive catalogue puts... Read more
djay Pro 1.1 - Transform your Mac into a...
djay Pro provides a complete toolkit for performing DJs. Its unique modern interface is built around a sophisticated integration with iTunes and Spotify, giving you instant access to millions of... Read more
Vivaldi 1.0.118.19 - Lightweight browser...
Vivaldi browser. In 1994, two programmers started working on a web browser. Our idea was to make a really fast browser, capable of running on limited hardware, keeping in mind that users are... Read more
Stacks 2.6.11 - New way to create pages...
Stacks is a new way to create pages in RapidWeaver. It's a plugin designed to combine drag-and-drop simplicity with the power of fluid layout. Features: Fluid Layout: Stacks lets you build pages... Read more
xScope 4.1.3 - Onscreen graphic measurem...
xScope is powerful set of tools that are ideal for measuring, inspecting, and testing on-screen graphics and layouts. Its tools float above your desktop windows and can be accessed via a toolbar,... Read more
Cyberduck 4.7 - FTP and SFTP browser. (F...
Cyberduck is a robust FTP/FTP-TLS/SFTP browser for the Mac whose lack of visual clutter and cleverly intuitive features make it easy to use. Support for external editors and system technologies such... Read more
Labels & Addresses 1.7 - Powerful la...
Labels & Addresses is a home and office tool for printing all sorts of labels, envelopes, inventory labels, and price tags. Merge-printing capability makes the program a great tool for holiday... Read more

Discover Your Reflexes With Minimalist G...
Discover O, BYOF Studios, may look simple at first with its' color matching premise and swipe controls, but as you speed up the task becomes more daunting. [Read more] | Read more »
Here's Another Roundup of Notable A...
Now that the Apple Watch is publically available (kind of), even more apps and games have been popping up for it. Some of them are updates to existing software, others are brand new. The main thing is that they're all for the Apple Watch, and if you... | Read more »
Use Batting Average and the Apple Watch...
Batting Average, by Pixolini, is designed to help you manage your statistics. Every time you go to bat, you can use your Apple Watch to track  your swings, strikes, and hits. [Read more] | Read more »
Celebrate Studio Pango's 3rd Annive...
It is time to party, Pangoland pals! Studio Pango is celebrating their 3rd birthday and their gift to you is a new update to Pangoland. [Read more] | Read more »
Become the World's Most Important D...
Must Deliver, by cherrypick games, is a top-down endless-runner witha healthy dose of the living dead. [Read more] | Read more »
SoundHound + LiveLyrics is Making its De...
SoundHound Inc. has announced that SoundHound + LiveLyrics, will be one of the first third-party apps to hit the Apple Watch. With  SoundHound you'll be able to tap on your watch and have the app recognize the music you are listening to, then have... | Read more »
Adobe Joins the Apple Watch Lineup With...
A whole tidal wave of apps are headed for the Apple Watch, and Adobe has joined in with 3 new ways to enhance your creativity and collaborate with others. The watch apps pair with iPad/iPhone apps to give you total control over your Adobe projects... | Read more »
Z Steel Soldiers, Sequel to Kavcom'...
Kavcom has released Z Steel Soldiers, which continues the story of the comedic RTS originally created by the Bitmap Brothers. [Read more] | Read more »
Seene Lets You Create 3D Images With You...
Seene, by Obvious Engineering, is a 3D capture app that's meant to allow you to create visually stunning 3D images with a tap of your finger, and then share them as a 3D photo, video or gif. [Read more] | Read more »
Lost Within - Tips, Tricks, and Strategi...
Have you just downloaded Lost Within and are you in need of a guiding hand? While it’s not the toughest of games out there you might still want some helpful tips to get you started. [Read more] | Read more »

Price Scanner via MacPrices.net

Zoho Business Apps for Apple Watch Put Select...
Pleasanton, California based Zoho has launched Zoho Business Apps for Apple Watch, a line of apps that extends Zoho business applications to let users perform select functions from an Apple Watch.... Read more
Universal Stylus Initiative Launched to Creat...
OEMs, stylus and touch controller manufacturers have announced the launch of Universal Stylus Initiative (USI), a new organization formed to develop and promote an industry specification for an... Read more
Amazon Shopping App for Apple Watch
With the new Amazon shopping app for Apple Watch, Amazon customers with one of the wearable devices can simply tap the app on the watch to purchase items in seconds, or save an idea for later. The... Read more
Intel Compute Stick: A New Mini-Computing For...
The Intel Compute Stick, a new pocket-sized computer based on a quad-core Intel Atom processor running Windows 8.1 with Bing, is available now through Intel Authorized Dealers across much of the... Read more
Heal to Launch First One-Touch House Call Doc...
Santa Monica, California based Heal, a pioneer in on-demand personal health care services — will offer the first one-touch, on-demand house call doctor app for the Apple Watch. Heal’s Watch app,... Read more
Mac Notebooks: Avoiding MagSafe Power Adapter...
Apple Support says proper usage, care, and maintenance of Your Mac notebook’s MagSafe power adapter can substantially increase the the adapter’s service life. Of course, MagSafe itself is an Apple... Read more
12″ Retina MacBook In Shootout With Air And P...
BareFeats’ rob-ART morgan has posted another comparison of the 12″ MacBook with other Mac laptops, noting that the general goodness of all Mac laptops can make which one to purchase a tough decision... Read more
FileMaker Go for iPad and iPhone: Over 1.5 Mi...
FileMaker has announced that its FileMaker Go for iPad and iPhone app has surpassed 1.5 million downloads from the iTunes App Store. The milestone confirms the continued popularity of the FileMaker... Read more
Sale! 13-inch 2.7GHz Retina MacBook Pro for $...
 Best Buy has the new 2015 13″ 2.7GHz/128GB Retina MacBook Pro on sale for $1099 – $200 off MSRP. Choose free shipping or free local store pickup (if available). Price for online orders only, in-... Read more
Minimalist MacBook Confirms Death of Steve Jo...
ReadWrite’s Adriana Lee has posted a eulogy for the “Digital Hub” concept Steve Jobs first proposed back in 2001, declaring the new 12-inch MacBook with its single, over-subscribed USB-C port to be... Read more

Jobs Board

*Apple* Client Systems Solution Specialist -...
…drive revenue and profit in assigned sales segment and/or region specific to the Apple brand and product sets. This person will work directly with CDW Account Managers Read more
*Apple* Retail - Multiple Positions (US) - A...
Sales Specialist - Retail Customer Service and Sales Transform Apple Store visitors into loyal Apple customers. When customers enter the store, you're also the Read more
*Apple* Support Technician IV - Jack Henry a...
Job Description Jack Henry & Associates is seeking an Apple Support Technician. This position while acting independently, ensures the proper day-to-day control of Read more
*Apple* Client Systems Solution Specialist -...
…drive revenue and profit in assigned sales segment and/or region specific to the Apple brand and product sets. This person will work directly with CDW Account Managers Read more
*Apple* Software Support - Casper (Can work...
…experience . Full knowledge of Mac OS X and prior . Mac OSX / Server . Apple Remote Desktop . Process Documentation . Ability to prioritize multiple tasks in a fast pace Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.