Debian Codegraph @

upstream/fedora-44/man1/icewmbg.1

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.47)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\"
56 .\" Required to disable full justification in groff 1.23.0.
57 .if n .ds AD l
58 .\" ========================================================================
59 .\"
60 .IX Title "ICEWMBG 1"
61 .TH ICEWMBG 1 2026-01-16 "icewm\ 4.0.0" "User Commands"
62 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
63 .\" way too many mistakes in technical documents.
64 .if n .ad l
65 .nh
66 .SS NAME
67 .IX Subsection "NAME"
68 .Vb 1
69 \& icewmbg \- a desktop background image manager for IceWM
70 .Ve
71 .SS SYNOPSIS
72 .IX Subsection "SYNOPSIS"
73 \&\fBicewmbg\fR [\fIOPTIONS\fR] [\fIARGUMENTS\fR]
74 .SS DESCRIPTION
75 .IX Subsection "DESCRIPTION"
76 \&\fBicewmbg\fR can assign a colour or image to the \fIX11\fR desktop background.
77 Common image formats are supported. Each \fBicewm\fR\|(1) workspace can have
78 its own background.
79 .PP
80 When the background image changes, \fBicewmbg\fR can be notified to
81 update the background. When switching workspaces, it checks the image
82 file modification time. If it has changed, it reloads the image.
83 .PP
84 \&\fBicewmbg\fR supports semitransparency. Semitransparent background
85 images and colours can be configured.
86 .PP
87 It uses RandR or Xinerama to support backgrounds on all connected
88 monitors. When monitors appear/disappear, or change their resolution,
89 \&\fBicewmbg\fR will adjust. It supports an option for one large background
90 over all monitors.
91 .PP
92 It will update the \f(CW\*(C`_ICEWMBG_IMAGE\*(C'\fR property of the root window to the
93 path of the background image whenever it changes the desktop background.
94 .PP
95 \&\fBicewmbg\fR is started automatically by \fBicewm\-session\fR\|(1).
96 If there is just a single background for all workspaces, icewmbg may
97 conclude that it can safely exit after setting the desktop background,
98 to free its system memory. If the screen size changes, icewm will then
99 attempt to restart icewmbg, preferably via icewm\-session.
100 .SS ARGUMENTS
101 .IX Subsection "ARGUMENTS"
102 .SS "SPECIFIC OPTIONS"
103 .IX Subsection "SPECIFIC OPTIONS"
104 Where multiple values can be given for images
105 or colours, they are separated by comma\*(Aqs.
106 Each such value may be enclosed in double quotes.
107 If \fIFILE\fR is a directory, all images
108 from that directory are used in sorted order.
109 If the value starts with an exclamation mark, as in \fI!FILE\fR,
110 the images from the directory \fIFILE\fR are permuted randomly.
111 Image file names or directory names may have \fBglob\fR\|(7) wildcards,
112 or they may start with a tilde or environment variable.
113 .IP "\fB\-f\fR, \fB\-\-fork\fR" 4
114 .IX Item "-f, --fork"
115 Fork into the background and detach from the terminal.
116 .IP "\fB\-p\fR, \fB\-\-replace\fR" 4
117 .IX Item "-p, --replace"
118 Replace an existing \fBicewmbg\fR. If there is a running \fBicewmbg\fR,
119 it is instructed to quit. The new \fBicewmbg\fR will take over.
120 .IP "\fB\-q\fR, \fB\-\-quit\fR" 4
121 .IX Item "-q, --quit"
122 Tell the running \fBicewmbg\fR to quit. This option is used by
123 \&\fBicewm\-session\fR\|(1) when \fBicewm\fR\|(1) exits.
124 .IP "\fB\-r\fR, \fB\-\-restart\fR" 4
125 .IX Item "-r, --restart"
126 Tell the running \fBicewmbg\fR to restart itself. This is useful when
127 settings in have changed. If no icewmbg is active, it starts one.
128 .IP "\fB\-u\fR, \fB\-\-shuffle\fR" 4
129 .IX Item "-u, --shuffle"
130 Shuffle the list of background images randomly.
131 This option may be given again whenever the running
132 \&\fBicewmbg\fR should reshuffle its list of background images.
133 .IP "\fB\-c\fR, \fB\-\-config\fR=\fIFILE\fR" 4
134 .IX Item "-c, --config=FILE"
135 Load preferences from \fIFILE\fR.
136 .IP "\fB\-t\fR, \fB\-\-theme\fR=\fITHEME\fR" 4
137 .IX Item "-t, --theme=THEME"
138 Use the theme named \fITHEME\fR.
139 .IP "\fB\-i\fR, \fB\-\-image\fR=\fIFILE\fR[,\fIFILE\fR]*" 4
140 .IX Item "-i, --image=FILE[,FILE]*"
141 Load background images from each \fIFILE\fR.
142 This overrules the \f(CW\*(C`DesktopBackgroundImage\*(C'\fR preference.
143 When more than one image is given, they are assigned
144 to each workspace in the given order.
145 .IP "\fB\-k\fR, \fB\-\-color\fR=\fICOLOR\fR[,\fICOLOR\fR]*" 4
146 .IX Item "-k, --color=COLOR[,COLOR]*"
147 Use background colours from each \fICOLOR\fR.
148 This overrules the \f(CW\*(C`DesktopBackgroundColor\*(C'\fR preference.
149 .IP "\fB\-s\fR, \fB\-\-semis\fR=\fIFILE\fR[,\fIFILE\fR]*" 4
150 .IX Item "-s, --semis=FILE[,FILE]*"
151 Load transparency images from each \fIFILE\fR.
152 This overrules the \f(CW\*(C`DesktopTransparencyImage\*(C'\fR preference.
153 .IP "\fB\-x\fR, \fB\-\-trans\fR=\fINAME\fR[,\fINAME\fR]" 4
154 .IX Item "-x, --trans=NAME[,NAME]"
155 Use transparency colours for each \fINAME\fR.
156 This overrules the \f(CW\*(C`DesktopTransparencyColor\*(C'\fR preference.
157 .IP "\fB\-e\fR, \fB\-\-center\fR={\fI0\fR|\fI1\fR}" 4
158 .IX Item "-e, --center={0|1}"
159 Disable/Enable centring background.
160 This overrules the \f(CW\*(C`DesktopBackgroundCenter\*(C'\fR preference.
161 .IP "\fB\-a\fR, \fB\-\-scaled\fR={\fI0\fR|\fI1\fR}" 4
162 .IX Item "-a, --scaled={0|1}"
163 Disable/Enable scaling background.
164 This overrules the \f(CW\*(C`DesktopBackgroundScaled\*(C'\fR preference.
165 .IP "\fB\-m\fR, \fB\-\-multi\fR={\fI0\fR|\fI1\fR}" 4
166 .IX Item "-m, --multi={0|1}"
167 Disable or enable a single background over all monitors.
168 This overrules the \f(CW\*(C`DesktopBackgroundMultihead\*(C'\fR preference.
169 .IP "\fB\-y\fR, \fB\-\-cycle\fR=\fISECONDS\fR" 4
170 .IX Item "-y, --cycle=SECONDS"
171 Cycle over the list of background images every \fISECONDS\fR.
172 This overrules the \f(CW\*(C`CycleBackgroundsPeriod\*(C'\fR preference.
173 .IP "\fB\-o\fR, \fB\-\-output=FILE\fR" 4
174 .IX Item "-o, --output=FILE"
175 Redirect all output to \fIFILE\fR.
176 A leading tilde or environment variable is expanded.
177 .IP \fB\-\-postpreferences\fR 4
178 .IX Item "--postpreferences"
179 Print a list of all preference values that \fBicewmbg\fR will use.
180 .IP \fB\-\-verbose\fR 4
181 .IX Item "--verbose"
182 Print a log of actions and some events.
183 .SS "GENERAL OPTIONS"
184 .IX Subsection "GENERAL OPTIONS"
185 .IP "\fB\-d\fR, \fB\-\-display\fR=\fIDISPLAY\fR" 4
186 .IX Item "-d, --display=DISPLAY"
187 Use \fIDISPLAY\fR to connect to the X server.
188 Otherwise use DISPLAY from the environment.
189 .IP "\fB\-h\fR, \fB\-\-help\fR" 4
190 .IX Item "-h, --help"
191 Print a brief usage statement to \fIstdout\fR and exit.
192 .IP "\fB\-V\fR, \fB\-\-version\fR" 4
193 .IX Item "-V, --version"
194 Print the program version to \fIstdout\fR and exit.
195 .IP "\fB\-C\fR, \fB\-\-copying\fR" 4
196 .IX Item "-C, --copying"
197 Print copying permissions to \fIstdout\fR for the program and exit.
198 .IP \fB\-\-sync\fR 4
199 .IX Item "--sync"
200 Use a slow synchronous mode to communicate with the \fIX11\fR server.
201 .IP \fB\-\-verbose\fR 4
202 .IX Item "--verbose"
203 Report on some of the activities.
204 .SS FILES
205 .IX Subsection "FILES"
206 Additional arguments, which either are a path or which have an image
207 extension, are assumed to be background image files or directories.
208 .SS PREFERENCES
209 .IX Subsection "PREFERENCES"
210 By default \fBicewmbg\fR loads settings from the \fBicewm\fR\|(1)
211 preferences file. See \fBicewm\-preferences\fR\|(5) for details.
212 The settings read are:
213 .PP
214 .Vb 10
215 \& DesktopBackgroundCenter \- Display desktop background centered
216 \& DesktopBackgroundScaled \- Display desktop background scaled
217 \& DesktopBackgroundColor \- Desktop background color(s)
218 \& DesktopBackgroundImage \- Desktop background image(s)
219 \& ShuffleBackgroundImages \- Shuffle the list of background images
220 \& SupportSemitransparency \- Support for semitransparent terminals
221 \& DesktopTransparencyColor \- Semitransparency background color(s)
222 \& DesktopTransparencyImage \- Semitransparency background image(s)
223 \& DesktopBackgroundMultihead \- One background over all monitors
224 \& CycleBackgroundsPeriod \- Seconds between cycling over backgrounds
225 .Ve
226 .PP
227 If these settings are set in the \fIpreferences\fR file, they can
228 be overridden by the theme in the theme defaults file.
229 To enforce a certain setting, set it in the \fIprefoverride\fR file instead.
230 See \fBicewm\-prefoverride\fR\|(5).
231 .SS WORKSPACES
232 .IX Subsection "WORKSPACES"
233 Each workspace can have a unique image. Specify multiple images to
234 \&\fBDesktopBackgroundImage\fR separated by comma\*(Aqs. Or give at least one
235 directory with images. The images are assigned to each workspace in
236 the order given. When icewm changes workspace, the running icewmbg
237 will adapt the desktop background to the assigned image.
238 .PP
239 If you specify more images then there are workspaces, then
240 \&\fBCycleBackgroundsPeriod\fR can set a period. When the period expires,
241 icewmbg will switch to the next set of images. If you give less images
242 than there are workspaces, then icewmbg will reuse previous images
243 for the remaining workspaces.
244 .SS "IMAGE SCALING"
245 .IX Subsection "IMAGE SCALING"
246 Often a background image has a different width or height than the screen.
247 The image can then be replicated (tiled), centered or scaled. This is
248 controlled by \f(CW\*(C`DesktopBackgroundCenter\*(C'\fR and \f(CW\*(C`DesktopBackgroundScaled\*(C'\fR.
249 What happens for their combination is given by the following table:
250 .PP
251 .Vb 4
252 \& center:0 scaled:0 = The background is replicated in both directions.
253 \& center:1 scaled:0 = The background is centered, but not scaled.
254 \& center:1 scaled:1 = Fill one dimension and preserve the aspect ratio.
255 \& center:0 scaled:1 = Fill both dimensions and preserve the aspect ratio.
256 .Ve
257 .SS EXAMPLES
258 .IX Subsection "EXAMPLES"
259 .Vb 1
260 \& # For four unique desktop backgrounds for four workspaces do:
261 \&
262 \& icewmbg \-f \-p \-i image0,image1,image2,image3
263 \&
264 \& # Or create a directory with the four images and do:
265 \&
266 \& icewmbg \-f \-p \-i /path/to/directory
267 \&
268 \& # The images should have proper image filename extensions.
269 .Ve
270 .SS SIGNALS
271 .IX Subsection "SIGNALS"
272 \&\fBicewmbg\fR supports the following signals:
273 .IP \fBSIGHUP\fR 4
274 .IX Item "SIGHUP"
275 \&\fBicewmbg\fR will restart itself.
276 .IP "\fBSIGINT\fR, \fBSIGTERM\fR" 4
277 .IX Item "SIGINT, SIGTERM"
278 \&\fBicewmbg\fR will terminate.
279 .IP \fBSIGUSR1\fR 4
280 .IX Item "SIGUSR1"
281 \&\fBicewmbg\fR will reshuffle the list of background images and
282 update the backgrounds of all workspaces.
283 .SS "SEE ALSO"
284 .IX Subsection "SEE ALSO"
285 \&\fBicewm\fR\|(1),
286 \&\fBicewm\-preferences\fR\|(5),
287 \&\fBicewm\-prefoverride\fR\|(5),
288 \&\fBwmsetbg\fR\|(1),
289 \&\fBxsetbg\fR\|(1),
290 \&\fBxwallpaper\fR\|(1).
291 .SS BUGS
292 .IX Subsection "BUGS"
293 Please report bugs at <https://github.com/ice\-wm/icewm/issues>.
294 .SS AUTHOR
295 .IX Subsection "AUTHOR"
296 Brian Bidulock <mailto:[email protected]>.
297 .PP
298 See \fB\-\-copying\fR for full copyright notice and copying permissions.
299 .SS LICENSE
300 .IX Subsection "LICENSE"
301 \&\fBIceWM\fR is licensed under the GNU Library General Public License.
302 See the \fICOPYING\fR file in the distribution or use the \fB\-\-copying\fR flag
303 to display copying permissions.