1ICEWMBG(1) User Commands ICEWMBG(1)
2 NAME
6 icewmbg - a background settings manager for the IceWM window manager
7 SYNOPSIS
9 icewmbg [OPTIONS] [ARGUMENTS]
10 DESCRIPTION
12 icewmbg can assign a colour or image to the X11 desktop background.
13 Common image formats are supported. Each icewm(1) workspace can have
14 its own background.
15 When the background image changes, icewmbg can be notified to update
17 the background. When switching workspaces, it checks the image file
18 modification time. If the file has changed, it reloads the image from
19 file.
20 icewmbg supports semitransparency. Semitransparent background images
22 and colours can be configured.
23 It uses RandR or Xinerama to support backgrounds on all connected
25 monitors. When monitors appear/disappear, or change their resolution,
26 icewmbg will adjust. It supports an option for one large background
27 over all monitors.
28 It will update the "_ICEWMBG_IMAGE" property of the root window to the
30 path of the background image whenever it changes the desktop
31 background.
32 icewmbg is started automatically by icewm-session(1). If there is just
34 a single background for all workspaces, icewmbg may conclude that it
35 can safely exit after setting the desktop background, to free its
36 system memory. If the screen size changes, icewm will then attempt to
37 restart icewmbg, preferably via icewm-session.
38 ARGUMENTS
40 SPECIFIC OPTIONS
41 Where multiple values can be given for images or colours, they are
42 separated by comma's. Each such value may be enclosed in double
43 quotes. If FILE is a directory, all images from that directory are
44 used in sorted order. If the value starts with an exclamation mark, as
45 in !FILE, the images from the directory FILE are permuted randomly.
46 Image file names or directory names may have glob(7) wildcards, or they
47 may start with a tilde or environment variable.
48 -f, --fork
50 Fork into the background and detach from the terminal.
51 -p, --replace
53 Replace an existing icewmbg. If there is a running icewmbg, it is
54 instructed to quit. The new icewmbg will take over.
55 -q, --quit
57 Tell the running icewmbg to quit. This option is used by
58 icewm-session(1) when icewm(1) exits.
59 -r, --restart
61 Tell the running icewmbg to restart itself. This is useful when
62 settings in have changed. If no icewmbg is active, it starts one.
63 -u, --shuffle
65 Shuffle the list of background images randomly. This option may be
66 given again whenever the running icewmbg should reshuffle its list
67 of background images.
68 -c, --config=FILE
70 Load preferences from FILE.
71 -t, --theme=THEME
73 Use the theme named THEME.
74 -i, --image=FILE[,FILE]*
76 Load background images from each FILE. This overrules the
77 "DesktopBackgroundImage" preference. When more than one image is
78 given, they are assigned to each workspace in the given order.
79 -k, --color=COLOR[,COLOR]*
81 Use background colours from each COLOR. This overrules the
82 "DesktopBackgroundColor" preference.
83 -s, --semis=FILE[,FILE]*
85 Load transparency images from each FILE. This overrules the
86 "DesktopTransparencyImage" preference.
87 -x, --trans=NAME[,NAME]
89 Use transparency colours for each NAME. This overrules the
90 "DesktopTransparencyColor" preference.
91 -e, --center={0|1}
93 Disable/Enable centring background. This overrules the
94 "DesktopBackgroundCenter" preference.
95 -a, --scaled={0|1}
97 Disable/Enable scaling background. This overrules the
98 "DesktopBackgroundScaled" preference.
99 -m, --multi={0|1}
101 Disable or enable a single background over all monitors. This
102 overrules the "DesktopBackgroundMultihead" preference.
103 -y, --cycle=SECONDS
105 Cycle over the list of background images every SECONDS. This
106 overrules the "CycleBackgroundsPeriod" preference.
107 -o, --output=FILE
109 Redirect all output to FILE. A leading tilde or environment
110 variable is expanded.
111 --postpreferences
113 Print a list of all preference values that icewmbg will use.
114 GENERAL OPTIONS
116 -d, --display=DISPLAY
117 Use DISPLAY to connect to the X server. Otherwise use DISPLAY from
118 the environment.
119 -h, --help
121 Print a brief usage statement to stdout and exit.
122 -V, --version
124 Print the program version to stdout and exit.
125 -C, --copying
127 Print copying permissions to stdout for the program and exit.
128 --sync
130 Use a slow synchronous mode to communicate with the X11 server.
131 --verbose
133 Report on some of the activities.
134 FILES
136 Additional arguments, which either are a path or which have an image
137 extension, are assumed to be background image files or directories.
138 PREFERENCES
140 By default icewmbg loads settings from the icewm(1) preferences file.
141 See icewm-preferences(5) for details. The settings read are:
142 DesktopBackgroundCenter - Display desktop background centered
144 DesktopBackgroundScaled - Display desktop background scaled
145 DesktopBackgroundColor - Desktop background color(s)
146 DesktopBackgroundImage - Desktop background image(s)
147 ShuffleBackgroundImages - Shuffle the list of background images
148 SupportSemitransparency - Support for semitransparent terminals
149 DesktopTransparencyColor - Semitransparency background color(s)
150 DesktopTransparencyImage - Semitransparency background image(s)
151 DesktopBackgroundMultihead - One background over all monitors
152 CycleBackgroundsPeriod - Seconds between cycling over backgrounds
153 If these settings are set in the preferences file, they can be
155 overridden by the theme in the theme defaults file. To enforce a
156 certain setting, set it in the prefoverride file instead. See
157 icewm-prefoverride(5).
158 WORKSPACES
160 Each workspace can have a unique image. Specify multiple images to
161 DesktopBackgroundImage separated by comma's. Or give at least one
162 directory with images. The images are assigned to each workspace in the
163 order given. When icewm changes workspace, the running icewmbg will
164 adapt the desktop background to the assigned image.
165 If you specify more images then there are workspaces, then
167 CycleBackgroundsPeriod can set a period. When the period expires,
168 icewmbg will switch to the next set of images. If you give less images
169 than there are workspaces, then icewmbg will reuse previous images for
170 the remaining workspaces.
171 IMAGE SCALING
173 Often a background image has a different width or height than the
174 screen. The image can then be replicated (tiled), centered or scaled.
175 This is controlled by "DesktopBackgroundCenter" and
176 "DesktopBackgroundScaled". What happens for their combination is given
177 by the following table:
178 center:0 scaled:0 = The background is replicated in both directions.
180 center:1 scaled:0 = The background is centered, but not scaled.
181 center:1 scaled:1 = Fill one dimension and preserve the aspect ratio.
182 center:0 scaled:1 = Fill both dimensions and preserve the aspect ratio.
183 EXAMPLES
185 # For four unique desktop backgrounds for four workspaces do:
186 icewmbg -f -p -i image0,image1,image2,image3
188 # Or create a directory with the four images and do:
190 icewmbg -f -p -i /path/to/directory
192 # The images should have proper image filename extensions.
194 SIGNALS
196 icewmbg supports the following signals:
197 SIGHUP
199 icewmbg will restart itself.
200 SIGINT, SIGTERM
202 icewmbg will terminate.
203 SIGUSR1
205 icewmbg will reshuffle the list of background images and update the
206 backgrounds of all workspaces.
207 SEE ALSO
209 icewm(1), icewm-preferences(5), icewm-prefoverride(5), wmsetbg(1),
210 xsetbg(1), xwallpaper(1).
211 BUGS
213 Please report bugs at <https://github.com/bbidulock/icewm/issues>.
214 AUTHOR
216 Brian Bidulock <mailto:bidulock@openss7.org>.
217 See --copying for full copyright notice and copying permissions.
219 LICENSE
221 IceWM is licensed under the GNU Library General Public License. See
222 the COPYING file in the distribution or use the --copying flag to
223 display copying permissions.
224icewm 3.4.4 2023-11-03 ICEWMBG(1)