<?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 date "October 2008"> 
  <!ENTITY appversion "@PACKAGE_VERSION@"> 
  <!ENTITY app "<application>@PACKAGE_NAME@</application>"> 
]>

<article id="xfce4-power-manager" lang="en">
<!-- Header --> 
<articleinfo>

  <title>Xfce 4 Power Manager</title>
 
  <copyright>
    <year>2008</year> <holder>Ali Abdallah</holder>
  </copyright>


<authorgroup>

    <author>
      <firstname>Ali</firstname> <surname>Abdallah</surname>
      <affiliation>
	<address><email>aliov@xfce.org</email></address>
      </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>translator@gnome.org</email> </address>
      </affiliation> <contrib>Latin translation</contrib>
    </othercredit>
-->

</authorgroup>

<releaseinfo>This manual describes &app; version &appversion;
</releaseinfo>

</articleinfo>

  <!-- extra space -->
  <para>&nbsp;</para>
    
<sect1 id="xfpm-intro">
  <title>Introduction</title>
 This software is a power manager for the Xfce desktop, Xfce power manager manages the power sources on the computer and the devices that can 
 be controlled to reduce their power consumption (such as LCD brightness level, monitor sleep, CPU frequency scaling). 
 In addition, xfce4-power-manager provides a set of freedesktop-compliant DBus interfaces to inform other applications about current power level so that 
 they can adjust their power consumption, and it provides the inhibit interface which allows applications to prevent automatic sleep actions via the power manager; 
 as an example, the operating system’s package manager should make use of this interface while it is performing update operations.
  
  <sect2 id="xfpm-started">
  
  <title>Getting Started</title>
  <para>If your distribution doesn't come with a default installation of &app; usually when you install it, it will be started next time you log into your Xfce desktop.
  In order to start it manually you just need to run  the following command &app; from your terminal emulator. Please note that running this &app; command 
  will cause the power manager to run in daemon mode. You can optionally add --no-daemon as a command line argument to disable this behaviour, 
  This can be useful if you want to see debugging outputs from your terminal emulator.
  </para>
   
  </sect2>
   

</sect1>

 <!-- extra space -->
  <para>&nbsp;</para>
 
 <sect1 id="xfpm">
 <title>Power Manager</title>

<sect2 id="xfpm-command-line">
<title>Command line options</title>

<variablelist><title></title>

	<varlistentry><term><keycap>--no-daemon</keycap></term>
	<listitem>
	<para>
	Starts the power manager in non-daemon mode: useful for debugging.
	</para>
	</listitem>
	</varlistentry>
	
    <varlistentry><term><keycap>--restart</keycap></term>
	<listitem>
	<para>
	Restarts the power manager.
	</para>
	</listitem>
	</varlistentry>	
	
    <varlistentry><term><keycap>--quit</keycap></term>
	<listitem>
	<para>
	Causes any running instance of the power manager to exit.
	</para>
	</listitem>
	</varlistentry>	
	
</variablelist>

</sect2> 
 
<sect2 id="xfpm-menu">
<title>Context menu</title>

<para><figure float="0">
	<title>Context menu</title>
	<screenshot><mediaobject>
	<imageobject>
	<imagedata fileref="images/xfpm-context-menu.png" format="png"/>
	</imageobject>
	<textobject>
	<phrase></phrase>
	</textobject>
	</mediaobject></screenshot>
</figure></para>

<para>
The context menu pops up when you click on the icon placed in your notification area for example a battery or an adapter icon. It contains some useful options like suspend/hibernate,
display information of the battery device and open the settings dialog. It contains as well option to inhibit the power manager. If enabled, the power manager will not attempt
to dim the screen or switch off the monitor.

<note><para>If the inhibit option is selected and the computer is in idle for a long time the power manager will not put the system in suspend or hibernate, even
if it is enabled in the settings dialog. Only critical actions are processed.</para></note>

</para>

