+<?xml version="1.0"?>

+<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"

+"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [

+ <!ENTITY legal SYSTEM "legal.xml">

+ <!ENTITY appletversion "2.12.0">

+ <!ENTITY applet "Battery Charge Monitor">

+]>

+

+<!--

+ (Do not remove this comment block.)

+ Maintained by the MATE Documentation Project

+ http://developer.mate.org/projects/gdp

+ Template version: 2.0 beta

+ Template last modified Feb 12, 2002

+-->

+

+<!-- =============Document Header ============================= -->

+<article id="index" lang="en">

+<!-- please do not change the id; for translations, change lang to -->

+<!-- appropriate code -->

+ <articleinfo>

+ <title>&applet; Manual</title>

+ <abstract role="description">

+ <para>&applet; shows the current charge of the

+ battery and provides notifications if charge drops below a certain

+ threshold.</para>

+ </abstract>

+ <copyright>

+ <year>2005</year>

+ <holder>Davyd Madeley</holder>

+ </copyright>

+ <copyright>

+ <year>2004</year>

+ <holder>Angela Boyle</holder>

+ </copyright>

+ <copyright>

+ <year>2004</year>

+ <holder>Sun Microsystems</holder>

+ </copyright>

+ <copyright>

+ <year>2002</year>

+ <holder>Trevor Curtis</holder>

+ </copyright>

+ <copyright>

+ <year>1999</year>

+ <year>2000</year>

+ <holder>Jorgen Pehrson</holder>

+ </copyright>

+<!-- translators: uncomment this:

+

+ <copyright>

+ <year>2002</year>

+ <holder>ME-THE-TRANSLATOR (Latin translation)</holder>

+ </copyright>

+

+ -->

+

+ <publisher role="maintainer">

+ <publishername> MATE Documentation Project </publishername>

+ </publisher>

+

+ &legal;

+<!-- This file contains link to license for the documentation (GNU FDL), and

+ other legal stuff such as "NO WARRANTY" statement. Please do not change

+ any of this. -->

+

+ <authorgroup>

+ <author>

+ <firstname>Sun</firstname>

+ <surname>MATE Documentation Team</surname>

+ <affiliation><orgname>Sun Microsystems</orgname></affiliation>

+ </author>

+ <author>

+ <firstname>Trevor</firstname>

+ <surname>Curtis</surname>

+ <affiliation>

+ <orgname>MATE Documentation Project</orgname>

+ <address> <email>[email protected]</email> </address>

+ </affiliation>

+ </author>

+ <author>

+ <firstname>Jorgen </firstname>

+ <surname> Pehrson</surname>

+ <affiliation>

+ <orgname>MATE Documentation Project</orgname>

+ <address> <email>[email protected]</email> </address>

+ </affiliation>

+ </author>

+ <author>

+ <firstname>Angela</firstname>

+ <surname>Boyle</surname>

+ <affiliation>

+ <orgname>MATE Documentation Project</orgname>

+ </affiliation>

+ </author>

+ <author>

+ <firstname>Davyd</firstname>

+ <surname>Madeley</surname>

+ <affiliation>

+ <orgname>MATE Project</orgname>

+ </affiliation>

+ </author>

+ <!-- This is appropriate place for other contributors: translators,

+ maintainers, etc. Commented out by default.

+ <othercredit role="translator">

+ <firstname>Latin</firstname>

+ <surname>Translator 1</surname>

+ <affiliation>

+ <orgname>Latin Translation Team</orgname>

+ <address> <email>[email protected]</email> </address>

+ </affiliation>

+ <contrib>Latin translation</contrib>

+ </othercredit>

+-->

+

+ </authorgroup>

+

+ <releaseinfo revision="2.26" role="review"/>

+

+ <revhistory>

+ <revision>

+ <revnumber>Version 2.12</revnumber>

+ <date>September 2005</date>

+ <revdescription>

+ <para role="author">Davyd Madeley</para>

+ </revdescription>

+ </revision>

+ <revision>

+ <revnumber>Version 2.10</revnumber>

+ <date>March 2005</date>

+ <revdescription>

+ <para role="author">Davyd Madeley</para>

+ </revdescription>

+ </revision>

+ <revision>

+ <revnumber>Version 2.8</revnumber>

+ <date>September 2004</date>

+ <revdescription>

+ <para role="author">Angela Boyle</para>

+ <para role="publisher">MATE Documentation Project</para>

+ </revdescription>

+ </revision>

