======================================================
VoltageControl HACK - v3.2 - (c)4/13/98, Peter Strobel
======================================================



CONTENTS:
=========

 1. WHAT'S VOLTAGE CONTROL?
 2. INSTALLATION
 3. HOW CAN I SWITCH THE BATTERY TYPE?
 4. DEFAULT SETTINGS
 5. WHAT IS VCPatch?
 6. VCPATCH INSTALLATION
 7. HOW TO USE VCPATCH?
 8. RELEASE HISTORY AND UPDATES - previous users, read this!
 9. WHAT'S COOKING
10. HOW TO REGISTER AND HOW TO CONTACT ME
11. SPECIAL THANKS
12. DISCLAIMER




1. WHAT'S VOLTAGE CONTROL?
--------------------------

With VoltageControl, you can keep your battery condition always in sight. It
displays a little symbol in all apps that's more or less filled.
Additionally VC handles the low battery warning levels. You can set your own
values, and switch off the annoying 3 minute nag, though you still have alot of
power left! You can choose to be warned only once for the first 2 levels.
Due to a very strange routine in the OS, previous attempts to control that
warning levels *had* to fail. The system routines, obviously offering the
modification of the warning level, don't work, I had to replace the system
routines completely.
IMPORTANT: VC is compatible with programs displaying the warning levels, they
*will* show the new levels setup by VoltageControl. But it may take up to 5-6
minutes until the value is updated. So be patient after activating VC.

If you like the warning level management mainly, without seeing the symbol all
the time, you can choose to hide the symbol as long as the voltage is above a
certain level. And - setting this level lower than the battery can ever reach -
you can use the warning management only. Please have a look at page 6 of the
'TELL ME MORE' menu in VCPatch 3.0 .

The main reason to write VoltageControl was, that - except the default OS
launcher - no program is considering the Alkaline / NiCad system switch,
and I'm a fan of rechargeables (NiMH). So the standard displays, like the
one in LaunchPad or AppMan gave me always nearly empty batteries, only
because rechargeables just have a lower voltage.
Second, I read alot of e-texts on my Pilot and I hated it, whenever the
system nagged me out of the blue to change batteries.




2. INSTALLATION
---------------

VoltageControl is a Hackmaster extension ...

----------------------------------------------------------------------------
... we will be back after these short messages ...

To use VoltageControl, you need to run Ed Keyes HackMaster on your Pilot. Look
for the latest version of HackMaster on http://www.daggerware.com.
Because of questions I got from users, I want to point out once more: I have
nothing to do with HackMaster. HackMaster is a program, that allows system
extensions/replacements like VoltageControl to reside in 'peace' amongst others
of its kind on the Pilot. If you want to know more about HackMaster, please
check Ed's pages. There you'll find also the HackMaster API, in case you want
to write your own hack.

PLEASE NOTE: Hackmaster is a great piece of software, and the farsight of Ed
============ made it possible, that the Pilot community can enjoy alot of
             great system extensions, Palm (USR, 3Com, whoever) missed to
             implement. PLEASE REGISTER HACKMASTER IF YOU USE IT !

ATTENTION:   A hack *MUST BE DISABLED* before you can delete it safely from
==========   your Pilot! I still get angry e-mails from people, who had bad
             crashes. I'm sorry, there is nothing a hack programmer can do.
             This is just a Hackmaster rule.

TRG-USER:    Note that it's not yet possible to run a hack in Flash. My
=========    best experience is, to keep Hackmaster and all hacks in RAM.
             Rumors are saying that Ed's working on an update for that.

... and now for something completely different ...
----------------------------------------------------------------------------

After you hotsynced VoltageControl the usual way with your desktop app, go to
Hackmaster and activate the VoltageControl Hack. That's it!

NOTE: If you previously used BatteryControl, please delete it first. Voltage
Control uses the same creator ID than BatteryControl, but due to any strange
OS behaviour, you won't get the new name in the memory manager, though the new
hack is installed and working.




3. HOW CAN I SWITCH THE BATTERY TYPE
------------------------------------

