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