RISC DISC 2/RISC_DISC_2.iso/pd_share/utilities/scrsavers/endeavour/!Help

Text File | 1995-03-19 | 18.3 KB | 600 lines

| !Help file for !Endeavour
| ©Scott Newby 08/08/94

----------------------------------------------------
*****IMPORTANT*****
----------------------------------------------------

To register see bottom of the file.  ***************

This version is only a demonstration and not all
features are useable.
  You cannot save as a module.
  Only the first ten savers are catalogued.
  Only a selection of the savers are provided.
  The program quits after a certain amount of time
  has expired.
  There is an annoying window that pops up from time
  to time.

The full version...

  the ability to save as a module.
  allows up to 72 savers to be used.
  comes with a lot more savers to use.
  won't quit on it's own or show any silly windows.
  comes with a utility to edit argument help files.

I am very sorry to have to limit the use like I have.
Only a small fee is made for the full version and a
lot of people use shareware and don't register.  So
to try and get around this problem I have released
this demo and held back a number of features.

Once again I am very sorry to have to do this but it
seems the only way.

If you register any new versions will be sent to you
for the cost of a disk and post & packaging.

Look out for any new savers being released into PD,
and for any little utilities that you can adapt for
your own use.

----------------------------------------------------
About Endeavour
----------------------------------------------------

Endeavour is a screen saver.  It stops images being
burnt into your monitor.  It does this by waiting
until the computer hasn't been used for a while and
starts a small program which changes what is on the
screen.
There are many other screen savers available but
Endeavour allows the user to write their own savers
more easily than other available.
There is no need for file headers or complex ARM
code to be used.  These screen savers can be written
in any language.
It is very easy to convert a 'graphical utility' by
another author into your own screen saver.
Another new feature of Endeavour is the ability to
save as a module.  These can be used without the
original program.

----------------------------------------------------
Starting Endeavour
----------------------------------------------------

To start Endeavour double click select on the
!Endeavour icon.  Endeavour will load and run
automatically.

----------------------------------------------------
Instructions On Use
----------------------------------------------------

Click select once on the Endeavour icon on the
iconbar.  A window will appear, this is the
control window.

The window is split up into four different areas.


----Selecting a screen saver----

The smaller window in the top left corner of the
control window shows a list of the screensavers
currently available.  This window is scrollable if
there are more screen savers than can be seen.

If there is more than one screen saver available the
first item in the smaller window will be called
'Random'.

Clicking select in the small window will highlight a
screen saver.  If 'Random' is highlighted Endeavour
will pick a screen saver at random when it is
activated.

The current screen saver is shown in the title bar
of the smaller window.


----Sleepcorners and Time----

The bottom left corner of the control window shows
the circumstances of when a screen saver will start.

The four round buttons show which corners will
activate a screen saver when the mouse is moved into
them.  These are known as 'Sleepcorners'.

By default both the top left and top right corners
will activate a screen saver.

Clicking on a button will toggle that corner on and
off.


The two square icons show the amount of time that
will have to lapse without mouse movement or key
presses so a screen saver will start.

The square icon on the left is minutes and the
square icon on the right is the seconds.

Clicking select on one of these icons will decrease
the number whilst clicking adjust will increment
the number.

The minimum amount of time before a screen saver
kicks in is 5 seconds.

This time is know as the blanktime.

The saver can also be started by pressing :-

     <shift>
     <ctrl>
     <tab>

all together.  They are the three keys grouped together
on the left hand side of the key-board.

----Passwords----

The two boxes in the bottom right of the screen are
for a password.

To enter a password click select over one of these
boxes and a 'caret' will appear.  Now type in your
chosen password.  Repeat this in the other box.
BOTH PASSWORDS MUST MATCH UP.

If either of the boxes contain nothing then
a password will not be asked for.

To remove a password click select in a box and
hold down the control key ('Ctrl') and press 'U'
the password will be removed.


----Active / Inactive and Saving----

In the top right of the control window is an icon
with 'Active' inside.  Clicking on this will change
the text to 'Inactive'.  Clicking on "Inactive" will
return the text to 'Active'.

The screen saver will only operate if the text is
'Active' else nothing will happen.

To save a screen saver as a Relocatable Module type
the name in the box below the sprite and drag the
sprite to the directory window where you want it
saved.

This module can be used in the boot up sequence of
your computer so there is no need to load Endeavour
up each time, or it can be loaded by clicking on it
twice.


----Menus----

There is only one menu and this consists of these
options : -

              Info
              Catalogue
              Arguments    ⇨    On
                                Off
              Help
              Quit

Following the arrow next to info will show a window
containing information about this program.

Clicking select on 'Catalogue' will recatalogue the
Savers directory within !Endeavour.  This only
needs to be done when a new screen saver is created,
one is deleted or one is renamed.  When amending
a screen saver there is no need to recatalogue
unless the filename has been changed.

