NAME¶
fdpowermon - add a battery level icon to a freedesktop.org-compliant system tray
SYNOPSIS¶
fdpowermon
DESCRIPTION¶
This program allows one to display a "battery level" icon in any
freedesktop.org-compliant status area. It can be themed through either a
plain-text configuration file (
/etc/fdpowermon/theme.cfg or
$HOME /.config/fdpowermon/theme.cfg), or through a short
perl script (
/etc/fdpowermon/theme.pl or
$HOME/.config/fdpowermon/theme.pl).
The former is easier, as it doesn't require any scripting; and indeed the
default configuration is an example of such a plain-text theme. However, the
latter allows for more flexibility, as one can define callbacks that should be
run when the battery level reaches a certain threshold.
Themes, whether perl themes or plain-text themes, are built through 'steps',
which are defined in a single line. In a plain-text config file, such a line
looks like this:
discharging = 2:missing.png:low.png, 10:low.png, 100:full.png
This defines three steps. The highest step shows "full.png" when the
battery level is between 11% and 100% (inclusive); the second step shows
"low.png" when the battery level is between 3% and 10% (inclusive);
and the third step will alternate between "missing.png" and
"low.png" on three-second intervals, when the battery is between 0%
and 2%.
Since the line starts with "discharging", these steps are used when
the system is running on battery power. A similar line of steps could be
defined for when the battery is charging:
charging = 0:empty-charging.png, 10:low-charging.png, 100: full-charging.png
this will show "empty-charging.png" when the battery is at 0%
(exactly), "low-charging.png" between 1% and 10% (inclusive), and
"full-charging.png" at 11% and above.
Note that ordering is significant: steps should be defined from low to high.
To complete the theme configuration, we must add a few more items:
[mytheme]
steps = 3
dir = /home/wouter/.fdpowermon/mytheme-icons
charging = 0:empty-charging.png, 10:low-charging.png, 100: full-charging.png
discharging = 2:missing.png:low.png, 10:low.png, 100:full.png
This defines a theme called "mytheme" which has three steps, and will
look for images in the directory
"/home/wouter/.fdpowermon/mytheme-icons". It is not possible to
define a theme which has a different number of steps for the charging phase
than it does for the discharging phase; if you want that, just define (an)
extra step(s) for the phase that you would like to have less steps, which has
the same icon as the step above or below.
Note that ordering is significant here, too; the "steps" line should
appear before any "charging" or "discharging" lines (this
was not the case in fdpowermon 1.7 or below).
If more than one theme is configured, fdpowermon will, by default, use the last
theme defined in the per-user configuration, or (if no per-user configuration
file exists) the last theme defined in the system-wide configuration.
Perl theme config files can use fdpowermon::theme::make_default to change the
default theme.
PERL API¶
@warnings¶
The @fdpowermon::theme::warnings array can be used to specify at which levels
fdpowermon should issue a standard warning. The default is (10, 5, 1), which
means to issue a warning at a level of 10%, 5%, and 1%. Note that if the
battery runs flat at a particularly fast pace, the level may have reduced even
further than that before the warning is issued; also, fdpowermon will issue a
warning immediately when power is removed from the machine and the power is
below the first level.
To make fdpowermon always issue a warning when power is removed, set this to
something like (100, 10, 5, 1). To make fdpowermon issue warnings at 20%, 10%,
and 5%, set this to (20, 10, 5).
Note that it is not possible to change the text of the warning. If you want
that, see the fdpowermon::theme::warning sub, and use an event.
$use_notify¶
The variable $fdpowermon::theme::use_notify can be used to decide whether to use
a libnotify message (if set to a nonzero value), or a dialog window (if set to
a value which evaluates to zero).
The default is to use libnotify if Gtk2::Notify is installed, or a dialog box if
not. Because dialog boxes can steal the focus and therefore wreak havoc with
the user's work, using libnotify is strongly recommended by the author.
Note that if you set the variable to nonzero explicitly, then the test whether
or not Gtk2::Notify is installed will be ignored. Make sure it's available in
that case!
new¶
Create a new fdpowermon theme. Returns a blessed reference; e.g.,
my $theme = new fdpowermon::theme;
$theme->set_stepcount($count)¶
Set the number of steps in the theme. Note that an fdpowermon theme must have an
equal number of steps in both the "charging" and the
"discharging" direction.
Should be called before calling set_charging, set_discharging, or parse_step.
$theme->set_dir($dir)¶
Set the base directory used for icon file names.
$theme->set_charging(\@elements)¶
Set the icons that should be shown when the battery is charging. The argument
should be created by way of the parse_step method.
$theme->set_discharging(\@elements)¶
Set the icons that should be shown when the battery is discharging. The argument
should be created by way of the parse_step method.
$theme->parse_step($defs)¶
Parses the given string into something that can be passed on to set_charging or
set_discharging. The definitions should be in the steps format, described
above, without the leading " charging = " or " discharging =
".
While this method returns an arrayref that can be inspected and (probably)
modified, themes that want to be forward-compatible should treat it as an
opaque data structure.
$theme->set_event($step, \&callback, 'd')¶
Update the theme so the sub 'callback' is executed when we're discharging and we
reach $step for the first time. To set an event when charging instead, pass a
'c' as the third argument.
Note that the steps are arrays, and are therefore 0-based; the lowest-numbered
items are the lowest-level steps.
When the event triggers, the callback routine will be passed two arguments: the
first is the current battery level (in percent); the second is a number
denoting whether the battery is currently charging (1) or discharging (0). In
case the parsing of the ACPI command fails, however, the second argument may
be undef; you should prepare for this possibility. Note that fdpowermon itself
handles that case by assuming the battery is charging; you may or may not wish
to do the same.
$theme->register($name)¶
Registers a theme under a given name. If a theme already exists under that name,
it is replaced.
make_default($name)¶
Makes a theme with a given name be the default theme.
get_theme($name)¶
Looks up a theme with the given name; e.g.,
my $theme = fdpowermon::theme::get_theme("default");
warning($message)¶
Produce a warning, either using Gtk2::Notify, or using a dialog box:
fdpowermon::theme::warning($message);
See the documentation on $fdpowermon::theme::use_notify above for details on
which implementation is chosen.
EXAMPLES¶
For a full .cfg theme example, look above.
To construct the same theme fully from perl, you'd do something like this:
my $theme = new fdpowermon::theme;
$theme->set_stepcount(3);
$theme->set_dir("/home/wouter/.fdpowermon/mytheme-icons");
$theme->set_charging($theme->parse_step("0:empty-charging.png, 10:low-charging.png, 100: full-charging.png"));
$theme->set_discharging($theme->parse_step("2:missing.png:low.png, 10:low.png, 100:full.png"));
(note, as a perl theme, this would go in theme.pl, not theme.cfg; see above for
possible locations for perl themes)
However, unless you want to build the theme dynamically, doing it this way is
not recommended. Instead, you would build the theme from a .cfg file, and
possibly modify it from perl. Let's say you wish to add an event to suspend
the system when the power gets low; in that case, you'd do something like
this:
sub suspend {
system("sudo pm-suspend");
}
my $theme = fdpowermon::theme::get_theme("mytheme");
$theme->set_event(0, \&suspend, 'd');
This would call the 'suspend' sub when the battery is discharging and we reach
the lowest step (in the above example, that would be when the battery reaches
10%; you might want to do that somewhat later). This 'suspend' sub simply
calls the "pm-suspend" program, with sudo, to suspend the
system.