1ICEWMBG(1) User Commands ICEWMBG(1)
2 NAME
6 icewmbg - a background settings manager for the IceWM window manager
7 SYNOPSIS
9 icewmbg [OPTIONS]
10 DESCRIPTION
12 icewmbg can assign a colour or image to the X11 desktop background.
13 Common image formats are supported. Each icewm(1) work space can have
14 its own background.
15 When the background image has changed, 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, it reloads the image
19 from file.
20 icewmbg supports semi-transparency. 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).
34 OPTIONS
36 SPECIFIC OPTIONS
37 Where multiple values can be given for images or colours, they are
38 separated by comma's. Each such value may be enclosed in double
39 quotes. If FILE is a directory, all images from that directory are
40 used in sorted order. If the value starts with an exclamation mark, as
41 in !FILE, the images from the directory FILE are permuted randomly.
42 Image file names or directory names may have glob(7) wildcards,
43 -p, --replace
45 Replace an existing icewmbg. If there is a running icewmbg, it is
46 instructed to quit. The new icewmbg will take over.
47 -q, --quit
49 Tell the running icewmbg to quit. This option is used by
50 icewm-session(1) when icewm(1) exits.
51 -r, --restart
53 Tell the running icewmbg to restart itself. This is useful when
54 settings in have changed. If no icewmbg is active, it starts one.
55 -u, --shuffle
57 Shuffle the list of background images randomly. This option may be
58 given again whenever the running icewmbg should reshuffle its list
59 of background images.
60 -c, --config=FILE
62 Load preferences from FILE.
63 -t, --theme=THEME
65 Use the theme named THEME.
66 -i, --image=FILE[,FILE]*
68 Load background images from each FILE. This overrules the
69 "DesktopBackgroundImage" preference. When more than one image is
70 given, they are assigned to each workspace in the given order.
71 -k, --color=COLOR[,COLOR]*
73 Use background colours from each COLOR. This overrules the
74 "DesktopBackgroundColor" preference.
75 -s, --semis=FILE[,FILE]*
77 Load transparency images from each FILE. This overrules the
78 "DesktopTransparencyImage" preference.
79 -x, --trans=NAME[,NAME]
81 Use transparency colours for each NAME. This overrules the
82 "DesktopTransparencyColor" preference.
83 -e, --center={0|1}
85 Disable/Enable centring background. This overrules the
86 "DesktopBackgroundCenter" preference.
87 -a, --scaled={0|1}
89 Disable/Enable scaling background. This overrules the
90 "DesktopBackgroundScaled" preference.
91 -m, --multi={0|1}
93 Disable or enable a single background over all monitors. This
94 overrules the "DesktopBackgroundMultihead" preference.
95 -y, --cycle=SECONDS
97 Cycle over the list of background images every SECONDS. This
98 overrules the "CycleBackgroundsPeriod" preference.
99 GENERAL OPTIONS
101 -d, --display=DISPLAY
102 Use DISPLAY to connect to the X server. If this option is missing
103 then DISPLAY is read from the environment variable "DISPLAY".
104 -h, --help
106 Print a brief usage statement to stdout and exit.
107 -V, --version
109 Print the program version to stdout and exit.
110 -C, --copying
112 Print copying permissions to stdout for the program and exit.
113 --sync
115 Use a slower synchronous mode communication with X11 server.
116 FILES
118 PREFERENCES
119 By default icewmbg loads settings from the icewm(1) preferences file.
120 See icewm-preferences(5) for details. The settings read are:
121 DesktopBackgroundCenter - Display desktop background centered
123 DesktopBackgroundScaled - Display desktop background scaled
124 DesktopBackgroundColor - Desktop background color(s)
125 DesktopBackgroundImage - Desktop background image(s)
126 ShuffleBackgroundImages - Shuffle the list of background images
127 SupportSemitransparency - Support for semitransparent terminals
128 DesktopTransparencyColor - Semitransparency background color(s)
129 DesktopTransparencyImage - Semitransparency background image(s)
130 DesktopBackgroundMultihead - One background over all monitors
131 CycleBackgroundsPeriod - Seconds between cycling over backgrounds
132 If these settings are set in the preferences file, they can be
134 overridden by the theme in the theme defaults file. To prevent this,
135 set these preferences in prefoverride instead. See
136 icewm-prefoverride(5).
137 WORK SPACES
139 Each work space can have a unique image. Specify multiple images to
140 DesktopBackgroundImage separated by comma's. Or give at least one
141 directory with images. The images are assigned to each work space in
142 the order given. When icewm changes work space, the running icewmbg
143 will adapt the desktop background to the assigned image.
144 If you specify more images then there are work spaces, then
146 CycleBackgroundsPeriod can set a period. When the period expires,
147 icewmbg will switch to the next set of images. If you give less images
148 than there are work spaces, then icewmbg will reuse previous images for
149 the remaining work spaces.
150 IMAGE SCALING
152 Often a background image has a different width or height than the
153 screen. The image can then be replicated (tiled), centered or scaled.
154 This is controlled by "DesktopBackgroundCenter" and
155 "DesktopBackgroundScaled". What happens for their combination is given
156 by the following table:
157 center:0 scaled:0 = The background is replicated in both directions.
159 center:1 scaled:0 = The background is centered, but not scaled.
160 center:1 scaled:1 = Fill one dimension and preserve the aspect ratio.
161 center:0 scaled:1 = Fill both dimensions and preserve the aspect ratio.
162 EXAMPLES
164 # For four unique desktop backgrounds for four work spaces do:
165 icewmbg -p -i image0,image1,image2,image3 &
167 # Or create a directory with the four images and do:
169 icewmbg -p -i /path/to/directory &
171 # The images should have proper image filename extensions.
173 SIGNALS
175 icewmbg supports the following signals:
176 SIGHUP
178 icewmbg will restart itself.
179 SIGINT, SIGTERM
181 icewmbg will terminate.
182 SIGUSR1
184 icewmbg will reshuffle the list of background images and update the
185 backgrounds of all work spaces.
186 SEE ALSO
188 icewm(1), icewm-preferences(5), icewm-prefoverride(5), wmsetbg(1),
189 xsetbg(1), xwallpaper(1).
190 BUGS
192 Please report bugs at <https://github.com/bbidulock/icewm/issues>.
193 AUTHOR
195 Brian Bidulock <mailto:bidulock@openss7.org>.
196 See --copying for full copyright notice and copying permissions.
198 LICENSE
200 IceWM is licensed under the GNU Library General Public License. See
201 the COPYING file in the distribution or use the --copying flag to
202 display copying permissions.
203icewm 3.3.1 2023-01-24 ICEWMBG(1)