=======================================================
BatteryControl HACK - v1.1 - (c)11/22/97, Peter Strobel
=======================================================
BatteryControl HACK - v2.0 - (c)12/14/97, Peter Strobel
           (only available for registered user of v1.1)
=======================================================

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

With BatteryControl, you can keep your battery condition always in sight. It
displays a little symbol in all apps that's more or less filled.
BatteryControl is a Hack, so you'll need Ed Keyes HackMaster to run it. 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 BatteryControl 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.

... we will be back after this short messages ...

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, USR missed to implement.
             PLEASE REGISTER HACKMASTER IF YOU USE IT !

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

BatteryControl also works correctly in gray-scale apps (like Wingman), there
it will fill the battery symbol with a light gray - pure luxury :). Before
you e-mail me: I know, it will not work in Galax. I think Galax passes a few
(quite a few) system calls, that's why.
Since v1.1, BatteryControl disables the symbol while image programs are active,
that use their own databases for screen-memory. Typical candidates are Image
Viewer or Sweetheart. Without a significant slow-down of the system, there is
no chance for BatteryControl to overlay the little symbol on a database
related screen-memory. It might be nicer anyway, when the images are not
disturbed by the battery symbol. When the display returns to normal, the
battery symbol appears again. My special thanks go to Art Dahm, the author of
Image Viewer. He was a great help fixing that problem.

Version 2 adds a whole new functionality in controlling also the low battery
warning levels. Due to a very strange routine in the OS, previous attempts to
control that warning level *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. Such, displaying the warning level what some
programs do (FPSUtil), is merely a read-out of the OS defaults. 
IMPORTANT: Programs that display the warning level *will* show the new levels
setup by BatteryControl, *but* it may take up to 5-6 minutes until the value
is updated. So be patient after activating the hack :)
 
There are two more features in version 2: You can choose to hide the symbol
as long as the battery is above a certain level and - my favourite feature -
you can choose to be warned only once for the first 2 low battery levels
(yes, there are three!).
For customers who _only_ want the warning level management, whithout seeing
the symbol at all, I lowered the minimum calibration level. Look at point 6
of 'TELL ME MORE' in BCPatch 2.1 .



2. WHY BATTERY CONTROL ?
------------------------

The main reason to write BatteryControl 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.
With version 2 however, I fulfilled my personally biggest wish: Not to be
annoyed *every 3 minutes* that my batteries are low, when I know they are
good for another few hours !!! And, as a user of rechargeables, the adaption
of the warning levels was important.


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 BatteryControl considers when displaying the
little symbol. Since you can freely define the calibration of either
setting, for BatteryControl 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. BatteryControl 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 toggle to NiCad.
Completely confused now :) ? Play with it, and you'll see what I mean.
   

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

When BatteryControl 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 default calibration
values are listed in the [i]nfo screen of the hack.
VERSION 2: Your actual calibration is listed in the [i]nfo screen, so you can
always look up your last modification.
The default settings for the low battery warning is the one of the OS 2.x. So,
as long as you don't change anything, you won't even recognize that Battery
Control does the warning.


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:

===========================================
BCPatch - v2.1 - (c)12/19/97, Peter Strobel
===========================================

1. WHAT IS BCPatch
------------------

With BCPatch, a desktop program, you can customize BatteryControl. 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 BatteryControl 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. 

VERSION 2: It will replace version 1. BCPatch v2 is able to patch all versions
of BatteryControl, automatically recognizing what hack version you have.

VERSION 2.1: This version will look for two hack files in it's directory,
either BATTCTRL.PRC, which is normally the unregistered version, or
BATT_V2.PRC, which is the version I send to my registered user. This feature
is for the safety and convenience of my registered users, so they don't have
to rename the BATT_V2 file anymore, and there no more danger of overwriting
the registered file with the unregistered, if they retrieve a new version of
BCPatch in the archive on my site.
To save you time: Renaming the unregistered version BATTCTRL to BATT_V2,
doesn't make it a full featured version. The unregistered version misses alot
of code, which BCPatch recognizes.
If you have a BATTCTRL.PRC and a BATT_V2.PRC in the same directory, BCPatch
prefers the BATT_V2.PRC.


