The Desk Accessory (DA) is an open standard to provide a safe method of extending the Palm Computing Platform. Programs conforming to the standard are referred to as Desk Accessories.
This document outlines the basic specifications of the DA standard, programming for DAs, limitations in DA programming, and the recommended user-interface. DAs must be launched from "DA launchers" which are explained in a separate document. The DA website (http://member.nifty.ne.jp/yamakado/da/) is a good starting point for extra reading.
The document assumes that the reader has a working knowledge of programming applications for the Palm Computing Platform using C.
One well known method of extending the Palm Computing Platform is the "Hack". The Palm Computing Platform OS (PalmOS) was developed based on a wonderful concept, but did not provide developers with a method for extending the system.
By developing the "HackMaster" application and writing guidelines for programming "Hacks", Edward Keyes of DaggerWare provided an easy way of extending PalmOS without having to analyze the workings of the OS everytime.
The Hack patches traps to the OS. While it makes precise control of the OS possible, even a simple extension can result in slowdowns or instability. Developers have been forced to search for workarounds - often more work than the programming itself.
In the light of these events, Tatsushi Yamada (aka Hacker Dude-san) wrote the original DA Launcher and several sample DAs. DAs are small applications launched from the DA Launcher. The method and timing of launching DAs is controlled completely by the DA Launcher.
While each Hack results in an additional patch to the OS, the DA is unique in that only the Launcher patches the system. All of the DAs utilize that single patch, and hence do not suffer the conflicts that Hacks trying to patch the same trap run into. Once freed of the possibility that a separate, unrelated Hack may conflict and cause a Fatal Error, the developer can concentrate on the task of writing the functions themselves.
We recommend that only those extensions that directly affect the OS itself - and can only be written as Hacks - be written as hacks, and that the DA be used for everyday extensions that can be written as DAs.
Several examples of DAs are: memopad (reads and writes to the built-in Memo app database), small calculator, and an Uppercase-Lowercase converter. These functions allow the user to make small distractions from the parent application, without having to quit the parent application and completely interrupting the user's train of thought.
Other DAs include a screenshot DA, a DA to toggle display of "private" items, a time-table viewer, and a serial-keyboard driver. These DAs work with the parent applications, and are unique in that they are always available to extend the parent application.
As the above examples show, the DA is a useful extension that (1) allows the user to do a little work on the side without interrupting his main workflow or (2) extends the parent application without making actual changes to the parent application.
The DA, like any other Palm Computing Platform application or Hack, is stored as a database. Each DA must have a unique Creator ID. The DA's type is "DAcc".
The Startup Function
While regular Palm Computing Platform applications run the function PilotMain upon startup, DAs do not look for a specific function name (for example, DAMain). Instead, the function at the top of 'code ID=1000' is executed upon startup. This is because the DA Launcher launches the resource at 'code ID=1000' directly, rather than accessing a startup-code function. In other words, the startup function (equivalent to 'PilotMain' for apps) must be placed at the top of 'code ID=1000'. The startup function must be placed at the top of the source code, or if using CodeWarrior R4 or later, must be designated as the 'Entry Point' function in the Project. If the startup function is designated as the 'Entry Point' it can be placed anywhere within the source code. Since the function is not called by name, the name of the function can be "start()", "DAMain()" or whatever else the developer wishes to name it.
Variables
A DA can be launched at any time and coexist with other applications. To achieve this, the DA must share a common heap space with the running parent application. In other words, since the DA uses heap space left over from the parent application's allocated heap space, if the parent has already used much of the heap, there is that much less space left over for the DA. In the same manner, the DA must also share a common stack with the parent application. Some DA launchers allocate a separate stack for DA use. For example, the standard DA launcher 'DAL' allocates a stack of 2Kbytes for use by DAs. In programming DAs, do not use more than 2kbytes stack. Some DA launchers allow the user to change the allocated stack space, but the recommended stack is 2kbytes.
Reference: DA launchers that do allocate their own stack do so in the following way. Before launching a DA, the launcher stores the A7 register, allocates a predetermined amount of memory from the dynamic heap space as its own stack, and points A7 to that stack, therefore changing the memory space that the stack calls. When the DA quits running, the launcher frees the dynamic heap space and restores A7 to its previous value. Refer to the source code of one of the open DA launchers for the exact method.
Global and static variables CANNOT BE USED in DAs. When launching a DA, the launcher accesses the code at ID=1000 directly. Thus the content of the A5 register is not changed and still points to the parent application's global variable space. THE A5 REGISTER IS NOT ALLOCATED SEPARATELY FOR DAS. Compilers, in compiling DAs, do not assume the possibility of a conflict in the variable space. If a DA writes to the global variable space, it may overwrite some of the parent application's global variables and cause problems, including Fatal Errors, in the DA or the parent application after the DA quits.
Resource IDs
As has been stated before, the 'code' must have ID=1000. There are no specifications on the values that other resource IDs can have. There is no safe area (such as the IDs 1000 through 9999 for applications) reserved for DA use. If a DA resource should conflict with a resource in use by an application, or even the OS, the DA resource takes precedence. Therefore, while it is possible to use any arbitrary resource ID, it is generally a good idea to stay within the IDs recommended for applications, i.e. 1000 through 9999. Current DA launchers cannot display icons, so DAs do not need an Icon resource (tAIB). However, having such a resource does not harm the DA - future launchers may be able to display icons.
Some of the items listed here have already been mentioned in Section 2, they are important issues and warrant reiteration here.
The following guidelines are not mandatory. However, DAs following these guidelines have a consistent user interface, and can be easily used by users without the need for detailed documentation.
DAs are a safe method of extending the possibilities of the Palm Computing Platform. This document, and the many DAs whose source code has been released, should serve as reference for creating many more new DAs. If you write a new DA, be sure to release it for other users.
We look forward to many new DAs coming into the Palm community.
Enjoy!