+ <revision>

+ <revnumber>Battery Charge Monitor Applet Manual V2.2</revnumber>

+ <date>August 2004</date>

+ <revdescription>

+ <para role="author">Sun MATE Documentation Team</para>

+ <para role="publisher">MATE Documentation Project</para>

+ </revdescription>

+ </revision>

+ <revision>

+ <revnumber>Battery Charge Monitor Applet Manual V2.0</revnumber>

+ <date>May 2002</date>

+ <revdescription>

+ <para role="author">Trevor Curtis

+ <email>[email protected]</email>

+ </para>

+ <para role="author">Jorgen Pehrson

+ <email>[email protected]</email>

+ </para>

+ <para role="publisher">MATE Documentation Project</para>

+ </revdescription>

+ </revision>

+ </revhistory>

+

+ <releaseinfo>This manual describes version &appletversion; of &applet;.

+ </releaseinfo>

+

+ <legalnotice>

+ <title>Feedback</title>

+ <para>

+ To report a bug or make a suggestion regarding the &applet; applet or

+ this manual, follow the directions in the <ulink url="help:mate-feedback"

+ type="help">MATE Feedback Page</ulink>.

+ </para>

+ </legalnotice>

+ </articleinfo>

+

+ <indexterm zone="index">

+ <primary>Battery Charge Monitor Applet</primary>

+ </indexterm>

+

+ <indexterm zone="index">

+ <primary>Battstat Applet</primary>

+ </indexterm>

+

+<!-- ============= Document Body ============================= -->

+<!-- ============= Introduction ============================== -->

+ <sect1 id="battstat-introduction">

+ <title>Introduction</title>

+

+ <figure id="battstat-applet-fig">

+ <title>&applet; Applet</title>

+ <screenshot>

+ <mediaobject>

+ <imageobject><imagedata

+ fileref="figures/battstat-applet.png" format="PNG"/>

+ </imageobject>

+ <textobject>

+ <phrase>The &applet; applet.</phrase>

+ </textobject>

+ </mediaobject>

+ </screenshot>

+ </figure>

+

+ <para>

+ The <application>&applet;</application> shows the

+ status of any batteries in your laptop computer. The monitor can tell you

+ the capacity remaining both visually and as a percentage, as well as offer

+ you an estimate of the time remaining based off the current usage rate.

+ </para>

+

+ <sect2 id="battstat-introduction-add">

+ <title>To Add &applet; to a Panel</title>

+ <para>To add <application>&applet;</application> to a panel,

+ right-click on the panel, then choose <guimenuitem>Add to

+ Panel</guimenuitem>. Select <application>&applet;</application>

+ in the <application>Add to the panel</application> dialog, then

+ click <guibutton>OK</guibutton>.</para>

+ <para>

+ The layout of the <application>&applet;</application> applet varies depending on the size and type of panel in which the applet resides.

+ </para>

+ </sect2>

+

+ <sect2 id="battstat-power-backends">

+ <title>Power Management Backends</title>

+

+ <para>

+ The battery monitor supports a number of power management backends.

+ If it is available, the monitor will attempt to use the freedesktop.org

+ <ulink url="http://upower.freedesktop.org/">upower</ulink> interface.

+ If it is unavailable or unsupported on your platform, it will fall back

+ to the freedesktop.org

+ <ulink url="http://freedesktop.org/Software/hal">HAL (Hardware

+ Abstraction Layer)</ulink>. If that is also not availble, the

+ battery monitor will attempt direct access to the power management system

+ </para>

+ <para>

+ Not all power management backends are available from all vendors, and some

+ vendors add their own additional backends for specific platforms and

+ hardware. If the battery monitor is misreporting information from your

+ battery see <xref linkend="battstat-troubleshooting" />.

+ </para>

+ </sect2>

+

+ <sect2 id="battstat-getting-help">

+ <title>Getting Help</title>

+ <para>

+ If the battery monitor doesn't work for you,

+ see these additional resources:

+ </para>

+ <itemizedlist>

+ <listitem><para>

+ <xref linkend="battstat-troubleshooting"/>;

+ </para></listitem>

+ <listitem><para>

+ <ulink url="http://mail.mate.org/archives/">MATE mailing

+ lists</ulink>

+ </para></listitem>

+ </itemizedlist>

+ </sect2>

+

+</sect1>

+

+<!-- ================ Customizing the Appearance ========================= -->

+

+ <sect1 id="battstat-appearance">

