=pod

=head1 NAME

 icewmbg - a background settings manager for the IceWM window manager

=head1 SYNOPSIS

B<icewmbg> [I<OPTIONS>]

=head1 DESCRIPTION

B<icewmbg> can assign a colour or image to the I<X11> desktop background.
Many image formats are supported.  Each L<icewm(1)> work space can have
its own background.

When the background image has changed then B<icewmbg> can be notified to
update the background.  When switching work spaces it checks the image
file modification time.  If the file has changed then it reloads the
background image from file.

B<icewmbg> supports semi-transparency.  Semitransparent background
images and colours can be configured.  If these are not specified then
the default background is used.

It uses XINERAMA and RANDR to support backgrounds on all connected
monitors.  When monitors appear/disappear or change their resolution
B<icewmbg> will adjust.  It supports an option for one large background
over all monitors.

It will update the C<_ICEWMBG_IMAGE> property of the root window to the
path of the background image whenever it changes the desktop background.

It should be started before L<icewm(1)>, preferably by the
L<icewm-session(1)> program.

=head1 OPTIONS

=head2 SPECIFIC OPTIONS

Where multiple values can be given for images
or colours they are separated by commas.
Each such value may be enclosed in double quotes.
When I<FILE> is a directory then all images
from that directory are used in sorted order.
If the value starts with an exclamation mark,
as in I<!FILE>, then the images from the
directory I<FILE> are permuted randomly.
Image file names or directory names may have wildcards,
which will be expanded according to L<glob(7)>.

=over

=item B<-p>, B<--replace>

Replace an existing B<icewmbg>. If there is a running B<icewmbg> it is
instructed to quit.  The new B<icewmbg> will take over.

=item B<-q>, B<--quit>

Tell the running B<icewmbg> to quit. This option is used by
L<icewm-session(1)> when L<icewm(1)> exits.

=item B<-r>, B<--restart>

Tell the running B<icewmbg> to restart itself.  This is useful when a
background file or directory has changed or when settings in preferences
files have changed.

=item B<-u>, B<--shuffle>

Shuffle the list of background images randomly.
This option may be given again whenever the running
B<icewmbg> should reshuffle its list of background images.

=item B<-c>, B<--config>=I<FILE>

Load preferences from I<FILE>.

=item B<-t>, B<--theme>=I<THEME>

Load the theme named I<THEME>.

=item B<-i>, B<--image>=I<FILE>[,I<FILE>]*

Load background images from each I<FILE>.
This overrules the C<DesktopBackgroundImage> preference.

=item B<-k>, B<--color>=I<COLOR>[,I<COLOR>]*

Use background colours from each I<COLOR>.
This overrules the C<DesktopBackgroundColor> preference.

=item B<-s>, B<--semis>=I<FILE>[,I<FILE>]*

Load transparency images from each I<FILE>.
This overrules the C<DesktopTransparencyImage> preference.

=item B<-x>, B<--trans>=I<NAME>[,I<NAME>]

Use transparency colours for each I<NAME>.
This overrules the C<DesktopTransparencyColor> preference.

=item B<-e>, B<--center>={I<0>|I<1>}

Disable/Enable centring background.
This overrules the C<DesktopBackgroundCenter> preference.

=item B<-a>, B<--scaled>={I<0>|I<1>}

Disable/Enable scaling background.
This overrules the C<DesktopBackgroundScaled> preference.

=item B<-m>, B<--multi>={I<0>|I<1>}

Disable/Enable multi-head background.
This overrules the C<DesktopBackgroundMultihead> preference.

=item B<-y>, B<--cycle>=I<SECONDS>

Cycle over the list of background images every I<SECONDS>.
This overrules the C<CycleBackgroundsPeriod> preference.

=item B<-d>, B<--display>=I<DISPLAY>

Use I<DISPLAY> to connect to the X server.
If this option is missing then I<DISPLAY>
is read from the environment variable C<DISPLAY>.

=item B<--sync>

Use a slower synchronous mode communication with I<X11> server.

=back

=head2 GENERAL OPTIONS

=over

=item B<-h>, B<--help>

Print a brief usage statement to F<stdout> and exit.

=item B<-V>, B<--version>

Print the program version to F<stdout> and exit.

=item B<-C>, B<--copying>

Print copying permissions to F<stdout> for the program and exit.

=back

=head1 FILES

=head2 PREFERENCES

By default B<icewmbg> will load the background settings from the
L<icewm(1)> preferences files (see L<icewm-preferences(5)>).  The
settings read are:

  DesktopBackgroundCenter    - Display desktop background centered
  DesktopBackgroundScaled    - Display desktop background scaled
  DesktopBackgroundColor     - Desktop background color(s)
  DesktopBackgroundImage     - Desktop background image(s)
  ShuffleBackgroundImages    - Shuffle the list of background images
  SupportSemitransparency    - Support for semitransparent terminals
  DesktopTransparencyColor   - Semitransparency background color(s)
  DesktopTransparencyImage   - Semitransparency background image(s)
  DesktopBackgroundMultihead - One background over all monitors
  CycleBackgroundsPeriod     - Seconds between cycling over backgrounds

First these settings are read from the F<preferences> file.  Then the
theme file from the current theme is read, which may overrule the
F<preferences> settings.  Lastly the F<prefoverride> file is read, which
overrides again.  Therefore, if you want to allow the theme to set the
background use F<preferences> for your settings, otherwise use
F<prefoverride>.  See L<icewm-prefoverride(5)>.

=head2 SCALING

Often a background image has a different width or height than the
screen.  The settings can specify to centre (C<DesktopBackgroundCenter>)
or scale (C<DesktopBackgroundScaled>) an image.  Either option is either
B<0> (disabled) or B<1> (enabled).  What happens for their combination
is given by the following table:

  center:0 scaled:0 = the background is replicated in both directions
  center:1 scaled:0 = the background is centered, but not scaled
  center:1 scaled:1 = fill one dimension and preserve the aspect ratio
  center:0 scaled:1 = fill both dimensions and preserve the aspect ratio

=head1 SIGNALS

B<icewmbg> supports the following signals:

=over

=item B<SIGHUP>

B<icewmbg> will restart itself.

=item B<SIGINT>, B<SIGTERM>

B<icewmbg> will terminate.

=item B<SIGUSR1>

B<icewmbg> will reshuffle the list of background images and
update the backgrounds of all work spaces.

=back

=head1 SEE ALSO

L<icewm(1)>,
L<icewm-preferences(5)>,
L<icewm-prefoverride(5)>,
L<wmsetbg(1)>,
L<xsetbg(1)>,
L<xv(1)>.

=head1 BUGS

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

=head1 AUTHOR

Brian Bidulock L<mailto:bidulock@openss7.org>.

See B<--copying> for full copyright notice and copying permissions.

=head1 LICENSE

B<IceWM> is licensed under the GNU Library General Public License.
See the F<COPYING> file in the distribution or use the B<--copying> flag
to display copying permissions.

=cut

# vim: set sw=4 tw=72 nocin spell spelllang=en_ca:
