NAME

        icewmbg - a background settings manager for the IceWM window manager

SYNOPSIS

       icewmbg [OPTIONS]

DESCRIPTION

       icewmbg can assign a colour or image to the X11 desktop background.  Many image formats are supported.
       Each icewm(1) work space can have its own background.

       When the background image has changed, then icewmbg can be notified to update the background.  When
       switching work spaces, it checks the image file modification time.  If the file has changed, then it
       reloads the background image from file.

       icewmbg supports semi-transparency.  Semitransparent background images and colours can be configured.  If
       these are not specified then the default background is used.

       It uses RandR or Xinerama to support backgrounds on all connected monitors.  When monitors
       appear/disappear, or change their resolution, icewmbg will adjust.  It supports an option for one large
       background over all monitors.

       It will update the "_ICEWMBG_IMAGE" property of the root window to the path of the background image
       whenever it changes the desktop background.

       icewmbg is started automatically by icewm-session(1).

OPTIONS

   SPECIFIC OPTIONS
       Where multiple values can be given for images or colours, they are separated by commas.  Each such value
       may be enclosed in double quotes.  When FILE is a directory then all images from that directory are used
       in sorted order.  If the value starts with an exclamation mark, as in !FILE, then the images from the
       directory FILE are permuted randomly.  Image file names or directory names may have wildcards, which will
       be expanded according to glob(7).

       -p, --replace
           Replace  an  existing  icewmbg.  If  there  is  a running icewmbg, it is instructed to quit.  The new
           icewmbg will take over.

       -q, --quit
           Tell the running icewmbg to quit. This option is used by icewm-session(1) when icewm(1) exits.

       -r, --restart
           Tell the running icewmbg to restart itself.  This is useful when a background file or  directory  has
           changed, or when settings in preferences files have changed.

       -u, --shuffle
           Shuffle  the list of background images randomly.  This option may be given again whenever the running
           icewmbg should reshuffle its list of background images.

       -c, --config=FILE
           Load preferences from FILE.

       -t, --theme=THEME
           Load the theme named THEME.

       -i, --image=FILE[,FILE]*
           Load background images from each FILE.  This overrules the "DesktopBackgroundImage" preference.

       -k, --color=COLOR[,COLOR]*
           Use background colours from each COLOR.  This overrules the "DesktopBackgroundColor" preference.

       -s, --semis=FILE[,FILE]*
           Load transparency images from each FILE.  This overrules the "DesktopTransparencyImage" preference.

       -x, --trans=NAME[,NAME]
           Use transparency colours for each NAME.  This overrules the "DesktopTransparencyColor" preference.

       -e, --center={0|1}
           Disable/Enable centring background.  This overrules the "DesktopBackgroundCenter" preference.

       -a, --scaled={0|1}
           Disable/Enable scaling background.  This overrules the "DesktopBackgroundScaled" preference.

       -m, --multi={0|1}
           Disable   or   enable   a   single   background   over   all   monitors.     This    overrules    the
           "DesktopBackgroundMultihead" preference.

       -y, --cycle=SECONDS
           Cycle  over the list of background images every SECONDS.  This overrules the "CycleBackgroundsPeriod"
           preference.

   GENERAL OPTIONS
       -d, --display=DISPLAY
           Use DISPLAY to connect to the X server.  If this option is missing then  DISPLAY  is  read  from  the
           environment variable "DISPLAY".

       -h, --help
           Print a brief usage statement to stdout and exit.

       -V, --version
           Print the program version to stdout and exit.

       -C, --copying
           Print copying permissions to stdout for the program and exit.

       --sync
           Use a slower synchronous mode communication with X11 server.

FILES

   PREFERENCES
       By  default  icewmbg  will  load  the  background  settings  from  the  icewm(1)  preferences  files (see
       icewm-preferences(5)).  The settings read are:

         DesktopBackgroundCenter    - Display desktop background centered
         DesktopBackgroundScaled    - Display desktop background scaled
         DesktopBackgroundColor     - Desktop background color(s)
         DesktopBackgroundImage     - Desktop background image(s)
         ShuffleBackgroundImages    - Shuffle the list of background images
         SupportSemitransparency    - Support for semitransparent terminals
         DesktopTransparencyColor   - Semitransparency background color(s)
         DesktopTransparencyImage   - Semitransparency background image(s)
         DesktopBackgroundMultihead - One background over all monitors
         CycleBackgroundsPeriod     - Seconds between cycling over backgrounds

       First these settings are read from the preferences file.  Then the theme file from the current  theme  is
       read, which may overrule the preferences settings.  Lastly the prefoverride file is read, which overrides
       again.   Therefore,  if  you  want  to  allow  the  theme  to set the background use preferences for your
       settings, otherwise use prefoverride.  See icewm-prefoverride(5).

   IMAGE SCALING
       Often a background image has a different width or  height  than  the  screen.   The  image  can  then  be
       replicated   (tiled),   centered   or   scaled.  This  is  controlled  by  "DesktopBackgroundCenter"  and
       "DesktopBackgroundScaled".  What happens for their combination is given by the following table:

         center:0 scaled:0 = The background is replicated in both directions.
         center:1 scaled:0 = The background is centered, but not scaled.
         center:1 scaled:1 = Fill one dimension and preserve the aspect ratio.
         center:0 scaled:1 = Fill both dimensions and preserve the aspect ratio.

SIGNALS

       icewmbg supports the following signals:

       SIGHUP
           icewmbg will restart itself.

       SIGINT, SIGTERM
           icewmbg will terminate.

       SIGUSR1
           icewmbg will reshuffle the list of background images and update the backgrounds of all work spaces.

SEE ALSO

       icewm(1), icewm-preferences(5), icewm-prefoverride(5), wmsetbg(1), xsetbg(1), xwallpaper(1).

BUGS

       Please report bugs at <https://github.com/bbidulock/icewm/issues>.

AUTHOR

       Brian Bidulock <mailto:bidulock@openss7.org>.

       See --copying for full copyright notice and copying permissions.

LICENSE

       IceWM is licensed under the GNU Library General Public License.  See the COPYING file in the distribution
       or use the --copying flag to display copying permissions.

icewm 2.9.6                                        2022-02-23                                         ICEWMBG(1)