asetroot(1.7.9)

NAME
asetroot - the AfterStep desktop background management module

SYNOPSIS
asetroot [-f config_file] [-v | --version] [-h | --help] [-l | --loadonly] [-k | --kill] [n [m]]

Although asetroot can be run from the command line, it is normally spawned by afterstep in the autoexec file, in the following manner:

	Module	"I"	asetroot
	Wait	"I"	asetroot

In case you use asetroot to switch your root backgrounds, Wait can be used as shown above. This will insure that the asetroot has set the root background before you start any further apps (like transparent aterms and Eterms).

This module can also be spawned from within an afterstep menu file:

% cat "~/GNUstep/Library/AfterStep/start/Modules/asetroot"
	Module "asetroot" asetroot
	MiniPixmap "mini-as.xpm"
To stop the asetroot module, a menu item can be used:

% cat "~/GNUstep/Library/AfterStep/start/Modules/asetroot_Stop"
	KillModuleByName "Stop asetroot" asetroot
	MiniPixmap "mini-as.xpm"
Note: if asetroot used with either -k(--kill) or -l(--loadonly) options it can be started both as a module or as regular app, as it does not communicate with AfterStep in that case. You can even add it to your .xinitrc to load X root background prior to starting the window manager.

DESCRIPTION
Depending on the options it is started with, asetroot can perform different tasks:

Normal mode: asetroot will load root backgrounds for specified range of desks into memory, set X property containing information allowing usage of this backgrounds by other modules/applications, and will remain resident, tracking desk changes and changing root background accordingly. It is recommended that you don't use any other apps to switch backgrounds in this mode for this particular range of desks.

Load-only mode: asetroot will load root backgrounds for specified range of desks into memory, and will set X property containing information allowing usage of this backgrounds by other modules/applications. It will then quit, leaving all the required images resident in X memory, leaving it to other apps to switch backgrounds (like Pager). That provides some memory savings, as you run only one module instead of two. Caveat : You should not run asetroot like that on screens other then first one, or whenever you use executable name other then "asetroot". This is related to the fact that Pager only knows about asetroot named as asetroot.

Kill mode: It's not good to litter the memory with multimegabyte images. You can use kill mode of asetroot to cleanup memory from loaded images when they are no longer needed, for example when quiting AfterStep, or when using same background on all desks (in that latter case it's enough to set background once and it will stay there forever). Kill mode will kill all backgrounds - you can't specify desks range here!

asetroot was designed to be as bulletproof as possible, but improper usage can lead it to cause crashes in AfterStep, Pager, Wharf and transparent aterms, if you are heavily using transparency features. By all means avoid running two different asetroots on the same range of desks, at the same time.

ENVIRONMENT VARIABLES

$SCREEN_GAMMA
    Value of this env variable is used to gamma-correct PNG and JPEG images, when loading them from files. Default value of 1.0 is used if this variable is not defined - which means no correction at all. Try using 2.2 for some older monitors to get brighter images.

OPTIONS

-f config_file
    Use config_file instead of the default configuration file.

-h | --help
    Print a usage message and exit successfully.

-v | --version
    Print version information and exit successfully.

-l | --loadonly
    asetroot starts in Load-only mode ( see above ).

-k | --kill
    asetroot starts in Kill mode ( see above ).

n [m]
    Optional parameter that is limiting asetroot functionality to range of desks. n - specifies lower desk number, m - upper desk number.

INITIALIZATION
During initialization, asetroot will search for a configuration file which describes the image operations to perform on the root pixmap. This file will be the one specified by the -f option (if given). Else, the ~/GNUstep/Library/AfterStep/asetroot file will be used if it exists. Else, /usr/local/share/afterstep/asetroot will be used.

CONFIGURATION OPTIONS

*asetrootDeskBack  desk# "background"
    Specifies what background to use for desk#. "background" can be either image filename in doublequotes, or the name of background definition (see below).

MyBackground "background_name"

background_option

~MyBackground
    Specifies the beginning of a background definition. The background can be referred to later by background_name. ~MyBackground ends a root background definition. The possible background_options follow:

    Use type  "data"
        Specifies what to use as the root background. Possible type values are :
        0: load image from the file. In that case ""data"" should specify
        filename.
        1: Use MyStyle definition to fill root. In that case ""data""
        should specify one of the MyStyle names defined in your look file.
        2: Use external application to set root background. ""data""
        should specify command line options to this external app. (asetroot
        is coded by default to use xli. If you wish to use another application
        to display the root background, you need to set the "--with-imageloader"
        flag to use that application then recompile AfterStep.)

        Note: remaining Background options are valid only for type of 0 !!!

        The remaining options will perform transformations on the source image, in this order: Cut->Tint->Scale->Align->Pad.

    Cut geometry
        will cut piece with specified geometry from the source image.

    Tint color
        will tint image with color. Use shades of gray to obtain darkened image. Note: this only works on TrueColor displays.

    Scale [geometry]
        scale image to specified geometry. If geometry is omitted asetroot will scale it to the screen size.

    Align [type]
        it will align resulting image according to type. Possible values are :
        1: - align to the right of the screen
        2: - align to the bottom of the screen
        3: - align to the bottom-right of the screen
        0 or 4: - align to the center of the screen
        This option works only in conjunction with the following Pad option.

    Pad [type color]
        will pad image if it is smaller then screen with specified color. Possible type values are :
        1: - pad horizontally and tile vertically
        2: - pad vertically and tile horizontally
        3: - pad both vertically and horizontally to make the image the
        size of the screen.

BUGS
SCALE produces low quality images.

AUTHOR
Rafal Wierzbicki
Sasha Vasko (asimagelib)

SEE ALSO
afterstep(1) Pager(1)