The main() Function

Programming
After Dark modules

The `main()` Function

When the function main() is called, four parameters are passed:

storage: A handle to storage allocated by the graphics module. This memory is used to store variables used by the module.
blankRgn: A handle to the region the graphics module is allowed to draw in. This region encompasses the screens of all attached monitors. Drawing is clipped to this region.
message: This value tells the graphics module which task After Dark wants it to perform.
params: This value points to a structure that contains information about the Macintosh that After Dark is running on. It also contains the values of any controls the module has created. The fields of this structure are described in depth in "Advanced Features."

Note: all examples in the manual are in Pascal. Examples in C are on the After Dark disk.

The function main() is defined as:

function main ( VAR  storage:  Handle;
                     blankRgn: RgnHandle;
                     message:  Integer;
                     params:   GMParamBlockPtr;) : OSErr;

main() acts as a "dispatcher." It looks at the message passed and calls a function to perform the task specified in the message. Messages are passed in a specific order.

On the After Dark disk, we provide a sample main() function that you can use as-is. To use our sample main() function, just write your own routines DoInitialize(), DoBlank(), DoDrawFrame(), and DoClose() as described briefly in the next section. Link them with main() to make a code resource of type 'ADgm'. Put the resource in a file of type 'ADgm' and creator 'ADrk'. Your module is ready to run.

Message Calling Sequence

When a user invokes After Dark, the function main() is called repeatedly. In the example code, main() calls a different message handling function for each message. The messages are (in order passed):

Initialize: main() calls your function DoInitialize(). This function should allocate memory needed by the graphics module and initialize the module's variables. The graphics module should allocate a Handle to a block of memory that it will use to hold any variables it needs. It should then assign it to the parameter storage. No drawing should be done at this time.
Blank: main() calls your function DoBlank(). This function should blank the screen. A banner titling the graphics module or giving credit to its author might be drawn here. No further drawing should happen.
DrawFrame: main() calls your function DoDrawFrame(). This function is responsible for drawing the animation on the screen. It is called repeatedly and should draw the next frame of the animation sequence. The basic idea is to "erase old, draw new."
Close: main() calls your function DoClose(). At this point, the screen saver is finished. Any memory allocated should be disposed of and any other "house cleaning" should be performed. Drawing is allowed, but your module should return quickly since the user is waiting to regain control. After Dark handles updating the screen.

A graphics module may call any of the routines documented in Inside Macintosh with one exception. Calls to the Window Manager and Palette Manager are not recommended since After Dark does not draw into a window.

The Next Step

If you are ready to build a simple graphics module, go for it! With this information you should be able to build a basic screen saver. Try using the source code included on the disk as a starting point. If you want to learn more about the features of After Dark, read on.

ProgrammingAfter Dark modules