+ <title>Preferences</title>

+ <para>To bring up the preferences for the monitor, right-click on

+ the monitor in the panel and then choose

+ <guimenuitem>Preferences</guimenuitem></para>

+ <figure id="battstat-applet-prefs-menu">

+ <title>&applet; context (right-click) menu</title>

+ <screenshot>

+ <mediaobject>

+ <imageobject><imagedata

+ fileref="figures/context-menu.png" format="PNG"/>

+ </imageobject>

+ <textobject>

+ <phrase>&applet; context menu</phrase>

+ </textobject>

+ </mediaobject>

+ </screenshot>

+ </figure>

+ <figure id="battstat-applet-prefs">

+ <title>Preferences Dialog</title>

+ <screenshot>

+ <mediaobject>

+ <imageobject><imagedata

+ fileref="figures/battstat-preferences.png" format="PNG"/>

+ </imageobject>

+ <textobject>

+ <phrase>Preferences Dialog</phrase>

+ </textobject>

+ </mediaobject>

+ </screenshot>

+ </figure>

+ <variablelist>

+ <varlistentry>

+ <term><guilabel>Appearance</guilabel></term>

+ <listitem>

+ <variablelist>

+ <varlistentry>

+ <term><guilabel>Compact view</guilabel></term>

+ <listitem><para>

+ This view shows only a single graphic in the panel, either an

+ upright battery to indicate remaining capacity or a plug to

+ indicate your laptop is connected to an external power source.

+ <figure id="battstat-applet-compact">

+ <title>Compact view</title>

+ <screenshot>

+ <mediaobject>

+ <imageobject><imagedata

+ fileref="figures/battstat-applet.png" format="PNG"/>

+ </imageobject>

+ <textobject>

+ <phrase>Compact View</phrase>

+ </textobject>

+ </mediaobject>

+ </screenshot>

+ </figure>

+ </para>

+ <para>

+ The compact view is the default view for the monitor as of MATE

+ 2.12.

+ </para></listitem>

+ </varlistentry>

+ <varlistentry>

+ <term><guilabel>Expanded view</guilabel></term>

+ <listitem><para>

+ The expanded view is old look from previous versions of MATE. It

+ has the larger graphic for the battery as well as a separate

+ graphic to indicate what state the battery is in.

+ <figure id="battstat-applet-expanded">

+ <title>Expanded view</title>

+ <screenshot>

+ <mediaobject>

+ <imageobject><imagedata

+ fileref="figures/battstat-applet-expanded.png" format="PNG"/>

+ </imageobject>

+ <textobject>

+ <phrase>Expanded View</phrase>

+ </textobject>

+ </mediaobject>

+ </screenshot>

+ </figure>

+ </para></listitem>

+ </varlistentry>

+ <varlistentry>

+ <term><guilabel>Show time/percentage</guilabel></term>

+ <listitem><para>Selecting this option will display one of two

+ pieces of information. <guilabel>Show time remaining</guilabel>

+ will tell you how many hours and minutes until the battery is

+ fully discharged or recharged. <guilabel>Show percentage

+ remaining</guilabel> will tell you the percentage charge remaining

+ in the battery.</para></listitem>

+ </varlistentry>

+ </variablelist>

+ </listitem>

+ </varlistentry>

+ <varlistentry>

+ <term><guilabel>Notifications</guilabel></term>

+ <listitem>

+ <itemizedlist>

+ <listitem><para><guilabel>

+ Warn when battery charge drops to

+ </guilabel></para>

+ <para>

+ Selecting this option will cause a warning dialog to be displayed

+ whenever your laptop

+ battery reaches specified value, either as a percentage remaining or

+ a number of minutes remaining. This indicates that the amount of

+ charge remaining in your battery is critically low.

+ charge. You can dismiss this warning dialog yourself, otherwise it

+ will vanish automatically when you plug your laptop into mains

+ power.

+ </para>

+ </listitem>

+ <listitem>

+ <para><guilabel>

+ Notify when the battery is fully recharged

+ </guilabel></para>

+ <para>

+ Selecting this option notifies when your battery is fully

+ recharged. If you have compiled the &applet; with libnotify

+ support a non-intrusive notification will popup from the monitor on

+ the panel.

+ </para>

+ </listitem>

+ </itemizedlist>

+ </listitem>

+ </varlistentry>

+ </variablelist>

+ </sect1>

+

+ <sect1 id="battstat-troubleshooting">

+ <title>Troubleshooting</title>

+

