Battery Widget Readme

From OS2World.com Wiki
Jump to: navigation, search
BatteryWidget V0.2.1
--------------------

This is a Battery life/status display widget for XCenter.  It displays the power and battery status as
an icon and/or a percentage or number of minutes.  When the cursor is over the widget, the tool tip
displays the power source (AC or Battery), the battery life and the remaining life in minutes.  When
running on the battery, the icon displays the approximate battery life left.  If the battery is being
charged, it will be displayed behind the AC power icon.

The battery life and power status are shown in the following ways:

- When running on the battery, the battery icon changes to indicate how "full" the battery is.  It will
  change to red when the life drops below 15%.
- The icon indicates when AC is plugged in.  The text colour can also be changed.
- If the AC icon and the battery ar displayed at the same time, the battery is being charged.  If only
  the AC icon is displayed, the battery is more than 95% full.
- When the battery drops below 15%, the background colour changes.  This defaults to red.
- The text colour can change if AC is plugged in.  This must be set before it happens.
- The tooltip displays the power status, the battery life as a percentage and the time the battery will last.

Note: The battery time is reported from APM.  This is the battery's or APM's guess of how long the battery
will last.  See "The Time Divider" below for some adjustments to this.



Installation
------------
Copy Battery.DLL into the "plugins\xcenter" subdirectory of your XWorkPlace intallation directory.
Then start XCenter and add a new Battery widget.


Usage
-----

To change the colours used, drag a colour from the colour palette and drop it on the widget.  Hold the
control key down while dropping to change the text colour.  The colour changed will depend on the current
status.  i.e. To change the text colour for AC power, plug the power in.  Then to change the text colour
for the battery powered state, unplug the power.  Similary for the background colours.
Note: This changes the background and text colours.  The icon colours cannot be changed.

Double-clicking the widget will open the OS/2 Power object.

On the properties dialog, the following can be set:
- Display "Icon and Text", "Icon only" or "Text Only".
- When displaying text, the battery life can be displayed as "Percentage" or "Time".
- The time can be either "Minutes" or "Hours:Minutes".
- The "Time Divider" can be set as a number.  See below for details.
- For debugging purposes, check "Debug Info In Tool Tip" will display some of the raw data that is being
  returned from APM.  See "Bug Reporting" for what to do with this

The Time Divider
According to the information I have on APM, one of the pieces of data return from APM is "Battery Time".
This is an estimate of the time remaining for the battery.  It is either in minutes or seconds (depending
on the value of "Battery Time Form").  On my system, the battery time returned is about twice what I expect
and is displayed when I'm running Win2000.   So, I set this value to two, to give me a more better report on
the time.


Known Problems
--------------
- I'm displaying the remaining time for the battery in the tool tip.  But, this is double what Windows 2000
reports for my laptop.  And double what I expect.
- Help might not display.


Bug Reporting
-------------
If you find any bugs, please tell me at the contact address below.  Tell me:
- version of BatteryWidget.
- OS/2 Version and fixpack level
- Version of XWorkplace
- Any relevent sections from the XWP logs.
- APM version.
- Get Roman Stangl APM/2 (APM2V14.ZIP on hobbes), and send me the result of running "APM /verbose".
- Turn on "Debug Info in Tool Tip" copy the info displayed.


Version History
---------------
01/06/2001 - 0.1.0
- Initial release

10/06/2001 - 0.2.0
- Icon or text display
- Displaying percentage or time in minutes
- Icon "borrowed" from "Battery power monitor" widget in XWorplace.
- Settings dialog for display style
- Better error checking (but still not that much :)

28/06/2001 - 0.2.1
- Time remaining can be displayed in minutes or hours and minutes.
- Better display if there is no battery.
- Corrected spelling mistakes in this file.
- A bit more error checking
- Added version number to properties dialog.


Copyright
---------
Copyright (c) 2001 David Forrester. All rights reserved.
Parts copyright (C) 2000 Ulrich M”ller.
Other parts Copyright (C) by Roman Stangl (rstangl@vnet.ibm.com) 1997, 1998


WARNING!
--------
This software is provided as is.  No warranty is given by the author,
expressed or implied.  Use this software at your own risk.  The author
assumes no responsibility for any damage from the use of this software.

This software is freeware which means that it is free for use and distribution.



Contact
-------
If you find any bugs, have any suggestions or simply want to say how wonderful
or terrible the BatteryWidget is, drop me an e-mail

Author:        David Forrester
e-mail:        davidfor@terrigal.net.au
www:           http://www.os2world.com/djfos2