fdpowermon

FDPOWERMON(1)         User Contributed Perl Documentation        FDPOWERMON(1)



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
       $XDG_CONFIG_DIR/fdpowermon/theme.cfg), or through a short perl script
       (/etc/fdpowermon/theme.pl or $XDG_CONFIG_DIR/fdpowermon/theme.pl).  If
       $XDG_CONFIG_DIR is not set, $HOME/.config is used as a default.

       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 the libnotify Glib introspection
       data 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 the Glib introspection data 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 libnotify, 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.



perl v5.22.2                      2016-06-27                     FDPOWERMON(1)