NAME

 icewmbg - a background settings manager for the IceWM window manager

SYNOPSIS

icewmbg [OPTIONS]

DESCRIPTION

icewmbg can assign a colour or image to the X11 desktop background. Common image formats are supported. Each icewm(1) work space can have its own background.

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

icewmbg supports semi-transparency. Semitransparent background images and colours can be configured.

It uses RandR or Xinerama to support backgrounds on all connected monitors. When monitors appear/disappear, or change their resolution, icewmbg will adjust. It supports an option for one large background over all monitors.

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

icewmbg is started automatically by icewm-session(1).

OPTIONS

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 FILE is a directory, all images from that directory are used in sorted order. If the value starts with an exclamation mark, as in !FILE, the images from the directory FILE are permuted randomly. Image file names or directory names may have glob(7) wildcards,

-p, --replace

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

-q, --quit

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

-r, --restart

Tell the running icewmbg to restart itself. This is useful when settings in have changed. If no icewmbg is active, it starts one.

-u, --shuffle

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

-c, --config=FILE

Load preferences from FILE.

-t, --theme=THEME

Use the theme named THEME.

-i, --image=FILE[,FILE]*

Load background images from each FILE. This overrules the "DesktopBackgroundImage" preference. When more than one image is given, they are assigned to each workspace in the given order.

-k, --color=COLOR[,COLOR]*

Use background colours from each COLOR. This overrules the "DesktopBackgroundColor" preference.

-s, --semis=FILE[,FILE]*

Load transparency images from each FILE. This overrules the "DesktopTransparencyImage" preference.

-x, --trans=NAME[,NAME]

Use transparency colours for each NAME. This overrules the "DesktopTransparencyColor" preference.

-e, --center={0|1}

Disable/Enable centring background. This overrules the "DesktopBackgroundCenter" preference.

-a, --scaled={0|1}

Disable/Enable scaling background. This overrules the "DesktopBackgroundScaled" preference.

-m, --multi={0|1}

Disable or enable a single background over all monitors. This overrules the "DesktopBackgroundMultihead" preference.

-y, --cycle=SECONDS

Cycle over the list of background images every SECONDS. This overrules the "CycleBackgroundsPeriod" preference.

GENERAL OPTIONS

-d, --display=DISPLAY

Use DISPLAY to connect to the X server. If this option is missing then DISPLAY is read from the environment variable "DISPLAY".

-h, --help

Print a brief usage statement to stdout and exit.

-V, --version

Print the program version to stdout and exit.

-C, --copying

Print copying permissions to stdout for the program and exit.

--sync

Use a slower synchronous mode communication with X11 server.

FILES

PREFERENCES

By default icewmbg loads settings from the icewm(1) preferences file. See icewm-preferences(5) for details. 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

If these settings are set in the preferences file, they can be overridden by the theme in the theme defaults file. To prevent this, set these preferences in prefoverride instead. See icewm-prefoverride(5).

WORK SPACES

Each work space can have a unique image. Specify multiple images to DesktopBackgroundImage separated by comma's. Or give at least one directory with images. The images are assigned to each work space in the order given. When icewm changes work space, the running icewmbg will adapt the desktop background to the assigned image.

If you specify more images then there are work spaces, then CycleBackgroundsPeriod 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 work spaces, then icewmbg will reuse previous images for the remaining work spaces.

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 "DesktopBackgroundCenter" and "DesktopBackgroundScaled". 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.

EXAMPLES

    # For four unique desktop backgrounds for four work spaces do:
    icewmbg -p -i image0,image1,image2,image3 &
    # Or create a directory with the four images and do:
    icewmbg -p -i /path/to/directory &
    # The images should have proper image filename extensions.

SIGNALS

icewmbg supports the following signals:

SIGHUP

icewmbg will restart itself.

SIGINT, SIGTERM

icewmbg will terminate.

SIGUSR1

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

SEE ALSO

icewm(1), icewm-preferences(5), icewm-prefoverride(5), wmsetbg(1), xsetbg(1), xwallpaper(1).

BUGS

Please report bugs at <https://github.com/bbidulock/icewm/issues>.

AUTHOR

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

See --copying for full copyright notice and copying permissions.

LICENSE

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