LPsaver - THE LAUNCHPAD SCREEN SAVER SYSTEM

by Dilwyn Jones

(Manual for program version 1.03)

LPsaver is a screen saver system used by the Launchpad
desktop system for QDOS and SMSQ systems. A screen saver is a
program which blanks or otherwise alters the display on the
screen, originally to prevent a condition known as "burn-in"
whereby text appears to "burn" into the screen and shows on
the screen even when it is switched off. With modern
monitors, this is less likely to happen and screen savers are
now used either to mask what is on the screen if the computer
is left unattended or unused for a while, or simply to
provide an attractive distraction or even adevrtising display
when the computer is otherwise unused. After a preset number
of minutes, this program cuts in with the selected display.

12 screen saver modules are built into LPsaver, and it is
possible to specify an external module which you can write
yourself if you prefer as long as you follow simple
guidelines. Almost any executable program may be used,
including QLiberator or Turbo compiled basic programs. SMSQ/E
users can write external saver modules in SBASIC.

LPsaver may be used independently of Launchpad if required,
the program merely requires the presence of pointer
environment and Toolkit 2 which is available on almost all
modern QL systems. When used with Launchpad, LPsaver may be
controlled from the Display menu of the MyQL section of
Launchpad.

CONFIGURATION

LPsaver has a level 1 configuration block built in, so that
the program may be configured using either the Config or
MenuConfig programs, supplied with most modern QL software.

Two versions of LPsaver are supplied:

* LPsaver_rtm - includes QLiberator compiler extensions.
* LPsaver_obj - about 10 kilobytes shorter, but does not
  include the compiler extensions (users who already have
  QLiberator extensions can use this version).

Configure the version best suited to your needs.

The first item to configure is the screen saver module to be
used by default. Luanchpad can override this if required. You
can select any of the 12 built in ones, an external module of
your own, or set the program to choose one of the thirteen at
random. If no external module is specified, the inbuilt
screen blanker is used instead. The built in modules are:

1. Screen Blanker - simply turns the screen black.

2. Starfield - the effect of a space ship flying into or past
a star field.

3. Polygons - fancy coloured lines, shapes or curves floating
around the screen.

4. Collapse - the screen content collapses slowly by little
squares to a blank screen.

5. Messages - pans a message across the screen. This message
may be configured and if none is specified in configuration,
defaults to "LPsaver - The Launchpad Screen Saver System".
Where the QL is used in a business environment such as a
shop, this may come in useful for advertising, for example,
by putting information text or the company's name into the
screen saver.

6. Meltdown - the screen appears to 'melt' until it goes
blank. Pretty weird if you see it for the first time without
knowing it's a screen saver.

7. Dayglow - brightly coloured bars are printed across the
screen, particularly effective if the "colour drivers" (GD2)
are in use on Q40, QXL or QPC for example!

8. Mazes - wanders through a 3D maze on the screen!

9. Bubbles - coloured bubbles float along the screen!

10. Wipes - Transitions to blank screens.

11. Wobble - the screen picture slides around, not for those
who get travel-sick easily!

12. Cords - random coloured blob lines float around the
screen.

13. Fish - rudimentary fish shapes floating across the
screen.

14. Holes - "holes" appear all over the screeen, as though
bullets were shot at the screen!

Secondly, specify the filename of an external screen saver
module. This filename should be complete, including drive and
directory name as well as the filename. This program is
executed after the number of minutes of inactivity specified,
then removed again when the mouse is used or a key pressed.
This saver module should not do anything to deactivate or
suspend the controller program (LPsaver). If no filename is
specified, the program uses the ordinary Blanker routine
instead.

In order to remove the external module LPsaver needs to know
the job name of the screen saver module. This is the name
which appears when you enter a JOBS command to list the
currently running jobs on a QL. It is usually stored near the
job header, and can usually be seen simply with a VIEW or
COPY_N command to copy the program to the screen. Obviously,
if the module was created with QLiberator or Turbo compiler,
for example, you can specify the job name as you compile the
program. If the module is written in SBASIC, you can either
use the job name SBASIC or give the program a name with
SBASIC's JOB_NAME extension (e.g. JOB_NAME "mymodule") and
use that name if you wish to be sure that LPsaver removes the
correct program if you are likely to have several SBASICs
executing! This job name should be entered as the third item
configured.

The fourth item is the text string used for the Messages
saver module. This may be up to 42 characters long. If no
text string is specified, an internal default text string of
"LPsaver - The Launchpad Screen Saver System" is used
instead.

The fifth item to be entered is the delay or period of
inactivity before the screen saver is started. This time is
specified in minutes, up to 24 hours in duration (i.e. from 1
minute up to 1440 minutes).

