NAME

X11::Protocol::XSetRoot -- set root window background

SYNOPSIS

 use X11::Protocol::XSetRoot;
 X11::Protocol::XSetRoot->set_background (color => 'green');

 # or given $X, which then can't be used any more
 X11::Protocol::XSetRoot->set_background
                            (X       => $X,
                             pixmap  => $pixmap_xid,
                             pixmap_allocated_colors => 1);

DESCRIPTION

This module sets the X root window background in the style of the xsetroot program.

The simplest use is a named colour, or a 1 to 4 digit hex string like "#RRGGBB" or "#RRRRGGGGBBBB". Named colours are per the server's usual AllocNamedColor etc.

    X11::Protocol::XSetRoot->set_background
                               (color => 'green');

    X11::Protocol::XSetRoot->set_background
                               (color => '#FF0000'); # red

A pattern can be set with a pixmap or a big pixmap the size of the whole screen.

    # draw $pixmap with black_pixel and white_pixel ...
    X11::Protocol::XSetRoot->set_background
                               (X      => $X,
                                pixmap => $pixmap);

set_background takes over ownership of the given $pixmap and frees it with FreePixmap once put into the window background. Setting an application drawn pixmap is the main use for this module. A solid colour can be simply by running the actual xsetroot program.

Allocated Pixels

If the pixmap has pixels allocated with AllocColor etc then this should be indicated with the pixmap_allocated_colors option,

    # draw $pixmap with AllocColor colours
    X11::Protocol::XSetRoot->set_background
                               (X      => $X,
                                pixmap => $pixmap,
                                pixmap_allocated_colors => 1);
    # don't use $X any more

The way allocated colour retention works means the $X connection cannot be used any more in this case, or if the color or pixel options are an allocated colour (anything except the X root colormap black_pixel and white_pixel).

Allocated colours are preserved in the root colormap using SetCloseDownMode RetainPermanent and a client XID recorded in the _XSETROOT_ID property on the root window. A subsequent xsetroot or compatible program does a KillClient to free the pixels. This can happen any time after setting, perhaps immediately.

If the root visual is static such as TrueColor then an AllocColor is just a lookup, not an actual allocation. On a static visual set_background skips the RetainPermanent and _XSETROOT_ID.

The easiest thing is to close an $X connection immediately after a set_background. Perhaps there could be a return value to say whether a retain was done and the connection cannot be used again. Or if in the future there's an explicit $X->close of some sort then that could be used here, and would indicate whether the connection is still good.

FUNCTIONS

X11::Protocol::XSetRoot->set_background (key=>value, ...)

Set the root window background to a pixmap or a pixel. The key/value parameters are

    X        => X11::Protocol object
    display  => string ":0:0" etc

    screen   => integer, eg. 0
    root     => XID of root window

    color    => string
    pixel    => integer pixel value
    pixmap   => XID of pixmap to display
    pixmap_allocated_colors => boolean, default false

The server is given by an X connection object , or a display name to connect to, otherwise the DISPLAY environment variable.

The root window is given by root or screen, or otherwise the current "chosen" screen on $X, or the screen part of the display name.

The background to show is given by a colour name or pixel, or a pixmap. color can be anything understood by the server AllocNamedColor, plus 1 to 4 digit hex like "#RGB" or "#RRRRGGGGBBBB".

pixel is an integer pixel value in the root window colormap. It's automatically recognised as allocated or not -- anything except the screen pre-defined black or white pixel value is allocated.

pixmap is an XID integer. set_background takes ownership of this pixmap and will FreePixmap once installed. "None" or 0 means no pixmap, which gives the server's default root background (usually a black and white weave pattern).

pixmap_allocated_colors should be true if any of the pixels in pixmap were allocated with AllocColor etc, as opposed to just the screen pre-defined black and white pixels.

When an allocated pixel or a pixmap with allocated pixels is set as the background the _XSETROOT_ID mechanism described above means the $X connection could be killed by another xsetroot at any time, so should not be used any more. The easiest thing is to make set_background the last thing done on $X.

Setting a pixel or pixmap can only be done on an X connection as such, not from the display option. This is because retaining the colours with the _XSETROOT_ID mechanism can only be done from the client connection which created them, not a new connection.

FILES

/etc/X11/rgb.txt on the server, the usual colour names database for the color option here.

SEE ALSO

xsetroot(1)

HOME PAGE

http://user42.tuxfamily.org/x11-protocol-other/index.html

LICENSE

Copyright 2010, 2011 Kevin Ryde

X11-Protocol-Other is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 3, or (at your option) any later version.

X11-Protocol-Other is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with X11-Protocol-Other. If not, see <http://www.gnu.org/licenses/>.

cpanm X11::Protocol::Other

perl -MCPAN -e shell
install X11::Protocol::Other