path: root/upstream/mageia-cauldron/man1/icewmbg.1

.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "ICEWMBG 1"
.TH ICEWMBG 1 2023-12-28 "icewm 3.4.5" "User Commands"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SS NAME
.IX Subsection "NAME"
.Vb 1
\& icewmbg \- a background settings manager for the IceWM window manager
.Ve
.SS SYNOPSIS
.IX Subsection "SYNOPSIS"
\&\fBicewmbg\fR [\fIOPTIONS\fR] [\fIARGUMENTS\fR]
.SS DESCRIPTION
.IX Subsection "DESCRIPTION"
\&\fBicewmbg\fR can assign a colour or image to the \fIX11\fR desktop background.
Common image formats are supported.  Each \fBicewm\fR\|(1) workspace can have
its own background.
.PP
When the background image changes, \fBicewmbg\fR can be notified to
update the background.  When switching workspaces, it checks the image
file modification time.  If the file has changed, it reloads the
image from file.
.PP
\&\fBicewmbg\fR supports semitransparency.  Semitransparent background
images and colours can be configured.
.PP
It uses RandR or Xinerama to support backgrounds on all connected
monitors.  When monitors appear/disappear, or change their resolution,
\&\fBicewmbg\fR will adjust.  It supports an option for one large background
over all monitors.
.PP
It will update the \f(CW\*(C`_ICEWMBG_IMAGE\*(C'\fR property of the root window to the
path of the background image whenever it changes the desktop background.
.PP
\&\fBicewmbg\fR is started automatically by \fBicewm\-session\fR\|(1).
If there is just a single background for all workspaces, icewmbg may
conclude that it can safely exit after setting the desktop background,
to free its system memory.  If the screen size changes, icewm will then
attempt to restart icewmbg, preferably via icewm-session.
.SS ARGUMENTS
.IX Subsection "ARGUMENTS"
.SS "SPECIFIC OPTIONS"
.IX Subsection "SPECIFIC OPTIONS"
Where multiple values can be given for images
or colours, they are separated by comma's.
Each such value may be enclosed in double quotes.
If \fIFILE\fR is a directory, all images
from that directory are used in sorted order.
If the value starts with an exclamation mark, as in \fI!FILE\fR,
the images from the directory \fIFILE\fR are permuted randomly.
Image file names or directory names may have \fBglob\fR\|(7) wildcards,
or they may start with a tilde or environment variable.
.IP "\fB\-f\fR, \fB\-\-fork\fR" 4
.IX Item "-f, --fork"
Fork into the background and detach from the terminal.
.IP "\fB\-p\fR, \fB\-\-replace\fR" 4
.IX Item "-p, --replace"
Replace an existing \fBicewmbg\fR. If there is a running \fBicewmbg\fR,
it is instructed to quit.  The new \fBicewmbg\fR will take over.
.IP "\fB\-q\fR, \fB\-\-quit\fR" 4
.IX Item "-q, --quit"
Tell the running \fBicewmbg\fR to quit. This option is used by
\&\fBicewm\-session\fR\|(1) when \fBicewm\fR\|(1) exits.
.IP "\fB\-r\fR, \fB\-\-restart\fR" 4
.IX Item "-r, --restart"
Tell the running \fBicewmbg\fR to restart itself.  This is useful when
settings in have changed. If no icewmbg is active, it starts one.
.IP "\fB\-u\fR, \fB\-\-shuffle\fR" 4
.IX Item "-u, --shuffle"
Shuffle the list of background images randomly.
This option may be given again whenever the running
\&\fBicewmbg\fR should reshuffle its list of background images.
.IP "\fB\-c\fR, \fB\-\-config\fR=\fIFILE\fR" 4
.IX Item "-c, --config=FILE"
Load preferences from \fIFILE\fR.
.IP "\fB\-t\fR, \fB\-\-theme\fR=\fITHEME\fR" 4
.IX Item "-t, --theme=THEME"
Use the theme named \fITHEME\fR.
.IP "\fB\-i\fR, \fB\-\-image\fR=\fIFILE\fR[,\fIFILE\fR]*" 4
.IX Item "-i, --image=FILE[,FILE]*"
Load background images from each \fIFILE\fR.
This overrules the \f(CW\*(C`DesktopBackgroundImage\*(C'\fR preference.
When more than one image is given, they are assigned
to each workspace in the given order.
.IP "\fB\-k\fR, \fB\-\-color\fR=\fICOLOR\fR[,\fICOLOR\fR]*" 4
.IX Item "-k, --color=COLOR[,COLOR]*"
Use background colours from each \fICOLOR\fR.
This overrules the \f(CW\*(C`DesktopBackgroundColor\*(C'\fR preference.
.IP "\fB\-s\fR, \fB\-\-semis\fR=\fIFILE\fR[,\fIFILE\fR]*" 4
.IX Item "-s, --semis=FILE[,FILE]*"
Load transparency images from each \fIFILE\fR.
This overrules the \f(CW\*(C`DesktopTransparencyImage\*(C'\fR preference.
.IP "\fB\-x\fR, \fB\-\-trans\fR=\fINAME\fR[,\fINAME\fR]" 4
.IX Item "-x, --trans=NAME[,NAME]"
Use transparency colours for each \fINAME\fR.
This overrules the \f(CW\*(C`DesktopTransparencyColor\*(C'\fR preference.
.IP "\fB\-e\fR, \fB\-\-center\fR={\fI0\fR|\fI1\fR}" 4
.IX Item "-e, --center={0|1}"
Disable/Enable centring background.
This overrules the \f(CW\*(C`DesktopBackgroundCenter\*(C'\fR preference.
.IP "\fB\-a\fR, \fB\-\-scaled\fR={\fI0\fR|\fI1\fR}" 4
.IX Item "-a, --scaled={0|1}"
Disable/Enable scaling background.
This overrules the \f(CW\*(C`DesktopBackgroundScaled\*(C'\fR preference.
.IP "\fB\-m\fR, \fB\-\-multi\fR={\fI0\fR|\fI1\fR}" 4
.IX Item "-m, --multi={0|1}"
Disable or enable a single background over all monitors.
This overrules the \f(CW\*(C`DesktopBackgroundMultihead\*(C'\fR preference.
.IP "\fB\-y\fR, \fB\-\-cycle\fR=\fISECONDS\fR" 4
.IX Item "-y, --cycle=SECONDS"
Cycle over the list of background images every \fISECONDS\fR.
This overrules the \f(CW\*(C`CycleBackgroundsPeriod\*(C'\fR preference.
.IP "\fB\-o\fR, \fB\-\-output=FILE\fR" 4
.IX Item "-o, --output=FILE"
Redirect all output to \fIFILE\fR.
A leading tilde or environment variable is expanded.
.IP \fB\-\-postpreferences\fR 4
.IX Item "--postpreferences"
Print a list of all preference values that \fBicewmbg\fR will use.
.SS "GENERAL OPTIONS"
.IX Subsection "GENERAL OPTIONS"
.IP "\fB\-d\fR, \fB\-\-display\fR=\fIDISPLAY\fR" 4
.IX Item "-d, --display=DISPLAY"
Use \fIDISPLAY\fR to connect to the X server.
Otherwise use DISPLAY from the environment.
.IP "\fB\-h\fR, \fB\-\-help\fR" 4
.IX Item "-h, --help"
Print a brief usage statement to \fIstdout\fR and exit.
.IP "\fB\-V\fR, \fB\-\-version\fR" 4
.IX Item "-V, --version"
Print the program version to \fIstdout\fR and exit.
.IP "\fB\-C\fR, \fB\-\-copying\fR" 4
.IX Item "-C, --copying"
Print copying permissions to \fIstdout\fR for the program and exit.
.IP \fB\-\-sync\fR 4
.IX Item "--sync"
Use a slow synchronous mode to communicate with the \fIX11\fR server.
.IP \fB\-\-verbose\fR 4
.IX Item "--verbose"
Report on some of the activities.
.SS FILES
.IX Subsection "FILES"
Additional arguments, which either are a path or which have an image
extension, are assumed to be background image files or directories.
.SS PREFERENCES
.IX Subsection "PREFERENCES"
By default \fBicewmbg\fR loads settings from the \fBicewm\fR\|(1)
preferences file. See \fBicewm\-preferences\fR\|(5) for details.
The settings read are:
.PP
.Vb 10
\&  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
.Ve
.PP
If these settings are set in the \fIpreferences\fR file, they can
be overridden by the theme in the theme defaults file.
To enforce a certain setting, set it in the \fIprefoverride\fR file instead.
See \fBicewm\-prefoverride\fR\|(5).
.SS WORKSPACES
.IX Subsection "WORKSPACES"
Each workspace can have a unique image. Specify multiple images to
\&\fBDesktopBackgroundImage\fR separated by comma's.  Or give at least one
directory with images. The images are assigned to each workspace in
the order given. When icewm changes workspace, the running icewmbg
will adapt the desktop background to the assigned image.
.PP
If you specify more images then there are workspaces, then
\&\fBCycleBackgroundsPeriod\fR can set a period. When the period expires,
icewmbg will switch to the next set of images. If you give less images
than there are workspaces, then icewmbg will reuse previous images
for the remaining workspaces.
.SS "IMAGE SCALING"
.IX Subsection "IMAGE SCALING"
Often a background image has a different width or height than the screen.
The image can then be replicated (tiled), centered or scaled. This is
controlled by \f(CW\*(C`DesktopBackgroundCenter\*(C'\fR and \f(CW\*(C`DesktopBackgroundScaled\*(C'\fR.
What happens for their combination is given by the following table:
.PP
.Vb 4
\&  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.
.Ve
.SS EXAMPLES
.IX Subsection "EXAMPLES"
.Vb 1
\&    # For four unique desktop backgrounds for four workspaces do:
\&
\&    icewmbg \-f \-p \-i image0,image1,image2,image3
\&
\&    # Or create a directory with the four images and do:
\&
\&    icewmbg \-f \-p \-i /path/to/directory
\&
\&    # The images should have proper image filename extensions.
.Ve
.SS SIGNALS
.IX Subsection "SIGNALS"
\&\fBicewmbg\fR supports the following signals:
.IP \fBSIGHUP\fR 4
.IX Item "SIGHUP"
\&\fBicewmbg\fR will restart itself.
.IP "\fBSIGINT\fR, \fBSIGTERM\fR" 4
.IX Item "SIGINT, SIGTERM"
\&\fBicewmbg\fR will terminate.
.IP \fBSIGUSR1\fR 4
.IX Item "SIGUSR1"
\&\fBicewmbg\fR will reshuffle the list of background images and
update the backgrounds of all workspaces.
.SS "SEE ALSO"
.IX Subsection "SEE ALSO"
\&\fBicewm\fR\|(1),
\&\fBicewm\-preferences\fR\|(5),
\&\fBicewm\-prefoverride\fR\|(5),
\&\fBwmsetbg\fR\|(1),
\&\fBxsetbg\fR\|(1),
\&\fBxwallpaper\fR\|(1).
.SS BUGS
.IX Subsection "BUGS"
Please report bugs at <https://github.com/bbidulock/icewm/issues>.
.SS AUTHOR
.IX Subsection "AUTHOR"
Brian Bidulock <mailto:bidulock@openss7.org>.
.PP
See \fB\-\-copying\fR for full copyright notice and copying permissions.
.SS LICENSE
.IX Subsection "LICENSE"
\&\fBIceWM\fR is licensed under the GNU Library General Public License.
See the \fICOPYING\fR file in the distribution or use the \fB\-\-copying\fR flag
to display copying permissions.