</sect2> 
  </sect1>
  
  <!--- Xfpm configurations --> 
 
<sect1 id="xfpm-configuration">
  <title>Power Manager Configuration</title>
  <para>
  In this section we will explain in details the possible configuration of the power manager running on laptop computer. Please note that the configurations are different when 
  the power manager is running on a desktop computer, for example you will not have LCD brightness etc.
  </para>
  
  <sect2 id="xfpm-general">
  <title>General options</title>

<para><figure float="0">
	<title>General settings</title>
	<screenshot><mediaobject>
	<imageobject>
	<imagedata fileref="images/xfpm-general-settings.png" format="png"/>
	</imageobject>
	<textobject>
	<phrase></phrase>
	</textobject>
	</mediaobject></screenshot>
</figure></para>

<para>

<variablelist><title></title>

	<varlistentry>
	<term><keycap>Notification area:</keycap></term>
	<listitem>
	<para>The notification area settings allow you to control the behaviour of the icon placed in your notification area. You can set it to be always visible. For battery devices,
	you can select the icon to be visible only when your are running on battery for example.</para>
	</listitem>
	</varlistentry>
	
    <varlistentry>
	<term><keycap>Keyboard special keys:</keycap></term>
	<listitem>
	<para>
	Enable you to specify which key will trigger which action. These keys are not found on all the systems. For example, in the screen shot the hibernate key is missing
	since the screen shot was taken on a computer which doesn't have this key.
	The default action of all these keys is set to do nothing. 
	</para>
	</listitem>
	</varlistentry>
	
	<varlistentry>
	<term><keycap>Monitor power management control:</keycap></term>
	<listitem>
	<para>Enable/Disable the Display Power Management Signaling (DPMS).</para>
	</listitem>
	</varlistentry>
	
	<varlistentry>
	<term><keycap>Power manager Notification:</keycap></term>
	<listitem>
	<para>If the notification of a battery status change are annoying you, you can always disable them by unselecting the checkbox. Please note this
	doesn't apply on the notification that the power manager sends notifying the user of errors or that the system is running out of power.
	 </para>
	</listitem>
	</varlistentry>	
	
</variablelist>
</para>  
  
  </sect2>  
  
   <sect2 id="xfpm-on-ac">
  <title>Running on  AC power</title>

  <para>
  The on AC power tab contains self explanatory options such as lid close, system idle and monitor sleep configurations.   
  </para>
  
  </sect2> 
  
  <sect2 id="xfpm-on-battery">
  <title>Running on battery power</title>
  
<para>
The on battery tab is only shown on systems that have battery devices. It contains the same options as the AC power tabs plus two other important options:

<variablelist><title></title>

	<varlistentry><term><keycap>Power is critical</keycap></term>
	<listitem>
	<para>
	With this option you can specify the action taken by the power manager in case the system is running on low power. If this option is disabled and the computer
	is running on low battery power, the power manager will display a warning message.
	</para></listitem>
	</varlistentry>
	
	<varlistentry><term><keycap>Prefer power savings over performance:</keycap></term>
	<listitem>
	<para>
	This is the power profile when running on battery. With this option your battery will last more when running on battery power.
	Enabling this option is always a good idea.
	</para></listitem>
	</varlistentry>
	
</variablelist>
</para>  
  
  </sect2>   
  
  <sect2 id="xfpm-extended">
  <title>Extended options</title>
  
  <para><figure float="0">
	<title>Extended settings</title>
	<screenshot><mediaobject>
	<imageobject>
	<imagedata fileref="images/xfpm-extended-settings.png" format="png"/>
	</imageobject>
	<textobject>
	<phrase></phrase>
	</textobject>
	</mediaobject></screenshot>
</figure></para>

