Documentation for YowZa! - A Screen Saver for OS/2 Presentation Manager
-----------------------------------------------------------------------

YowZa! v2.0 is my second attempt at a screen saver under OS/2 PM.
Please see the AVAIL(.AVA) file for details about what a screen saver is.

What YowZa! does:
-----------------

YowZa! is a PM application that runs in the background. At run time
a piece of code is installed to monitor all the input messages that PM is
sending to the other applications. The code, called an input hook, waits
for mouse or keyboard input. If no keyboard or mouse activity occurs within
a certain interval, the rest of YowZa! is started.
Once YowZa! has noticed that you haven't typed anything (or moved the
mouse) in a while, it first blanks the screen. Then, depending on what
entertainment you've selected (command line options) YowZa! displays some
funky graphics on the screen. As soon as you move the mouse or type a key
YowZa! goes back into hiding again.


Installation:
-------------

| After unpacking YowZa! from the RAMBIN file, you should have the
| following files:
|
| YOWZA.EXE - the main program
| YOWHOOK.DLL - the input hook
| YOWQIX.DLL - standard roaming lines
| YOWPNTS.DLL - static star field
| YOWOVQX.DLL - roaming ovals (like YOWQIX)
| YOWBXQX.DLL - roaming boxes (like YOWQIX)
| YOWTRQX.DLL - roaming triangles (like YOWQIX)
| YOWSPC.DLL - four space bitmaps (new w/ v2.0)
|
| To install YowZa!, simply copy the DLLs into a directory in your
| LIBPATH (which is set up in your machines CONFIG.SYS file). If any of
| the DLLs are not available for loading YowZa! will not run. After copying
| the files to the LIBPATH you are now ready to run YowZa! for the first time.
| However, the installation is not complete. To finish the installation
| go to an OS/2 command line and type:
|
| C:> YOWZA
|
| (Of course, YOWZA.EXE must be somewhere in your PATH statement.)
|
| You should now see the initial YowZa! dialog box which will look something
| like the following:
|
|
|
| YowZa! v2.0ax
|
| Blah blah blah blah blah
|
|
|
|
|
|
| Activate About Cancel Configure...
| ] ] ] ]
| ]
|
| Click on the push button that says "Configure...". This should bring
| up another dialog box - the configuration dialog which looks like:
|
|
| O-------O O-------O
| | | | | (List of installed DLLs)
| | | | |
| | | | | ]
| | | | |
| O-------O O-------O
| ] ]
| Install, Remove, Config DLLs
| ]
|
| Set Program to Spawn
| ]
|
| Other Settings
| ] ]
|
| OK Cancel
| ]]
| ]
|
| You should now click on the "Install, Remove, and Config DLLs" button which
| will bring up yet another dialog box. Before procedding any further, let me
| explain the way YowZa! is now designed to work.
| In v1.x of YowZa! all of the graphics routines were contained in one
| single DLL (YOWDRAW.DLL). The user was allowed to specify a parameter which
| could effect the currently selected graphics routine (the old -B option).
| This set up was fine except when the user also specified "random" mode where
| YowZa! picked randomly from the total number of available routines. In this
| case, the same -B option was applied to each routine as it was selected.
| In some cases the value of this user defined option didn't make sense for
| one routine while it did for another. Another problem stemming from
| the "random" mode of operation is that a particular user may have disliked
| a certain graphic and did not want it to be displayed during random
| operation. This lead to the -X (exclude) option. Messy, messy, messy.
| Version 2.x of YowZa! tries to alleviate these problems by placing
| each graphic routine in a separate DLL. The user must physically install
| each library into YowZa! (which is what we're about to do) before the routine
| can be used. Furthermore, each graphics DLL now maintains it's own
| configuration parameters so each routine can be uniquely configured.
| Ok, now you know what we're about to do, let's do it. You should now
| be looking at the Installation Dialog which looks something like:
|
|
|
|
|
| << Install new DLL
| List of installed ]
| DLLs which should
| be empty. >> Remove DLL
| ]
|
| Configure Selected DLL
| ]
|
|
|
| OK
| ] ]
| ]
|
| To install a new graphics DLL, click on the "<< Install new DLL"
| button. Another (!) dialog will appear in which you select the DLL you
| wish to install. Once you have located the DLL you wish to install, click
| on the "Install" button.
| At this point, YowZa! will first attempt to load the DLL you have
| selected. If the DLL is not in the LIBPATH this will fail and YowZa! will
| display an error message and return you to the file selection dialog box.
| Next YowZa! will attempt to verify that the DLL you have selected is
| a YowZa! compatible DLL. If the DLL is not YowZa! compatible, again you will
| see and error message and return to the file selection dialog box.
| If all goes well, the file selection dialog box will disappear and
| the name of the DLL you just selected will appear in the list on the left
| side of the Installation dialog box. (See crude picture above.)
| If you wish to install additional DLLs, repeat the above process for
| each DLL.
| Once you have installed all the DLLs, you are now ready to activate
| YowZa!. For details on how to remove installed DLLs and how to configure
| each graphics DLL, please see the section on "Configuring YowZa!" below.

