
This is Readme.txt for 3AlarmHack version 0.92b

3AlarmHack is 1999 by Roger Chaplin <foursquaredev@att.net>
                        http://home.att.net/~foursquaredev/


----------------
| Introduction |
----------------

3AlarmHack is a utility that enhances the alarms in Palm Computing(R) platform
handhelds that run Palm OS(tm) 3.x:
    o   a selection of alarm sounds to replace the standard tone
    o   select the number of times to play the sound (1-9)
    o   repeat the alarm any number of times (0-9999) at any interval
        (1 second to 9999 minutes)
    o   flash the backlight while sounding the alarm, or just turn it on
        and leave it on (great for night-time alarms)
    o   support for TaleLight and TaleVibes devices (for more information on
        these, see http://members.aol.com/gmayhak/tcl/)
    o   silent alarm, using only the backlight and Tale device

The original Pilot and PalmPilot devices were quite deficient in terms of
alarms; when an alarm sounded, the unit made a single beep. Wes Cherry
wrote a utility called AlarmHack that greatly enhanced the alarm sounding
ability for any app running on the device. Unfortunately, AlarmHack does not
run on handhelds that use Palm OS 3.x, such as the Palm III(tm) connected
organizer.

Palm Computing did include some alarm improvements in the Palm(tm) Date
Book app that comes built-in to the OS 3.x handhelds: different sounds, and
selectable repeat. However, the choice of repeat interval and number of
repeats is very limited, with the shortest repeat interval being one minute.
And other 3rd party apps that can sound alarms get no benefit from the Date
Book alarm improvements.

3AlarmHack overrides the alarm sound and repeat settings in the Date Book app,
and also gives the alarm enhancements to any 3rd party app that sounds alarms.

3AlarmHack is a Hackmaster hack, intended for use ONLY on Palm Computing
platform devices that use Palm OS 3.x. These include (at the time of this
writing) Palm III, Palm IIIx(tm), Palm V(tm) connected organizers, and
Pilot or PalmPilot handhelds with the Palm 2MB Upgrade. DO NOT USE
3AlarmHack ON ANY DEVICE THAT USES Palm OS EARLIER THAN 3.X. DOING SO WILL
VERY LIKELY CAUSE LOSS OF DATA ON THE DEVICE. For non 3.x devices, I recommend
Wes Cherry's AlarmHack (in fact, if AlarmHack ran on 3.x devices, there would
most likely not be a 3AlarmHack).

3AlarmHack requires Hackmaster, available at http://www.daggerware.com.
Hackmaster is shareware. If you decide to keep using it, please register.


----------------
| Installation |
----------------

The 3AlarmHack distribution includes this readme file, plus two PRC files:
3AlarmHack.prc and 3Alarm.prc. Use the following procedure to install
3AlarmHack:

1.  If you have not yet installed HackMaster, do so
2.  Install both the PRC files onto your Palm Computing device
3.  Launch HackMaster and enable 3AlarmHack


---------------
| Usage Notes |
---------------

When you enable 3AlarmHack, the Date Book alarm settings (on the Date Book
preferences screen) no longer have any effect; Date Book alarms will sound
according to the settings you have made in 3Alarm.

The Test button tests the "Alarm Sound" and "Alarm Visual" settings as they
appear on the screen.  You do not have to hit the Apply button before testing.
You do have to hit the Apply button in order for your settings to take effect
for alarms.

To select silent alarm, uncheck the "Play" checkbox. When an alarm goes off,
any Alarm Visual you have selected will activate as normal, but there will be
no alarm sound.

The "times" setting under "Alarm Sound" is the number of times the sound will
play on the first alarm, and on each optional repeat. Tap on the number to pop
up a list from which you may choose.  The "times" setting under "Repeat" is
the number of ADDITIONAL times the alarm will sound (the alarm will always
sound at least once). For example: set "Alarm Sound" to "play Sci-fi 2 times",
and set "Repeat" to "5 times every 10 seconds". When one of your apps alarms,
the Sci-fi sound will play twice, then 10 seconds later, it will play again
twice, and so on, a total of 6 times.

Uninterruptable sounds cannot be stopped by tapping on the screen or pressing
the hardware buttons. This could be useful if you carry your handheld in your
pocket and the case presses against the screen. An uninterruptable sound will
play at least once even if something is pressing on the screen.

All sounds generated under the control of 3AlarmHack and 3Alarm obey the
"Alarm Sound" setting on the general preferences screen.


-----------------
| Compatibility |
-----------------

