Debian Codegraph @

upstream/debian-unstable/man1/icewmbg.1

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