GKrellM BgChg README
====================

GKrellMBgChg is a plugin for GKrellM, which periodically updates the
desktops background image. It is also possible to force an image update by
clicking on the panel or to "hold" the image with the mouse wheel.

Compiling and Installing
------------------------

To compile the plugin, first untar it and change into the new directory
with

    tar xvfz gkrellmbgchg2-<version>.tar.gz
    cd gkrellmbgchg2-<version>

Then compile it with

    make

and install it into your GKrellM plugin directory (usually
$HOME/.gkrellm2/plugins) with

    cp gkrellmbgchg.so ~/.gkrellm2/plugins

or

    make install

After a restart of GKrellM the plugin should be visible in the
configuration dialogue.

Usage and Configuration
-----------------------

Mouse buttons:
    * Left changes the background image at once and resets the counter,
      +<Shift> toggles the background lock.
    * Middle reloads the images from the image database (see Image Database).
    * Right opens the GKrellM Background Changer config window,
      +<Shift> toggles the background lock.

Mouse wheel:
    * Up "locks" the current background image (if you like it very much).
    * Down unlocks the image again and the counter continues. Whether it
      should start from the initial value, or continue where it was, when
      the image was locked, is configurable.

Configuration:
    * Format String
      The text output format is controlled by this string, where
          o $s are the seconds that are remaining to the next update,
          o $S are the seconds that passed since the last change,
          o $m are the minutes that are remaining to the next update,
          o $M are the minutes that passed since the last change,
          o $t is the time remaining to the next update, displayed as
            "-mm:ss" and
          o $T is the time that passed since the last change, displayed as
            "mm:ss".
      Default: $t
    * Command
      The Program to use to set the desktop background image (including all
      parameters), has no effect on Windows.
      Default: Esetroot -f
    * Image Database
      Full path to a file containing all the images (wherein one full path/
      line) to be used by the plugin, e.g. the output from 
        find / -name *.jpg | sort.
      Entries starting with a "#" will be ignored.
      Default: /home/user/images.idb
    * Randomise Images
      Select whether the image list should be randomised or not. If it is
      not set, it will always start at the first entry of the image
      database.
      Note: If it is not set, it will *always* start at the first image in
      the list.
      Default: on
    * Reset timer on "lock" release
      Reset the timer to the initial value when the "image lock" is released.
      Default: off
    * Reset timer on config changes
      Reset the timer on config changes, i.e. when you hit "apply" button.
      Default: off
    * Change wallpaper on load
      Changes the wallpaper when the plugin loads.
      Default: off
    * Change wallpaper on config changes
      Changes the wallpaper when the config changes.
      Default: off
    * Remember "locked" state from last run
      Remembers whether the current wallpaper was "locked"
      or not when GKrellM last shut down. Use with change-on-load
      option off to load a new wallpaper *only* on request.
      Default: off
    * Remember image number from last run
      Remembers the image number from the database that was
      shown when GKrellM last shut down. It starts the next time with
      this image if the image list didn't change.
      Note: This does no longer work as before, since the image list
      is randomised on every start in a possibly different way.
      Default: off
    * Center text
      Centers the displayed text.
      Default: on
    * Display text
      Toggles the text on or off.
      Default: on
    * Display krell/slider
      Toggles the krell on or off.
      Default: on
    * Mouse wheel adjusts timer
      When selected, scrolling the mouse wheel adjusts the time
      rather than "lock" the image. Otherwise the adjustment
      works in combination with the <Shift>-key.
      Default: off
    * Mouse wheel adjusts the timer by nnn seconds
      This is the amount of seconds by which the timer is adjusted
      when scrolling the mouse wheel while holding the <Shift>-key.
      See also "Mouse wheel adjusts timer."
      Default: 60

Tips and Tricks
---------------

This plugin takes an "image database", i.e. a file with a bunch of *full*
pathnames as its input (see above). It is up to the user, to provide valid
ones. If unsure, try

    ls `grep -v '^#' images.idb`

and watch out for messages like "No such file or directory" at the prompt.

All these pathnames are stored in a list and the plugin takes care, that
the number of the new image is different from the one of the former. This
should prevent displaying of the same image accidently. However, if you
want to increase the probability of a certain image, you can include it
more than once, but then be aware, that it could happen that it gets
displayed twice in a row.

*Note* that the background setting program should fit your installation,
check that it works on the command line first, before reporting any bugs to
me. For example, if you don't have Esetroot installed you can stick to
plain xsetbg
    * xsetbg -fullscreen
or, if you use gnome2, set it to
    * gconftool-2 --type=string --set /desktop/gnome/background/picture_filename
and so on for your favourite window manager.

For KDE (at least for 3.x), you can use dcop to change the wallpaper. Since
it takes an extra argument after the filename, it cannot be used directly.
Instead, put the shell script called `kdewallpaper.sh' somewhere into your
path, edit it to suit your needs, make it executable, and use its name as
the changer command.

More information
----------------

The official website is: 
http://www.bender-suhl.de/stefan/english/comp/gkrellmbgchg.html

*Note* for Windows users:
The mouse wheel doesn't work on Windows, so you have to use
<Shift>+click for locking.

If you have any problems, suggestions, feel free to contact me.

Stefan Bender
stefan@bender-suhl.de