/ 
X11-Protocol-Other-24
/ 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 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 $pixmap with $X->black_pixel and $X->white_pixel,
# then set it with
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.

Setting a pixmap drawn by an application is the main use for this module. If you just 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,

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

The way colour retention is done means that the $X connection cannot be used any more in this case. 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 then that could be done here and a closed connection would indicate it cannot be used.

Allocated colours in the root colormap are preserved using SetCloseDownMode('RetainPermanent') and 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 that property is set, 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 or pixel options are 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 root_to_virtual_root() from X11::Protocol::WM and acts on that when applicable. Such a virtual root is used by amiwm, swm and tvtwm window managers and 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.

Esetroot

The Esetroot program and various compatible programs such as fvwm-root put their pixmap in properties _XROOTPMAP_ID and ESETROOT_PMAP_ID. These are deleted by set_background() since any pixmap there will no longer be the root pixmap.

set_background() does a KillClient() on the ESETROOT_PMAP_ID. Esetroot uses RetainPermanent to preserve the root pixmap and leaves ESETROOT_PMAP_ID ready to be killed to free that pixmap when replaced.

This _XROOTPMAP_ID style allows client programs to read the root window background to copy and manipulate for pseudo-transparency or other purposes. There's nothing yet for set_background() to store a pixmap this way.

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 the default is the default screen in $X either as set by $X->choose_screen() or from the display name.

The background to show is given by a colour name, pixel value, or 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 immediately, and so should not be used any more. The easiest way 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 with 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

Esetroot(1), fvwm-root(1)

HOME PAGE

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

LICENSE

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