1=pod
2
3=head1 NAME
4
5 icewmbg - a background settings manager for the IceWM window manager
6
7=head1 SYNOPSIS
8
9B<icewmbg> [I<OPTIONS>]
10
11=head1 DESCRIPTION
12
13B<icewmbg> can assign a colour or image to the I<X11> desktop background.
14Many image formats are supported.  Each L<icewm(1)> work space can have
15its own background.
16
17When the background image has changed, then B<icewmbg> can be notified to
18update the background.  When switching work spaces, it checks the image
19file modification time.  If the file has changed, then it reloads the
20background image from file.
21
22B<icewmbg> supports semi-transparency.  Semitransparent background
23images and colours can be configured.  If these are not specified then
24the default background is used.
25
26It uses RandR or Xinerama to support backgrounds on all connected
27monitors.  When monitors appear/disappear, or change their resolution,
28B<icewmbg> will adjust.  It supports an option for one large background
29over all monitors.
30
31It will update the C<_ICEWMBG_IMAGE> property of the root window to the
32path of the background image whenever it changes the desktop background.
33
34B<icewmbg> is started automatically by L<icewm-session(1)>.
35
36=head1 OPTIONS
37
38=head2 SPECIFIC OPTIONS
39
40Where multiple values can be given for images
41or colours, they are separated by commas.
42Each such value may be enclosed in double quotes.
43When I<FILE> is a directory then all images
44from that directory are used in sorted order.
45If the value starts with an exclamation mark,
46as in I<!FILE>, then the images from the
47directory I<FILE> are permuted randomly.
48Image file names or directory names may have wildcards,
49which will be expanded according to L<glob(7)>.
50
51=over
52
53=item B<-p>, B<--replace>
54
55Replace an existing B<icewmbg>. If there is a running B<icewmbg>,
56it is instructed to quit.  The new B<icewmbg> will take over.
57
58=item B<-q>, B<--quit>
59
60Tell the running B<icewmbg> to quit. This option is used by
61L<icewm-session(1)> when L<icewm(1)> exits.
62
63=item B<-r>, B<--restart>
64
65Tell the running B<icewmbg> to restart itself.  This is useful when
66a background file or directory has changed, or when settings in
67preferences files have changed.
68
69=item B<-u>, B<--shuffle>
70
71Shuffle the list of background images randomly.
72This option may be given again whenever the running
73B<icewmbg> should reshuffle its list of background images.
74
75=item B<-c>, B<--config>=I<FILE>
76
77Load preferences from I<FILE>.
78
79=item B<-t>, B<--theme>=I<THEME>
80
81Load the theme named I<THEME>.
82
83=item B<-i>, B<--image>=I<FILE>[,I<FILE>]*
84
85Load background images from each I<FILE>.
86This overrules the C<DesktopBackgroundImage> preference.
87
88=item B<-k>, B<--color>=I<COLOR>[,I<COLOR>]*
89
90Use background colours from each I<COLOR>.
91This overrules the C<DesktopBackgroundColor> preference.
92
93=item B<-s>, B<--semis>=I<FILE>[,I<FILE>]*
94
95Load transparency images from each I<FILE>.
96This overrules the C<DesktopTransparencyImage> preference.
97
98=item B<-x>, B<--trans>=I<NAME>[,I<NAME>]
99
100Use transparency colours for each I<NAME>.
101This overrules the C<DesktopTransparencyColor> preference.
102
103=item B<-e>, B<--center>={I<0>|I<1>}
104
105Disable/Enable centring background.
106This overrules the C<DesktopBackgroundCenter> preference.
107
108=item B<-a>, B<--scaled>={I<0>|I<1>}
109
110Disable/Enable scaling background.
111This overrules the C<DesktopBackgroundScaled> preference.
112
113=item B<-m>, B<--multi>={I<0>|I<1>}
114
115Disable or enable a single background over all monitors.
116This overrules the C<DesktopBackgroundMultihead> preference.
117
118=item B<-y>, B<--cycle>=I<SECONDS>
119
120Cycle over the list of background images every I<SECONDS>.
121This overrules the C<CycleBackgroundsPeriod> preference.
122
123=back
124
125=head2 GENERAL OPTIONS
126
127=over
128
129=item B<-d>, B<--display>=I<DISPLAY>
130
131Use I<DISPLAY> to connect to the X server.
132If this option is missing then I<DISPLAY>
133is read from the environment variable C<DISPLAY>.
134
135=item B<-h>, B<--help>
136
137Print a brief usage statement to F<stdout> and exit.
138
139=item B<-V>, B<--version>
140
141Print the program version to F<stdout> and exit.
142
143=item B<-C>, B<--copying>
144
145Print copying permissions to F<stdout> for the program and exit.
146
147=item B<--sync>
148
149Use a slower synchronous mode communication with I<X11> server.
150
151=back
152
153=head1 FILES
154
155=head2 PREFERENCES
156
157By default B<icewmbg> will load the background settings from the
158L<icewm(1)> preferences files (see L<icewm-preferences(5)>).  The
159settings read are:
160
161  DesktopBackgroundCenter    - Display desktop background centered
162  DesktopBackgroundScaled    - Display desktop background scaled
163  DesktopBackgroundColor     - Desktop background color(s)
164  DesktopBackgroundImage     - Desktop background image(s)
165  ShuffleBackgroundImages    - Shuffle the list of background images
166  SupportSemitransparency    - Support for semitransparent terminals
167  DesktopTransparencyColor   - Semitransparency background color(s)
168  DesktopTransparencyImage   - Semitransparency background image(s)
169  DesktopBackgroundMultihead - One background over all monitors
170  CycleBackgroundsPeriod     - Seconds between cycling over backgrounds
171
172First these settings are read from the F<preferences> file.  Then the
173theme file from the current theme is read, which may overrule the
174F<preferences> settings.  Lastly the F<prefoverride> file is read, which
175overrides again.  Therefore, if you want to allow the theme to set the
176background use F<preferences> for your settings, otherwise use
177F<prefoverride>.  See L<icewm-prefoverride(5)>.
178
179=head2 IMAGE SCALING
180
181Often a background image has a different width or height than the screen.
182The image can then be replicated (tiled), centered or scaled. This is
183controlled by C<DesktopBackgroundCenter> and C<DesktopBackgroundScaled>.
184What happens for their combination is given by the following table:
185
186  center:0 scaled:0 = The background is replicated in both directions.
187  center:1 scaled:0 = The background is centered, but not scaled.
188  center:1 scaled:1 = Fill one dimension and preserve the aspect ratio.
189  center:0 scaled:1 = Fill both dimensions and preserve the aspect ratio.
190
191=head1 SIGNALS
192
193B<icewmbg> supports the following signals:
194
195=over
196
197=item B<SIGHUP>
198
199B<icewmbg> will restart itself.
200
201=item B<SIGINT>, B<SIGTERM>
202
203B<icewmbg> will terminate.
204
205=item B<SIGUSR1>
206
207B<icewmbg> will reshuffle the list of background images and
208update the backgrounds of all work spaces.
209
210=back
211
212=head1 SEE ALSO
213
214L<icewm(1)>,
215L<icewm-preferences(5)>,
216L<icewm-prefoverride(5)>,
217L<wmsetbg(1)>,
218L<xsetbg(1)>,
219L<xwallpaper(1)>.
220
221=head1 BUGS
222
223Please report bugs at L<https://github.com/bbidulock/icewm/issues>.
224
225=head1 AUTHOR
226
227Brian Bidulock L<mailto:bidulock@openss7.org>.
228
229See B<--copying> for full copyright notice and copying permissions.
230
231=head1 LICENSE
232
233B<IceWM> is licensed under the GNU Library General Public License.
234See the F<COPYING> file in the distribution or use the B<--copying> flag
235to display copying permissions.
236
237=cut
238
239# vim: set sw=4 tw=72 nocin spell spelllang=en_ca:
240