07 Jul 2019 07:25:04 UTC
- Distribution: X11-Protocol-Other
- Module version: 31
- Source (raw)
- Browse (raw)
- How to Contribute
- Issues (0)
- Testers (190 / 1 / 0)
- KwaliteeBus factor: 1
- 37.74% Coverage
- License: gpl_3
- Perl: v5.4.0
- Activity24 month
- Download (265.1KB)
- MetaCPAN Explorer
- Subscribe to distribution
- This version
- Latest versionKRYDE Kevin Rydeand 1 contributors
- Kevin Ryde
- Virtual Root
- ROOT WINDOW PROPERTIES
- SEE ALSO
- HOME PAGE
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 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
$pixmapand 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
Allocated pixel colours (in
PseudoColoretc) and any
use_esetrootpreserve pixels and the pixmap with
SetCloseDownMode ('RetainPermanent')and leave root window properties
ESETROOT_PMAP_IDready to released by a
KillClient()in a future background change.
In these cases the
$Xconnection cannot be used any more since a further background change and consequent
KillClient()could occur at any time, perhaps immediately.
pixmapis given then if it contains any allocated pixels (
AllocColor()etc) then this should be indicated with the
pixmap_allocated_colorsoption. (Allocated pixels are noticed automatically for
# 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
$Xconnection 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::Protocolhad 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 (
TrueColoretc) then there's no colour allocation as such (
AllocColor()is just a lookup). In this case
set_background()knows there's no need for
RetainPermanentfor colours, only for pixmaps.
pixeloptions are the screen
white_pixelthen those pixels exist permanently in the root colormap and
set_background()knows there's no need to
RetainPermanentfor them. If the server has the TOG-CUP extension (see X11::Protocol::Ext::TOG_CUP) then any permanent pixels there are recognised too.
root_to_virtual_root()and acts on that when applicable. Such a virtual root is used by
tvtwmwindow managers and the
The enlightenment window manager, however, uses a background window covering the root window. This stops most root window programs from working, including XSetRoot here.
Esetrootprogram and various compatible programs such as
fvwm-rootuse a separate set of properties from what
Esetrootmethod 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).
Esetrootstyle rather than the default
xsetrootstyle. It can be used with the
coloroptions 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
Esetrootproperties since both are superseded by a new background.
For reference, to use
Eterm --trans(as of its version 0.9.6 March 2011) an
Esetrootbackground should be present when
Etermstarts and it should not be removed later (and not set to "None").
Etermwon't notice an initial
Esetrootwhile it's running. This means do an
Etermand then do all future background changes in
The advantage of the
Esetrootmethod 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
xsetrootstyle 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.
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
Xconnection object, or a
displayname to connect to, or the default is the
The root window is given by
screen, or the default is the default screen in
$X->choose_screen()or the default from the display name.
The background to show is given by a colour name, pixel value, or pixmap.
colorcan be anything understood by the server
AllocNamedColor(), plus 1 to 4 digit hex
blue named colours #RGB hex digits #RRGGBB #RRRGGGBBB #RRRRGGGGBBBB
pixelis 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).
pixmapis 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_colorsshould be true if any of the pixels in
pixmapwere allocated with
AllocColor()etc, as opposed to just the screen pre-defined black and white pixels (and any TOG-CUP permanent pixels).
use_esetrootmeans use the root window properties in the style of
Esetroot. This allows programs such as
Etermto 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_IDmechanism described above means the
$Xconnection could be killed by another
xsetrootat any time, perhaps immediately, and for that reason
$Xshould not be used any more. The easiest way is to make
set_background()the last thing done on
Setting an allocated
pixmapcan only be done on a
$Xconnection as such, not with the
displayoption. This is because retaining the colours with the
_XSETROOT_IDmechanism can only be done from the client connection which created the resources, not a new separate client connection.
xsetroot, if colours in the root window background are allocated by
_XSETROOT_IDis a pixmap XID which can be killed by
KillClient()to free those colours when the root background is replaced.
_XSETROOT_IDis only a 1x1 dummy pixmap, it's not the actual root background pixmap.
Esetrootstyle, this is the current root window background pixmap. It might be set by an
Esetrootwhich 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
PropertyNotifyon 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.
Esetrootstyle, this is the same as
_XROOTPMAP_IDif that pixmap was created by
Esetrootand 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_IDonly when equal to
_XROOTPMAP_ID. Probably it's safer to always kill
ESETROOT_PMAP_IDif replacing its value, to be sure of not leaking resources. But perhaps if both
_XROOTPMAP_IDexist then they are always equal.
The default X server.
/etc/X11/rgb.txt on the server, being the usual colour names database for the
See examples/view-root.pl for a simple program to display the root window contents.
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/>.
Module Install Instructions
To install X11::Protocol::Other, copy and paste the appropriate command in to your terminal.
perl -MCPAN -e shell install X11::Protocol::Other
For more information on module installation, please visit the detailed CPAN module installation guide.