Dream 44/Amiga_Dream_44.iso/RiscPc/Utils/HourExt.arc/!HourExt/!Help

Text File | 1994-09-19 | 11KB | 217 lines

Hourglass Extension version 1.10
⌐ Sam Kington 8th August 1994
This program is freeware, *not* public domain ù i.e., I retain copyright (see
öBoring legal messageò).
This module will only work with RISC OS 3 or later.


What this program does
**********************

   For a start, this program is essentially one small module, HourExt, which
at about 2300 bytes is considerably smaller than the whole application, which
weighs in at slightly less than 44K, of which most is the source code and
this help ₧le. If you decide you donæt need the whole application cluttering
up your hard disc or ƒoppy or whatever, you can put the module somewhere else
(!System.Modules would be a good place), and RMLoad it in your Boot sequence.
If you decide you donæt want *any* of the application, of course, you can
delete the whole thing. If you want to distribute this program or use it for
your own programs, see öDistributionò.

   Anyway, down to what the module does. Basically, it sits in the
background, and when you change the palette it changes the hourglass colours
to match. So if you change the mouse pointer colours, say to black and white
instead of the default dark and light blue, it will change the colour of the
Hourglass to black and white as well.

   Actually, you have slightly more choice than that. The hourglass only uses
two colours, and if you take a quick look at the palette you will notice that
there are in fact three different mouse colours: 1, used for the mouse
border, 2, used for the inside, and 3, usually red, used for öalertò-style
pointers such as when you want to copy a ₧le from the CLI. So there is a
special *command, *Hourglass_Colours <sand colour> <background colour>, where
<sand colour> and <background colour> are numbers between 1 and 3, which will
set the colours accordingly. The default setting is Hourglass_Colours 1 2;
experiment until you ₧nd your favourite setting.

   *Hourglass On|Off|<percentage> will turn the hourglass on or off, or
display the supplied percentage underneath the hourglass. You may already
have a module that supplies a command of the same name, but in practice there
shouldnæt be any conƒicts as once a command has been handled by one module,
it wonæt be passed onto another module. To ensure *Hourglass gets passed to
HourExt, load it before other modules with the same command.

   Note that when you type Hourglass Off, you will not necessarily turn it
off: you have to issue a Hourglass Off for every Hourglass On. Also, if you
set the percentage of the hourglass (say Hourglass Percentage 50), then issue
another Hourglass On, any subsequent Hourglass Percentage calls will be
ineffective until you issue as many Hourglass Offs as you issued Hourglass
Ons after setting the percentage. Issuing a further Hourglass_Off will turn
off the percentage. This is an internal feature of RISC OS, nothing to do
with HourExt.

   *Hourglass_LEDs On|Off On|Off will set the state of the LEDs, so
*Hourglass_LEDs On Off would set the first one on and the second one off.

   As well as changing the colour of the Hourglass to suit the palette, and
allowing you to muck around with the hourglass, HourExt sets up two ₧lters
which intercept all calls to Wimp_Poll, turning on the Hourglass after
control has been given to a program, and turning it off when they give it
back. The practical upshot is that whenever one application spends too much
time on its own without letting other applications have a turn (and, more
importantly, without letting you do anything), the Hourglass is turned on
until the task gives control back. You can alter the delay before the
hourglass is turned on when an application stops multitasking, with the
command *Hourglass_Delay <time in centiseconds>. *Hourglass_Delay 0 turns off
all multitasking checking.

   Finally, HourExt knows about Desktop saves, and will insert the relevent
commands in any Desktop ₧les. However, it needs to know where to load itself
from, and does so by looking at the variable HourExt$Module. If the module is
run by the !HourExt application, this will be set up automatically; however,
if it is RMLoaded from somewhere in a Boot sequence or whatever, the variable
will not be set up. If the variable doesn't exist, the module assumes it was
started as System:Modules.HourExt, which is a sensible default; if you load
it from somewhere else, say !Boot.AutoLoad.HourExt, add *Set HourExt$Module
!Boot.AutoLoad.HourExt to the file you load HourExt in.

Limitations
***********

   HourExt turns the hourglass on if the machine stops multitasking for a
de₧ned period, which works most of the time. It also notices if you press
F12, and wonæt turn the hourglass on in that case. However, if you select
*Commands from the Task Manager menu, the hourglass will come on, and stay on
until you go back to the desktop.

   In general, if you stop multitasking, HourExt will put up an hourglass;
however, if you are actually doing something but not multitasking, as opposed
to a program hogging the machine, then it shouldnæt put up an hourglass.
Unfortunately, it has no way of knowing which is which ù and do bear in mind
that this is just a quick program written in a couple of days. You are likely
to have problems with screen captures from Paint, and any single-tasking
program that doesnæt turn off the pointer, which includes most *Info programs
from Acorn User but not most games (I donæt think). If it annoys you, use
*Hourglass_Delay 0 to turn the checking off.

