X11::P...SetRoot(3pm)

📦
version 31 · 7 versions
, in debian bookworm, debian trixie, ubuntu jammy, ubuntu noble

💖 X11::P...SetRoot(3pm) 💖

okay bestie, this is the manual page for X11::P...SetRoot(3pm) from User Contributed Perl Documentation. no cap, it's literally the page that tells you how to set the X root window background, and it's giving main character energy. let's get into it. 🫶

✨ NAME ✨

X11::Protocol::XSetRoot — set that root window background, periodt.

📜 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 🌸

so this module sets the X root window background, exactly like the xsetroot program does. it's giving the same vibe, just from Perl. ✨

the simplest way to use it? a named colour that the server's usual AllocNamedColor() understands, or a 1 to 4 digit hex string like #RRGGBB or #RRRRGGGGBBBB. easy peasy. 💅

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

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

you can also set a pattern with a pixmap. a pixmap the size of the screen? that's a full background picture, bestie. 🖼️

           # 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 $pixmap you give it and frees it with FreePixmap() once it's put into the window background. so don't you dare free it yourself. 🙈

setting the root to a pixmap drawn by a program is literally the main use for this module. if you just want a solid colour, honestly the actual xsetroot program can do that easily enough. no need to flex here. 💁

🧚 Retained Resources 🧚

allocated pixel colours (like in PseudoColor etc) and any use_esetroot preserve pixels and the pixmap with SetCloseDownMode ('RetainPermanent'). they leave root window properties _XSETROOT_ID or ESETROOT_PMAP_ID ready to be released by a KillClient() in a future background change. it's giving resource retention, iykyk. 🔥

in these cases, the $X connection cannot be used any more. because a further background change and consequent KillClient() could happen at any time, maybe immediately. so like, don't touch it. 💀

