Dear Users of pToolSet:

pToolButtonsPro is a feature rich version of pToolButtons. Thanks to Bill
McIntyre's discovery, OS4- users utilizing HackMaster extensions can enjoy
all the benefits of pToolButtonsPro without any extra worry and hassle.

NOTE. If you do not use HackMaster extensions, whether OS5+ or OS5-, then you
do not need to read any further. Just install pToolButtonsPro (but NOT
pToolButtons) and enjoy the show.

NOTE. If you use external keyboards in OS5-, then please read EXAMPLE 1
below.

In what follows, I will assume that you are a "regular" Palm user who uses
the HotSync application to install and back up data, and who wants to enjoy
the benefits of both HackMaster extensions and pToolSet on her/his Palm
Powered handheld running Palm OS 3.5 through 4.1. Palm OS5+ users do not need
to follow these instructions although it won't hurt them either.

          INSTRUCTIONS FOR USING HACKS AND pToolButtonsPro

1. You need to use TealMaster as your hack manager application. Please don't
ask me if X-Master will work. I only experimented with TealMaster.

2. Launch TealMaster.

3. Make sure that you have one profile, say, "E", which has absolutely no
hacks enabled whatsoever.

4. Select the profile which you normally run, say, "A".

5. Select the "Profile Mapping" menu command.

6. Check the "Auto-switch profile by app" box.

7. In the bottom right list of applications, find "HotSync" and tap on it to
select it.

8. To the left of this list, tap on the profile that has no hacks enabled,
say. "E". You will see that the letter "x" next to HotSync has been replaced
by "E".

9. Repeat steps #7 and #8 with "pToolOff" and "pToolOn".

10. Optionally, check the "Beep on profile change" box.

11. Tap the "OK" button.

12. Select the "Preferences" menu command.

13. Pick either the "Manual" (I prefer it) or the "5" push button.

14. Tap the "OK" button.

          END OF INSTRUCTIONS FOR USING HACKS AND pToolButtonsPro

The next time you HotSync, TealMaster will change profiles to the one with no
hacks enabled and it will stay at that profile during the entire HotSync
procedure. It will switch back to the profile with the hacks enabled when you
go to any other application after the HotSync has been completed.

NOTE. If you have additional "hack-like" applications such as keyboard
drivers, then you may have to do a few extra steps manually to disable/enable
those whenever appropriate.

NOTE. As an additional benefit, from now on you can also update HackMaster
extensions without de-activating the current versions in TealMaster.

NOTE. Install EITHER pToolButtons OR pToolButtonsPro but NOT BOTH.

NOTE. Regarding #13 above, I use the "manual" delay in the auto-reactivation
preference in TealMaster. It is essential that pToolSet must activate before
TealMaster does. When pToolSet activates itself, you see a short message on
the screen. A 5 second delay with TealMaster may work but I recommend the
"manual" option.

Please read the enclosed 00README_pToolButtonsPro.txt regarding the use of
pToolButtonsPro.

Cheers, Paul [2me@PaulComputing.com]

################################## THE END ##################################

P.S. The reading of the material below is optional.

######################## OS 3.5 through OS 4.x NOTES ########################

Using pToolButtonsPro is not straightforward in Palm OS 3.5 through OS 4.x.
Hence, install it only if you know what you are doing. In the worse case
scenario, I expect that you may get an occasional crash which can be fixed
with a pin reset.

If pToolButtonsPro is used in OS 3.5 up to 4.x, then it behaves like a
HackMaster extension which operates independently of HackManager
applications. You can think of pToolButtonsPro as a self-regulating
HackMaster extension and HackManager combination. In other words, it works
just like most external keyboard drivers and other OS patching applications
such as such as Clipper and QuickBits.

If you don't use any HackMaster extensions, external keyboard drivers, or any
other OS patching application, then pToolSet does everything automatically
for you and you should have no problems whatsoever using pToolButtonsPro
instead of pToolButtons.

If you use HackMaster extensions, external keyboard drivers, or OS patching
applications, then you must keep in mind that pToolButtonsPro patches the
Palm OS functions EvtGetEvent() and EvtProcessSoftKeyStroke(). If some of
your active HackMaster extensions patch any of these, then you must make sure
that if you want to use pToolOff manually then you deactivate pToolSet (using
pToolOff), your HackMaster extensions, your keyboard drivers, and so forth,
in EXACTLY THE OPPOSITE ORDER as they were activated.

ANALOGY. If go into an apartment building, then first you open the entry door
and then the apartment door, but when you leave then you do it exactly in the
reverse order.

You can use, for instance, TealMaster's "Show Active Patches" menu command to
verify (see the Options menu) which Palm OS functions are currently modified
by your active HackMaster extensions.

SITUATION 1. Say, you use pToolSet with pToolButtonsPro and LapTopHack is
inactive via TealMaster. Now you go to TealMaster, activate LapTopHack, then
use pToolOff to turn off pToolSet. You will see that LapTopHack is
non-operational. Why? Because LapTopHack was counting on pToolSet to give
directions towards the patched functions but pToolSet has been turned off. If
you deactivate LapTopHack and then reactivate it again, then all will be
working again.

NOTE. If you can create similar scenarios which lead to reproducible crashes,
please let me know so I could include them as examples.

NOTE. The above explanation also explains why external keyboard drivers or
other OS patching applications tend to misbehave and/or crash.

EXAMPLE 1. I use TealMaster, LapTopHack, pToolButtonsPro, and Type'n Go on my
Palm 515. The latter is a keyboard driver. LapTopHack patches EvtGetEvent()
and EvtProcessSoftKeyStroke() and Type'n Go patches EvtGetEvent(). I use the
"manual" delay in the auto-reactivation preference in TealMaster. Before each
HotSync I go through the following procedure:

    switch to a profile which has no hacks enabled in TealMaster
    deactivate Type'n Go
    HotSync
    activate Type'n Go
    reactivate LapTopHack in TealMaster

The ORDER of action is essential. I never ever had any crashes related to
pToolButtonsPro yet.

EXAMPLE 2. I use TealMaster, LapTopHack, EventAnalyzerHack, and
pToolButtonsPro on my Palm 515. LapTopHack patches EvtGetEvent() and
EvtProcessSoftKeyStroke() and EventAnalyzerHack patches EvtGetEvent(). I use
the "manual" delay in the auto-reactivation preference in TealMaster. Before
each HotSync I go through the following procedure:

    switch to a profile which has no hacks enabled in TealMaster
    HotSync
    reactivate EventAnalyzerHack and LapTopHack in TealMaster

The ORDER of action is essential except that inside TealMaster you can
deactivate and activate the hacks in any order you want it. I never ever had
any crashes related to pToolButtonsPro yet.

NOTE. If you think that you can save steps by turning all hacks off using the
"Off" profile in TealMaster in one fell swoop instead of switching to a
profile which has no hacks enabled, you will find out that this may or may
not work. It does work for some and it does not for others.

NOTE. The above examples use ideas of Ray Drew and Bill McIntyre.

NOTE.  As I mentioned above, if you want to use pToolOff manually then you
must deactivate pToolSet (using pToolOff), your HackMaster extensions, your
keyboard drivers, and so forth, in EXACTLY THE OPPOSITE ORDER as they were
activated.
