ProfitPress Mega CDROM2 …eeware (MSDOS)(1992)(Eng)/ProfitPress-MegaCDROM2.B6I/WINDOWS/MISC/SPEXTN.ZIP/SPEXT.DOC

Text File | 1990-06-16 | 5.3 KB | 150 lines

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     [phone]
       User # /74  - OS/2 Mag BBS   [phone]