+ <para>

+ Due to the complexities of power management and the vast differences

+ between each of the different power management systems available,

+ debugging errors in the battery monitor can be difficult. You will need to

+ determine if the error exists in the battery monitor or is a bug in the

+ information provided by your machine.

+ </para>

+ <para>

+ The following information may be useful for troubleshooting what is wrong

+ with your battery monitor. It is by no means exhaustive. If you find a bug

+ with the &applet; (that is not caused by bad information being reported

+ by ACPI), please <ulink url="http://bugzilla.mate.org/">report it</ulink>.

+ </para>

+

+ <sect2 id="battstat-troubleshooting-backends">

+ <title>Determining the backend</title>

+ <para>

+ If you are using the upower interface, or the the Hardware

+ Abstraction Layer (see <xref linkend="battstat-power-backends"/>) then

+ that will be indicated in the about dialog by placing a star next to the

+ author of the HAL backend.

+ <figure id="battstat-credits-hal">

+ <title>Check you're using the HAL backend</title>

+ <screenshot>

+ <mediaobject>

+ <imageobject><imagedata

+ fileref="figures/battstat-credits-hal.png" format="PNG"/>

+ </imageobject>

+ <textobject>

+ <phrase>Expanded View</phrase>

+ </textobject>

+ </mediaobject>

+ </screenshot>

+ </figure>

+ </para>

+

+ <para>

+ Other backends do not currently give indication they are being used, so

+ you will have to guess based on your hardware. Most modern PC laptops are

+ using ACPI as the backend. This is also the backend with the largest

+ number of inconsistencies.

+ </para>

+ </sect2>

+

+ <sect2 id="battstat-troubleshooting-acpi">

+ <title>Checking the ACPI information</title>

+ <para>

+ If you are using the ACPI backend for the &applet;, it is important to

+ check that ACPI is giving you the right information. If it isn't, then

+ you will need to look into upgrading your DSDT or something else related

+ to ACPI.

+ </para>

+ <example><title>Example ACPI output</title>

+ <screen>

+[rupert@laptop ~]$ cat /proc/acpi/battery/BAT1/info

+present: yes

+design capacity: 41040 mWh

+last full capacity: 37044 mWh

+battery technology: rechargeable

+design voltage: 10800 mV

+design capacity warning: 745 mWh

+design capacity low: 0 mWh

+capacity granularity 1: 10 mWh

+capacity granularity 2: 10 mWh

+model number: G71C00056110

+serial number: 0000000008

+battery type: Li-ION

+OEM info:

+[rupert@laptop ~]$ cat /proc/acpi/battery/BAT1/state

+present: yes

+capacity state: ok

+charging state: discharging

+present rate: 11232 mW

+remaining capacity: 27140 mWh

+present voltage: 11400 mV

+[rupert@laptop ~]$</screen>

+ </example>

+ <para>

+ You can quickly calculate the percentage remaining using <guilabel>remaining

+ capacity</guilabel> divided by <guilabel>last full capacity</guilabel>, you can

+ calculate the time remaining by taking <guilabel>remaining capacity</guilabel>

+ divided by <guilabel>present rate</guilabel>.

+ </para>

+ </sect2>

+

+ <sect2 id="battstat-troubleshooting-nohal">

+ <title>Hardware Abstraction Layer</title>

+ <para>

+ You can check that your battery is detected by HAL using the command

+ <command>hal-device-manager</command>. If your battery is not detected

+ by HAL or the wrong information is being reported, you can attempt to

+ disable the HAL backend by setting a GSettings key.

+ </para>

+ <para>

+ Select <guimenuitem>Configuration Editor</guimenuitem> from the

+ <guimenu>Applications</guimenu> menu, under

+ <guisubmenu>System Tools</guisubmenu>. Search for the key value

+ <prompt>OAFIID:MATE_BattstatApplet</prompt> which should be located in

+ the path <filename>/apps/panel/applets</filename>.

+ </para>

+ <para>

+ Assuming the path is <filename>/apps/panel/applets/applet_1</filename>.

+ In <filename>/apps/panel/applets/applet_1/prefs</filename> add a

+ <guimenuitem>New Key...</guimenuitem> called <guilabel>no_hal</guilabel>

+ and set it to the boolean value of true. This will disable the usage of

+ HAL (see <xref linkend="battstat-troubleshooting-backends"/> to learn how

+ to check this).

+ </para>

+ </sect2>

+

+ </sect1>

+

+</article>