    **  NewAlarm  **
            a 'rough time' alarm program by Miss H.Bazley
                version 138

--------------------------------------------------------------------------------
PURPOSE OF PROGRAM

To tell the time and handle alarms in a vague text-based manner rather than
with digital precision.   This program supports interactive !Help.
--------------------------------------------------------------------------------
HARDWARE/SOFTWARE REQUIREMENTS

RISC OS 31 minimum (RISC OS 5 and StrongARM compatible) and 36-64k free
memory.   NewAlarm *should* work for French or German versions of RISC-OS, but
the syntax will sound really stupid so it is probably a waste of effort.

This program may be run from within a read-only archive.
--------------------------------------------------------------------------------
HOW TO USE THE PROGRAM

Run the program.   The main window will open and so will the alarm list,
showing all the current alarms in memory in descending order.

Drag SELECT to move the main window, or drag ADJUST to move it without bringing
it to the front.   Double-click SELECT to set a new alarm (like 'Set new
alarm...' on menu).   Double-click ADJUST to reopen the alarm list (like 'List
alarms...' on menu).

When an alarm goes off, an alert window will appear in the middle of the screen
displaying the alarm's text and, if it is a repeating alarm, the time at which
it will next go off.   Click on the OK icon (or press RETURN) to make it go
away.

--------------------------------------------------------------------------------
THE MAIN MENU

'Info' leads to a standard info window telling you the name and version of the
program.
'Set new alarm...' opens the 'Set alarm' window (see below under 'NEW ALARMS')
'Save alarms' updates the alarm file inside NewAlarm (or deletes it if there
are no alarms remaining) and saves the current position of both windows.
The  -autosave option (see below under CONFIGURING THE PROGRAM) will do this
automatically every time an alarm goes off.
'List alarms...' opens the alarm list.
'Most recent alarm' leads to a submenu allowing you to redisplay the the alarm
which has just gone off, or to recreate another alarm with similar text.   If
you are busy typing and automatically hit RETURN when the alarm goes off, you
can use this option to get back what you missed!
'Quit' quits the program.   If you have unsaved alarm data a warning window
will open.   Select 'Save' (or press RETURN) to save alarms and quit, 'Discard'
to quit without saving, or 'Cancel' (or ESCAPE) if you decide you would rather
not quit after all.
--------------------------------------------------------------------------------
NEW ALARMS

Use the up and down arrow icons in the 'Set alarm' window to set the time at
which the alarm is to go off.   Type your message into the three writable
icons.   Note that pressing RETURN will have the same effect as clicking on the
'OK' icon - use the TAB or cursor arrow keys to move between icons.

Selecting the 'Repeats' option icon  or pressing CTRL-R will open the 'Repeat
alarm' window which controls how often your alarm will repeat - every month,
every two weeks, every six hours.   You can also control on which days of the
week the alarm will go off - for example, you can create a 'working week' alarm
which repeats every day but does not go off on Saturdays or Sundays.   Note
that careless use of this feature can create alarms that will never go off!

If the 'Repeats' icon is not selected then the alarm will not repeat.

The 'OK' button will set the alarm;  ADJUST-clicking on the 'OK' button will
set the alarm but keep the window open for you to create another alarm based on
this one.   Alarms must be set to go off in the future.   You will be warned if
the alarm would go off immediately it had been set.

Pressing the 'Cancel' button or ESCAPE key will close the window without
setting any alarm;  ADJUST-clicking on the 'Cancel' button will discard any
data you have entered but keep the window open for another try.
--------------------------------------------------------------------------------
THE ALARM LIST WINDOW

This scrolling window lists all the alarms currently waiting to go off, in date
order.   Alarms printed in red are those due to go off before 4am tomorrow.
Alarms marked with a narrow triangle at the left of the window are those set to
repeat.   If there is an asterisk at the end of the window title then the alarm
database has been modified since NewAlarm was loaded and not yet saved.   You
will be given the option to save it before the program quits.

Double-clicking on any of the alarms in this window will open the 'Alter alarm'
window.   This works like the 'Set alarm' window (see 'NEW ALARMS' above), only
it alters the settings of the selected alarm instead of creating a new alarm.
Click on 'Cancel' to leave the alarm unchanged - ADJUST-click on 'Cancel' to
restore its original settings but keep the window open for further editing.
Pressing 'Reset' will not delete the alarm - you need to delete alarms from the
menu (see below)

Clicking MENU over any of the alarms in this window will open a small menu with
four options which allow you to delete, alter (as above), copy or defer the
selected alarm.   If you elect to copy the alarm, a duplicate alarm will be
created and the 'Alter alarm' window will be opened to allow you to adjust the
settings, since it is assumed that you wish to base one alarm upon another
rather than creating two absolutely identical alarms!

To defer an alarm is to advance it by a week, a month, three hours or however
long the defined repeat interval might be; in effect, to skip the occasion when
it was next due to go off.  Only repeating alarms can be deferred.

--------------------------------------------------------------------------------
CONFIGURING THE PROGRAM

The default behaviour of various parts of NewAlarm may be changed by setting
the system variable <NewAlarm$Options> in your !Boot sequence (or by another
means) before the program is run.   This variable may contain any of the
following parameters, in any order:

-interval <number> and -value <number>
-autosave
-nowindow

If <NewAlarm$Options> does not exist when the program is first run, the default
settings in the !Run file will be used, namely
  Set NewAlarm$Options "-interval 4 -value 1  -autosave"
(repeating alarms default to once per week, alarm window opens on startup,
updates Alarms file every time alarm goes off)


The default setting in the 'Repeats' window can be altered using the -interval
and -value parameters.   Both need to be followed by a number showing the
required display:

 -interval (or -i) represents default repeat interval from 1 to 6, where
1=minutes and 6=years (see 'Intervals at which we can repeat', Messages file)

 -value (or -v) represents default repeat value from 1 to 255

i.e.  "-value 3 -interval 5" causes repeat window to open with
default value of 3 months.   If you pass invalid parameters or omit them
NewAlarm will revert to a setting of 5 minutes.


If <NewAlarm$Options> contains an "-a" or "-autosave" parameter, then the
Alarms file will be updated automatically every time an alarm goes off.   Note
that this will also store the position of both windows at that moment.   If you
wish to control what is saved and when, don't use this (I don't!)


