NAME

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

SYNOPSIS

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

 # or given $X, but 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 interpreted by the server's usual AllocNamedColor().

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

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

A pattern can be set with a pixmap. A complete background picture can be set with a pixmap the size of the whole screen.

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

set_background() takes ownership of the given $pixmap and frees it with FreePixmap once put into the window background.

Putting an application drawn pixmap into the background is the main uses for this module. If you want a solid colour then that can be done easily enough by running the actual xsetroot program.

Allocated Pixels

If a 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 is done means that the $X connection cannot be used any more in this case, and likewise if the color or pixel options are an allocated colour.

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 perhaps 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.

Allocated colours in the root colormap are preserved using SetCloseDownMode('RetainPermanent') and putting a client XID in the _XSETROOT_ID property on the root window. A subsequent xsetroot or compatible program does a KillClient() on that XID to free the pixels. Such a kill could happen any time after stored, perhaps immediately.

For a static visual such as TrueColor there's no colour allocation (AllocColor() is just a lookup) and in that case set_background() knows there's no need for RetainPermanent.

Also, if the color given results in the screen black_pixel or white_pixel then there's no RetainPermanent since those pixels are permanent in the root colormap. If the server has the TOG-CUP extension (see X11::Protocol::Ext::TOG_CUP) then the reserved pixels it lists are treated similarly.

Virtual Root

XSetRoot looks for __SWM_VROOT using X11::Protocol::WM root_to_virtual_root() and acts on that when applicable. Such a virtual root is used by amiwm, swm and tvtwm window managers, and as used the xscreensaver program.

The enlightenment window manager uses a background window covering the root window. This stops most root window programs from working, including XSetRoot here.

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, or "None"
    pixmap_allocated_colors => boolean, default false

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

The root window is given by root or screen, or otherwise the current choose_screen() on $X, or the default screen coming from 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

    blue              named colours
    #RGB              hex digits
    #RRGGBB
    #RRRGGGBBB
    #RRRRGGGGBBBB

pixel is an integer pixel value in the root window colormap. It's automatically recognised as allocated or not (the screen pre-defined black or white and TOG-CUP reserved pixels).

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 (and any TOG-CUP reserved).

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, perhaps almost immediately, and 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 a $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 the resources, not a new separate client connection.

FILES

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

SEE ALSO

xsetroot(1), X11::Protocol, X11::Protocol::Ext::TOG_CUP

HOME PAGE

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

LICENSE

Copyright 2010, 2011, 2012 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