2. HOW CAN I RUN BCPatch
------------------------

For running BCPatch, 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 BCPatch, 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, 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 BCPatch, just unzip the
2 files (bcpatch.exe, battctrl.prc) in the *same* directory (previous v1 users:
You don't need the file PILOT1.BMP anymore, it's now linked to the EXE).
Please make sure you use the battctrl.prc that comes in this archive. Versions
prior to 1.0 are not 'patchable'. BCPatch recognizes, whether a battctrl.prc 
or a batt_v2.prc and what version of it is present, and it'll give you an
appropriate info about what you can do with it.

NOTE: If you're a registered user, you'll get your version via e-mail with
the name BATT_V2.PRC. From BCPatch v2.1 on, you don't have to rename it
anymore. BCPatch v2.1 looks for two possible files (BATTCTRL and BATT_V2),
and preferes BATT_V2 if present.
BTW, BCPatch displays in the header bar of the window, what file was found.

* ANOTHER IMPORTANT NOTE: Recently, PilotGear advised registered customers to
* download a registered version from some URL and unzip it with a password.
* THAT IS NONSENSE! The registered version was - and will be - *never* on the
* net. The only way to get it, is directly from me by e-mail!


3. HOW TO USE BCPatch
---------------------

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 and hit the DO IT button. Then hot-sync the patched BATTCTRL.PRC .
If you want to leave the program without modifying battctrl, 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.
If you're using the unregistered version however, you will be notified, that
BCPatch is not able to patch your warning levels and the warn-once or the
blanking options.

PLEASE NOTE: You don't have to delete a previous version of BatteryControl
on your Pilot before hot-syncing the new one, *BUT*: You have to go to the
HackMaster control screen and disable BatteryControl 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.

Please note that BCPatch will read and display the actual settings from the
PRC-file thats in the directory of bcpatch. And it doesn't create a backup.
So if you're afraid of losing your default settings, keep a copy of your
original PRC anywhere else. Version 2 now offers a few default settings in the
menu which are 'hard-wired'. Except the two OS defaults, the values are just
my inventions. They come close to typical values for different battery types.

A last note: BCPatch 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 with the new functions of version 2, 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.


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

BatteryControl is a $5 shareware, the PatchBoard comes free with it.
BatteryControl v1.x is not crippled, nor has it any nag-screens. You can use
it for a time. If you keep it, please register at:http://www.pilotgear.com
With the available version 1.x however, you can not use the warning level
management and the additional options. The full functional version 2.x is
available for registered v1.x users only.

It'll give you a really good feeling, to *own* your very personal copy :), and
you'll get all further, improved versions of BatteryControl for free. Also,
only registered users get all the features of version 2.
If you decide not to register, please remove BatteryControl from your systems.

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

I took great care to release BatteryControl and BCPatch bugfree, and in the
moment there are no known bugs. However, BatteryControl 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 Battery-
Control or BCPatch. Both programs are copyright 1997 by Peter Strobel.


==============
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 :).
 

===========================
Release history and updates
===========================

v1.0	Initial release. (11/25/97) / BCPatch 1.1 initial release

v1.1    Fixed bug with various image programs like ImageViewer
        and Sweetheart. (12/06/97)

v2.0    Added warning level management, warn-once-only feature and blank
        feature. (12/14/97)

BCPatch 2.1
	Modified max. calibration level. Now 1.5V is possible to blank the
	symbol quasi permanently.
        Minor cosmetic changes, added 'Symbol Calibration' label to the
        approriate controls.
	BCPatch now recognizes the file-name BATT_V2.PRC for registered users.


==============
WHAT'S COMING?
==============

Well, did v2.0 with all the announced features now. I'm basically waiting for
bug reports (hopefully not ...), then I work on the debugging of course. Or I
get a wish-list (yes, please ...) from my users, then I'll see what is
possible to implement.
One of my plans for v2.x is to make the Alkaline/NiCad setting 'reset resis-
tant'.

---------------------------------------------------------------------------

For the latest version and news, check my site:
                                          http://home.t-online/home/PSPilot

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



(c)Peter Strobel - 1997, 18th December
