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 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 RandR or Xinerama 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 icewmbg is started automatically by icewm-session(1).
35 OPTIONS
37 SPECIFIC OPTIONS
38 Where multiple values can be given for images or colours, they are
39 separated by commas. Each such value may be enclosed in double quotes.
40 When FILE is a directory then all images from that directory are used
41 in sorted order. If the value starts with an exclamation mark, as in
42 !FILE, then the images from the directory FILE are permuted randomly.
43 Image file names or directory names may have wildcards, which will be
44 expanded according to glob(7).
45 -p, --replace
47 Replace an existing icewmbg. If there is a running icewmbg, it is
48 instructed to quit. The new icewmbg will take over.
49 -q, --quit
51 Tell the running icewmbg to quit. This option is used by
52 icewm-session(1) when icewm(1) exits.
53 -r, --restart
55 Tell the running icewmbg to restart itself. This is useful when a
56 background file or directory has changed, or when settings in
57 preferences files have changed.
58 -u, --shuffle
60 Shuffle the list of background images randomly. This option may be
61 given again whenever the running icewmbg should reshuffle its list
62 of background images.
63 -c, --config=FILE
65 Load preferences from FILE.
66 -t, --theme=THEME
68 Load the theme named THEME.
69 -i, --image=FILE[,FILE]*
71 Load background images from each FILE. This overrules the
72 "DesktopBackgroundImage" preference.
73 -k, --color=COLOR[,COLOR]*
75 Use background colours from each COLOR. This overrules the
76 "DesktopBackgroundColor" preference.
77 -s, --semis=FILE[,FILE]*
79 Load transparency images from each FILE. This overrules the
80 "DesktopTransparencyImage" preference.
81 -x, --trans=NAME[,NAME]
83 Use transparency colours for each NAME. This overrules the
84 "DesktopTransparencyColor" preference.
85 -e, --center={0|1}
87 Disable/Enable centring background. This overrules the
88 "DesktopBackgroundCenter" preference.
89 -a, --scaled={0|1}
91 Disable/Enable scaling background. This overrules the
92 "DesktopBackgroundScaled" preference.
93 -m, --multi={0|1}
95 Disable or enable a single background over all monitors. This
96 overrules the "DesktopBackgroundMultihead" preference.
97 -y, --cycle=SECONDS
99 Cycle over the list of background images every SECONDS. This
100 overrules the "CycleBackgroundsPeriod" preference.
101 GENERAL OPTIONS
103 -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 -h, --help
108 Print a brief usage statement to stdout and exit.
109 -V, --version
111 Print the program version to stdout and exit.
112 -C, --copying
114 Print copying permissions to stdout for the program and exit.
115 --sync
117 Use a slower synchronous mode communication with X11 server.
118 FILES
120 PREFERENCES
121 By default icewmbg will load the background settings from the icewm(1)
122 preferences files (see icewm-preferences(5)). The settings read are:
123 DesktopBackgroundCenter - Display desktop background centered
125 DesktopBackgroundScaled - Display desktop background scaled
126 DesktopBackgroundColor - Desktop background color(s)
127 DesktopBackgroundImage - Desktop background image(s)
128 ShuffleBackgroundImages - Shuffle the list of background images
129 SupportSemitransparency - Support for semitransparent terminals
130 DesktopTransparencyColor - Semitransparency background color(s)
131 DesktopTransparencyImage - Semitransparency background image(s)
132 DesktopBackgroundMultihead - One background over all monitors
133 CycleBackgroundsPeriod - Seconds between cycling over backgrounds
134 First these settings are read from the preferences file. Then the
136 theme file from the current theme is read, which may overrule the
137 preferences settings. Lastly the prefoverride file is read, which
138 overrides again. Therefore, if you want to allow the theme to set the
139 background use preferences for your settings, otherwise use
140 prefoverride. See icewm-prefoverride(5).
141 IMAGE SCALING
143 Often a background image has a different width or height than the
144 screen. The image can then be replicated (tiled), centered or scaled.
145 This is controlled by "DesktopBackgroundCenter" and
146 "DesktopBackgroundScaled". What happens for their combination is given
147 by the following table:
148 center:0 scaled:0 = The background is replicated in both directions.
150 center:1 scaled:0 = The background is centered, but not scaled.
151 center:1 scaled:1 = Fill one dimension and preserve the aspect ratio.
152 center:0 scaled:1 = Fill both dimensions and preserve the aspect ratio.
153 SIGNALS
155 icewmbg supports the following signals:
156 SIGHUP
158 icewmbg will restart itself.
159 SIGINT, SIGTERM
161 icewmbg will terminate.
162 SIGUSR1
164 icewmbg will reshuffle the list of background images and update the
165 backgrounds of all work spaces.
166 SEE ALSO
168 icewm(1), icewm-preferences(5), icewm-prefoverride(5), wmsetbg(1),
169 xsetbg(1), xwallpaper(1).
170 BUGS
172 Please report bugs at <https://github.com/bbidulock/icewm/issues>.
173 AUTHOR
175 Brian Bidulock <mailto:bidulock@openss7.org>.
176 See --copying for full copyright notice and copying permissions.
178 LICENSE
180 IceWM is licensed under the GNU Library General Public License. See
181 the COPYING file in the distribution or use the --copying flag to
182 display copying permissions.
183icewm 2.9.7 2022-05-16 ICEWMBG(1)