3AlarmHack works with any app that generates alarms using the standard alarm
sound or by playing a MIDI sound. Some apps, such as BigClock, have their own
alarm sound generation controls. To make these apps work with 3AlarmHack, make
sure you set their alarm setting to "standard" (or whatever they happen to
call it). You can experiment by disabling 3AlarmHack, then adjusting the app's
alarm setting until you get the standard alarm sound (the one called "Alarm"
in 3Alarm's popup list). Then when you re-enable 3AlarmHack, your app will
alarm using the 3Alarm settings.

Here are some notes about 3AlarmHack's compatibility with specific apps:

ReDo:           Alarms sounded using ReDo's NLT option will follow the
                settings on 3Alarm's "Alarm Sound" and "Alarm Visual", but
                ReDo controls the repeat interval and the number of repeats.
TrekSoundsHack: In 3Alarm's "Alarm Sound" section, select the "Alarm" sound.
                Also, make sure that in HackMaster you enable 3AlarmHack AFTER
                you have enabled TrekSoundsHack (so that 3AlarmHack appears
                higher up in the list). Now the alarm sound you choose in
                TrekSoundsHack will play according to the settings in 3Alarm!
                The net effect is that TrekSoundsHack overrides only the alarm
                sound selection (Alarm, Alert, Bird, Concerto, etc.), but all
                the other 3Alarm settings are still in control.
Datebk3:        3AlarmHack completely ignores alarms generated by Datebk3.
                This should be no big deal, since Datebk3 has essentially the
                same alarm controls as 3Alarm.
ActionNames:    3AlarmHack overrides the alarm settings, but the snooze
                feature still works.


-----------
| License |
-----------

3AlarmHack is freeware. Share and enjoy. However, 3AlarmHack is not in the
public domain. I retain the copyright and all ownership rights.


--------------------
| Revision History |
--------------------

May 21, 1999        v0.92b (Beta)
    o   Fixed problem with DateBk3 alarms not making any sound

May 17, 1999        v0.91b (Beta)
    o   Added support for ActionNames. This fix should help not only
        ActionNames, but indeed 3AlarmHack should now work more reliably and
        smoothly with ALL apps that can generate alarms
    o   Added option to just turn the backlight on without flashing it (thanks
        to Arthur Ehrlich for the idea)
    o   Added support for Tale devices
    o   Added silent alarm feature

April 29, 1999      v0.9b (Beta)
    o   Added flashing backlight option
    o   Added uninterruptable sound option

April 25, 1999      v0.8b (Beta)
    o   Radical change. 3Alarm now provides all the alarms setting controls;
        no more switching to Date Book to change alarm settings. 3Alarm now
        completely overrides the settings on the Date Book preferences screen.

April 20, 1999      v0.7b (Beta)
    o   3AlarmHack no longer causes fatal errors with alarms sounded by
        Pimlico Software's Datebk3 app. 3AlarmHack completely ignores alarms
        sounded by Datebk3 (this is no loss, since Datebk3 provides a great
        deal more flexibility in control of alarms than you can get with
        3AlarmHack)

April 17, 1999      v0.6b (Beta)
    o   3Alarm remembers settings across soft reset
    o   Added small icon for the app launcher
    o   Alarm sound does no longer repeats if being played from the system
        preferences screen (try this on v0.5b and you find that there's no way
        to cancel the repeats!)

April 5, 1999       v0.5b (Beta)
    o   Major new feature: use Datebook alarm settings for ANY app that
        generates alarms

March 25, 1999      v0.4b (Beta)
    o   Fixed a memory leak. Opening Datebook's preferences form and then
        popping up the Play Every list caused you to lose 60 bytes.

March 22, 1999      v0.3b (Beta)
    o   Fixed a very serious bug that could cause a fatal error to occur in
        just about any app. One specific instance is closing the Address Book
        "Edit" form after having popped up the "Category" list on the
        "Details" form.

March 21, 1999      v0.2b (Beta)
    o   First beta release. Added modification of the "Play every" list items
        to show the hacked interval times.

March 14, 1999      v0.0a (Alpha)
    o   First alpha release. No user interface hack.


-----------
| Support |
-----------

If you have suggestions, comments, constructive criticism, or questions,
please let me know. Even though 3AlarmHack is freeware, it is my intention
that any software I release to the public is well-designed, robust, and
essentially bug-free. If you encounter a bug, please let me know!

The most recent version of 3AlarmHack has been thoroughly tested on
PalmOS 3.0.2, both on real hardware and under emulation, and on PalmOS 3.1
under emulation. There are no known bugs.


---------------
| Limitations |
---------------

1.  If an app generates an alarm, and subsequently generates another alarm
    while the first alarm sound is still repeating, the subsequent alarm will
    not produce any sound. However, the subsequent alarm's dialog will still
    appear. All of this is by design.

2.  When setting the alarm volume on the system preferences screen, you won't
    hear the effect of your change until you switch from the preferences app
    to another app. I may add a workaround for this in a future release.
