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, X11::Protocol::Ext::TOG_CUP

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/>.

cpanm X11::Protocol::Other

perl -MCPAN -e shell
install X11::Protocol::Other