Boring legal message
********************

   This application is freeware, that is, it can be distributed freely as
long as only reasonable charges are made for media and distribution. I retain
copyright on all program code and documentation.

   This software is supplied öasáisò: I make no warranty, expressed or
implied, of the merchantability of this software or its ₧tness for any
particular purpose. In no circumstances shall I be liable for any damage,
loss of pro₧ts, or any indirect or consequential loss arising out of the use
of this software or inability to use this software, even if I have been
advised of the possibility of such loss.

   In other words, if your computer crashes, blows up, you lose all your work
etc. all because of HourExt (unlikely I know), donæt blame me.

Distribution
************

   The following ₧les should be present in a full version of HourExt (you
may, however, not have the full version):

Name        Purpose                       Usefulness
****************************************************
!Boot                                     Not very
!Run                                      Not very
!Sprites                                  Not very
HourExt     The main module               Essential
ModSource   The source code to the module Slightly
ShortHelp   Help text compaction          Quite
ShortHDocs  Help on ShortHelp             Quite
!Help       This ₧le                      Very
Vsn110      This is version 1.10          Not at all

The öVsn110ò ₧leæs only purpose is to show that this is version 1.10 ù which
is useful if youære browsing directory displays, or you have several
different versions. As it is, there is only one (distributed) version of
HourExt. If you remove this ₧le, nothing at all will fail to happen.

The only point of the !Boot, !Run, and !Sprites is to make this an
application, so there is a HourExt$Dir variable, so the source code can ₧nd
the ShortHelp routines (see below). They also set up HourExt$Module; if you
simply RMLoad the module from a path different from System:Modules.HourExt,
you must set this up yourself (see above).

ModSource and ShortHelp are basically the source code of the module; or
rather, ModSource is the source code, and uses routines in ShortHelp.
ShortHelp is a collection of routines which will compact strings using RISC
OSæs internal dictionary, to be re-expanded by *Help. ShortHDocs is
essentially a !Help ₧le for ShortHelp.

HourExt is of course the main module, without which the whole thing is
useless.

Although I would prefer you distributed all the ₧les together, if you want to
include any of the routines in your own programs (the module or the ShortHelp
routines) you will probably not want to distribute all the almost-useless
₧les. So here are the conditions for distribution:
   Å This ₧le (!Help) must always be distributed with the HourExt module,
complete and unmodi₧ed.
   Å If you distribute ModSource, you must include ShortHelp (otherwise it
wonæt compile). If you donæt include the !Boot etc. ₧les, you will have to
change the ModSource code so it can ₧nd ShortHelp (putting it in your Library
should be quite sensible - replace <HourExt$Dir>.ShortHelp by %.ShortHelp).
   Å You can however distribute ShortHelp separately from any of the other
₧les, and use it in your own programs. See the ₧le öShortHDocsò for more
information.
   Å You must distribute !Boot, !Run, !Sprites and Vsn110 together, or not at
all.

About all these strange foreign characters in this ₧le
*******************************************************

   OK, so if youære reading this on a PC or a Mac or another strange machine
like that, you may be wondering what all these strange ae things are. Well,
theyære quotes (sorry, there was another one), dashes, ligatures, etc.
Honest. But not on all machines...
   Basically, character sets are only standard up to character 127, which is
basically alphanumerics and a few standard punctuation marks. Foreign
characters, typographical oddities like quotes and ligatures, and other more
obscure symbols are önon-standardò, and each computer often has its own idea
of where they should go in the character set. So donæt worry: even if itæs
hard to read on your current machine, it wonæt be on an Acorn machine. It may
look slightly strange if youære using the System font, however.
   But why am I using these strange characters in the ₧rst place? Well,
theyære in the character set and they look nice in an outine font, and Iæve
written a program called Smart Quotes (sorry for the plug) that substitutes
these sort of characters automatically, and Iæve got it turned on at the
moment...

How to contact me
*****************

All bug-reports, suggestions, comments or indeed any feedback at all will be
welcomed. Hereæs how to get to me:

E-mail     : [e-mail], [e-mail] during term-time
             These should be OK until June 1996
             At Christmas, Easter and during the summer, you can get me at
             [e-mail], [e-mail] or [e-mail], in order
             of preference (that is, if mail bounces off one of these or I donæt
             answer within a week send to the next one).

Snail-mail : My term-time address, at least until June 1995, is:
             Sam Kington
             Flat 2/1
             44 Hotspur Street
             Glasgow G20 8NL
             SCOTLAND

             Again, a backup is the home address ù anything that goes here will get
             to me eventually.
             Sam Kington
             Merlhiot
             24420 Savignac les Eglises
             FRANCE

Term-time is October to June, with bits off at Christmas (3 weeks) and
Easter (4 weeks).