<para>
<variablelist><title></title>

	<varlistentry>
	<term><keycap>Inactivity sleep mode:</keycap></term>
	<listitem>
	<para>You can select the inactivity sleep action to be taken by the power manger when the system is idle for a interval of  time set by you
	either on ac power or on battery power. Of course if you disable idle timeout those settings will have no effects.</para>
	</listitem>
	</varlistentry>
	
    <varlistentry>
	<term><keycap>Monitor sleep mode:</keycap></term>
	<listitem>
	<para>
	DPMS sleep modes before switching off the monitor are either standby or suspend. They are technically different and provided for convenience.
	</para>
	</listitem>
	</varlistentry>
	
	<varlistentry>
	<term><keycap>Computer on low power level:</keycap></term>
	<listitem>
	<para>
	Ideally when the battery giving the main power to the computer reaches 10 percent of charge, the computer can be considered on low power. However, for some broken or old
	batteries the interval of time between 10 percent and a power cut is a matter of minutes if not seconds. You can adjust the level at which your computer will be considered on low power.
	<note><para>This option might disappear in future releases.</para></note>

	</para>
	</listitem>
	</varlistentry>
	
	<varlistentry>
	<term><keycap>CPU Frequency control:</keycap></term>
	<listitem>
	<para>
	Unselecting this checkbox, the power manager don't attempt to play with the CPU frequency.
	</para>
	</listitem>
	</varlistentry>	
	
    <varlistentry>
	<term><keycap>Lock screen when going for suspend/hibernate:</keycap></term>
	<listitem>
	<para>
	Just tell your power manager if it should lock the screen before suspending or hibernating the computer. It is enabled by default.
	</para>
	</listitem>
	</varlistentry>		
	
</variablelist>
	
</para>

</sect2>

<!-- Hidden options -->
<sect2 id="xfpm-hidden-options">
<title>Hidden options</title>

<para>
Hidden options are the options that in normal situations one should not be changed, but these options are provided in case of misbehaviour of the backend
that the power manager is relying on.
</para>

<para>
Since &app; relies on xfconf to store and retreive configurations, you can change any settings by using xfconf-query or by using your Xfce settings editor.
</para>

<variablelist><title></title>

	<varlistentry><term>LCD Brightness</term>
	<listitem>
	
	<para>
	 The &app; detects brightness key events and interacts with the backend to update the brightness level. This might be problematic on some systems therefore the key
	"/xfce4-power-manager/change-brightness-on-key-events" is provided. Just set this key to false if you have any such problem. Please refer
    to the xfconf-query manual, but as an example you can disable this property by running the following command.
	 
	<programlisting>xfconf-query -c &app; -n -p "/&app;/change-brightness-on-key-events" -t bool -s false</programlisting>
	 
	</para>
	
	</listitem>
	
	</varlistentry>
	
<varlistentry><term>Disabling Brightness popup</term>
	<listitem>
	
	<para>
	If you want for some reason to disable the brightness popup indicator (the one which popup to display the brightness level), just run the following command
	in your terminal. 
	 
	<programlisting>xfconf-query -c &app; -n -p "/&app;/show-brightness-popup" -t bool -s false</programlisting>
	 
	</para>
	
	</listitem>
	
	</varlistentry>	
	
</variablelist>

</sect2>
   
  
</sect1>

<!-- Panel Plugins -->
<sect1 id="xfpm-plugins">
<title> Panel plugins </title>

<para><figure float="0">
	<title>Brightness plugin</title>
	<screenshot><mediaobject>
	<imageobject>
	<imagedata fileref="images/xfpm-brightness-plugin.png" format="png"/>
	</imageobject>
	<textobject>
	<phrase></phrase>
	</textobject>
	</mediaobject></screenshot>
</figure></para>

<para>
&app; version &appversion; includes one panel plugin for LCD brightness control (possible other plugins might be added for future releases). The usage of the brightness plugin
is simple; just add the plugin to the panel same way  as the one used to add any other plugin; then click on the plugin; a slider will pop up that you move/scroll on it to change
the brightness level of your screen. Of course the plugin will not work on a system with no back light panel. 
</para>

