Topic       : The ATARI Compendium
Author      : Scott Sanders / JAY Software
Version     : 1.25 (20/6/2003)
Subject     : Documentation
Nodes       : 1117
Index Size  : 32614
HCP-Version : 6
Compiled on : Atari
@charset    : UTF-8
@lang       : en
@default    : 
@help       : %About
@options    : +g -i -t4 +y +z
@width      : 100
View Ref-File
                              Desk Accessories


Upon bootup, any files with the extension '.ACC' found in the root
directory of the user's boot drive will be loaded and executed up until
their first event library call. MultiTOS allows desk accessories to be
loaded and unloaded after bootup.

Unlike applications, desk accessories are not given all of available
system memory on startup. They are only allocated enough memory for their
text, data, and bss segments. No stack space is allocated for a desk
accessory either. Many high level language stubs reserve space in the BSS
or overwrite startup code to provide a stack but keep in mind that desk
accessory stacks are usually small compared to applications.

As with applications, GEM desk accessories should begin with an
appl_init() function call. Upon success, the ID should be stored and used
within a menu_register() call to place the applications' name on the menu
bar.

Desk accessories, unlike applications, do not begin user interaction
immediately. Most desk accessories initialize themselves and enter
a message loop waiting for an AC_OPEN message. Some desk accessories wait
for timer events or custom messages from another application. After being
triggered, they usually open a window in which user interaction may be
performed (dialogs and alerts may also be presented but are not
recommended because they prevent shuffling between other system
processes).

Desk accessories should not use a menu bar and should never exit (unless
appl_init() fails) after calling menu_register(). If an error condition
occurs which would make the accessory unusable, simply enter an indefinite
message loop.

Any resources loaded by an accessory should be loaded prior to entering
the first event loop and should never be freed after the accessory has
called menu_register(). Resource data for desk accessories should be
embedded in the executable rather than being soft-loaded because memory
allocated to a desk accessory is not freed during a resolution change on
TOS versions less than 2.06. This causes resource memory allocated by
rsrc_load() to be lost to the system after a resolution change and will
likely cause memory fragmentation.

An AC_CLOSE message is sent to an accessory when it is being closed at
the request of the OS. At this point, it should perform any cleanup
necessary to release system resources and close files opened at AC_OPEN
(accessory windows will be closed automatically by the AES). After
cleanup, the event loop should be reentered to wait for subsequent
AC_OPEN messages.

The following code represents a basic skeleton for an AES desk accessory.