1ICEWMBG(1) User Commands ICEWMBG(1)
2
6 icewmbg - a background settings manager for the IceWM window manager
7
9 icewmbg [OPTIONS]
10
12 icewmbg can assign a colour or image to the X11 desktop background.
13 Many image formats are supported. Each icewm(1) work space can have
14 its own background.
15 When the background image has changed then icewmbg can be notified to
17 update the background. When switching work spaces it checks the image
18 file modification time. If the file has changed then it reloads the
19 background image from file.
20 icewmbg supports semi-transparency. Semitransparent background images
22 and colours can be configured. If these are not specified then the
23 default background is used.
24 It uses XINERAMA and RANDR to support backgrounds on all connected
26 monitors. When monitors appear/disappear or change their resolution
27 icewmbg will adjust. It supports an option for one large background
28 over all monitors.
29 It will update the "_ICEWMBG_IMAGE" property of the root window to the
31 path of the background image whenever it changes the desktop
32 background.
33 It should be started before icewm(1), preferably by the
35 icewm-session(1) program.
36
38 SPECIFIC OPTIONS
39 Where multiple values can be given for images or colours they are
40 separated by commas. Each such value may be enclosed in double quotes.
41 When FILE is a directory then all images from that directory are used
42 in sorted order. If the value starts with an exclamation mark, as in
43 !FILE, then the images from the directory FILE are permuted randomly.
44 Image file names or directory names may have wildcards, which will be
45 expanded according to glob(7).
46 -p, --replace
48 Replace an existing icewmbg. If there is a running icewmbg it is
49 instructed to quit. The new icewmbg will take over.
50 -q, --quit
52 Tell the running icewmbg to quit. This option is used by
53 icewm-session(1) when icewm(1) exits.
54 -r, --restart
56 Tell the running icewmbg to restart itself. This is useful when a
57 background file or directory has changed or when settings in
58 preferences files have changed.
59 -u, --shuffle
61 Shuffle the list of background images randomly. This option may be
62 given again whenever the running icewmbg should reshuffle its list
63 of background images.
64 -c, --config=FILE
66 Load preferences from FILE.
67 -t, --theme=THEME
69 Load the theme named THEME.
70 -i, --image=FILE[,FILE]*
72 Load background images from each FILE. This overrules the
73 "DesktopBackgroundImage" preference.
74 -k, --color=COLOR[,COLOR]*
76 Use background colours from each COLOR. This overrules the
77 "DesktopBackgroundColor" preference.
78 -s, --semis=FILE[,FILE]*
80 Load transparency images from each FILE. This overrules the
81 "DesktopTransparencyImage" preference.
82 -x, --trans=NAME[,NAME]
84 Use transparency colours for each NAME. This overrules the
85 "DesktopTransparencyColor" preference.
86 -e, --center={0|1}
88 Disable/Enable centring background. This overrules the
89 "DesktopBackgroundCenter" preference.
90 -a, --scaled={0|1}
92 Disable/Enable scaling background. This overrules the
93 "DesktopBackgroundScaled" preference.
94 -m, --multi={0|1}
96 Disable/Enable multi-head background. This overrules the
97 "DesktopBackgroundMultihead" preference.
98 -y, --cycle=SECONDS
100 Cycle over the list of background images every SECONDS. This
101 overrules the "CycleBackgroundsPeriod" preference.
102 -d, --display=DISPLAY
104 Use DISPLAY to connect to the X server. If this option is missing
105 then DISPLAY is read from the environment variable "DISPLAY".
106 --sync
108 Use a slower synchronous mode communication with X11 server.
109 GENERAL OPTIONS
111 -h, --help
112 Print a brief usage statement to stdout and exit.
113 -V, --version
115 Print the program version to stdout and exit.
116 -C, --copying
118 Print copying permissions to stdout for the program and exit.
119
121 PREFERENCES
122 By default icewmbg will load the background settings from the icewm(1)
123 preferences files (see icewm-preferences(5)). The settings read are:
124 DesktopBackgroundCenter - Display desktop background centered
126 DesktopBackgroundScaled - Display desktop background scaled
127 DesktopBackgroundColor - Desktop background color(s)
128 DesktopBackgroundImage - Desktop background image(s)
129 ShuffleBackgroundImages - Shuffle the list of background images
130 SupportSemitransparency - Support for semitransparent terminals
131 DesktopTransparencyColor - Semitransparency background color(s)
132 DesktopTransparencyImage - Semitransparency background image(s)
133 DesktopBackgroundMultihead - One background over all monitors
134 CycleBackgroundsPeriod - Seconds between cycling over backgrounds
135 First these settings are read from the preferences file. Then the
137 theme file from the current theme is read, which may overrule the
138 preferences settings. Lastly the prefoverride file is read, which
139 overrides again. Therefore, if you want to allow the theme to set the
140 background use preferences for your settings, otherwise use
141 prefoverride. See icewm-prefoverride(5).
142 SCALING
144 Often a background image has a different width or height than the
145 screen. The settings can specify to centre ("DesktopBackgroundCenter")
146 or scale ("DesktopBackgroundScaled") an image. Either option is either
147 0 (disabled) or 1 (enabled). What happens for their combination is
148 given by the following table:
149 center:0 scaled:0 = the background is replicated in both directions
151 center:1 scaled:0 = the background is centered, but not scaled
152 center:1 scaled:1 = fill one dimension and preserve the aspect ratio
153 center:0 scaled:1 = fill both dimensions and preserve the aspect ratio
154
156 icewmbg supports the following signals:
157 SIGHUP
159 icewmbg will restart itself.
160 SIGINT, SIGTERM
162 icewmbg will terminate.
163 SIGUSR1
165 icewmbg will reshuffle the list of background images and update the
166 backgrounds of all work spaces.
167
169 icewm(1), icewm-preferences(5), icewm-prefoverride(5), wmsetbg(1),
170 xsetbg(1), xv(1).
171
173 icewmbg had no known bugs at the time of release. Please report bugs
174 for current versions to the source code repository at
175 <https://github.com/bbidulock/icewm/issues>.
176
178 Brian Bidulock <mailto:bidulock@openss7.org>.
179 See --copying for full copyright notice and copying permissions.
181
183 IceWM is licensed under the GNU Library General Public License. See
184 the COPYING file in the distribution or use the --copying flag to
185 display copying permissions.
186icewm 2.3.0 2021-04-02 ICEWMBG(1)