home *** CD-ROM | disk | FTP | other *** search
/ Inside Multimedia 1995 July / IMM0795.ISO / share / os2 / ssaver14 / ssdll.hlp (.txt) < prev    next >
OS/2 Help File  |  1994-07-16  |  22KB  |  504 lines
  1.  
  2. ΓòÉΓòÉΓòÉ 1. About ScreenSaver ΓòÉΓòÉΓòÉ
  3.  
  4.                                    Version 1.4
  5.  
  6.  
  7.                      Copyright (C) 1993-94 Siegfried Hanisch
  8.  
  9.                      This program is dedicated to Michaela.
  10.  
  11.  
  12. Permission to copy and distribute this software and its documentation for any 
  13. purpose and without charging more than a nominal fee for copying is hereby 
  14. granted, provided that the above copyright notice appear in all copies and that 
  15. both that copyright notice and this permission notice appear in supporting 
  16. documentation.  This software is provided "as is" without express or implied 
  17. warranty. 
  18.  
  19. Please note that from version 1.3 on ScreenSaver is Shareware not Freeware. 
  20.  
  21. ScreenSaver is an easy-to-use 32-bit screen saver for OS/2 2.x. 
  22.  
  23. When ScreenSaver is started, it monitors your keyboard and mouse activity in 
  24. the backgound. If there has not been any activity for some time, the saver 
  25. becomes active. It stays active until the mouse is moved or clicked or a key is 
  26. pressed. You can set various options by double clicking ScreenSaver in the 
  27. window list (press Ctrl+Esc to show the window list). If you want to quit 
  28. ScreenSaver, press the "Exit ScreenSaver" button in the configuration panel. 
  29.  
  30. ScreenSaver has the advantage of low memory consumption and very low CPU usage 
  31. - this means virtually no performance impact on your normal work. 
  32.  
  33. ScreenSaver has a very modular structure: It searches its directory for saver 
  34. modules and selects a module randomly when the saver becomes active. Therefore 
  35. it is very easy to extend ScreenSaver by just copying new saver modules to its 
  36. directory. 
  37. Version 1.3 has now password protection similar to the OS/2 lockup feature. 
  38. It is now possible to use Deskpic modules with ScreenSaver. Just copy them to 
  39. the ScreenSaver directory. 
  40. Sample source code for do-it-yourself saver modules is included in the archive; 
  41. see Creating new saver modules for information on how to create your own 
  42. modules. 
  43. Even for people who don't know anything about programming it is possible to 
  44. create their own saver modules; see Creating bitmap saver modules for more 
  45. information. 
  46.  
  47. Related information: 
  48. Options dialog controls 
  49. Contacting the author 
  50. Registration 
  51.  
  52.  
  53. ΓòÉΓòÉΓòÉ 2. Options dialog controls ΓòÉΓòÉΓòÉ
  54.  
  55. The options dialog allows you to select various ScreenSaver options. The 
  56. settings take effect immediately. 
  57.  
  58. It contains the following controls: 
  59. Close button 
  60. Exit ScreenSaver button 
  61. Timeout slider 
  62. Saver now corner 
  63. Saver now corner enabled 
  64. Saver never corner 
  65. Saver never corner enabled 
  66. Configure module button 
  67. Test module button 
  68. Saver enabled check box 
  69. Mouse sensing check box 
  70. Available saver modules list box 
  71. Low priority check box 
  72. Monitor fullscreen sessions check box 
  73. Password push button 
  74.  
  75. Related information: 
  76. About ScreenSaver 
  77. Registration 
  78.  
  79.  
  80. ΓòÉΓòÉΓòÉ 2.1. Close button ΓòÉΓòÉΓòÉ
  81.  
  82. The "Close" button closes the Options dialog. You can also press the Hide 
  83. button in the top right corner of the dialog window. 
  84.  
  85. Related information: 
  86. Options dialog controls 
  87. About ScreenSaver 
  88.  
  89.  
  90. ΓòÉΓòÉΓòÉ 2.2. Exit ScreenSaver button ΓòÉΓòÉΓòÉ
  91.  
  92. Use the "Exit ScreenSaver" button to end ScreenSaver. You can also double click 
  93. the system menu or select Close from the system menu in the top left corner of 
  94. the dialog window. 
  95.  
  96. Related information: 
  97. Options dialog controls 
  98.  
  99.  
  100. ΓòÉΓòÉΓòÉ 2.3. Timeout slider ΓòÉΓòÉΓòÉ
  101.  
  102. With the "Timeout" slider you can adjust the time after which the saver becomes 
  103. active. 
  104.  
  105. Related information: 
  106. Options dialog controls 
  107.  
  108.  
  109. ΓòÉΓòÉΓòÉ 2.4. Saver now corner ΓòÉΓòÉΓòÉ
  110.  
  111. Use these radio buttons to select the corner of the screen into which you have 
  112. to move the mouse pointer to activate the saver immediately. 
  113.  
  114. Related information: 
  115. Options dialog controls 
  116.  
  117.  
  118. ΓòÉΓòÉΓòÉ 2.5. Saver now corner enabled ΓòÉΓòÉΓòÉ
  119.  
  120. With this check box you can enable and disable the "saver now" feature. 
  121.  
  122. Related information: 
  123. Saver now corner 
  124. Options dialog controls 
  125.  
  126.  
  127. ΓòÉΓòÉΓòÉ 2.6. Saver never corner ΓòÉΓòÉΓòÉ
  128.  
  129. With these radio buttons you can select the corner of the screen into which you 
  130. have to move the mouse pointer to temporarily disable monitoring mouse and 
  131. keyboard activity. 
  132.  
  133. Related information: 
  134. Options dialog controls 
  135.  
  136.  
  137. ΓòÉΓòÉΓòÉ 2.7. Saver never corner enabled ΓòÉΓòÉΓòÉ
  138.  
  139. With this check box you can enable and disable the "saver never" feature. 
  140.  
  141. Related information: 
  142. Saver never corner 
  143. Options dialog controls 
  144.  
  145.  
  146. ΓòÉΓòÉΓòÉ 2.8. Configure module button ΓòÉΓòÉΓòÉ
  147.  
  148. This button displays the configuration dialog of the saver module which is 
  149. selected in the list box. You can also double click on the list box item to 
  150. display the corresponding configuration dialog, too. Press the '+' or '-' keys 
  151. to directly enable or disable a saver module (this does not work for Deskpic 
  152. modules ). 
  153.  
  154. Related information: 
  155. Options dialog controls 
  156.  
  157.  
  158. ΓòÉΓòÉΓòÉ 2.9. Test module button ΓòÉΓòÉΓòÉ
  159.  
  160. This button activates the saver module that is selected in the list box. To 
  161. stop the test, either move the mouse or click a mouse button or press a key. 
  162.  
  163. Related information: 
  164. Options dialog controls 
  165.  
  166.  
  167. ΓòÉΓòÉΓòÉ 2.10. Saver enabled check box ΓòÉΓòÉΓòÉ
  168.  
  169. Use the "Saver enabled" check box to enable or disable screen saving. 
  170.  
  171. Related information: 
  172. Options dialog controls 
  173.  
  174.  
  175. ΓòÉΓòÉΓòÉ 2.11. Mouse sensing check box ΓòÉΓòÉΓòÉ
  176.  
  177. The "Mouse sensing" check box enables or disables monitoring of mouse movement 
  178. while the saver is active. This means, if mouse sensing is disabled and the 
  179. saver is active, the saver can only be stopped by pressing a key or clicking a 
  180. mouse button, but not by moving the mouse; this may be useful if you do not 
  181. want the saver to stop if you accidentially touch the mouse. 
  182.  
  183. Related information: 
  184. Options dialog controls 
  185.  
  186.  
  187. ΓòÉΓòÉΓòÉ 2.12. Available saver modules list box ΓòÉΓòÉΓòÉ
  188.  
  189. The "Available saver modules" list box shows all available saver modules. 
  190. Double clicking on a list box item displays the corresponding configuration 
  191. dialog. A plus sign in front of a module name means the module is enabled, a 
  192. minus sign means it is disabled. You can enable or disable a module in its 
  193. configuration dialog or by highlighting it and pressing '+' or '-' (this does 
  194. not work for Deskpic modules ). When the timeout interval expires, ScreenSaver 
  195. chooses one of the enabled saver modules randomly. If all modules are disabled, 
  196. the built-in "Eternal Blackness" module is used for screen saving. 
  197.  
  198. If you want another font in the list box, choose one from the font palette and 
  199. drag it into the list box. 
  200.  
  201. Related information: 
  202. Options dialog controls 
  203. About ScreenSaver 
  204. Contacting the author 
  205. Registration 
  206.  
  207.  
  208. ΓòÉΓòÉΓòÉ 2.13. Low priority check box ΓòÉΓòÉΓòÉ
  209.  
  210. Use the "Low priority" check box to decide wether the saver, when activated, 
  211. should run with low priority or normal priority. On low priority the saver gets 
  212. CPU time only when no other application requests CPU time. Normal priority 
  213. means the saver shares CPU usage with all other tasks; this means the animation 
  214. is smoother, but other applications may run slightly slower. Some saver module 
  215. animations may work considerably slower when low priority is disabled. 
  216.  
  217. Related information: 
  218. Options dialog controls 
  219.  
  220.  
  221. ΓòÉΓòÉΓòÉ 2.14. Monitor fullscreen sessions check box ΓòÉΓòÉΓòÉ
  222.  
  223. If monitoring of fullscreen sessions is enabled, ScreenSaver will switch from 
  224. an active fullscreen session to the Presentation Manager when the timeout 
  225. interval expires to do its saver action. When a key is pressed or the mouse is 
  226. moved, ScreenSaver switches back to the fullscreen session. 
  227.  
  228. In this version only OS/2 fullscreen sessions are monitored. DOS fullscreen 
  229. sessions and Win-OS/2 fullscreen sessions are not monitored. 
  230.  
  231. This option is not available on OS/2 2.0. 
  232.  
  233. Related information: 
  234. Options dialog controls 
  235.  
  236.  
  237. ΓòÉΓòÉΓòÉ 2.15. Password push button ΓòÉΓòÉΓòÉ
  238.  
  239. This button displays the password protection dialog. 
  240.  
  241. Related information: 
  242. Options dialog controls 
  243. Password protection dialog 
  244.  
  245.  
  246. ΓòÉΓòÉΓòÉ 3. Password protection dialog ΓòÉΓòÉΓòÉ
  247.  
  248. This dialog lets you change your password and enabled/disable password 
  249. protection and startup locking. 
  250.  
  251. In order to enable or disable password protection, you must enter the old 
  252. password. 
  253.  
  254. In order to enable or disable the "Lock on startup" feature, you must enter the 
  255. old password. 
  256.  
  257. In order to change your password, you must enter the old password and the new 
  258. password (enter the new password twice for verification). 
  259.  
  260. When you install ScreenSaver, the predefined password is 
  261. I will send money 
  262. to remind you to register ScreenSaver :-) 
  263. See also Registration 
  264.  
  265.  
  266. ΓòÉΓòÉΓòÉ 4. Creating your own saver modules ΓòÉΓòÉΓòÉ
  267.  
  268. The following two sections describe how to create saver modules: 
  269. Creating bitmap saver modules 
  270. Creating new saver modules 
  271.  
  272.  
  273. ΓòÉΓòÉΓòÉ 4.1. Creating bitmap saver modules ΓòÉΓòÉΓòÉ
  274.  
  275. Even for a non-programmer, it is VERY easy to create new bitmap saver modules. 
  276. There are six steps involved in doing so: 
  277.  
  278.  1. Open an OS/2 command session, change your working directory to the 
  279.     ScreenSaver directory, and make sure the files BITMAPS.RES, BITMAPS.SSM, 
  280.     BMPSAMP.RC and MAKEMOD.EXE are there. If they are not, unzip them from the 
  281.     file CUSTBMP.ZIP (CUSTBMP.ZIP can be found in the ScreenSaver distribution 
  282.     file). 
  283.  2. Get some pictures in bitmap format (*.BMP). 
  284.     You can create bitmaps by scanning photographs, you can convert existing 
  285.     pictures from other formats (*.GIF, *.TIF etc.) to bitmap format with 
  286.     appropriate software, or you can draw them yourself (with the OS/2 Icon 
  287.     Editor or Paintbrush or any other program that can handle bitmap files). 
  288.     Copy all the bitmaps you want to use to the ScreenSaver directory. 
  289.  3. Choose a name for the new saver module and a name for the file in which 
  290.     your saver is stored. The name for the file must be exactly 8 characters 
  291.     long; the name of the saver module should have a maximum length of 32 
  292.     characters. Now type "COPY BMPSAMP.RC FILENAME.RC" and press Enter (replace 
  293.     FILENAME with the file name you chose). Load the new file into an editor. 
  294.     You can use the OS/2 system editor E.EXE to edit the file. 
  295.  4. Replace the string "Custom Bitmaps" with the name you chose for your saver 
  296.     module. Do not change the number in front of the string. 
  297.  5. Insert lines with the name of your bitmap files. The lines must have the 
  298.     following format: 
  299.  
  300.         BITMAP     number  bitmap-file-name
  301.  
  302.     The numbers must be consecutive and in ascending order (in the first line 
  303.     inserted number must be 1, in the second 2 and so on). 
  304.     There is no limit on the number of bitmaps in your saver module. Now save 
  305.     the file and quit the editor. 
  306.  6. Type "MAKEMOD FILENAME" (again, replace FILENAME with the file name you 
  307.     chose) and press Enter. If everything is ok, MAKEMOD tells you that it 
  308.     created the new module. In case of an error, MAKEMOD prints an error 
  309.     message and some hints what you should do; it is most likely that you 
  310.     mistyped the name of a bitmap file. 
  311.     If module creation was successful you have to restart ScreenSaver. The name 
  312.     of the new module should be listed in the "Available saver modules" list 
  313.     box then. 
  314.  
  315. The following tutorial shows how to build a new bitmap module. 
  316. Assume that you want to use the three bitmaps ME.BMP, YOU.BMP and DOG_BOO.BMP; 
  317. you chose the name of the saver module to be "My Family" and the name of the 
  318. saver module file to be "MYFAMILY". 
  319. You enter 
  320.  
  321. COPY BMPSAMP.RC MYFAMILY.RC
  322.  
  323. at the command prompt. Then edit the new file (in this example we use the OS/2 
  324. system editor E.EXE) 
  325.  
  326. E MYFAMILY.RC
  327.  
  328. and change the file contents to look like this. 
  329.  
  330. The part of the file that is marked green  (the text between "/*" and "*/") is 
  331. a comment. You can include your own comments if you like. 
  332. The red text is the module name you insert and the cyan text are the lines 
  333. enumerating the bitmap files. The rest of the text has to be there; don't alter 
  334. it. Note that the name of the module and the names of the bitmap files have to 
  335. be enclosed in double quotation marks. 
  336.  
  337. /*
  338.     MYFAMILY.RC
  339.     resource file for custom bitmaps saver module
  340. */
  341. STRINGTABLE
  342. {
  343.     1    "My Family"
  344. }
  345. BITMAP    1    "ME.BMP"
  346. BITMAP    2    "YOU.BMP"
  347. BITMAP    3    "DOG_BOO.BMP"
  348.  
  349. Now save the file, quit the editor and type 
  350.  
  351. MAKEMOD MYFAMILY
  352.  
  353. at the command prompt. MAKEMOD prints a few messages as it works, and finally a 
  354. success message or a self-explanatory error message. 
  355. Now you restart ScreenSaver. The item "My Family" should appear in the list 
  356. box. 
  357.  
  358. Related information: 
  359. Creating new saver modules 
  360.  
  361.  
  362. ΓòÉΓòÉΓòÉ 4.2. Creating new saver modules ΓòÉΓòÉΓòÉ
  363.  
  364. You should have some experience with Presentation Manager programming and 
  365. knowledge of the C programming language to create your own saver modules. 
  366. The ScreenSaver archive comprises sample source code that shows you how to do 
  367. it. Unzip the files sample.c, sample.h, sample.rc, sample.dlg, sample.def and 
  368. sample.mak from the file SAMPLE.ZIP (SAMPLE.ZIP can be found in the ScreenSaver 
  369. distribution file) and copy these files to some other name of your choice (keep 
  370. the original extensions). If you compile and link in another directory than the 
  371. ScreenSaver directory, also copy the file SSAVER.ICO to your working directory. 
  372. Now take a look at these files. They are are commented and contain something 
  373. like 
  374.  
  375. /*
  376.     $$$$$ insert code here $$$$$
  377.     ... comment ...
  378.  
  379.     $$$$$ for example $$$$$
  380.     ... example code ...
  381. */
  382.  
  383. at those places where you should fill in your code. You can't miss it. Be sure 
  384. to read the comments before inserting your code. 
  385. In the "for example" sections of the comments you will find the source code of 
  386. the "Pyramids" saver module that comes with the ScreenSaver distribution. You 
  387. can use it as a template for creating your own saver modules. 
  388. After having successfully compiled your new module the first time, you can use 
  389. the Dialog Editor to edit the *.RES file and change the configure dialog if 
  390. required. 
  391. You should be able to use EMX0.8g (or higher) or the IBM compiler to build new 
  392. modules. Maybe other compilers work too, but I have not tested that. 
  393.  
  394. Now some explanations how a saver module works: 
  395. After the timeout occurred, the ScreenSaver program loads a saver module into 
  396. memory and makes it start screen saving. The saver module creates a window that 
  397. has the size of the whole screen. It then starts another thread (the one you 
  398. will have to write the code for) that draws anything it wants in this window; 
  399. see the sample code for more information. When the ScreenSaver program stops 
  400. the saver module, this thread ends, the window is destroyed and the saver 
  401. module is unloaded from memory. The idea is, that this independent thread can 
  402. run with idle time priority without considering any processing of PM messages. 
  403.  
  404. Related information: 
  405. Creating bitmap saver modules 
  406.  
  407.  
  408. ΓòÉΓòÉΓòÉ 5. Note for users of OS/2 2.1 ΓòÉΓòÉΓòÉ
  409.  
  410. There is a known bug in OS/2 2.1 which sometimes prevents applications from 
  411. saving their data to the OS/2 INI-files. Therefore, if you experience that the 
  412. ScreenSaver options are not saved correctly, please try the following solution: 
  413.  
  414. Add the line 
  415.  
  416. attrib -r x:\os2\os2*.ini
  417.  
  418. to the file x:\startup.cmd (x is the drive letter of your boot drive; if the 
  419. file x:\startup.cmd does not exist, create it) and reboot. 
  420.  
  421.  
  422. ΓòÉΓòÉΓòÉ 6. Using Deskpic modules ΓòÉΓòÉΓòÉ
  423.  
  424. It is now possible to use Deskpic modules with ScreenSaver. 
  425. Deskpic is a public domain OS/2 screen saver written by John Ridges. A lot of 
  426. saver modules exist for this program. They can be found at the usual locations 
  427. such as Internet FTP sites and BBSs. 
  428. The saver module files have the extension *.DSS. In order to use them with 
  429. ScreenSaver, just copy them into the ScreenSaver directory. 
  430. Deskpic modules are marked with "[Deskpic]" in the list box. The only 
  431. restriction is that you can not enable or disable them by pressing '+' or '-'; 
  432. you have to use the module configuration dialog to do so. 
  433.  
  434.  
  435. ΓòÉΓòÉΓòÉ 7. Contacting the author ΓòÉΓòÉΓòÉ
  436.  
  437. My mail address is 
  438.  
  439. Dipl.-Ing. Siegfried Hanisch 
  440. Einsiedlergasse 6/16 
  441. A - 1050 Vienna 
  442. AUSTRIA / EUROPE 
  443.  
  444. My Internet address is 
  445.  
  446. hanisch@ci.tuwien.ac.at 
  447.  
  448. Please send any suggestions, comments or bug reports to one of the above 
  449. addresses. 
  450.  
  451. If you have questions concerning the programming of new saver modules, please 
  452. contact me via e-mail. 
  453.  
  454. Related information: 
  455. Registration 
  456.  
  457.  
  458. ΓòÉΓòÉΓòÉ 8. Registration ΓòÉΓòÉΓòÉ
  459.  
  460. The registration fee for ScreenSaver is 20 US$ / 30 DM / 200 ATS. 
  461.  
  462. There are several ways to register ScreenSaver: 
  463.  
  464. o Send a cheque or cash to the following mail address: 
  465.  
  466.     Dipl.-Ing. Siegfried Hanisch
  467.     Einsiedlergasse 6/16
  468.     A - 1050 Vienna
  469.     AUSTRIA / EUROPE
  470.  
  471. o You can register by contacting BMT Micro : 
  472.  
  473.     By Mail:
  474.      BMT Micro
  475.      452 Horn Rd
  476.      Wilmington, NC 28412-2411
  477.      USA
  478.     By Phone:
  479.      (910) 791-7052   Voice
  480.      (800) 414-4268   Orders Only
  481.     By Fax:
  482.      (910) 350-2937
  483.     By BBS:
  484.      (910) 350-8061  (10 lines, all 14.4)
  485.      (910) 799-0923  (28.8 Line)
  486.  
  487.   BMT Micro accept Visa, Mastercard, Discover, Cashiers Checks, Money Orders, 
  488.   Personal Checks.  Payment must be in US Currency.  No cash please! 
  489.   No charge for 1st Class shipping anywhere in the world.  Priority shipping 
  490.   extra and will be explained when the order is placed. 
  491.  
  492. o For users in Austria only:  Sie k╨ñnnen den Betrag auch auf folgendes Konto 
  493.   ╨æberweisen:Bank Austria, BLZ 20151, Kto.Nr. 709353049, lautend auf Siegfried 
  494.   Hanisch.  Bitte teilen Sie mir auch Ihre e-mail- oder Post-Adresse mit, damit 
  495.   ich Ihnen die Registrierungsnummer zukommen lassen kann. 
  496.  
  497. o For users in Germany only:  Sie k╨ñnnen den Betrag auch auf folgendes Konto 
  498.   ╨æberweisen:Dresdner Bank, BLZ 76080040, Kto.Nr. 45422942, lautend auf 
  499.   Anneliese Hanisch.  Bitte teilen Sie mir auch Ihre e-mail- oder Post-Adresse 
  500.   mit, damit ich Ihnen die Registrierungsnummer zukommen lassen kann. 
  501.  
  502. Registered users receive a registration key. You can then enter the 
  503. registration information by typing 
  504. ssaver -r key Your Name