X11::Protocol::XSetRoot -- set root window background
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);
This module sets the X root window background in the style of the
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
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
If a pixmap has pixels allocated with
AllocColor() etc then this should be indicated with the
# 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
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
Also, if the
color given results in the screen
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.
XSetRoot looks for
root_to_virtual_root() and acts on that when applicable. Such a virtual root is used by
tvtwm window managers, and as used the
The enlightenment window manager uses a background window covering the root window. This stops most root window programs from working, including XSetRoot here.
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
screen, or otherwise the current
$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
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.
/etc/X11/rgb.txt on the server, being the usual colour names database for the
color option above.
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/>.