Category : Windows 3.X Files
Archive   : SPEXTN.ZIP
Filename : SPEXT.DOC

Documentation for Screen Peace saver extensions.

"Saver extensions" are simply Windows DLL's that are loaded by Screen Peace.
They use ".SPX" rather than ".DLL" as the file name extension.

You should compile the extension as a regular dll. Make sure to export all
the routines. The export number is unimportant.

example: sticks.def

LIBRARY sticks

EXETYPE WINDOWS

CODE PRELOAD MOVEABLE DISCARDABLE
DATA PRELOAD SINGLE

HEAPSIZE 1024

EXPORTS
WEP @1 RESIDENTNAME !!! This is a standard dll routine
saverinit @2
saverdraw @3
saverdlgproc @4
LibMain @5 !!! This is a standard dll routine

The LibMain routine is called by the LibEntry routine found in the file
LIBENTRY.ASM. This file is included in the Windows 3.0 SDK as a sample file
and must be linked in with the DLL. If you don't have this file, you can
write your own LibEntry routine. See the SDK documentation for more details.
LibMain is declared as follows:

int FAR PASCAL LibMain(HANDLE hModule,WORD wDataSeg,WORD cbHeapSize,
LPSTR lpszCmdLine);

The WEP routine is called by Windows when the saver DLL is unloaded. This
routine should deallocate everything allocated in the LibMain routine.
WEP is declared as follows:

int FAR PASCAL WEP (int bSystemExit);

In addition, the following three routines must be included in your
extension.


CHAR FAR * FAR PASCAL saverinit(BOOL far *enabled);

!!! MAY BE CALLED ANY NUMBER OF TIMES SO DON'T ALLOCATE ANYTHING HERE !!!
This function is called to see if the saver is enabled and to get the
name of the saver. You must return a far pointer to a string describing
the saver if you want the saver's name displayed in the list box in the
Options dialog. Make sure to return NULL otherwise or your saver may
kill the whole Screen Peace program.

vars:
enabled - set non-zero if the saver is enabled otherwise set to zero.

return:
a far pointer to the name of the saver.


BOOL FAR PASCAL saverdlgproc(HWND hdlg,unsigned message,WORD wparam,
LONG lparam);

Just a regular dialog proc. This gets called when the user double clicks
on the saver name in the Configure list box in the Options dialog. You
should perform any user customization in this routine.

NOTES: the Screen Peace Options dialog is both the parent and the owner
of the extension dialog.

the return value from the dialog is not used by Screen Peace.

DO NOT call the DefDlgProc from this dialog. Bad things will
happen.

If you want to have a dialog, you must give the dialog resource the
name "DIALOGBOX".

vars:
just a regular dialog proc.

VOID FAR PASCAL saverdraw(HWND hwnd,HDC hdc,HANDLE hinst,FARPROC yieldproc);

Called once each time the saver is invoked. This proc should consist of
a loop which first calls the yieldproc and then does any drawing. When
the yieldproc returns FALSE you should exit the loop.

NOTES: the screen is NOT "blacked out" before the call to the saverdraw
procedure. It is the responsibility of the extension to draw
EVERYTHING.

If you drop out of the saverdraw procedure, nothing more will be
drawn to the screen until the mouse is moved or clicked or a
key is hit. In other words, Screen Peace does NOTHING if the
extension it selects contains a saverdraw procedure.

The default brush for the window is guaranteed to be NULL upon
entry to saverdraw.

It is !!!VERY IMPORTANT!!! to call the yieldproc OFTEN. Windows
is DEAD, DEAD, DEAD while you're in your loop unless you call
this procedure. Windows will be completely locked up unless you
call this procedure.

vars:
hwnd - the window into which you should draw.
hdc - the dc into which you should draw.
hinst - handle to instance.
yieldproc - must be called often to allow Windows to "multitask"

yieldproc is defined as follows:

BOOL FAR PASCAL yieldproc(VOID)

returns TRUE if you should keep drawing or FALSE if you
should return. This may be called AFTER it has already
returned FALSE if you need to. It will continue to return FALSE
until the saver delay time has been passed again.


To make creating saver extensions easier, I've included a file called
NEWSAVER.EXE. This creates a skeleton screen saver that is ready to compile.
All it does is black out the screen. Type NEWSAVER FILENAME where
FILENAME is the name you want to use for the new saver's source files.
FILENAME should not include the '.' character or have any file extension.

An example screen saver extension project, STICKS, is also included because
I've always found that learning by example is the best way.


How to get in touch with me:

1. Write to:

Anthony Andersen
1211 S. Quebec Wy #3-108
Denver, CO 80231

2. Send Compuserve mail to:

[72037,2474]

3. Send mail on a BBS to:

User # /496 - Magnum BBS (805)582-9306
User # /74 - OS/2 Mag BBS (805)684-0589