if you pass a pixmap and it contains any allocated pixels (AllocColor() etc), you must indicate that with the pixmap_allocated_colors option. (for pixel and color options, allocated pixels are noticed automatically, so you're covered there.)

           # 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 the $X connection immediately after a set_background(). maybe someday there'll be a return value that says whether a retain was done, so you know the connection can't be used again. or maybe in the future, if X11::Protocol had an explicit $X->close(), that could be done here, and a closed connection would show it can't be used further. wishlist vibes. 🌈

if the root visual is static (TrueColor etc) then there's no colour allocation as such — AllocColor() is just a lookup. in that case, set_background() knows there's no need for RetainPermanent for colours, only for pixmaps. smart, right? 🧠

if the color or pixel options are the screen's black_pixel or white_pixel, those pixels already exist permanently in the root colormap, so set_background() knows there's no need to RetainPermanent for them. and if the server has the TOG-CUP extension (check out X11::Protocol::Ext::TOG_CUP), any permanent pixels there are recognised too. periodt. 💅

🦋 Virtual Root 🦋

XSetRoot looks for __SWM_VROOT using X11::Protocol::WM's root_to_virtual_root() and acts on that when applicable. this kind of virtual root is used by amiwm, swm and tvtwm window managers, plus the xscreensaver program. so if you're running those, you're covered. ✨

but the enlightenment window manager? it uses a background window covering the root window, which stops most root window programs from working — including XSetRoot here. so that's a thing. 😭

🍓 Esetroot 🍓

the Esetroot program and various compatible programs like fvwm-root use a separate set of properties from what xsetroot uses. the Esetroot method records the root pixmap, ready for programs like Eterm to use — for example, to implement pseudo-transparency (that's Eterm --trans, which this method was literally designed for). 💖

the set_background() option use_esetroot uses the Esetroot style instead of the default xsetroot style. you can use it with the pixel or color options too, and in that case set_background() makes a 1x1 pixmap to give a solid colour. tiny but mighty. 🎀

set_background() always deletes and kills (as appropriate) both the xsetroot and Esetroot properties, because both are superseded by a new background. no leftovers. 🧹

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 definitely not set to None). Eterm won't notice an initial Esetroot while it's running. so that means: do an Esetroot before running Eterm, then do all future background changes in Esetroot style. write that down. 📝

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, it can appear semi-transparent. this doesn't require the SHAPE extension, and it allows visual effects like shading or dithering too. iconic. 👑

for comparison, the xsetroot style means the root pixmap is not available to client programs. in principle, that lets the server apply it to the hardware and never refer to it again. in practice, that might not happen — for example, if multiple console virtual terminals mean the server has to give up the hardware when you switch away. so it's not always that simple. 🤷

💅 FUNCTIONS 💅

X11::Protocol::XSetRoot->set_background (key=>value, ...) — sets the root window background to a pixmap or colour. here are the key/value parameters you can pass, bestie:

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. if you don't give either, the default is the DISPLAY environment variable. easy. 🌟

the root window is given by root or screen. if neither, the default is the default screen in $X, either per $X->choose_screen() or the default from the display name. you got this. 💪

the background to show is given by a colour name, pixel value, or pixmap. color can be anything the server's AllocNamedColor() understands, plus 1 to 4 digit hex. here's the menu:

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's pre-defined black or white and TOG-CUP reserved pixels are permanent, so they're reckoned not allocated. so you don't have to worry. 😌

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. retro. 🖤🤍

pixmap_allocated_colors should be true if any of the pixels in pixmap were allocated with AllocColor() etc, as opposed to just the screen's pre-defined black and white pixels (and any TOG-CUP permanent pixels). so be honest. 🙈

use_esetroot means use the root window properties in the style of Esetroot. this lets programs like Eterm use the root background for pseudo-transparency or in other creative ways. the possibilities are endless. 🌈

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 — maybe immediately. for that reason, $X should not be used any more. the easiest way is to make set_background() the last thing you do on $X. like, literally the last thing. 💀

setting an allocated pixel or any pixmap can only be done on a $X connection as such, not with the display option. why? because retaining the colours with the _XSETROOT_ID mechanism can only be done from the client connection that created the resources, not from a new separate client connection. rules are rules. 🤷‍♀️

🔮 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. and just so you know: _XSETROOT_ID is only a 1x1 dummy pixmap, it's not the actual root background pixmap. it's a placeholder, bestie. 🎀

_XROOTPMAP_ID — for Esetroot style, this is the current root window background pixmap. it might be set by an Esetroot that has run and exited, or it might be set by a window manager or similar that's still running. so it can be a ghost or a current thing. 👻

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: 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. don't panic. 🧘

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. keep it tidy. 🧹

the specification <http://www.eterm.org/docs/view.php?doc=ref#trans> advises killing ESETROOT_PMAP_ID only when it's equal to _XROOTPMAP_ID. probably it's safer to always kill ESETROOT_PMAP_ID if you're replacing its value, just to be sure you're not leaking resources. but maybe if both ESETROOT_PMAP_ID and _XROOTPMAP_ID exist, they're always equal? just a thought. 🤔

🌍 ENVIRONMENT 🌍

DISPLAY — the default X server. that's it. that's the whole environment section. 💖

📁 FILES 📁

/etc/X11/rgb.txt on the server — the usual colour names database for the color option above. so that's where the named colours live. 🌈

✨ SEE ALSO ✨

ok so if you wanna go deeper (and bestie, you know you do 💅), go peek at:

  • X11::Protocol — the whole entire main character of this universe
  • X11::Protocol::Ext::TOG_CUP — the extension buddy that hangs with it

and for the OG command-line girlies who do this stuff without Perl:

and some links, because of course 📚:

also!! there's examples/view-root.pl — a lil simple program that shows you what's actually in your root window. it's giving tutorial energy, fr fr 🫶

🏠 HOME PAGE 🏠

the whole thing lives here:

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

go say hi, it's iconic 👑

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

translation for the girlies who don't speak Legalese: it's free, it's GPL v3-or-later, you can share it and remix it — just keep it free, don't blame Kevin if it breaks, and if you never got a copy of the license with it, the link above has you covered 💖

and that's a wrap on the whole page, bestie!! 🌸 this one shipped as part of perl v5.28.1, dated 2019-08-26, filed under X11::P...SetRoot(3pm). no cap, that's the whole vibe — now go set some root windows and slay 💅✨🎀

📦 where this page comes from