Clicking on Arguments bring up the arguments window.
By following the arrow a sub-menu will appear, this
allows the arguments to be turned on or off.

Clicking on Help will show the argument help window.

Clicking on Quit will quit the program.


----Entering A Password----

If the passwords in both boxes are the same then
when the screen saver has started and the mouse
moved or key pressed a password will need to be
entered before continuing.

Click select in the box and type in the password,
when done either press return or click 'ok'

You are given three chances to type it correctly
before the screen saver comes back on.

If the blanktime has lapsed before typing in the
password then the screen saver will restart.

----------------------------------------------------
Module Information
----------------------------------------------------

When saving a module the module takes one of two
forms.
It either saves the path name for the screen saver,
or it saves the actual program in the module so it
is not needed again.

If the screen saver is an application then the
pathname will be saved else it saves the program.
The module length is determined by the size of the
program.  The longer the program the larger the size
of the module.

If the save is an application (ideally used for
savers that require sprites) then the pathname of
the saver is saved.  The saver cannot be removed,
renamed or moved elsewhere as this makes the
pathname incorrect and an error will be reported
when the saver is started.

----------------------------------------------------
Using The Module
----------------------------------------------------

Two commands are provided for the user :-

        SleepCorners        EndeavourTime

These allow you to change when the screensaver is
activated.

To see the values type in the command with no
parameters.

To alter a value type in the command followed by
the new value.


----SleepCorners----

The corners are identified by using bits : -

              (2) top left     (3) top right


              (0) bottom left  (1) bottom right

Bits are laid out as follows :-

Bit number         3 2 1 0
                   -------
Value              8 4 2 1

Therefore if you want the bottom left corner to
activate the screen saver, the value is 1.
If you want the top left corner as a sleep corner
the value is 4.
If you want both the top left and top right corners
the values are added together - 8 + 4
Therefore the value is 12

Here are some value to use....

All corners on     - 15
No corners         -  0
Top two corners    - 12
Bottom two corners -  3


----EndeavourTime----

This allows you to alter the time when a screen
saver will come on.  The number is centi-seconds.

Use this method to work out the required time.

time=(minute%*6000)+(second%*100)



----------------------------------------------------
Writing Your Own Screen Savers
----------------------------------------------------

It is very quick and easy to write your own screen
savers.  They can be written in any language you
like and only need to obey a two obvious rules.

     1)  It must run indefinately.

   The program must keep on running and changing the
screen.  It would be silly to write a screen saver
that drew a white circle on a black background and
did not change as this would still burn the screen.
   It would also be silly to write a screen saver
that stops after a few seconds as the computer
would return to the desktop and this would burn in.

     2) It must end when required.

   A procedure is provided that ends the program
when the mouse is moved or a key pressed.
   To end the program though you could write your
screen saver to end only when a certain key is
pressed.  This can provide another type of
protection.

When you have written your screen saver copy it into
the Savers directory and it is ready to be used.

Any variables which can be changed to make different
effects should be REM'ed out.

----Other Notes----

Inside the Savers directory there is a program
called 'Shell'.  This is an outline of a saver
showing all the basic things to know.

Care must be taken when changing the mode as it
can result in a 'Bad screen mode' error.
This often happens when the desktop is in a mode
that uses less screen memory than the mode you
want to change to.
 i.e desktop in MODE 12 and changing to MODE 15.

When using outside files, such as sprite files or
sound trackers.  Two methods can be employed.
 Firstly you could create your own application,
with a !Run file and !RunImage, such as !Eat or
you could make a directory with all the files
needed by all of your screen savers and refer to
them by pathname.
 Using the first method, when saving as a module,
the module uses the pathname of the application so
the application is still needed and cannot be moved.
If you use the second method then when the module
is saved the program is saved in the module so the
program is not needed again.
 If you then add this line in your !Boot file :-
  Set ScreenSaverResources$Dir 'pathname'
where 'pathname' is the name of the directory with
all the files in it.  These files can then be
referred as "<ScreenSaverResources$Dir>.Sprites"
for example.
  I prefer the second method especially if you own
a harddisc as all your screen savers can refer to
the same file.  For example if three of the savers
use a tracker module then rather making three copies
of the module only one is needed as all three savers
can refer to it.

The best way to test your saver to see if it works
is to double-click on the file.  The saver should
run fine with no problems.

Arguments cannot be changed within the module.  If
you require the arguments to be changed then you
will have to so manually.  Go to the command line
(press F12) and type :-

*Set Argument1$Value <new value here>
*Set Argument2$Value <new value here>
*Set Argument3$Value <new value here>
*Set Argument4$Value <new value here>

You do not have to set all if you only want to
one.

Remember savers can contain samples, sprites etc.
Unfortunately I do not have the resources to include
ones like the After-Dark savers for the PC.  If you
write some like that then PLEASE send them to me.

----------------------------------------------------
Arguments
----------------------------------------------------

