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

Provided by: libx11-protocol-other-perl_28-1_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 and any "use_esetroot" preserve pixels and pixmap with
       "SetCloseDownMode('RetainPermanent')" and leave root window properties "_XSETROOT_ID" or
       "ESETROOT_PMAP_ID" ready to released by "KillClient()" at 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 so the
       connection cannot be used again.  Or perhaps if in the future "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 such as "TrueColor" 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
       for "RetainPermanent".  Similarly if the server has the TOG-CUP extension (see
       X11::Protocol::Ext::TOG_CUP) then any reserved pixels listed there are recognised as
       permanent.

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.

       Alas 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" use different
properties than "xsetroot". The "Esetroot" method records the root pixmap ready for use
by programs such as "Eterm", for example to implement pseudo-transparency ("Eterm
--trans", which is what the method was designed for).

The "set_background()" option "use_esetroot" uses the "Esetroot" style rather than the
default "xsetroot" style. If this is given with "pixel" or "color" options then
"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 at "Eterm" startup and should not be removed later (or set to
"None"). It doesn't notice a later "Esetroot" or re-install. In practice this means
"Esetroot" before running "Eterm" and then 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 without the SHAPE extension, and perhaps do
some visual effects like shading or dithering.

For comparison the "xsetroot" style means the root pixmap is not available to client
programs and therefore in principle allows the server to apply it to the hardware and
never refer to it again. In practice that might not occur, if for example on multiple
console "virtual terminals" 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 background
changes. Note that since this pixmap belongs to another client it could be freed at
any time, so 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 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/>.