</sect1>

 <!-- extra space -->
  <para>&nbsp;</para>
  
<sect1 id="xfpm-faq">
  <title>FAQ</title>
  <variablelist>

   <varlistentry>
	<term>Q: Why the icons look very similar to the icon of gnome power manager?</term>
	<listitem>
	<para>A: No, they are not similar; they are the same. Just there is no point of re-drawing icons.
	gnome power manager icons are good enough. Not all the gnome power manager icons are used. Please note that 
	for version &appversion; the icons are renamed to avoid possible conflicts with a gnome power manager installation.   
	</para>
	</listitem>
	</varlistentry>

	 <varlistentry>
	<term>Q: What is the difference between suspend and hibernate?</term>
	<listitem>
	<para>A: Suspend is a power save feature. When suspending, the computer is still using power,
	since the running applications are kept in the memory, but it is the lowest power level that the computer
	can use. While Hibernate saves the system state on the hard drive and turns off the power, when you start up your 
	computer	again those data will be loaded and the system back up. 
	</para>
	</listitem>
	</varlistentry>
	
	 <varlistentry>
	<term>Q: Why the options of suspend/hibernate are not there or I can not select them?</term>
	<listitem>
	<para>A: Many possible reasons, for example your kernel is not compiled with suspend/hibernate options.
	Another possible reason is the fact that you don't have engough premission to use them.
	</para>
	</listitem>
	</varlistentry>
	
   <varlistentry>
	<term>Q: I had put my computer into suspend or hibernate mode, but the computer is not waking up?</term>
	<listitem>
	<para>A: This was subject for many bug reports, please note that the power manager has nothing to do with these problems, since the kernel
	is responsible of these tasks. The kernel team are puting a lot of efforts into fixing these kind of problems, if you still have troubles please
	report a bug to your distribution provider, they can contact the kernel team and possibly they can provide you a work-around.  
	</para>
	</listitem>
	</varlistentry>	
		
	 <varlistentry>
	<term>Q: I'm not able to control my laptop brightness and/or my brightness plug in is reporting no device found?</term>
	<listitem>
	
	<para>A: One possible reason is the fact that the correct kernel driver is missing or doesn't exist for your laptop brightness panel, you can debug this fact by running this
	command:  
	<programlisting>lshal > output.txt</programlisting>
	then search in output.txt for "laptop_panel", if you don't find this key this means a driver problem, but in the other hand if you find it then come to us complaining.
	</para>
	
	</listitem>
	</varlistentry>
			
</variablelist>

</sect1>  


<!-- Technical stuff -->
<sect1 id="xfpm-technical">
 <title>
 Technical information
 </title>
 
<para>
Ideally these details should go in a technical guide not the user guide, but we need someplace to keep this information, please
 ignore if these is not what you are looking for.
</para> 
 
 <sect2 id="xfpm-dbus">
 <title>DBus interfaces</title>
 
 <para>
 in this section the DBus interfaces provided by &app; are expanded, those interfaces listed here are freedesktop compliant power
 management interfaces. This section might be useful if you are developing an application and wishing to use these interfaces, or they
 can be useful for debugging purpose.
 
 </para>
 
<keycap>Power management DBus interface.</keycap>

<para>

<table frame='all'><title>Standard methods (org.freedesktop.PowerManagement):</title>
<tgroup cols='5' align='left' colsep='1' rowsep='1'>
<colspec colname='c1'/>
<colspec colname='c2'/>
<colspec colname='c3'/>
<colspec colnum='5' colname='c5'/>

<thead>
<row>
  <entry namest="c1" nameend="c2" align="center">Name</entry>
  <entry>Input parameter</entry>
  <entry>Return Values</entry>
  <entry>Errors</entry>
  <entry>Description</entry>
</row>
</thead>

<thead>
<row>
  <entry namest="c1" nameend="c2" align="center">CanHibernate</entry>
  <entry></entry>
  <entry>bool</entry>
  <entry></entry>
  <entry>whether the system is able to hibernate</entry>
