AfterDark SDK
Copyright (C) Richard R. Sands CIS 70274,103
All rights reserved

Translated from the C SDK from Berkeley Systems
Copyright (C) Berkeley Systems
All rights reserved


This program is Public Domain. I only ask that if you successfully write a
module, please send me a copy of the .AD file.

If you have any questions regarding this document or the writing After Dark
modules themselves, please feel free to mail me.


------------------------------------------------------------------------------
OVERVIEW
--------
This is a Software Development Kit for Pascal to support writing modules for
the After Dark Screen Savers. It is object oriented so writing the modules
is easier than doing it in C, and maintanence of those modules is safer /
easier than with the C SDK.

This unit exports two primary items: the AD object called tAfterDark and
a procedure called "module" that you must export in your program. The
tAfterDark object handles all initialization, messages, and control values
from the AD system. As an object, it provides several virtual methods that
you may override depending on the complexity of your saver. Each method
corresponds to a message that the main AD program sends to the applications
and are documented in the After Dark manual and the C code. I tried to keep
the types, constants, and (some) variable names the same as in the C SDK so
the C docuementation could also double as the Pascal SDK doc.


------------------------------------------------------------------------------
COMPILING AND SETUP
-------------------
The recommended directory structure is (APP should be your module name):

C:\AFTERDRK\PASDK
AfterDark.Pas - tAfterDark object
AfterDark.Doc - documentation
C:\AFTERDRK\PASDK\YourApp
App pas - Your Pascal Application Code
App dll - Compiled DLL

mak bat - Batch File to create .AD module
App def - You must change first line to your module
name
App rc - Resource script - Never need to change
res_ids h - Resource include file
cstr rsc - ADRES Resource
ctrl1 rsc - " "
ctrl2 rsc - " "
ctrl3 rsc - " "
ctrl4 rsc - " "
cwin rsc - " "
mname rsc - " "
App res - Compiled Resource
mak2 bat - Advanced MAKE batch file
Apppas res - Additional Resource file


The contents of MAK.BAT
------------------------
del APP.ad
REM add -V to see messages...
rc APP.rc APP.dll
copy APP.dll c:\afterdrk\APP.ad


The contents of APP.DEF (First lines changes only)
--------------------------------------------------
LIBRARY APP
DESCRIPTION 'Graphics Module Library'
EXETYPE WINDOWS
STUB 'WINSTUB.EXE'
CODE MOVEABLE
DATA MOVEABLE SINGLE
HEAPSIZE 1024
EXPORTS Module @1
WEP @2 RESIDENTNAME


Normal module creation steps
----------------------------
1. Make a directory under PASDK and copy the files listed above into it.

2. Write your library in Pascal
There is no need for the $R directive since you need to run MAK.BAT
anyway. However, you do need $R if you are going to add your own
resources. (See next part.)

3. Edit the MAK.BAT file and APP.DEF file to contain the correct
application names.

4. Write/Edit your resources with ADRES.EXE

5. Compile the Pascal.

6. Run the MAK batch file.
In my Program Manager group, in addition to having my APP as an icon,
I also have the batch file. This way I can just double click the
batch file and proceed to the next step.

7. Test your Module.
Press the control key and double click the After Dark icon to reload
all of the modules.

8. Repeat steps 4 through 7 until a good module has hatched!


Adding your own resources to the Resource file
----------------------------------------------
Since RC.EXE destroys the existing resource file, you must create you
resources in a second resource file. Use WRT (or whatever) to create a new
resource file. Use ADRES.EXE to create the "standard" application resource
file. Compile your module as in the steps above to get RC.EXE to create a
new APP.RES file. Then use WRT to copy your resources into the APP.RES file.
Now place a statement at the top of your module: {$R APP.RES}. Now rather
than use MAK.BAT, use MAK2.BAT. MAK2.BAT contains one line:

copy APP.dll c:\afterdrk\APP.ad

As long as you do not run RC.EXE you can modify your own resources as often
as you like. However, if you do modify the ADRES.EXE resources and run
RC.EXE via MAK.BAT, you must recopy your special resources back into the
APP.RES file via WRT.

This procedure sounds more complicated as it is because we are bootstrapping
ourselves. When actually done, it is as simple as using the normal method
of building a AD application - if fact, it's faster.


------------------------------------------------------------------------------
TAFTERDARK OBJECT
-----------------

