OS/2 Professional/OS2PRO194.ISO/os2/wps/utils/scrnsave/ssaver11/ssdll.hlp

OS/2 Help File | 1993-12-14 | 17.5 KB | 404 lines

ΓòÉΓòÉΓòÉ 1. About ScreenSaver ΓòÉΓòÉΓòÉ

                                   Version 1.1


                      Copyright (C) 1993 Siegfried Hanisch


Permission to use, copy and distribute this software and its documentation for
any purpose and without charging more than a nominal fee for copying is hereby
granted, provided that the above copyright notice appear in all copies and that
both that copyright notice and this permission notice appear in supporting
documentation.  This software is provided "as is" without express or implied
warranty.

ScreenSaver is an easy-to-use 32-bit screen saver for OS/2 2.x.

When ScreenSaver is started, it monitors your keyboard and mouse activity in
the backgound. If there has not been any activity for some time, the saver
becomes active. It stays active until the mouse is moved or clicked or a key is
pressed. You can set various options by double clicking ScreenSaver in the
window list (press Ctrl+Esc to show the window list). If you want to quit
ScreenSaver, press the "Exit ScreenSaver" button in the configuration panel.

ScreenSaver has the advantage of low memory consumption and very low CPU usage
- this means virtually no performance impact on your normal work.

ScreenSaver has a very modular structure: It searches its directory for saver
modules and selects a module randomly when the saver becomes active. Therefore
it is very easy to extend ScreenSaver by just copying new saver modules to its
directory.
Sample source code for do-it-yourself saver modules is included in the archive;
see Creating new saver modules for information on how to create your own
modules.
Even for people who don't know anything about programming it is possible to
create their own saver modules; see Creating bitmap saver modules for more
information.

Related information:
Options dialog controls
Note for users of OS/2 2.1
Contacting the author


ΓòÉΓòÉΓòÉ 2. Options dialog controls ΓòÉΓòÉΓòÉ

The options dialog allows you to select various ScreenSaver options. The
settings take effect immediately.

It contains the following controls:
Close button
Exit ScreenSaver button
Timeout slider
Saver now corner
Saver now corner enabled
Saver never corner
Saver never corner enabled
Configure module button
Test module button
Saver enabled check box
Mouse sensing check box
Available saver modules list box
Low priority check box
Monitor fullscreen sessions check box

Related information:
About ScreenSaver
Note for users of OS/2 2.1


ΓòÉΓòÉΓòÉ 2.1. Close button ΓòÉΓòÉΓòÉ

The "Close" button closes the Options dialog. You can also press the minimize
button in the top right corner of the dialog window.

Related information:
Options dialog controls
Note for users of OS/2 2.1
About ScreenSaver


ΓòÉΓòÉΓòÉ 2.2. Exit ScreenSaver button ΓòÉΓòÉΓòÉ

Use the "Exit ScreenSaver" button to end ScreenSaver. You can also double click
the system menu or select Close from the system menu in the top left corner of
the dialog window.

Related information:
Options dialog controls


ΓòÉΓòÉΓòÉ 2.3. Timeout slider ΓòÉΓòÉΓòÉ

With the "Timeout" slider you can adjust the time after which the saver becomes
active.

Related information:
Options dialog controls


ΓòÉΓòÉΓòÉ 2.4. Saver now corner ΓòÉΓòÉΓòÉ

Use these radio buttons to select the corner of the screen into which you have
to move the mouse pointer to activate the saver immediately.

Related information:
Options dialog controls


ΓòÉΓòÉΓòÉ 2.5. Saver now corner enabled ΓòÉΓòÉΓòÉ

With this check box you can enable and disable the "saver now" feature.

Related information:
Saver now corner
Options dialog controls


ΓòÉΓòÉΓòÉ 2.6. Saver never corner ΓòÉΓòÉΓòÉ

With these radio buttons you can select the corner of the screen into which you
have to move the mouse pointer to temporarily disable monitoring mouse and
keyboard activity.

Related information:
Options dialog controls


ΓòÉΓòÉΓòÉ 2.7. Saver never corner enabled ΓòÉΓòÉΓòÉ

With this check box you can enable and disable the "saver never" feature.

Related information:
Saver never corner
Options dialog controls


ΓòÉΓòÉΓòÉ 2.8. Configure module button ΓòÉΓòÉΓòÉ

This button displays the configuration dialog of the saver module which is
selected in the list box. You can also double click on the list box item to
display the corresponding configuration dialog, too. Press the '+' or '-' keys
to directly enable or disable a saver module.

Related information:
Options dialog controls


ΓòÉΓòÉΓòÉ 2.9. Test module button ΓòÉΓòÉΓòÉ

