Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
ICEWMBG(1)			 User Commands			    ICEWMBG(1)

	icewmbg	- a background settings	manager	for the	IceWM window manager

       icewmbg [OPTIONS]

       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 XINERAMA	and RANDR 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

       It should be started before icewm(1), preferably	by the
       icewm-session(1)	program.

       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/Enable multi-head background.  This overrules the
	   "DesktopBackgroundMultihead"	preference.

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

       -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".

	   Use a slower	synchronous mode communication with X11	server.

       -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.

       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).

       Often a background image	has a different	width or height	than the
       screen.	The settings can specify to centre ("DesktopBackgroundCenter")
       or scale	("DesktopBackgroundScaled") an image.  Either option is	either
       0 (disabled) or 1 (enabled).  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

       icewmbg supports	the following signals:

	   icewmbg will	restart	itself.

	   icewmbg will	terminate.

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

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

       icewmbg had no known bugs at the	time of	release.  Please report	bugs
       for current versions to the source code repository at

       Brian Bidulock <>.

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

       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 1.9.2			  2020-11-10			    ICEWMBG(1)


Want to link to this manual page? Use this URL:

home | help