Again, because of some e-mails I got, here a short explanation of the dot
commands:
For certain actions - most of them are for developers - the OS knows the
undocumented dot commands. A dot command consists of a shortcut stroke,
followed by a dot (double tap) and a number between 0 and 7. The commands
0 to 6 are for development purposes, if you don't know what you're doing,
*don't* try them out! But the dot 7 command toggles the system between
Alkaline and NiCad batteries. To get a visible feedback, go to any text
entry form - i.e. NotePad - and enter: shortcut . 7 , you will see the
system response [Alkaline] or [NiCad] (its a toggle function).
IMPORTANT: Some of the dot commands can even wipe your Pilot. So please be
careful and don't try numbers other than 7.
Now, this setting is, what VoltageControl considers when displaying the
little symbol. Since you can freely define the calibration of either
setting, for VoltageControl the names Alkaline and NiCad just mean battery
type 1 and 2. I say this, because there is a drawback: After a soft reset,
the battery kind always returns to Alkaline. So, when you use the NiCad set,
you had to switch back everytime a reset occurs. To avoid that if you are
a regular rechargeable user, you can also store the NiCad values - i.e
max. 2.6 / min. 2.1 - as the 'Alkaline' setting. VoltageControl doesn't
care about the name. Then 'your' Alkaline set displays between 2.1 and 2.6
and you don't have to switch to set 2 (NiCad) at all. Got that? I'm sorry
if that sounds overexplained, but I caused some confusion with my first
explanation. To go a step further: If you are using mostly rechargeables
and only sometimes (i.e. on the road) Alkalines, it can be a good idea
to swap the two settings. Put the values for NiCads in the Alkaline set
and the Alkaline values (2.1 - 3.0) in the NiCad set. Then, after a reset
you have your mostly used NiCad values available and only when you use
rarely Alkalines, do the shortcut toggle to NiCad.
Completely confused now :) ? Play with it, and you'll see what I mean.




4. DEFAULT SETTINGS
-------------------

When VoltageControl is distributed, the default position for the symbol is the
lower/right corner. I found it most discrete there. Even when the battery
symbol (partly) overlays a control in an app, the control remains fully
functional. (To respond to a question I already had: No, you'll get no points
in SubHunt for a hit with the battery symbol <g>).
The actual calibration is listed in the [i]nfo screen, so you can always look
it up. The [i]nfo screen also changes, when you modify the default values with
VCPatch.
The default settings for the low battery warning are the one of the OS 2.x (or
OS 3.0). So, as long as you don't change anything, you won't even recognize
that Voltage Control does the warning management.


You may say now: Argg, exactly in the lower/right corner is the most important
information of my most beloved app ... well, if you run Win95 or NT, there's a
solution:



==========================================
VCPatch - v3.0 - (c)13/4/97, Peter Strobel
==========================================

5. WHAT IS VCPatch
------------------

With VCPatch, a desktop program, you can customize VoltageControl. You can
change the position of the symbol on the screen and the calibration of it.
I know, it's a strange solution, but I wanted VoltageControl to be flexible
and still keep the code as small as possible on the Pilot. A lot of people
will customize it once only anyway.

VCPatch will look for a valid VC Hack file in it's directory. Normally that's
the unregistered version VCTL.PRC or the registered one, VCTL_REG.PRC. If
you're an old BatteryControl user and want to keep for any reason BCHack,
VCPatch will also handle an existing BATTCTRL.PRC or BATT_V2. But I strongly
recommend the VC update, since only VoltageControl is OS3 compatible.

The different file names are for the convenience of my registered users, so
they don't have to rename the file I send them after registration. VCPatch
always prefers the registered version over the unregistered if both files are
existing in the VCPatch directory.




6. VCPATCH INSTALLATION
-----------------------

For running VCPatch, you need to run a 32-bit Windows (95 or NT) and you need
the Visual Basic 5 runtime system. I didn't include it in the archiv,
because it's 1.3MB and you may have it already on your system. I recommend,
just to run VCPatch, and if you get an unexpected error or a MSVBVM50.DLL
missing message, you probably never ran a Visual Basic 5.0 program on your
PC. Thanks to *Alan Weiner* (the author of fine software like AlCalc and
AlVenture), I could place a copy of the latest VB5 runtime system on his
server. Just look for the link on my software page, download the archive,
unzip it and run the VB5RUNT.EXE.

Now, you don't need to run an installation process for VCPatch, just unzip the
2 files (VCPatch.exe, VCTL.PRC) in the *same* directory and run VCPatch.




7. HOW TO USE VCPatch
---------------------

The program should be pretty self-explanatory. Move the symbol to where you
want to have it, customize the calibration values for each of the two battery
types, set your warning levels with the sliders and the way you want to be
warned with the check boxes. Then choose the first menu entry 'Do the patch
and EXIT'. Don't forget to hotsync your new VoltageControl file.
If you want to leave the program without modifying the hack, just use the
standard close button of the window (you know, the little x in the upper/right
corner <g>), or the menu item EXIT WITHOUT PATCH.

PLEASE NOTE: You don't have to delete a previous version of VoltageControl
on your Pilot before hot-syncing the new one, *BUT*: You have to go to the
Hackmaster control screen and disable VoltageControl there, as you have to
do with all hacks, before replacing (or deleting) them! A hack is a free
floating piece of code, that could be active all the time - so it's basically
not a good idea to change or delete it during its work :)

A word about moving the symbol: The green background of the symbol just points
out, what area will be covered on the Pilot. You can move the symbol vertically
in single pixel steps, while horizontal there are only 8 pixel steps (it is
much faster to work with byte boundaries).

