/ 
X11-Protocol-Other-17
/ X11::Protocol::XSetRoot

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() 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 complete background picture with a big 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 works 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 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() to free those pixels. This kill could happen any time after setting, 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 never any need for RetainPermanent.

Also if the color given results in the screen black_pixel or white_pixel then there's no a RetainPermanent since those pixels are fixed 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.

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, otherwise 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"
"#RGB"
"#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 or 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 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 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/>.