Programming
After Dark modules

Advanced Features

This section describes the advanced features available in After Dark and provides a complete description of all data structures and resources use. y After Dark. This section also explains how to create controls for graphics modules such as sliders, menus, text strings, check boxes, and buttons, how to include sound in your module, and how to add a "Help Box" to your module.

More About Messages

The function main() must be the first routine in your graphics module code resource. main() is passed a sequence of messages to direct its behavior:
Initialize
When this message is received, your module should allocate a Handle of memory and assign it to the parameter storage. This block of memory is used to store the graphics module's variables.

It is important to understand why variables might be stored this way. In many development systems a code resource cannot have global variables. If your development system does not support globals, a structure must be declared and memory allocated as in our example code. The fields of this structure can be any data type.

Remember, the storage handle is not locked down when it is passed to main() so it is the module's responsibility to lock the handle when necessary, and unlock it before returning.

Blank
When you receive the blank message, blank the screen if you want. Call your major animation routines when you receive the DrawFrame message.
DrawFrame
The frequency with which this message is received depends on how loaded down the system is. This is because After Dark tries to cooperate with the system by calling graphics modules only at idle times. In keeping with this philosophy, a graphics module should not try to do too much at one time.
Close
It is important to dispose of any memory you have allocated. If you do not, the Macintosh will think it has less memory available than it actually does. Each time your module is used, the memory available to your Macintosh will decrease.
ButtonMessage
If a user clicks on a button in the Control Panel (buttons are described in the section "Control Resources"), the message ButtonMessage is passed to main(). The value of ButtonMessage depends on which button was hit. The value of each button is distinct and is defined in a resource. All messages with a value of 8 or greater are button messages. In the example code, ButtonMessage is handled by the DoSetup() function.

The graphics module could use this kind of message to open a dialog box allowing the user to set values not easily handled by sliders, menus, or check boxes. A button could allow the user to select a color from the "Color Picker" or choose a picture from a scrapbook, for example.

ModuleSelected
After Dark can send this message to your module when a user selects it in the Control Panel. This feature can be used to setup your module's controls before they are displayed. For example, a menu of the fonts in the system can be built when your module is selected.

To receive this message, add the 'Cals' resource to your module and set it as described in the "Graphics Module Resources" section.

DoHelp
As described in the "Graphics Module Resources" section, modules may include a "Help Box" that provides the user with additional information or help. The "Help Box" is displayed when the user clicks in the "Credits" area. While no programming is necessary to display text or a picture, your module may want to handle the display itself (MultiModule does this).

As above, to receive this message, add a 'Cals' resource to your module and set it as described in the "Graphics Module Resources" section.

Graphics Module Return Values

Normally a graphics module returns the OSErr type value noErr. There are two conditions where this will not be the case:

Errors
In DoInitialize() a graphics module usually attempts to allocate memory. If there is an error in allocating the storage, the graphics module should return the value ModuleError (defined as integer value -1). If errors occur on later calls, the graphics module should dispose of any memory allocated and return this error value to After Dark.

Special Values
There are three special values that the graphics module can use to ask After Dark to perform certain functions.

Returning the value RestartMe (defined as the integer value 1) tells After Dark to restart the graphics module immediately with an Initialize message without an intervening Close message. The graphics module should close itself before returning this value. The graphics module might use this service if it finds that it has been passed changing parameters that require it to reallocate storage.

Returning the value ImDone (defined as the integer value 2) tells After Dark to take over the drawing. The graphics module uses this when it is done drawing but wants something else to happen on the screen.

Returning the value RefreshResources (defined as the integer value 3) updates all sliders, buttons, check boxes, menus, and text strings in the Control Panel to their values in the module's resource file. This allows you to change the items in a menu or the values of text strings in your module's resource file and have these changes immediately reflected in the Control Panel. This value should only be returned in response to ButtonMessage or ModuleSelected.

Next

Begin | Introduction | Getting Started | main() | Advanced | Parameters | Sound | Resources | Hints & Tips | Further Info