
wmbackground 1.0.1
----------------------------------------------------------------------------

wmbackground is a Window Maker dockable application that changes the
backgrounds (switches the wallpapers).  The application reads the
~/.wmbackground directory and accepts the backgrounds stored in *.png files
only.

To use the program prepare the ~/.wmbackground directory, copy there some
backgrounds in *.png format, and run wmbackground.  The program started for
the first time prepares some additional files if it is necessary -- in such
a case it displays the message: ,,processing backgrounds, please wait''.

You can add some *.png files to the ~/.wmbackground directory at any time
without exiting wmbackground.  The program recognizes the new files and
process them preparing the necessary additional files.

The wmbackground requires the montage program from the ImageMagick package. 
It is used to scale and convert the backgrounds to the format required by
wmbackground.


The installation
----------------------------------------------------------------------------

To install the program use the following procedure:

      cd wmbackground
      make
      make install

If you prefer to install wmbackground in /usr directory rather than /usr/local
one go to Makefile file and before the installation change the variable:

      PREFIX=/usr/local

to:

      PREFIX=/usr

During the installation the complete documents set including contrib
directory is copied to the /usr/local/doc/wmbackground-1.0.1 or
/usr/doc/wmbackground-1.0.1 directory.

If the compilation breaks with the following error message:

      wmbackground.h:13:21: fatal error: X11/xpm.h: No such file or directory

install the libXpm, or libxpm-dev, or similar library specific for your
system.

If the compilation breaks with the following error message:

      wmbackground.h:14:34: fatal error: X11/extensions/shape.h: No such file or directory

install the libXext, or libxext-dev, or similar library specific for your
system.


The files
----------------------------------------------------------------------------

The program scans the ~/.wmbackground directory.  That directory can contain
three types of files:

1. The backgrounds -- all *.png files.

2. The miniatures -- all *.xpm.gz files.

3. The configuration files -- all files without the extension.

For example: wallpaper.png is a valid background file name, wallpaper.xpm.gz
is a valid miniature file name corresponding to the wallpaper.png file, and
wallpaper is a valid configuration file name corresponding to the
wallpaper.png file.  The files such as wallpaper.gif, wallpaper.jpg, or
wallpaper.tif mean nothing to the wmbackground program.

In order to prepare the files for wmbackground you have to:

1. Make ~/.wmbackground directory:

      mkdir ~/.wmbackground

2. Convert your backgrounds to *.png files, for example:

      convert wallpaper-1.gif wallpaper-1.png
      convert wallpaper-2.jpg wallpaper-2.png
      convert wallpaper-3.tif wallpaper-3.png

3. Copy the *.png files to ~/.wmbackground directory:

      cp *.png ~/.wmbackground

4. Run wmbackground:

      wmbackground

The program inspects the ~/.wmbackground directory, seeks for the *.png
files, and checks wheter exist the appropriate miniatures and configuration
files.  If necessary it prepares them.  During that process the wmbackgroud
application displays the message: ``processing backgrounds, please wait''.

The other method to prepare the files for wmbackground is to use
the scale-backgrounds script.  It is described below.

You can switch the backgrounds manually or display them as a slide show. 
Each background accepts up to two related commands.  You can run them using
the first or the second mouse buttons when the application displays the
background.


The commandline
----------------------------------------------------------------------------

The wmbackground can be run in three ways:

1. The command `wmbackground' runs the program and displays the first
   miniature in *.xpm.gz format from ~/.wmbackground directory switching at
   the same time to the first background in *.png format.  To see the other
   backgrounds press the third mouse button.  To run the command press the
   first or the second mouse buttons.  This is the interactive mode.

2. The command `wmbackground -t 60' runs the program and changes the
   background every minute (every 60 seconds).  The number after the -t
   switch is the number of the seconds.  You can run the commands in that
   mode as well.  This is the slide show mode.

3. The command `wmbackground -h' displays the short help.


The mouse buttons and the keyboard shortcuts
----------------------------------------------------------------------------

The first mouse button runs the first command related to the current
background.

The second mouse button runs the second command related to the current
background.

The third mouse button changes the displayed background.  It is particularly
useful in the interactive mode of the work of the program.

The Backspace keyboard shortcut switches the order of the displayed
backgrounds back and forth.

The Enter keyboard shortcut switches between the manual and the slide show
modes on the fly.  If the program was started without the defined period
between the backgrounds and you switch it to the slide show mode it uses the
default 60 seconds long period.

Before using the keyboard shortcuts you have to put the mouse cursor above
the application window.  As a result some system- and program-related
keyboard shortcuts may not work because the program checks the keyboard
actions intercepting them.


The configuration
----------------------------------------------------------------------------

Let us assume there are the following files in the ~/.wmbackground directory:

      wallpaper-1.png
      wallpaper-2.png
      wallpaper-3.png
      wallpaper-1.xpm.gz
      wallpaper-2.xpm.gz
      wallpaper-3.xpm.gz
      wallpaper-1
      wallpaper-2
      wallpaper-3

The *.png files are the backgrounds (the wallpapers).  The *.xpm.gz files
are the miniatures displayed in the application window.  The files without
the extensions contain the commands.

The sample wallpaper-1 configuration file can look like:

      xterm -e mutt john.doe@gmail.com
      

The first command starts mutt in the writing mode -- the default e-mail
address is john.doe@gmail.com.  The other command is not defined so it does
nothing.


The batch conversions
----------------------------------------------------------------------------

The contrib directory includes the scale-backgrounds script which does the
batch images conversion.  The script converts *.gif, *.jpg, *.jpeg, *.tif,
*.tiff, *.GIF, *.JPG, *.JPEG, *.PNG, *.TIF, and *.TIFF files to *.png ones,
copies all *.png backgrounds to the ~/.wmbackground directory, and prepares
*.xpm.gz and configuration files in ~/.wmbackground directory.  To use the
script copy it to the directory containing the background image files in
the mentioned above formats and run the script using the following command:

      ./scale-backgrounds