Please note that VCPatch will also read and display the actual settings from
the hack. That way it's easy to do little modifications, since you always get
your last settings. But VCPatch doesn't create a backup. With the presets in
the menu, you can always set the values to any OS standard values. The OS3
standard values are the same than the OS2 ones. Except the two OS defaults,
the values are just my inventions. They come close to typical values for
different battery types.

A last note: VCPatch will look a bit nicer and compact on Windows desktops set
to small fonts. But it will work also on large fonts.

For additional help, look at the TELL ME MORE menu item. Point 6 is particulary
interesting for people, who don't like to see the symbol, but still want to
use the warning level management.




8. Release history and updates
------------------------------

Well, old BatteryControl users will have noticed, that VoltageControl is just
another name for BatteryControl - but they got the update and an explanation
anyway. I was just tired of the constant name confusion with Battery Monitor,
also a program of mine, but with basically a total different functionality.

So, the history starts from the last stage of BatteryControl:


v3.0        (04/13/98)
          - Initial release of VoltageControl.
            VoltageControl is the OS3 compatible BatteryControl. Along with VC,
            VCPatch was updated to v3.0 to handle the new file name of VC.

v3.1        (07/20/98)
          - Makes VC compatible with VDisplay.
            Well, it was no bug, but VC interferred with VDisplay. When VC was
            installed, VDisplay 'punched' the voltage also in the additional
            launcher screens and the category pulldown menu. Now VC sets a flag
            for VDisplay.

v3.2        (08/06/98)
          - Fixed a bug that rarely prevented the second warning level to show up
            (how embarrasing, it was there since v1.0 and nobody ever mentioned
             it .. <g>).
          - Code is now 100% OS3 compatible (PALM, GREAT: Some *old* OS1 and OS2
            routines behave different in OS3 now, although implemented for
            compatibility!)
          - The tiny battery symbol is Fitaly Keyboard 'friendly' now and stays
            behind Fitaly's window.
          - Cleaned the code and safed 200 bytes without loosing any functionality.
          - v3.1 was out a short time only, so most users might still be using v3.0.
            For all v3.0 users: VC 3.2 is is 'compatible' with VDisplay now. It
            prevents VDisplay from overwriting the category menu and the other
            screens in the original PIII launcher.


9. WHAT'S COOKING
-----------------

- Frankly, VoltageControl does what it should. As long as there are no nasty
  bugs, VC will remain as it is in the moment.
  I will however test it more thoroughly on a real PIII hardware as soon as I
  get one (due to 3Com's *phantastic* developer support, we have to wait as
  every user for a device ... not to talk about prereleases!)




10. HOW TO REGISTER AND HOW TO CONTACT ME
-----------------------------------------

To register VoltageControl, please visit:

either
          http://www.pilotgear.com

or
          http://www.pspilot.de  (section Software)


HINT: On my page you'll find a 'Buy Me' button right beside the download link,
      that brings you directly to my register page at PilotGear, so you don't
      have to search for it.
      German users can also pay me directly, click on the link 'berweisung'
      below the 'Buy Me' buttons.

      And for the latest version, always check *my* site - I can't track all
      archives and whether they always offer the latest version of my apps.


After registering, you'll receive your new version directly from me, usual
within the next 24 hours.

Registered users get also all further, improved versions and updates for free.


If you have suggestions, likes, dislikes, found bugs etc., feel free to e-mail
me at:
       PSPilot@pstec.de




11. SPECIAL THANKS
------------------

My special thanks are going to Murray Dowling, the author of many indispensable
apps and hacks (Recycle, SwitchHack, ClipHack), as well as to Alan Weiner the
maker of AlCalc and AlAdventure. Since English is not my native language,
Murray was a great help to avoid quite a few mistakes in that readme. Of course
my thanks go also to all the other regular IRC members of the pilot-pda channel.
All of them helped a lot, to keep the learning curve of a newbie bearable :).




======================================================
12. Now for the unavoidable disclaimer and legal stuff
======================================================

VoltageControl is an $8 shareware. You can try it out for 3 weeks without any
limitations. After the trial period, VC will nag you from time to time. VCPatch
is freeware and belongs to VoltageControl.

If you decide not to register, please remove VoltageControl from your systems.
ATTENTION: As all hacks, you *have* to disable VoltageControl first in
           hackmaster before deleting it!

You may give a copy of VCTL.ZIP to others under the same terms, but make
sure to keep always all files in the archive. VCTL.ZIP may be included on
any disk or CDROM of shareware sold by non-profit organizations. If you want
to include it in a commercial software collection, please contact me. Under
no circumstances the registered version of VoltageControl is allowed to be
distributed without the written permission of the author.

I took great care to release VoltageControl bugfree, and in the moment there
are no known bugs. However, VoltageControl is provided without warranty of
any kind, express or implied. I can accept no liability for data loss or any
other problems caused directly or indirectly by the use of VoltageControl.

All mentioned trademarks are of course property of their respective owners.

Both programs - VoltageControl and VCPatch - are copyright 1998 by Peter Strobel.



(c)Peter Strobel - 1998, 6th August