The final item allows you to specify if sound prompts are off
or on. This includes the beeps made by the Holes screen
savers, and the error "grunts" when LPsaver tries and fails
to start or remove an external module.


STARTING THE PROGRAM

Simple execute the program with an EXEC or EX command from
BASIC. EX FLP1_LPsaver_obj or EX FLP1_LPsaver_rtm as
required.

From Launchpad, go to the Display section of the MyQL menu
and start the screen saver from there. Note: for Launchpad to
be able to find LPsaver, it must be stored in Launchpad's
system directory.

You can, of course, create an icon for Launchpad to start
LPsaver in the normal way if preferred. Or if you'd like
LPsaver to be started every time Launchpad is started, simply
add a line to Launchpad's boot program to execute LPsaver_obj
or LPsaver_rtm as described above.


STARTING WITH A COMMAND LINE

It is possible to override the configured defaults to some
extent by passing an option command parameter to the program
in the following format:

EX LPsaver_rtm;"saver_number time"

"saver_number" is a number from 1 to 12 (as listed above) to
use one of the internal screen saver module, or 0 to call the
configured external screen saver module. Alternatively,
supply a value of 255 or -1 to make the program choose any
module at random if you want some variety!

"time" is the number of minutes of inactivity before the
screen saver cuts in. Unlike the configured default,
fractions may be entered (e.g. 0.5 for half a minute), though
this is not likely to be useful unless you want to set a
deliberately short time the first time you use it to view the
screen saver modules quickly at random:

EX LPsaver_rtm;'255 0.1'

This will start a random module after just 6 seconds of
inactivity, not normally useful but can be used to view the
saver modules I suppose.

Both parameters should be separated by a space. Either may be
omitted, in which case the internal configured default is
used. If you only specify the time delay, it should be
preceded by a space character:

EX LPsaver_rtm;' 5'

This starts the screen saver module after 5 minutes on
inactivity, with the configured screen saver module.

Alternatively, a comma may be used as separator instead of a
space if preferred.

Passing a command parameter like this is the mechanism used
by Launchpad to start its screen saver, of course.


MAKING YOUR OWN SCREEN SAVER MODULES

Here are some guidelines for creating your own screen saver
modules.

In principle, any executable program may be used as long as
it does not suspend LPsaver or perform any action to
interfere with correct operation of LPsaver.

It is suggested that the screen saver module does not use CON
channels, use SCR channels if possible. LPsaver may work with
screen saver modules using CON channels under some
circumstances (you will of course have to use CON in
uncompiled SBASIC programs!), but cannot be guaranteed as the
method used to check for mouse movement is somewhat
"unofficial" (direct reading of pointer linkage block). Try
using a CON channel if you wish, if LPsaver does not stop the
module successfully, you have to use a SCR channel instead.

Your program will need to check screen dimensions in order to
allow the module to open a window to cover the whole screen.
If you are using SBASIC on an SMSQ/E system, no problem, just
use the SCR_XLIM and SCR_YLIM functions:

OPEN #0,'SCR'
WINDOW #0,SCR_XLIM,SCR_YLIM,0,0

If you want the program to run on QDOS or SMSQ/E systems,
"hide" the extensions like this:

OPEN #0,'SCR'
xsize=512:ysize=256:REMark default to QL screen size
v$=VER$
IF ver$='HBA' THEN
  REMark 'HBA' is the version string for SBASIC
  xsize=SCR_XLIM:ysize=SCR_YLIM
END IF
WINDOW #0,xsize,ysize,0,0

With a little bit of care, SMSQ/E users can write saver
modules in SBASIC (sadly, it is not possible to use a Minerva
or DIY Toolkit MultiBASIC). A simple example is included,
called Example1_bas. This program can be compiled. Ensure you
either copy window channel #0 over when compiling, or
explicitly open channel #0 in the compiled program -
QLiberator users could use IF Q_MYJOB <> 0 THEN OPEN #0,'SCR'
and Turbo users could use IF COMPILED THEN OPEN #0,'SCR'.

LPsaver executes SBASIC programs, and this means that (in
current versions at least) the program is started with
channel #0 open as a CON channel, so unless you need more
than one window you may not need to open any SCR or CON
channels in your SBASIC saver module.

