Battery Widget Readme

Battery Widget 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: 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.
 * 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 are 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.

Installation
Copy Battery.DLL into the "plugins\xcenter" subdirectory of your XWorkPlace installation 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. Similarly 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 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 relevant 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 XWorkplace.
 * 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