home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: WPS_PM / WPS_PM.zip / DESKEXT.ZIP / DSSEXT.DOC < prev    next >
Text File  |  1990-04-30  |  5KB  |  107 lines
  1. Instructions for writing a Desktop Screen Saver Extension for DESKPIC.EXE
  2.  
  3.  
  4. Good for you! You've decided to write an Desktop Screen Saver Extension.
  5. What do you need to know to write an extension? Well, a pretty good working
  6. knowledge of Presentation Manager wouldn't hurt. These instructions will
  7. attempt to tell you how to write an extension, but they won't tell you how to
  8. program in PM. To help, an example extension is provided and is a good place
  9. to start. When I write a new extension, I usually use 'BOUNCE' as a
  10. framework and go from there.
  11.  
  12. A Desktop Screen Saver Extension is a Dynamic Link Library that contains
  13. three functions and has the file extension of '.DSS' instead of '.DLL'.
  14. The three functions must be exported with the following ordinals:
  15.  
  16.    saverstatus  @1
  17.    saverdialog  @2
  18.    saverthread  @3
  19.  
  20.  
  21. The three functions are specified by the following function prototypes:
  22.  
  23.    char far * far pascal _loadds saverstatus(SAVERBLOCK far *, BOOL far *);
  24.    MRESULT CALLBACK saverdialog(HWND, USHORT, MPARAM, MPARAM);
  25.    void far pascal _loadds saverthread(void);
  26.  
  27.  
  28. And the structure SAVERBLOCK is defined as follows:
  29.  
  30.    typedef struct {
  31.       HAB deskpichab;
  32.       HWND screenhwnd;
  33.       RECTL screenrectl;
  34.       ULONG volatile closesemaphore;
  35.       HMODULE thismodule;
  36.    } SAVERBLOCK;
  37.  
  38. The SAVERBLOCK structure is how DESKPIC provides the extension with
  39. information about its environment. The fields have the following meaning:
  40.  
  41. 'deskpichab' is the handle of the DESKPIC program's Anchor Block. This may
  42.    be needed by some OS/2 functions.
  43. 'screenhwnd' is the handle of the screen saver window. This will be needed
  44.    by 'saverthread' to get a Presentation Space to draw into.
  45. 'screenrectl' is the coordinates of the screen saver window.
  46. 'closesemaphore' is a memory semaphore that is used by 'saverthread' to
  47.    determine when to stop.
  48. 'thismodule' is the module handle of the Desktop Screen Saver Extension.
  49.    This will be needed to access any local resources.
  50.  
  51. The values of 'deskpichab' and 'thismodule' are always valid, but the values
  52. of 'screenhwnd', 'screenrectl', and 'closesemaphore' are only valid during
  53. the execution of 'saverthread'.
  54.  
  55.  
  56. saverstatus
  57.  
  58. This function is called by DESKPIC to get the name of the screen saver.
  59. DESKPIC passes a pointer to a SAVERBLOCK structure, and a pointer to a
  60. BOOL. The function should save the pointer to the SAVERBLOCK structure in
  61. global memory so that it can be accessed by the other two functions. The
  62. function should also indicate whether the screen saver is enabled by setting
  63. the BOOL to TRUE if enabled, and FALSE if disabled. When finished, the
  64. function should return a pointer to a zero terminated string which is the
  65. name of the Desktop Screen Saver Extension, or NULL if the screen saver has
  66. no name. Note that while DESKPIC will call this function before calling the
  67. other two, it may call this function multiple times. 
  68.  
  69.  
  70. saverdialog
  71.  
  72. This is a dialog procedure for the dialog that DESKPIC will invoke when
  73. the user chooses this screen saver from the list of Desktop Screen Saver
  74. Extensions. The dialog should allow the user to modify any parameters that
  75. the screen saver may have. The dialog template should be part of the
  76. resources of the Desktop Screen Saver Extension and should have a dialog
  77. template ID of 42. If 'saverstatus' returns NULL instead of a screen saver
  78. name, the dialog will never be invoked.
  79.  
  80.  
  81. saverthread
  82.  
  83. This procedure will be started as a separate thread when DESKPIC invokes
  84. the screen saver. The procedure should clear the screen and then display
  85. whatever graphics the screen saver employs until 'closesemaphore' in the
  86. SAVERBLOCK structure becomes non-zero. When 'closesemaphore' becomes
  87. non-zero, the procedure should release any resources it might have, enter
  88. a critical section using 'DosEnterCritSec', clear 'closesemaphore' using
  89. 'DosSemClear', and exit (in that order). It is important that the procedure
  90. respond quickly to 'closesemaphore' becoming non-zero so that users will
  91. not be delayed by the screen saver. The procedure should also get its own
  92. Anchor Block, since threads shouldn't make calls to the PM API without one.
  93. Note that stack space is limited, so any sizeable memory needed should be
  94. allocated at run time.
  95.  
  96.  
  97.  
  98. That completes the explanation. Where the instructions are a little sketchy,
  99. use the example source code to see at least one way of doing it. Good luck,
  100. and may the bits be with you.
  101.  
  102.  
  103. John Ridges
  104.  
  105. Gilmore /108 or Compuserve 72000,2057 (checked weekly)
  106. April 29, 1990
  107.