1ICEWMBG(1)                       User Commands                      ICEWMBG(1)
2
3
4
5   NAME
6        icewmbg - a background settings manager for the IceWM window manager
7
8   SYNOPSIS
9       icewmbg [OPTIONS]
10
11   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
16       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
21       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
25       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
30       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
34       icewmbg is started automatically by icewm-session(1).
35
36   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
46       -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
50       -q, --quit
51           Tell the running icewmbg to quit. This option is used by
52           icewm-session(1) when icewm(1) exits.
53
54       -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
59       -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
64       -c, --config=FILE
65           Load preferences from FILE.
66
67       -t, --theme=THEME
68           Load the theme named THEME.
69
70       -i, --image=FILE[,FILE]*
71           Load background images from each FILE.  This overrules the
72           "DesktopBackgroundImage" preference.
73
74       -k, --color=COLOR[,COLOR]*
75           Use background colours from each COLOR.  This overrules the
76           "DesktopBackgroundColor" preference.
77
78       -s, --semis=FILE[,FILE]*
79           Load transparency images from each FILE.  This overrules the
80           "DesktopTransparencyImage" preference.
81
82       -x, --trans=NAME[,NAME]
83           Use transparency colours for each NAME.  This overrules the
84           "DesktopTransparencyColor" preference.
85
86       -e, --center={0|1}
87           Disable/Enable centring background.  This overrules the
88           "DesktopBackgroundCenter" preference.
89
90       -a, --scaled={0|1}
91           Disable/Enable scaling background.  This overrules the
92           "DesktopBackgroundScaled" preference.
93
94       -m, --multi={0|1}
95           Disable or enable a single background over all monitors.  This
96           overrules the "DesktopBackgroundMultihead" preference.
97
98       -y, --cycle=SECONDS
99           Cycle over the list of background images every SECONDS.  This
100           overrules the "CycleBackgroundsPeriod" preference.
101
102   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
107       -h, --help
108           Print a brief usage statement to stdout and exit.
109
110       -V, --version
111           Print the program version to stdout and exit.
112
113       -C, --copying
114           Print copying permissions to stdout for the program and exit.
115
116       --sync
117           Use a slower synchronous mode communication with X11 server.
118
119   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
124         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
135       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
142   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
149         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
154   SIGNALS
155       icewmbg supports the following signals:
156
157       SIGHUP
158           icewmbg will restart itself.
159
160       SIGINT, SIGTERM
161           icewmbg will terminate.
162
163       SIGUSR1
164           icewmbg will reshuffle the list of background images and update the
165           backgrounds of all work spaces.
166
167   SEE ALSO
168       icewm(1), icewm-preferences(5), icewm-prefoverride(5), wmsetbg(1),
169       xsetbg(1), xwallpaper(1).
170
171   BUGS
172       Please report bugs at <https://github.com/bbidulock/icewm/issues>.
173
174   AUTHOR
175       Brian Bidulock <mailto:bidulock@openss7.org>.
176
177       See --copying for full copyright notice and copying permissions.
178
179   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.
183
184
185
186icewm 2.9.7                       2022-05-16                        ICEWMBG(1)
Impressum