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 fvwm man page 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. 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 within 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)

MODIFIED BY

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

       Michael Han (mikehan@best.com)

       Mikhael Goikhman (migo@homemail.com)

                                            2023-09-19                              FVWMBACKER(1)