SETROOT(1)

NAME
setroot - sets your wallpaper.

SYNOPSIS

setroot [storage flag] [global flag] { [image flags, manipulations, options] <filename> }+ [monitor flag]

DESCRIPTION

setroot is a lightweight Xinerama-aware CLI background setter in the vein of imlibsetroot, hsetroot, and feh. Its only non-obvious dependency is imlib2.

INVOCATION

The order of the filenames determines which monitor the wallpaper is set to. The first invoked filename is set to the first Xinerama monitor; the second to the second; and so on.

If more than one image option is applied, the last one takes effect.

If n filenames are supplied for k monitors, where n > k, only the first k filenames will be processed.

An illegal invocation sequence will result in setroot terminating with exit status 1.

STORAGE FLAGS

--store
    creates an executable file ".setroot-restore" located in directory "${XDG_CONFIG_HOME:-$HOME/.config}/setroot/.setroot-restore"

    If the directory path and/or file does not exist, it will be created (see section FILES).

--restore
    looks for "${XDG_CONFIG_HOME:-$HOME/.config}/setroot/.setroot-restore" and executes it in shell (restores your previously set wallpapers and options)

GLOBAL FLAGS

--blank-color #RRGGBB
    sets background color of blank walls, unless overriden by --bg-color option

IMAGE FLAGS

--span
    have image span all screens (no cropping).

    If more than one image is specified, the later image will be spanned.

    Note that this overrides the --on option. Note also that further images that are set (in the case of multiple monitors) will "cover" the spanned image.

--bg-color #RRGGBB
    set empty space around image to color

--on n
    assign image to be wallpaper on Xinerama monitor n

    If not all images are passed this option, the unassigned walls will be placed on monitors by their position in the invocation sequence.

    Images which do have a specified assignment will then be assigned to their monitors, replacing any images which may have already been assigned.

    If --on is supplied a screen which does not exist, no error is raised and the other walls are set as normal. This can be used with setroot --store to "preset" an unconnected monitor's wallpaper.

    If setroot was not compiled with Xinerama support then --on is considered an invalid command and the program will terminate will terminate with exit status 1.

IMAGE MANIPULATIONS

--blur <radius>
    blur image

--sharpen <radius>
    sharpen image

--brighten <amount>
    modify image brightness by amount (between -1 and 1)

--contrast <amount>
    modify contrast of image by amount (between -100 and 100)

--flip[hvd]
    flip image [h]orizontally, [v]ertically, or [d]iagonally

--tint #RRGGBB
    tint image with color #RRGGBB (also accepts valid XColor)

--greyscale
    renders image as greyscale (uses luminosity algorithm)

IMAGE OPTIONS

-c, --center
    place unscaled image centered and cropped to screen

-t, --tiled
    tile image on invoked screen (Xinerama aware)

-s, --stretch
    stretch image (disregard aspect) on invoked screen

-z, --zoom
    scale image (preserve aspect) to fit screen completely (could cut off image)

-f, --fit-auto
    scale image (preserve aspect) to fit screen (entire image on screen) - default

-fh, --fit-height
    scale image (preserve aspect) until height matches invoked screen

-fw, --fit-width
    scale image (preserve aspect) until width matches invoked screen

-gx, --gravity-x <position>
    set the image gravity center in the X axis at position (an integer absolute position or a float percentage) - default: 50%

-gy, --gravity-y <position>
    set the image gravity center in the Y axis at position (an integer absolute position or a float percentage) - default: 50%

-sc, --solid-color #RRGGBB
    set background to solid color #RRGGBB (hex code, also accepts valid XColor)

MONITOR FLAGS

--use-x-geometry
    number Xinerama monitors from leftmost to rightmost

--use-y-geometry
    number Xinerama monitors from topmost to bottommost

GRAVITY

When the -z option is used, the image is zoomed in to fill the screen and cropped if neccessary. The --gravity-x and --gravity-y parameters let you choose the 'gravity center' of the image: setroot will try to match that center with the display center if possible.

Both parameters can be given in two formats, both relative to the image dimensions: as an integer, which means an absolute coordinate; or as a decimal percentage of the total width or height.

FILES

setroot creates the directory "${XDG_CONFIG_HOME:-$HOME/.config}/setroot" and places an executable file .setroot-restore there when setroot --store is invoked for the first time.

setroot --restore uses this file to restore the most recent (valid) invocation of setroot.

AUTHOR

© 2016 Tim Zhou <ttzhou@uwaterloo.ca>

ACKNOWLEDGMENTS

set_pixmap_property() is © 1998 Michael Jennings <mej@eterm.org>

find_desktop() is a modification of get_desktop_window() © 2004-2012 Jonathan Koren <jonathan@jonathankoren.com>