TYPE
PAfterDark = ^TAfterDark;
TAfterDark = object
DC: hDC; { Provided Display Context }
lpSystemAD: pAdSystem; { Pointer to AD System Param Block }
lpModule : pAdModule; { Pointer to Module's Parameters }
constructor Init;
destructor Done; virtual;
function DoPreInitialize:Integer; virtual;
function DoInitialize:Integer; virtual;
function DoBlank: Integer; virtual;
function DoDrawFrame: Integer; virtual;
function DoClose: Integer; virtual;
function DoSelected: Integer; virtual;

function DoAbout:Integer; virtual;
function DoButtonMessage1(Value:Integer):Integer; virtual;
function DoButtonMessage2(Value:Integer):Integer; virtual;
function DoButtonMessage3(Value:Integer):Integer; virtual;
function DoButtonMessage4(Value:Integer):Integer; virtual;
end;

function Module(iMessage:Integer; hDrawDC:hDC; AdSystem:THandle):Integer; EXPORT;


------------------------------------------------------------------------------
Module
------
Purpose : The message dispatcher for After Dark.

Declaration:
function Module(iMessage:Integer; hDrawDC:hDC;
AdSystem:THandle):Integer; EXPORT;

Comments : This routine handles all messages from the After Dark program.
It will decipher the messages and call the correct tAfterDark
object method. You must place the statement

EXPORTS Module;

in your module so the DLL is correctly compiled. Other than
that, you need to nothing.


------------------------------------------------------------------------------
tAfterDark.Init
---------------
Purpose : Initializes the Pascal SDK Module

Declaration:
constructor Init;

Override : Rarely. This should only be called once in the modules mainline
routine.

Comments : All this routine does is "hook" in the module to After Dark.
It should not do any other initialization (See the
DoPreInitialize/DoInitialize methods)

See Also : Done, DoPreInitialize, DoInitialize, DoClose


------------------------------------------------------------------------------
tAfterDark.Done
---------------
Purpose : Called during the WEP routine.

Declaration:
destructor Done; virtual;

Override : Rarely.

Comments : This is called by the Windows Exit Proc. It is for any tasks
that need to be done when the module is unloaded. Normally, you
do not need to perform any actions here.

See Also : DoClose


------------------------------------------------------------------------------
tAfterDark.DoPreInitialize
--------------------------
Purpose : Called whenever the Windows is about to go to "sleep".

Declaration:
function DoPreInitialize:Integer; virtual;

Override : Often.

Comments : This method should reset the value of any variables you need to
operate your module. You should not allocate memory here, since
it is called many times without a corresponding "cleanup"
routine.

See Also : DoInitialize


------------------------------------------------------------------------------
tAfterDark.DoInitialize
-----------------------
Purpose : Called when the module is loaded into memory.

Declaration:
function DoInitialize:Integer; virtual;

Override : Often.

Comments : This method should allocate memory for your application, and set
the initial values of any variables your module requires. This
will always have a matching DoClose called so you may deallocate
your memory here.

See Also : DoClose


------------------------------------------------------------------------------
tAfterDark.DoClose
------------------
Purpose : Cleanup Method. Called when the module is unloaded from memory.

Declaration:
function DoClose:Integer; virtual;

Override : Often.

Comments : This method should deallocate any memory your application had
allocated. It is called once. This is where you may write
your control values to the AD_PREFS.INI file.

See Also : DoInitialize


------------------------------------------------------------------------------
tAfterDark.DoBlank
------------------
Purpose : Called when After Dark requests a blank screen

Declaration:
function DoBlank:Integer; virtual;

Override : Once in awhile.

Comments : This should blank the screen upon request from After Dark if
your module allows it. If you override this method, you must
call it's ancestor tAfterDark.DoBlank since this method also
sets up your control values.


------------------------------------------------------------------------------
tAfterDark.DoDrawFrame
----------------------
Purpose : Called repeatedly when Windows is "sleeping".

Declaration:
function DoDrawFrame:Integer; virtual;

Override : Always (for all practical purposes).

Comments : This is the work-horse method. It is responsible for actually
drawing the screen animation. You should do as little work as
possible so windows remains "lively".


------------------------------------------------------------------------------
tAfterDark.DoSelected
---------------------
Purpose : Called whenever your module is selected from the control panel.

Declaration:
function DoSelected:Integer; virtual;

Override : Once in awhile.

Comments : This routine allows you to disable/enable your controls.


------------------------------------------------------------------------------
tAfterDark.DoAbout
------------------
Purpose : Called when the "About" window in the Control Panel is
activated.

Declaration:
function DoAbout:Integer; virtual;

Override : Once in awhile.

Comments : This allows you to animate (or whatever) you about screen.
Normally, After Dark will display your module information with
whatever you have placed via the ADRES.EXE program, however,
this allows you to perform more tasks.


------------------------------------------------------------------------------
tAfterDark.DoButtonMessageX
---------------------------
Purpose : These are called whenever your module's controls are moved by
the user.

Declaration:
function DoButtonMessage1(Value:Integer):Integer; virtual;
function DoButtonMessage2(Value:Integer):Integer; virtual;
function DoButtonMessage3(Value:Integer):Integer; virtual;
function DoButtonMessage4(Value:Integer):Integer; virtual;

Override : Often.

Comments : These routines will give you the value of the controls whenever
the user moves the controls via the control panel.

See also : DoBlank