</row>
</thead>

<thead>
<row>
  <entry namest="c1" nameend="c2" align="center">CanSuspend</entry>
  <entry></entry>
  <entry>bool</entry>
  <entry></entry>
  <entry>whether the system is able to suspend</entry>
</row>
</thead>

<thead>
<row>
  <entry namest="c1" nameend="c2" align="center">CanReboot</entry>
  <entry></entry>
  <entry>bool</entry>
  <entry></entry>
  <entry>whether the system is able to reboot</entry>
</row>
</thead>

<thead>
<row>
  <entry namest="c1" nameend="c2" align="center">CanShutdown</entry>
  <entry></entry>
  <entry>bool</entry>
  <entry></entry>
  <entry>whether the system is able to shutdown</entry>
</row>
</thead>

<thead>
<row>
  <entry namest="c1" nameend="c2" align="center">GetOnBattery</entry>
  <entry></entry>
  <entry>bool</entry>
  <entry></entry>
  <entry>whether the system is running on battery</entry>
</row>
</thead>

<thead>
<row>
  <entry namest="c1" nameend="c2" align="center">GetLowBattery</entry>
  <entry></entry>
  <entry>bool</entry>
  <entry></entry>
  <entry>whether the system is running on low battery</entry>
</row>
</thead>

<thead>
<row>
  <entry namest="c1" nameend="c2" align="center">GetPowerSaveStatus</entry>
  <entry></entry>
  <entry>bool</entry>
  <entry></entry>
  <entry>whether the system is running in power save mode.</entry>
</row>
</thead>


<thead>
<row>
  <entry namest="c1" nameend="c2" align="center">Hibernate</entry>
  <entry></entry>
  <entry></entry>
  <entry>PermissionDenied, NoHardwareSupport</entry>
  <entry></entry>
</row>
</thead>

<thead>
<row>
  <entry namest="c1" nameend="c2" align="center">Suspend</entry>
  <entry></entry>
  <entry></entry>
  <entry>PermissionDenied, NoHardwareSupport</entry>
  <entry></entry>
</row>
</thead>

<thead>
<row>
  <entry namest="c1" nameend="c2" align="center">Reboot</entry>
  <entry></entry>
  <entry></entry>
  <entry>PermissionDenied, NoHardwareSupport</entry>
  <entry></entry>
</row>
</thead>

<thead>
<row>
  <entry namest="c1" nameend="c2" align="center">Shutdown</entry>
  <entry></entry>
  <entry></entry>
  <entry>PermissionDenied, NoHardwareSupport</entry>
  <entry></entry>
</row>
</thead>

</tgroup>
</table>

<!-- Signals -->
    <table frame='all'><title>Standard signals (org.freedesktop.PowerManagement):</title>
<tgroup cols='3' align='left' colsep='1' rowsep='1'>
<colspec colname='c1'/>
<colspec colname='c2'/>
<colspec colname='c3'/>

<thead>
<row>
  <entry namest="c1" nameend="c2" align="center">Name</entry>
  <entry>Values</entry>
  <entry>Description</entry>
</row>
</thead>

<thead>
<row>
  <entry namest="c1" nameend="c2" align="center">OnBatteryChanged</entry>
  <entry>bool</entry>
  <entry>whether on battery status changed</entry>
</row>
</thead>

<thead>
<row>
  <entry namest="c1" nameend="c2" align="center">LowBatteryChanged</entry>
  <entry>bool</entry>
  <entry>whether on low battery status changed</entry>
</row>
</thead>

</tgroup>
</table>

</para>

 <keycap>Power management DBus inhibit interface.</keycap>

<para>

<table frame='all'><title>Standard methods (org.freedesktop.PowerManagement.Inhibit):</title>
<tgroup cols='5' align='left' colsep='1' rowsep='1'>
<colspec colname='c1'/>
<colspec colname='c2'/>
<colspec colname='c3'/>
<colspec colnum='5' colname='c5'/>

