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

Provided by: libx11-protocol-other-perl_31-1build1_all

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 interpreted by the server's usual AllocNamedColor() or a 1 to 4 digit
       hex string like "#RRGGBB" or "#RRRRGGGGBBBB".

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

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

       A pattern can be set with a pixmap.  A pixmap the size of the screen can give a full background picture.

           # draw $pixmap with say $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 the root to a pixmap drawn by a program is the main use for this module.  If you just want a
       solid colour then that can be done easily enough with the actual "xsetroot" program.

   Retained Resources
       Allocated pixel colours (in "PseudoColor" etc) and any "use_esetroot" preserve pixels and the pixmap with
       "SetCloseDownMode ('RetainPermanent')" and leave root window properties "_XSETROOT_ID" or
       "ESETROOT_PMAP_ID" ready to released by a KillClient() in a future background change.

       In these cases the $X connection cannot be used any more since a further background change and consequent
       KillClient() could occur at any time, perhaps immediately.

       If a "pixmap" is given then if it contains any allocated pixels (AllocColor() etc) then this should be
       indicated with the "pixmap_allocated_colors" option.  (Allocated pixels are noticed automatically for
       "pixel" and "color" options.)

           # 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 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 thus the connection cannot be used again.  Or
       perhaps in the future if "X11::Protocol" had an explicit "$X->close()" then that could be done here so a
       closed connection would indicate it cannot be used further.

       If the root visual is static ("TrueColor" etc) then there's no colour allocation as such (AllocColor() is
       just a lookup).  In this case set_background() knows there's no need for "RetainPermanent" for colours,
       only for pixmaps.

       If the "color" or "pixel" options are the screen "black_pixel" or "white_pixel" then those pixels exist
       permanently in the root colormap and set_background() knows there's no need to "RetainPermanent" for
       them.  If the server has the TOG-CUP extension (see X11::Protocol::Ext::TOG_CUP) then any permanent
       pixels there are recognised too.

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 the
       "xscreensaver" program.

       The enlightenment window manager, however, 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" use a separate set of
properties from what "xsetroot" uses. The "Esetroot" method records the root pixmap ready for use by
programs such as "Eterm", eg. to implement pseudo-transparency (its "Eterm --trans", which the method was
designed for).

The set_background() option "use_esetroot" uses the "Esetroot" style rather than the default "xsetroot"
style. It can be used with the "pixel" or "color" options too and in that case set_background() makes a
1x1 pixmap to give a solid colour.

set_background() always deletes and kills (as appropriate) both the "xsetroot" and "Esetroot" properties
since both are superseded by a new background.

For reference, to use "Eterm --trans" (as of its version 0.9.6 March 2011) an "Esetroot" background
should be present when "Eterm" starts and it should not be removed later (and not set to "None").
"Eterm" won't notice an initial "Esetroot" while it's running. This means do an "Esetroot" before
running "Eterm" and then do all future background changes in "Esetroot" style.

The advantage of the "Esetroot" method is that the root pixmap is available for client programs to use in
creative ways. If the client draws some of the root pixmap as its own background then it can appear
semi-transparent. This doesn't require the SHAPE extension and allows visual effects like shading or
dithering too.

For comparison, the "xsetroot" style means the root pixmap is not available to client programs. In
principle that allows the server to apply it to the hardware and never refer to it again. In practice
that might not occur, for example if multiple console "virtual terminals" mean the server must give up
the hardware when switched away.

FUNCTIONS

"X11::Protocol::XSetRoot->set_background (key=>value, ...)"
Set the root window background to a pixmap or colour. 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
use_esetroot => 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 per
"$X->choose_screen()" or the default 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 are permanent and
so reckoned not 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 (and any TOG-CUP
permanent pixels).

"use_esetroot" means use the root window properties in the style of "Esetroot". This allows programs
such as "Eterm" to use the root background for "pseudo-transparency" or in other creative ways.

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 for that reason $X should not be used any more. The easiest way is to make
set_background() the last thing done on $X.

Setting an allocated "pixel" or any "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.

ROOT WINDOW PROPERTIES

"_XSETROOT_ID"
For "xsetroot", if colours in the root window background are allocated by AllocColor() etc then
"_XSETROOT_ID" is a pixmap XID which can be killed by KillClient() to free those colours when the
root background is replaced. "_XSETROOT_ID" is only a 1x1 dummy pixmap, it's not the actual root
background pixmap.

"_XROOTPMAP_ID"
For "Esetroot" style, this is the current root window background pixmap. It might be set by an
"Esetroot" which has run and exited, or it might be set by a window manager or similar which is still
running.

Client programs can use this to combine the root background into their own window in interesting
ways. Listen to "PropertyNotify" on the root window for changes to "_XROOTPMAP_ID". Note that this
pixmap belongs to another client so it could be freed at any time. Protocol errors when copying or
drawing from it should generally be ignored, or cause a fallback to some default.

"ESETROOT_PMAP_ID"
For "Esetroot" style, this is the same as "_XROOTPMAP_ID" if that pixmap was created by "Esetroot"
and saved by SetCloseDownMode('RetainPermanent'). This should be freed by KillClient() if the
background is replaced.

The specification <http://www.eterm.org/docs/view.php?doc=ref#trans> advises killing
"ESETROOT_PMAP_ID" only when equal to "_XROOTPMAP_ID". Probably it's safer to always kill
"ESETROOT_PMAP_ID" if replacing its value, to be sure of not leaking resources. But perhaps if both
"ESETROOT_PMAP_ID" and "_XROOTPMAP_ID" exist then they are always equal.

ENVIRONMENT

       "DISPLAY"
           The default X server.

FILES

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

HOME PAGE

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

LICENSE

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

perl v5.40.1                                       2025-11-24                       X11::Protocol::XSetRoot(3pm)