X11::Protocol::XSetRoot(3)
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.
SEE ALSO
X11::Protocol(3), X11::Protocol::Ext::TOG_CUP(3)
xsetroot(1), Esetroot(1), Eterm(1), fvwm-root(1)
<http://www.eterm.org/docs/view.php?doc=ref#trans>
<http://www.eterm.org/doc/Eterm_reference.html#trans>
<file:///usr/share/doc/eterm/Eterm_reference.html#trans>
See examples/view-root.pl for a simple program to display the root
window contents.
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.28.1 2017-04-06 X11::Protocol::XSetRoot(3)
x11-protocol-other 30 - Generated Tue Feb 19 13:16:09 CST 2019