1ICEWMBG(1)                       User Commands                      ICEWMBG(1)
2
3
4

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
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 XINERAMA and RANDR 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       It should be started before icewm(1), preferably by the
35       icewm-session(1) program.
36

OPTIONS

38   SPECIFIC OPTIONS
39       Where multiple values can be given for images or colours they are
40       separated by commas.  Each such value may be enclosed in double quotes.
41       When FILE is a directory then all images from that directory are used
42       in sorted order.  If the value starts with an exclamation mark, as in
43       !FILE, then the images from the directory FILE are permuted randomly.
44       Image file names or directory names may have wildcards, which will be
45       expanded according to glob(7).
46
47       -p, --replace
48           Replace an existing icewmbg. If there is a running icewmbg it is
49           instructed to quit.  The new icewmbg will take over.
50
51       -q, --quit
52           Tell the running icewmbg to quit. This option is used by
53           icewm-session(1) when icewm(1) exits.
54
55       -r, --restart
56           Tell the running icewmbg to restart itself.  This is useful when a
57           background file or directory has changed or when settings in
58           preferences files have changed.
59
60       -u, --shuffle
61           Shuffle the list of background images randomly.  This option may be
62           given again whenever the running icewmbg should reshuffle its list
63           of background images.
64
65       -c, --config=FILE
66           Load preferences from FILE.
67
68       -t, --theme=THEME
69           Load the theme named THEME.
70
71       -i, --image=FILE[,FILE]*
72           Load background images from each FILE.  This overrules the
73           "DesktopBackgroundImage" preference.
74
75       -k, --color=COLOR[,COLOR]*
76           Use background colours from each COLOR.  This overrules the
77           "DesktopBackgroundColor" preference.
78
79       -s, --semis=FILE[,FILE]*
80           Load transparency images from each FILE.  This overrules the
81           "DesktopTransparencyImage" preference.
82
83       -x, --trans=NAME[,NAME]
84           Use transparency colours for each NAME.  This overrules the
85           "DesktopTransparencyColor" preference.
86
87       -e, --center={0|1}
88           Disable/Enable centring background.  This overrules the
89           "DesktopBackgroundCenter" preference.
90
91       -a, --scaled={0|1}
92           Disable/Enable scaling background.  This overrules the
93           "DesktopBackgroundScaled" preference.
94
95       -m, --multi={0|1}
96           Disable/Enable multi-head background.  This overrules the
97           "DesktopBackgroundMultihead" preference.
98
99       -y, --cycle=SECONDS
100           Cycle over the list of background images every SECONDS.  This
101           overrules the "CycleBackgroundsPeriod" preference.
102
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       --sync
108           Use a slower synchronous mode communication with X11 server.
109
110   GENERAL OPTIONS
111       -h, --help
112           Print a brief usage statement to stdout and exit.
113
114       -V, --version
115           Print the program version to stdout and exit.
116
117       -C, --copying
118           Print copying permissions to stdout for the program and exit.
119

FILES

121   PREFERENCES
122       By default icewmbg will load the background settings from the icewm(1)
123       preferences files (see icewm-preferences(5)).  The settings read are:
124
125         DesktopBackgroundCenter    - Display desktop background centered
126         DesktopBackgroundScaled    - Display desktop background scaled
127         DesktopBackgroundColor     - Desktop background color(s)
128         DesktopBackgroundImage     - Desktop background image(s)
129         ShuffleBackgroundImages    - Shuffle the list of background images
130         SupportSemitransparency    - Support for semitransparent terminals
131         DesktopTransparencyColor   - Semitransparency background color(s)
132         DesktopTransparencyImage   - Semitransparency background image(s)
133         DesktopBackgroundMultihead - One background over all monitors
134         CycleBackgroundsPeriod     - Seconds between cycling over backgrounds
135
136       First these settings are read from the preferences file.  Then the
137       theme file from the current theme is read, which may overrule the
138       preferences settings.  Lastly the prefoverride file is read, which
139       overrides again.  Therefore, if you want to allow the theme to set the
140       background use preferences for your settings, otherwise use
141       prefoverride.  See icewm-prefoverride(5).
142
143   SCALING
144       Often a background image has a different width or height than the
145       screen.  The settings can specify to centre ("DesktopBackgroundCenter")
146       or scale ("DesktopBackgroundScaled") an image.  Either option is either
147       0 (disabled) or 1 (enabled).  What happens for their combination is
148       given by the following table:
149
150         center:0 scaled:0 = the background is replicated in both directions
151         center:1 scaled:0 = the background is centered, but not scaled
152         center:1 scaled:1 = fill one dimension and preserve the aspect ratio
153         center:0 scaled:1 = fill both dimensions and preserve the aspect ratio
154

SIGNALS

156       icewmbg supports the following signals:
157
158       SIGHUP
159           icewmbg will restart itself.
160
161       SIGINT, SIGTERM
162           icewmbg will terminate.
163
164       SIGUSR1
165           icewmbg will reshuffle the list of background images and update the
166           backgrounds of all work spaces.
167

SEE ALSO

169       icewm(1), icewm-preferences(5), icewm-prefoverride(5), wmsetbg(1),
170       xsetbg(1), xv(1).
171

BUGS

173       icewmbg had no known bugs at the time of release.  Please report bugs
174       for current versions to the source code repository at
175       <https://github.com/bbidulock/icewm/issues>.
176

AUTHOR

178       Brian Bidulock <mailto:bidulock@openss7.org>.
179
180       See --copying for full copyright notice and copying permissions.
181

LICENSE

183       IceWM is licensed under the GNU Library General Public License.  See
184       the COPYING file in the distribution or use the --copying flag to
185       display copying permissions.
186
187
188
189icewm 2.3.0                       2021-04-02                        ICEWMBG(1)
Impressum