Starting YowZa!:
----------------

The simplest way to activate YowZa! is to type YOWZA on any OS/2
command line. For example:

C:> YOWZA

| YowZa! will then start running in the background. All graphics DLLs will
| use the defaults saved in the OS2.INI file.


Command Line Options:
---------------------
| The following options may be specified on the YowZa! command line.

-N, /N - No dialog.
This command option supresses the activate/cancel dialog that appears
after starting YowZa!

-K, /K - No screen blank.
This option causes YowZa! to not blank the screen to black each time
the graphics routines are made active.

-R, /R - Random drawing routine.
Using this option the user can have YowZa! randomly pick which
graphics routine to use each time YowZa! becomes active.
YowZa! automatically knows whether each graphics routine should
have the screen cleared before the graphics begin.

-T, /T - Time out value.
By specifying an integer value with this option you can vary the amount
of time YowZa! waits before blanking the screen. The default time out is
two minutes but you can select any value up to thirty minutes (1800 seconds).
The timeout is specified in *seconds* to allow small time out values. For
example


C:> YOWZA -T180

would cause YowZa! to time out after three minutes (approx.)


Stopping YowZa!
--------------

To stop YowZa! simply close the process from the Task List or
select the YowZa! icon and click on close. Naturally if you happen to have
psPM around, you can also use that to kill the process (plug, plug).



Configuring YowZa!
------------------

| As mentioned above, clicking on the "Configure..." button from the
| opening dialog box will allow you to change YowZa!'s settings to your
| liking. Please refer to the diagram of the "Configure..." dialog above
| throughout this section.
| In the top left hand corner of the configuration dialog are two
| groups of radio buttons labelled "Activate Corner" and "Deactivate Corner."
| These two corners allow you to force YowZa! to start painting and force
| YowZa! to never paint respectively. The four buttons in each group
| correspond to the four corners of your monitor. Simply click on the
| button which represents the corner you want.
| Next to the radio button groups on the top right hand corner is the
| list of installed graphics routines. This is the way you select which
| routine you wish YowZa! to use (in non-random mode). You'll note that
| routines are listed by names rather than the DLLs they come from.
| Below the list of installed graphics are three additional pushbuttons.
| The first takes you to the dialog for installing, removing and configuring
| the graphics DLLs (more on configuring the DLLs later).
| The second allows you to specify a program that YowZa! will spawn
| whenever it activates. A good example of a use for this feature is to
| run a keyboard locking program (such as LOCKITUP on OS2TOOLS) so that if you
| leave your machine unattended for x seconds your keyboard and mouse will
| lock until you type a password.
| To specify a program to run you must provide the full OS/2 path to
| the .EXE or .CMD file. YowZa! simply uses DosExecPgm to perform this
| function. After specifying the path you must also enable the program spawning
| using the dialog detailed below.
|
| The final button of the three is the "Other Settings..." button which
| groups together some miscellaneous YowZa! parmaeters. After clicking on
| the "Other Settings..." button you'll be presented with a dialog containing
| four sets of "Yes/No" radio buttons. The first set enables program
| spawning which is described above. If this option is specified without
| specifying a program to run YowZa! simply ignores this setting.
| The second set controls how often the program is spawned once program
| spawning has been turned on. If this set of buttons is switched to "Yes"
| the program will be spawned each time YowZa! activates (this is the desired
| setting for LOCKITUP). The set to "no" the program will only be spawned
| the first time YowZa! activates.
| The third set of radio buttons turns YowZa!'s random mode on and off.
| When random mode is turned on (button set to "Yes") YowZa! will decide which
| graphics routine to use by randomly picking from the installed DLLs.
| The fourth and final set of radio buttons only effects YowZa! when
| random mode is turned off. By default, YowZa! blanks the screen to black
| before starting the graphics routine. For some graphics, however, this
| is not desired and thus you can turn of this screen blank here.
| In random mode, YowZa! asks the graphic DLL it has selected whether or not
| the screen should be blanked.
|
| YowZa! saves all of the settings made from the above dialogs in the OS2.INI
| file of your system under the program name YOWZA. Each time YowZa! is run
| it will read the settings from the OS2.INI file. Any command line options
| will override the OS2.INI settings and will then be subsequently saved
| when YowZa! exits.

