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 below).
    * 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
    * Background Info Command (available only on Windows)
      The program to run to parse it's output for information.  Used
      only if Use Background Info Command is checked.
      Default: empty
    * Background Change Command (not available on Windows)
      The Program to use to set the desktop background image (including all
      parameters). If the command has exactly one '%s' it will be replaced
      by the properly quoted background file name.
      Default: Esetroot -f
    * Parse Background Change Command / Use Background Info Command
      If checked Background Change/Info Command's output will be
      parsed.  This is still experimental but allows to control tool
      tip and timeout which the plugin will use from the command.  See
      Tips & Tricks for more information.
      Default: off
    * 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: ~/images.idb
    * Auto update image list (not available on Windows)
      Select whether the image list should be automatically updated when
      the image database file is modified.
      Default: off
    * Ignore not found images
      Remove image files which could not be found from the (internal) list.
      Default: off
    * 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*
path names 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.

The plugin can check if there might be problems accessing the files (see
option "ignore not found images" above). It does not check, however, if it
is a valid image file that can be displayed by your background setting
program.

All these path names are stored in a list which might get randomised at
start-up (see available option above). These (possibly randomised) images
are then displayed one after the other, which means that the same image is
not shown again unless it went through the complete list and you did not
include the same file more than once.

*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, you have to use '%s' in the
command line:
    * dcop kdesktop KBackgroundIface setWallpaper %s 6
The last number in the command is the mode, available modes are:
    * 0 = NoWallpaper
    * 1 = Centred
    * 2 = Tiled
    * 3 = CenterTiled
    * 4 = CentredMaxpect
    * 5 = TiledMaxpect
    * 6 = Scaled
    * 7 = CentredAutoFit
    * 8 = ScaleAndCrop
    * 9 = lastWallpaperMode
Since KDE 3.3 you can specify the number of the desktop as well:
    * dcop kdesktop KBackgroundIface setWallpaper 4 %s 6
where 4 is the desktop number.

Alternatively you can use (an individually adapted version of) the
'kdewallpaper.sh' shell-script that comes with the tarball.
It takes only one argument, the filename supplied by the plugin.

You can also check the 'Parse Background Change Command' (under un*x)
or 'Use Background Info Command' to have a control over the plugin
from the command. If this option is checked, the plugin will check the exit
code and output of the command. If the exit code is different from zero,
the timeout will be set to 10 seconds and the tool tip is left unchanged.
Otherwise, the output will be parsed for control commands.

These commands must be written in the following format:

   tag ":" value "\n"

No whitespaces, comments or anything else is allowed at the moment.
The following tags are recognised:

    * file - sets the file name. Under un*x it is currently used only
      if tooltip was not set from the command. Under Windows it is
      used to set the wallpaper using WinAPI function.
    * tooltip - sets the tool tip message.
    * time - modifies the timeout:
      - if value is '+<number>' or '-<number>' <number> will be
        added/subtracted from the timeout;
      - if value is '*<number>' or 'x<number>' the timeout will be
        multiplied by <number>;
      - if value is '/<number>' the timeout will be divided by
        <number>;
      - if value is '<<number>' the timeout will be set to <number>
        if it is less then <number>;
      - if value is '><number>' the timeout will be set to <number>
        off it is greater then <number>;
      - if value is just a '<number>' the timeout will be set to
        <number>.

You can use the function from bgchg_info.sh file in your shell scripts to
print commands. A simple shell script could look like follows:

    ## Set background
    Esetroot -scale "$1" || exit $?
    ## This is not needed but it's good to keep it
    printf 'file:%s\n' "$1"
    ## If the path contains SUPER multiply the timeout by two
    if [ -z "${1##*SUPER*}" ]; then
        echo time:x2
    fi
    ## If the path contains COOL add 5 minutes to timeout
    if [ -z "${1##*COOL*}" ]; then
        echo time:+300
    fi
    ## Get file name without extension
    FILE="${1##*/}"
    FILE="${FILE%.*}"
    ## Remove numbers, whitespaces and '-' from the end and beginning
    while [ X"$FILE" != X"${FILE%[-0-9 ]}" ]; do
        FILE"${FILE%[-0-9 ]}"
    done
    while [ X"$FILE" != X"${FILE#[-0-9 ]}" ]; do
        FILE"${FILE#[-0-9 ]}"
    done
    ## Set that as tooltip
    printf 'tooltip:%s\n' "$FILE"
    exit 0

Note that the script is run with one of the lines from the image
database file as an argument. The database does not have to contain
valid path names (however, make sure not to check 'Ignore not found
images' if that is the case) so you can create it in any format and
then parse each line from the script. For example, if you generate
an image database to contain lines in the format:

    time:tooltip:file

you can use the following script:

    TIME=$(printf '%s' "$1" | cut -d: -f1)
    TOOLTIP=$(printf '%s' "$1" | cut -d: -f2)
    FILE=$(printf '%s' "$1" | cut -d: -f3-)
    Esetroot -scale "$FILE" || exit $?
    printf 'file:%s\ntooltip:%s\ntime:%s\n' "$FILE" "$TOOLTIP" "$FILE"

Under Windows you'll have to write a similar script but without the
"Esetroot" line. It gets even better when you realise that the script
may ignore the argument or treat it as a path of a image database file.
Let say you have two sets of wallpapers. One is saved in ~/set1.idb and
contains e.g. 100 files whereas the other is saved in ~/set2.idb and
contains e.g. 500 files. In the traditional way, images from the second set
would be chosen five times more frequent then images from the first
set. But with this new feature you can customise the way images are
chosen. Your image database can contain two lines:
'/home/foo/set1.idb' and '/home/foo/set2.idb' (where /home/foo is your
home directory) and the the script used to change the wallpaper could look
as follows:

    NUM=$(wc -l <"$1")
    [ $NUM -gt 0 ] || exit 1
    FILE="$(tail -n +$(( $(date +%s) % $NUM + 1 )) <"$1" |head -n 1)" || \
        exit 1
    Esetroot -scale "$FILE" || exit $?
    printf 'file:%s\n' "$FILE"
    ## ... some other stuff

If you plan to experiment with such scripts beware that the image
database must have at least two elements (they can be identical) or
else the plugin won't call the script as it'll assume there's no
wallpaper to change to.

License
-------

This program is free software which I release under the GNU General Public
License. You may redistribute and/or modify this program under the terms of
that license as published by the Free Software Foundation; either version 2
of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

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.,
59 Temple Place, Suite 330, Boston, MA  02111-1307, USA.

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

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

The source code is managed in a git repository at:
git://repo.or.cz/gkrellmbgchg.git

which is browsable online at:
http://repo.or.cz/w/gkrellmbgchg.git


*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