<thead>
<row>
  <entry namest="c1" nameend="c2" align="center">Name</entry>
  <entry>Input parameter</entry>
  <entry>Return Values</entry>
  <entry>Errors</entry>
  <entry>Description</entry>
</row>
</thead>

<thead>
<row>
  <entry namest="c1" nameend="c2" align="center">Inhibit</entry>
  <entry>string application name, string reason</entry>
  <entry>uint32 (random cookie)</entry>
  <entry></entry>
  <entry>Inhibit the power manager.</entry>
</row>
</thead>

<thead>
<row>
  <entry namest="c1" nameend="c2" align="center">UnInhibit</entry>
  <entry>uint32 cookie</entry>
  <entry></entry>
  <entry>InvalidCookie</entry>
  <entry>Unihibit the power manager.</entry>
</row>
</thead>

<thead>
<row>
  <entry namest="c1" nameend="c2" align="center">HasInhibit</entry>
  <entry></entry>
  <entry>bool</entry>
  <entry></entry>
  <entry>Whether the power manager is currently inhibited or not.</entry>
</row>
</thead>

<thead>
<row>
  <entry namest="c1" nameend="c2" align="center">GetInhibitors</entry>
  <entry></entry>
  <entry>Array of strings</entry>
  <entry></entry>
  <entry>List all the applications currently inhibiting the power manager (Not standard, use just for debugging)</entry>
</row>
</thead>

</tgroup>
</table>

<!-- Signals -->
    <table frame='all'><title>Standard signals (org.freedesktop.PowerManagement.Inhibit):</title>
<tgroup cols='3' align='left' colsep='1' rowsep='1'>
<colspec colname='c1'/>
<colspec colname='c2'/>
<colspec colname='c3'/>

<thead>
<row>
  <entry namest="c1" nameend="c2" align="center">Name</entry>
  <entry>Values</entry>
  <entry>Description</entry>
</row>
</thead>

<thead>
<row>
  <entry namest="c1" nameend="c2" align="center">HasInhibitChanged</entry>
  <entry>bool</entry>
  <entry>whether the inhibit status changed.</entry>
</row>
</thead>

</tgroup>
</table>

</para>


<para>
In addition, &app; has other interfaces, but those interfaces are mainly used internally, for example the settings application uses such interface to
get information about the current status of the running instance of the power manager.
</para>

</sect2>

</sect1>


<!-- ABOUT -->

 <!-- extra space -->
  <para>&nbsp;</para>
<sect1 id="xfpm-about">
  <title>About &app;</title>
  <para>
	This power manager was written following the philosophy of Xfce, having light weight application that does
	what the user is expecting from it.
	</para>

  <para>To report a bug or make a suggestion regarding this application or
    this manual, use the bug tracking system at <ulink 
      url="http://bugzilla.xfce.org/" 
      type="http">http://bugzilla.xfce.org/</ulink>. 
  </para>

  <para>If you have questions about the use or installation of this package,
    please ask on the <ulink 
      url="http://lunar-linux.org/mailman/listinfo/xfce"
      type="http">xfce</ulink> mailing list. Development discussion takes
    place on the <ulink 
      url="http://lunar-linux.org/mailman/listinfo/xfce4-dev"
      type="http">xfce4-dev</ulink> mailing list
    or on  <ulink 
      url="http://lunar-linux.org/mailman/listinfo/xfce4-goodies-dev"
      type="http">xfce4-goodies-dev</ulink> mailing list.
  </para>
  
</sect1>  

 <!-- extra space -->
  <para>&nbsp;</para>
  <para> This program is distributed under the terms of the
    GNU General Public License as published by the Free Software Foundation; 
    either version 2 of the License, or (at your option) any later version.
  </para>

  <para>You should have received a copy of the GNU General Public License 
    along with this program; if not, write to the Free Software 
    Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA.
  </para>

</article>