Now if arguments are required by your saver it gets
a little more complicated - but I have tried to keep
it as simple as possible.  The easiest way to learn
is by looking at the savers provided but here's an
explanation.

When !Endeavour is run four system variables are
provided.  These are :-

    Argument1$Value
    Argument2$Value
    Argument3$Value
    Argument4$Value

Arguments 1 and 2 contain intger (whole) numbers.
Argument 2 can contain a floating point number.
Argument 4 contains a string.

Two functions are provided to read these and
convert them to a string or number.

If the arguments are turned off these will be set
to zero and your program must contain a check so
a set of default values will be used.  This,
however, means that 0 cannot be used for an
argument and I suggest that if there is to be an
option that is either on or off use 1 to denote
on and 2 to denote off.

A value of -1 is returned if the System variables
are not present.  This can only happen if the
program is being run from a module and !Endeavour
has not been run.  In this case default values
must be used.

----Help----

When arguments are wanted there should be text
telling the user what each argument does.  Also,
there should be default values in case the user
does not want to change them.

For each saver that requires arguments there must
be a text file of the same name as the saver in the
directory 'Text' that is in the !Endeavour
application.

There is an application available that allows the
help for the arguments to be written easily but if
you have not got that it is still very simple to
type them into a text file.  Here's how to do it..

The first four lines contains the text for the four
arguments respectively.  The next four the default
values for the four arguments in the same order.

Leave a blank line if no argument is required.
ie. If no string or value is needed leave it blank.
Remember to press enter after the default value for
argument four.
The default values should match up with the ones in
the saver.
The file MUST consist of 8 lines.
If in doubt edit an existing file.

Step by step...

1. Open a text file using a text editor.
2. Enter the short help for argument 1.
3. Press <space> then a '*' and then the long help.
4. Press <return>.
5. Repeat steps 2-4 until all text entered.
6. Enter the default value for argument 1.
7. Press <return>
8. Repeat step 6 and 7 until all default values are
   entered.

----------------------------------------------------
Files Contained With Endeavour
----------------------------------------------------

With the Endeavour application you should receive
these files : -

        !Boot         - Obey File     - file_feb
        !Help         - Text File     - file_fff
        !Run          - Obey File     - file_feb
        !RunImage     - Program       - file_???
        !Sprites      - Sprite File   - file_ff9
        Immaculate    - Module        - file_ffa
        Sprites       - Sprite File   - file_ff9
        Templates     - Templates     - file_fec

Copying of these files is allowed.

You may distribute this program as long as all
files are kept intact.

The directory of screen savers and all modules
created by Endeavour may be freely copied and
distributed.  I encourage you to send good
ones to all the popular PD libaries and BBS'es.


----------------------------------------------------
Problems, Bugs with the Demo Version.
----------------------------------------------------

At the moment when a saver is run or a new one is
selected then disk with the savers on is needed.
This is because when a new one is chosen and the
arguments are switched on the help file for it has
to be read in and when one is run it needs it from
the disk.
If you have a hard-disc this is no problem when the
program is installed but for those without then the
disk is needed all the while.  If you register
and state you have no hard-disc I will include a
few within the program so !Endeavour can be run and
the disk removed.  This will only work for the ones
I have included.

One error can be caused when a saver is run which
wants a mode with more screen-memory than you have.
ie. desktop in Mode 12 and the saver wants Mode 15.
The easiest way around this is to put the desktop
in Mode 15.  Currently I am working a way around
this problem which should be solved for the full
version.  If anyone can help get my email address
at the bottom and mail me....

There is a few bugs still in the Demo version but
the full version has not got these.

The best way to test your saver to see if it works
is to double-click on the file.  The saver should
run fine with no problems.


----------------------------------------------------
Registering And Sending any Savers to me.
----------------------------------------------------

If you have written any spectacular screen-savers
then please send them to me and I will include them
with the full version.  If you send a stamp
addressed envelope I will return the disk with
various items of PD.  I will be making a disk of the
best ones and sending them to all major PD libaries
and BBS'es.

***Registering***

To register tell me what machine it is for and
send a Cheque or Postal Order for £8.00 to :-

     Scott Newby
     130 Locarno Road
     Tipton
     West-Midlands
     DY4-9SB

If you have any questions, found some bugs,
need any help or just want to drop me a line then
email me at :-

     [e-mail]

By the way, after the cost of a disk, P & P any
money left will be put towards upgrading my computer
so I can write even more programs....

At the moment I own a lowly A310, 1 Meg and no
hard-drive <sob, sob>.  !Endeavour runs perfectly
on this.  It also runs, but I haven't tested
everything, on a Risc PC.

----------------------------------------------------
Thanks & Credits.
----------------------------------------------------

This program was written by Scott Newby.......

A big THANKS goes to Philip & David Partridge for
their help.  Another THANKS goes to David Fisher for
a LOT of help in the module bit.  But between me
and you he's a few directories short of a full
pathname.  And finally another THANKS to Gary
Blewitt for letting me test it on his RISC PC.....