NAME

       FvwmBacker - the fvwm background changer module

SYNOPSIS

       Module FvwmBacker

       FvwmBacker  can only be invoked by fvwm.  Command line invocation of the FvwmBacker module
       will not work.

DESCRIPTION

       The FvwmBacker module provides  functionality  to  change  the  background  when  changing
       desktops.  Any command can be executed to change the backgrounds.  Actually, any arbitrary
       command can be sent to fvwm to execute, so you could  also  do  things  such  as  changing
       window border colors, etc.

COPYRIGHTS

       The FvwmBacker module is the original work of Mike Finger.

       Copyright  1994,  Mike  Finger.  The  author makes no guarantees or warranties of any kind
       about the use of this module.  Use this module at your own risk.  You may freely use  this
       module or any portion of it for any purpose as long as the copyright is kept intact.

INITIALIZATION

       During  initialization,  FvwmBacker  gets  config  info  from  fvwm's module configuration
       database (see fvwm(1), section MODULE COMMANDS).  Available options  are  discussed  in  a
       later section.

INVOCATION

       FvwmBacker can be invoked by fvwm during initialization by inserting the line

       AddToFunc StartFunction I Module FvwmBacker

       in the .fvwm2rc file.

       FvwmBacker  can  be  started  using  a  'Module  FvwmBacker'  command  or  stopped using a
       'KillModule FvwmBacker' command at any time when fvwm is running.

       FvwmBacker must reside in a directory that is listed in the ModulePath option of fvwm  for
       it to be executed by fvwm.

CONFIGURATION OPTIONS

       The following options can be placed in the .fvwm2rc file

       *FvwmBacker: Command (Desk d, Page x y) command
              Specifies  the  command  to execute when the viewport matches the arguments for the
              desk d, page x coordinate and y coordinate. Any  or  all  of  these  three  numeric
              arguments  can be replaced with an asterisk (*) to indicate that any value matches,
              in this case Desk or Page parts can be skipped.

              If either the Desk or the Page parts are omitted, the command is  not  executed  if
              only  the  desk  or  the  page  is  switched.   If neither is given, the command is
              executed only once when the module is started.  This  is  not  the  same  as  using
              asterisks  for the numeric arguments:  if asterisks are used, the command is always
              executed when only the desk or page changes, if the corresponding part is  omitted,
              the command is never executed when only the desk or page changes.

              If  the  command  is  -solid  FvwmBacker uses the next argument as a color in the X
              database and sets the background to that color without generating a system call  to
              xsetroot (only single word color names may be used).

              If  the  command is colorset FvwmBacker uses the background specified in colorset n
              for the given desk.  Please refer to the man  page  of  the  FvwmTheme  module  for
              details about colorsets.

              Otherwise the command is sent to fvwm to execute.

       *FvwmBacker: RetainPixmap
              Causes  FvwmBacker  to  retain and publish the Pixmap with which the background has
              been set. This works only for the -solid or colorset commands. This is  useful  for
              applications  which  want  to  use  the  root  Pixmap on the background to simulate
              transparency (for example, Eterm and Aterm use this  method).  This  option  should
              also  be used for the RootTransparent colorset option (see the FvwmTheme man page).
              Note: with a colorset background this command may add a lot  of  memory  to  the  X
              server.  For  example,  this  adds  the  pixmap  width  times  height  bytes with a
              TiledPixmap image, screen_width times screen_height bytes with a Pixmap image or  a
              C,B,D,R,S  or  Y  Gradient and screen_width bytes with a VGradient or screen height
              bytes with an HGradient.

       *FvwmBacker: DoNotRetainPixmap
              Cancels the effect of the previous option. This is the default.

RUN-TIME CONFIGURATION

       It it possible to replace FvwmBacker's configuration at run-time, although it is  not  yet
       possible  to remove existing configuration lines.  This is done by simply removing the old
       configuration from withing fvwm and then read a new one.  This can be done in  many  ways,
       for example by using an fvwm function or one of the modules FvwmCommand or FvwmConsole.

       Example:

       DestroyModuleConfig FvwmBacker*
       *FvwmBacker: Command (Desk 0) -solid black
       *FvwmBacker: Command (Desk 1) -solid blue

OLD-STYLE OPTIONS

       There is continued support for the now deprecated option:

       *FvwmBacker: Desk d command

              It  is  functionally  equivalent to omitting the page coordinates with *FvwmBacker:
              Command:

              *FvwmBacker: Command (Desk Id) command

SAMPLE CONFIGURATION

       The following are excerpts from an .fvwm2rc file which describe FvwmBacker  initialization
       commands:

       ####
       # Set Up Backgrounds for different desktop pages (2 desks, 3x2 pages).
       ####
       *FvwmBacker: Command (Page 2 *) -solid steelblue
       *FvwmBacker: Command (Desk 0, Page 0 0) Exec fvwm-root $[HOME]/bg2.xpm
       *FvwmBacker: Command (Desk 0, Page 0 1) -solid midnightblue
       *FvwmBacker: Command (Desk 0, Page 1 *) -solid yellow
       *FvwmBacker: Command (Desk 1, Page * 0) -solid navy
       *FvwmBacker: Command (Desk 1, Page * 1) Colorset 5

AUTHOR

       Mike Finger (mfinger@mermaid.micro.umn.edu)
                   (Mike_Finger@atk.com)
                   (doodman on IRC, check the #linux channel)

Modified by

       Andrew Davison (davison@cs.monash.edu.au)

       Michael Han (mikehan@best.com)

       Mikhael Goikhman (migo@homemail.com)