This button activates the saver module that is selected in the list box. To
stop the test, either move the mouse or click a mouse button or press a key.

Related information:
Options dialog controls


ΓòÉΓòÉΓòÉ 2.10. Saver enabled check box ΓòÉΓòÉΓòÉ

Use the "Saver enabled" check box to enable or disable screen saving.

Related information:
Options dialog controls


ΓòÉΓòÉΓòÉ 2.11. Mouse sensing check box ΓòÉΓòÉΓòÉ

The "Mouse sensing" check box enables or disables monitoring of mouse movement
while the saver is active. This means, if mouse sensing is disabled and the
saver is active, the saver can only be stopped by pressing a key or clicking a
mouse button, but not by moving the mouse; this may be useful if you do not
want the saver to stop if you accidentially touch the mouse.

Related information:
Options dialog controls


ΓòÉΓòÉΓòÉ 2.12. Available saver modules list box ΓòÉΓòÉΓòÉ

The "Available saver modules" list box shows all available saver modules.
Double clicking on a list box item displays the corresponding configuration
dialog. A plus sign in front of a module name means the module is enabled, a
minus sign means it is disabled. You can enable or disable a module in its
configuration dialog or by highlighting it and pressing '+' or '-'. When the
timeout interval expires, ScreenSaver chooses one of the enabled saver modules
randomly. If all modules are disabled, the built-in "Eternal Blackness" module
is used for screen saving.

Related information:
Options dialog controls
Note for users of OS/2 2.1
About ScreenSaver


ΓòÉΓòÉΓòÉ 2.13. Low priority check box ΓòÉΓòÉΓòÉ

Use the "Low priority" check box to decide wether the saver, when activated,
should run with low priority or normal priority. On low priority the saver gets
CPU time only when no other application requests CPU time. Normal priority
means the saver shares CPU usage with all other tasks; this means the animation
is smoother, but other applications may run slightly slower. Some saver module
animations may work considerably slower when low priority is disabled.

Related information:
Options dialog controls


ΓòÉΓòÉΓòÉ 2.14. Monitor fullscreen sessions check box ΓòÉΓòÉΓòÉ

If monitoring of fullscreen sessions is enabled, ScreenSaver will switch from
an active fullscreen session to the Presentation Manager when the timeout
interval expires to do its saver action. When a key is pressed or the mouse is
moved, ScreenSaver switches back to the fullscreen session.

In this version only OS/2 fullscreen sessions are monitored. DOS fullscreen
sessions and Win-OS/2 fullscreen sessions are not monitored.

This option is not available on OS/2 2.0.

Related information:
Options dialog controls


ΓòÉΓòÉΓòÉ 3. Creating your own saver modules ΓòÉΓòÉΓòÉ

The following two sections describe how to create saver modules:
Creating bitmap saver modules
Creating new saver modules


ΓòÉΓòÉΓòÉ 3.1. Creating bitmap saver modules ΓòÉΓòÉΓòÉ

Even for a non-programmer, it is VERY easy to create new bitmap saver modules.
There are six steps involved in doing so:

 1. Open an OS/2 command session, change your working directory to the
    ScreenSaver directory, and make sure the files BITMAPS.RES, BITMAPS.SSM,
    BMPSAMP.RC and MAKEMOD.EXE are there. If they are not, unzip them from the
    file CUSTBMP.ZIP (CUSTBMP.ZIP can be found in the ScreenSaver distribution
    file).
 2. Get some pictures in bitmap format (*.BMP).
    You can create bitmaps by scanning photographs, you can convert existing
    pictures from other formats (*.GIF, *.TIF etc.) to bitmap format with
    appropriate software, or you can draw them yourself (with the OS/2 Icon
    Editor or Paintbrush or any other program that can handle bitmap files).
    Copy all the bitmaps you want to use to the ScreenSaver directory.
 3. Choose a name for the new saver module and a name for the file in which
    your saver is stored. The name for the file must be exactly 8 characters
    long; the name of the saver module should have a maximum length of 32
    characters. Now type "COPY BMPSAMP.RC FILENAME.RC" and press Enter (replace
    FILENAME with the file name you chose). Load the new file into an editor.
    You can use the OS/2 system editor E.EXE to edit the file.
 4. Replace the string "Custom Bitmaps" with the name you chose for your saver
    module. Do not change the number in front of the string.
 5. Insert lines with the name of your bitmap files. The lines must have the
    following format:

        BITMAP  number  bitmap-file-name

    The numbers must be consecutive and in ascending order (in the first line
    inserted number must be 1, in the second 2 and so on).
    There is no limit on the number of bitmaps in your saver module. Now save
    the file and quit the editor.
 6. Type "MAKEMOD FILENAME" (again, replace FILENAME with the file name you
    chose) and press Enter. If everything is ok, MAKEMOD tells you that it
    created the new module. In case of an error, MAKEMOD prints an error
    message and some hints what you should do; it is most likely that you
    mistyped the name of a bitmap file.
    If module creation was successful you have to restart ScreenSaver. The name
    of the new module should be listed in the "Available saver modules" list
    box then.

