Clock
version  1.2a

Dan Comiskey
cis 74547,3542

Clock is an alarm clock for the 3a.  It uses the full screen to display the time, and has an alarm that can be configured to ring once or daily, snoozed, selectable sound and volume, and will save its settings between launches if desired.

The installation is straightforward - put the Clock.opa file in any APP directory, and install on the system screen (or within an application launcher or shell).

Features: 

	Doesn't use the build-in ALM: driver!
	Will turn the Psion on and come to foreground when an alarm is due.
	Idles when in background, allows auto turn-off to occur.
	Will auto turn-off when in foreground (uses the time-out setting from system screen)
	Any Wve file may be used as alarm sound
	Plays any alarm sound for up to 45 seconds (regardless of how long sound is)
	Stops alarm playback after 45 seconds, repeats alarm every 5 minutes up to 4 times
	Saves prefs (if desired)
	Customizable snooze setting
	Psion still useable while alarm is snoozed
	Easily turn off Psion - just hit the space bar
*	Detects if 12 or 24 hour time format is in use, and displays accordingly
*	Esc key sends it to the background (last application comes to foreground)
*	Display shows if an alarm is pending, and when it will ring.
*	Option to come to foreground when machine is idle (only when auto-off inactive)
	Proper monitoring of system events, will quit if the system asks it to
		(even when in foreground, to keep rcom users happy)
	"Nifty" shadowed numerals

* New/improved feature

Its use is pretty straightforward. The clock runs continuously, if you set an alarm it will ring when next that time of day occurs (ie if it is 8am, an alarm set for 7am will ring the next day, whereas an alarm set for 10 am will ring later that same day). The space bar turns the psion off immediately. To snooze a ringing alarm, hit the space bar, any other key will silence the alarm. (The Psion can be configured turn off when snoozed, if desired.) The program is about 8k on disk, and uses 9-10k of memory for itself and the system uses 17-18k additional while it is running. (I've observed this to go to 26k while an alarm is sounding). These values are on my 512k 3a, which is the only machine this has been tested on.

This program is "cheap shareware" - if you use it, do something nice for some one that you wouldn't have done anyway. (Kind of pink and squishy sounding, I admit.) Personally I'm fed up with overpriced shareware for the Psion; IMHO, anyone charging more than 10-15$ for a program should have a very good reason why it's worth it, and the limited size of the potential market is not such a reason. I'd rather people use my work and enjoy it.  Sharing programs you have written for the Psion without charging for them would qualify as "something nice", especially if you share them with me!

Note: this program does not work if run on the PC Psion emulator. It panics when the call to the FRC: driver is made; I assume this driver must not exist in the emulator environment.

I've tried to make this program as complete as possible - the only other thing I thought of was multiple alarms. I've figured out how I would do that, but it would take a lot of work and time so I think it may not happen. (I'm a 4th year Medical student, so I'm not supposed to spend all my time writing code!) I'd also like to rewrite the code to be asynchronous, as demonstrated in Appman (thanks Jezar), so the clock would continue to run while menus and dialogs were up, but I just don't understand the Window server well enough to tackle this (eagerly awaiting the release of the Wserver psionics file...but begining to lose hope...) 

If you can think of any other functions that would be good, or just wish to give me feedback, please contact me. (note: I mean this. I've implemented all the requests made so far, so if you want something, don't hesitate to ask.)

The normal legal stuff applies - although I've done my best to make sure this program won't hurt you, use it at your own risk, there are no warrantees. I retain all rights to this program and the code, if you want the code email me and I'm likely to be agreeable (and it will be a lot more understandable than Revtran generated!). If you wish to put this on any media which you are selling for profit (CD or floppy) please contact me for permission.

All of the functions are pretty self-evident, however for those who *like* to read these readme files...

MENU choices

	Set Alarm (psion-s)

Allows you to set an alarm. The default time and mode (once vs. daily) are stored in the prefs file if it exists, otherwise the defaults of 8:00 am and once are offered)

	Preferences (psion-p)

Allows you to create a preferences file that will be used for default settings. The default settings (without a prefs file) are:

Default Alarm	Chimes
Default Time		8:00 am
Snooze Time		7 minutes
Alarm Volume	Loud
Daily Alarm		No
Off on Snooze	Yes
Front on Idle		No
Prefs Disk		M (Internal)

Alarm - may be any sound in a WVE directory, or the three sounds in ROM (Chimes, Fanfare, Soft bells).

Time - any time

Snooze Time - from 5 to 15 minutes

Alarm Volume - Soft, Medium, Loud, Ouch!

Daily Alarm - Yes or No (note even if this is Yes, you still need to set the alarm after you load the program, it will NOT "turn on" the alarm without being told to)

Off on Snooze - turn the Psion off when an alarm is snoozed.

Front on Idle - OK, I thought this was a strange request at first, but the idea kind of grew on me with time...like a fungus or a tick. Basically, after the machine is idle for a period of time, the clock will come to the foreground. I've taken great pains to make sure this only happens when auto-off is disabled, either by being turned off, or by being temporarily disabled since the machine is on external power. The idle period is either the off time + approx. 10 secs, or 5 minutes if auto-off is completely disabled (since there is no off time under these circumstances)

Prefs Disk - M, A, or B.  Note: this is the order the disks are searched for a prefs file at startup. If you change where this file is stored, only the first prefs file found will be used.  It is located in the OPD directory.

	Cancel Alarm (psion-c)

Cancels the pending alarm.  If the alarm is set to daily, it will prompt to cancel just the next alarm, or to turn off the daily alarms.

	About (psion-a)

Author and version.

	Exit

Exits the Program, cancels any outstanding alarm.

Credits: The numeral drawing routines were derived/modified from code posted on the Net by Juergen Weigert and Rudolf Koenig, called s7. (however I'd be inclined to give them more credit if they had chosen to comment this code!!)

Propeller-Head Section

	A question for the technically inclined: 
	I know that CALL($078b,0,4,0,$40a,ADDR(array%()) will return the time remaining before auto-off in array%(2)  (or a negative countdown if auto-off is turned off, as compared to disabled due to external power). However is there another way to ascertain when the last activity was without trying to do it indirectly via this CALL? (Also what meaning do the elements of the array% beyond array%(2) have, if any?)

History
1.2a	Fixed display of 24hr time (no 24 o'clock!)

1.2	Changed alarm pending indicator so the alarm time (and date) are also displayed.

	Esc key now sends program to background (therefore last foreground app comes to foreground)

	Added "Front on Idle" feature

	12 or 24 hour system setting aware, with appropriate display 

1.1	Rewrote alarm notification dialog (so you can hit ANY key to silence the alarm - except the spacebar which is the snooze bar) plus added background graphics

	Changed alarm playing procedure to play alarm for 45 seconds (regardless of length of WVE file or repeats saved with it); also to stop alarm automatically and reset it up to 4 times if not silenced.

	Enabled detection of external power, and system settings to determine if autooff should occur when on external power.

	Checked for existence of SSD before scanning it for wve files or trying to write prefs file to it.

	General cleaning up of code.

1.0	Never released - I didn't want to inflict a version 1.0 on anyone!