Interpreted SBASIC programs can be removed with the general
job name SBASIC (in effect, LPsaver will remove it with the
equivalent of RJOB 'SBASIC'. However, this is a bit dangerous
if you have another SBASIC executing at the time, so best to
give the saver module an explicit job name with the SBASIC
command called JOB_NAME, e.g. JOB_NAME "mymodule". In this
case, the external saver would be configured via its filename
and the job name given in the JOB_NAME statement.

Using SBASIC programs in this way makes it quite easy for
"colour drivers" (GD2) users to write some very colourful
screen saver modules! Example1_bas is just crying out to be
modified in this way, just change the colour values in the
BLOCK statement and/or use COLOUR_PAL or COLOUR_NATIVE or
COLOUR_24 extensions in your program as required!

There are a number of extensions packages in the public
domain, such as Norman Dunbar's DJToolkit and my own
DISPLAY_CDE extensions published originally in QL Today which
give the BASIC programmer the facility to extract the correct
information from the system on QDOS systems as well as SMSQ/E
- basically, using the iop.flim system trap is the best way
to check for maximum window size under pointer environment.
Of course, SBASIC users can use their SCR_XLIM and SCR_YLIM
extensions as described above.


REMOVING LPSAVER

Use the basic command RJOB "LPsaver" to remove this program,
or use the Rjob menu in QPAC2, or the Display section of the
MyQL menu in Launchpad. If it was started from a normal
program icon in Launchpad, simply right click on the icon and
use the Rjob command.


COPYRIGHT STATUS

Although released as part of a commercial product called
Launchpad, LPsaver itself is freeware and may be freely
copied.


PLEASE NOTE

Due to the rather indirect method used to detect mouse
movements, it should be pointed out that if BASIC is asleep
in the button frame when LPsaver is executed (usually shown
as a button called System in the button frame) it may not be
possible to use the mouse to stop the screen saver. Worse, it
is possible that if you have not used the keyboard during the
delay period, LPsaver may cut in while you are using the
mouse! Until I can figure out how to work around this, please
use the keyboard to stop the screen saver if the mouse seems
not to respond.


RELEASE HISTORY

v1.00 (11/04/03) First release version.

v1.01 (16/04/03) This version contains a number of bug fixes
      and improvements following feedback on the first
      release.
      The Dayglow saver should now work without overflow or
      out of range on GD2 systems such as Q40/Q60 (native
      colour number calculation error). It should run at a
      more leisurely pace on non-GD2 systems now (very fast
      stipple colouring was not easy on the eye).
      Q40/Q60 native colours now calculated correctly - green
      and red miscalculated.
      Now enables 'native' colour mode correctly (error in
      test for presence of COLOUR_NATIVE keyword if test
      first done in Dayglow saver module).
      Out of range error in Starfield saver caused by
      negative co-ordinates fixed.
      Response time to mouse movement in some savers
      improved.
      Mazes and Starfield savers now attempt to use full
      screen width in all resolutions, even 1024x512 on
      Q40/Q60 (SCALE calculation error).
      Starfield will randomly either 'fly into' the star
      scene or 'fly past' the stars now, the random selection
      of routines previously always selected 'fly into' when
      compiled due to a bug in handling of the random
      selection.
      The same key can now be used in succession to stop
      saver modules, at the cost of resetting the sv_arbuf
      system variable - if you find this causes problems
      please let me know and I will remove this from future
      versions.
      Please note the warning in the manual regarding the
      fact that the mouse cannot be used to stop a saver
      module if SBASIC is asleep in the button frame.

v1.02 (18/04/03) Corrected a few bugs reported by Duncan
      Neithercutt, and made it easier to use uncompiled
      SBASIC modules.
      Bubbles saver now works when scrolling from right to
      left and top down - scale being wrongly calculated and
      bubbles drawn off screen in previous version giving
      just a blank screen sometimes.
      Reflections now drawn on some bubbles at random from a
      light source vaguely above right of the screen. (OK,
      it's a very crude effect!)
      Wipes saver now works again (variable name clash with
      new array in v1.01). A couple of new wipes have been
      added in this module.
      Error message wrongly written to screen with some maze
      sizes in Mazes saver now removed.
      Minor bug in external modules routine when saver module
      is "not found" now rectified. Slight change made to
      more easily use interpreted SBASIC programs to be used
      as savers (see warning above regarding SBASIC job
      names) - it was possible to use SBASIC programs as
      modules in earlier versions, but not very reliable so
      was undocumented. If an error occurs when trying to
      start or stop the external module, LPsaver will now
      "grunt" an audible warning (unless sound configured to
      OFF).
      New item in Configuration Block allows sound to be
      configured off for silent operation.
      Command line parameter now allows comma instead of
      space if preferred, gets around problem in some older
      task switchers which would not allow spaces in command
      lines.
      Two new saver modules built in - Fish and Holes.
      (Launchpad alpha release 0.51 - the screen saver
      settings are not remembered between sessions, this
      requires a change in the configuration files, it is not
      an LPsaver bug!)

v1.03 (25/04/03) The new modules in v1.02 (Fish and Holes)
      did not end correctly and restore the display due to
      programming bugs. Now corrected.