The following tutorial shows how to build a new bitmap module.
Assume that you want to use the three bitmaps ME.BMP, YOU.BMP and DOG_BOO.BMP;
you chose the name of the saver module to be "My Family" and the name of the
saver module file to be "MYFAMILY".
You enter

COPY BMPSAMP.RC MYFAMILY.RC

at the command prompt. Then edit the new file (in this example we use the OS/2
system editor E.EXE)

E MYFAMILY.RC

and change the file contents to look like this.

The part of the file that is marked green  (the text between "/*" and "*/") is
a comment. You can include your own comments if you like.
The red text is the module name you insert and the cyan text are the lines
enumerating the bitmap files. The rest of the text has to be there; don't alter
it. Note that the name of the module and the names of the bitmap files have to
be enclosed in double quotation marks.

/*
    MYFAMILY.RC
    resource file for custom bitmaps saver module
*/
STRINGTABLE
{
    1    "My Family"
}
BITMAP  1    "ME.BMP"
BITMAP  2    "YOU.BMP"
BITMAP  3    "DOG_BOO.BMP"

Now save the file, quit the editor and type

MAKEMOD MYFAMILY

at the command prompt. MAKEMOD prints a few messages as it works, and finally a
success message or a self-explanatory error message.
Now you restart ScreenSaver. The item "My Family" should appear in the list
box.

Related information:
Creating new saver modules


ΓòÉΓòÉΓòÉ 3.2. Creating new saver modules ΓòÉΓòÉΓòÉ

You should have some experience with Presentation Manager programming and
knowledge of the C programming language to create your own saver modules.
The ScreenSaver archive comprises sample source code that shows you how to do
it. Unzip the files sample.c, sample.h, sample.rc, sample.dlg, sample.def and
sample.mak from the file SAMPLE.ZIP (SAMPLE.ZIP can be found in the ScreenSaver
distribution file) and copy these files to some other name of your choice (keep
the original extensions). If you compile and link in another directory than the
ScreenSaver directory, also copy the file SSAVER.ICO to your working directory.
Now take a look at these files. They are are commented and contain something
like

/*
    $$$$$ insert code here $$$$$
    ... comment ...

    $$$$$ for example $$$$$
    ... example code ...
*/

at those places where you should fill in your code. You can't miss it. Be sure
to read the comments before inserting your code.
In the "for example" sections of the comments you will find the source code of
the "Pyramids" saver module that comes with the ScreenSaver distribution. You
can use it as a template for creating your own saver modules.
After having successfully compiled your new module the first time, you can use
the Dialog Editor to edit the *.RES file and change the configure dialog if
required.
You should be able to use EMX0.8g (or higher) or the IBM compiler to build new
modules. Maybe other compilers work too, but I have not tested that.

Now some explanations how a saver module works:
After the timeout occurred, the ScreenSaver program loads a saver module into
memory and makes it start screen saving. The saver module creates a window that
has the size of the whole screen. It then starts a second thread (the one you
will have to write the code for) that draws anything it wants in this window;
see the sample code for more information. When the ScreenSaver program stops
the saver module, the second thread ends, the window is destroyed and the saver
module is unloaded from memory. The idea is, that the second thread can run
with idle time priority without considering any processing of PM messages.

Since version 1.0 there were minor changes in the sample files. These changes
are marked in the source file like the following line:
// !!!!! changes since version x.x

Related information:
Creating bitmap saver modules


ΓòÉΓòÉΓòÉ 4. Note for users of OS/2 2.1 ΓòÉΓòÉΓòÉ

There is a known bug in OS/2 2.1 which sometimes prevents applications from
saving their data to the OS/2 INI-files. Therefore, if you experience that the
ScreenSaver options are not saved correctly, please try the following solution:

Add the line

attrib -r x:\os2\os2*.ini

to the file x:\startup.cmd (x is the drive letter of your boot drive; if the
file x:\startup.cmd does not exist, create it) and reboot.


ΓòÉΓòÉΓòÉ 5. Contacting the author ΓòÉΓòÉΓòÉ

My mail address is

Siegfried Hanisch
Einsiedlergasse 6/16
A - 1050 Vienna
AUSTRIA / EUROPE

My Internet address is

[e-mail]

Please send any suggestions, comments or bug reports to one of the above
addresses.

If you have questions concerning the programming of new saver modules, please
contact me via e-mail.

If you like ScreenSaver please feel free to make a donation to the author.