If <NewAlarm$Options> contains a "-n" or "-nowindow" parameter, then the alarm
list window will not be opened automatically when the program is first run.

--------------------------------------------------------------------------------
FEATURES

Alarms are held in a file called Alarms in the directory Choices:NewAlarm
within the !Boot structure, if present, and the stored window positions are
held in a file Position.   Otherwise both files will be stored within the
!NewAlarm application directory itself.   Either of these files may be deleted
without ill-effects (apart from losing any data held in it!)

The time in the 'Set alarm' window is not reset to the current time whenever
you set a new alarm - nor are the repeats.   This is deliberate.   I find it
more convenient when setting a number of alarms.   The 'Reset' button will
update the displayed time if required.

If the top line of the alarm text begins with an asterisk then the text of the
three icons will be combined and run as a 'task alarm'.   If you want to do
anything complicated it is easier to create an Obey file with the necessary
commands in it, and then create a task alarm which runs this Obey file.

The alarm list window extends horizontally to fit the longest alarm entered,
but doesn't shrink back when they go off (or when you delete them).

To avoid confusion with the existing newly-updated entry in the alarm list, any
repeating alarms recalled using 'Show'/'Edit' 'Most recent alarm' are displayed
as simple one-off alarms without repeat information.   'Show' will display the
time the alarm was originally due;  'Edit' will update the 'Set alarm' window
with the current time but the original text.

If NewAlarm displays an hourglass and appears to hang when you run it, it is
probably calculating multiple repeats.   For example, if you set up an alarm to
repeat every five minutes and then don't load NewAlarm for two or three months,
it may take several minutes to calculate when the next repeat to go off should
be.   Pressing ESCAPE will bring up an error box telling you how far it has got
and giving you the option to abort the process.   If you select the CANCEL
button the repeating alarm will be deleted altogether - if you click on OK
NewAlarm will continue to calculate repeats.

The computer *will* continue to multitask while an alarm is going off.


Yes, my alarm clock really does look like that.

--------------------------------------------------------------------------------
CREDITS

I am indebted to the authors of Acorn's !Alarm, Doggysoft's !RoughTime, and
!Tyme for various features which I have put into this program  indeed, it was
intended to be an amalgam of what I liked best about all of them.   In true
Microsoft fashion, while I have imitated the 'look and feel' I haven't actually
copied any of the code!

I am also indebted to Andrew Ayre for his DrWimp library.   Although NewAlarm
now uses its own Wimp procedures, DrWimp made my life much easier during the
intial development of the program.

The SlidingHeap module and BASIC library are  Steven Haslam and may be
distributed under the terms of the GNU Public Licence (copy included).   This
module allows a program to set up a sliding heap of memory blocks within its
own Wimpslot, avoiding the fragmentation of the RMA caused by the OS_Heap
routines.   It works under RISC-OS 2 or greater.
--------------------------------------------------------------------------------
LICENCE

This program is freeware, distributed under the terms of the GNU Public
Licence.   Full source code is provided.   You may give copies to your friends,
alter the program, or borrow bits of it for your own programs, just as you
please without charge, provided you make it clear what you have done.
--------------------------------------------------------------------------------
CONTACTING THE AUTHOR

The author may be contacted at:
  144, Merton Hall Road
  Wimbledon
  London SW19 3PZ

or via e-mail at	harriet@bazleyfamily.co.uk

--------------------------------------------------------------------------------
HISTORY

See accompanying History file in this directory.