| Configuring the each graphic DLL
| --------------------------------
|
| One of the new features of YowZa! 2.0 is the ability to customize
| each graphics routine individually. Before the graphics routine can be
| customized, it must first be installed (see the "Instalation" section
| above for details.) Once the DLL is installed and is listed in the
| installed DLL list (see diagram of Installation dialog above) simply
| click on the DLL name in the list and then click on the "Configure Selected
| DLL" button.
| If all goes well, the graphics DLL will be loaded and then called to
| display it's configuration dialog box. Each configuration dialog will be
| different depending on the routine so no details are provided here. Once
| you've made your adjustments simply click the "OK" button on the dialog.
| Each graphics DLL is responsible for saving the settings. The DLLs provided
| with YowZa! 2.0 will save their settings in the OS2.INI file.


Changing the graphics after starting YowZa!
------------------------------------------
To change the graphics after YowZa! has been started simply move the
mouse into the "paint now" corner of the screen. YowZa! should now start
painting. Once the graphics have started, double click the mouse using button
one. It is important not to move the mouse while performing this double-click.
If you successfully double-clicked the YowZa! graphics will disappear
revealing the PM desktop and the Configuration dialog box will be
displayed. See the section above on how to configure YowZa! using this
dialog box. After clicking OK, YowZa! will start running again with the new
settings.


Restrictions w/ YowZa!
----------------------

One major problem with this screen saver is that it doesn't
time out if you leave your machine in an OS/2 Full Screen session. A
problem to be sure but I'm not sure about how to get around it.

I've found a solution to this problem by looking at another program on
OS2TOOLS. However, this program creates a thread for *each* foreground
process to watch the keyboard and mouse. Seems like an expensive way to
solve this problem. Still, I'm working on it.



Credits & Acknoledgments:
-------------------------

The bouncing line drawing routines are ports of an Applesoft BASIC
program I wrote back in high school.
The star-field drawing routines are a port (w/ modification) of an
Apple Macintosh (note the spelling people - little I!) program which
a friend of mine (Paul C. Ossenbruggen) and I worked on which is a port
(from TML Pascal to C) of a program found in MacTutor, an excellent
Macintosh programming journal.

|
| The "Open File" dialog is schwicked from the BITMAP package on
| OS2TOOLS and is used w/o permission.
|
The Spirograph (TM) and Rose graphics routines are ports (w/
modification) of code found in an excellent graphics book, "High Resolution
Computer Graphics Using C" by Ian O. Angell (ISBN 0-470-21634-4).

Spirograph (TM) is a trademark of some game company I can't for the life of
me remember (Milton-Bradley?).

Many thanks to those out in net-land who provided may of the ideas for
the features in this version. Specifically: Anders Jarnberg, Daniel Barton,
Tony Burns, and several others. (Sorry if I forgot anyone.)

Known problems:
--------------

| This is an alpha release of YowZa! version 2.0. As such, there
| certain to be problems. I am releasing this now so that with some
| luck all of the problems can be worked as early as possible.
|
| With v2.0a1, I have only converted a few of the old graphics routines
| into unique DLLs. I will be completing the rest as time allows.
|

Please feel free to send any comments to [email protected], or if you've
access to the InterNet I'm at [email protected]