1X11::Protocol::XSetRootU(s3e)r Contributed Perl DocumentaXt1i1o:n:Protocol::XSetRoot(3)
2
6 X11::Protocol::XSetRoot -- set root window background
7
9 use X11::Protocol::XSetRoot;
10 X11::Protocol::XSetRoot->set_background (color => 'green');
11 # or given $X, but which then can't be used any more
13 X11::Protocol::XSetRoot->set_background
14 (X => $X,
15 pixmap => $pixmap_xid,
16 pixmap_allocated_colors => 1);
17
19 This module sets the X root window background in the style of the
20 "xsetroot" program.
21 The simplest use is a named colour interpreted by the server's usual
23 AllocNamedColor() or a 1 to 4 digit hex string like "#RRGGBB" or
24 "#RRRRGGGGBBBB".
25 X11::Protocol::XSetRoot->set_background
27 (color => 'green');
28 X11::Protocol::XSetRoot->set_background
30 (color => '#FF0000'); # red
31 A pattern can be set with a pixmap. A pixmap the size of the screen
33 can give a full background picture.
34 # draw $pixmap with say $X->black_pixel and $X->white_pixel,
36 # then set it with
37 X11::Protocol::XSetRoot->set_background
38 (X => $X,
39 pixmap => $pixmap);
40 set_background() takes ownership of the given $pixmap and frees it with
42 FreePixmap() once put into the window background.
43 Setting the root to a pixmap drawn by a program is the main use for
45 this module. If you just want a solid colour then that can be done
46 easily enough with the actual "xsetroot" program.
47 Retained Resources
49 Allocated pixel colours (in "PseudoColor" etc) and any "use_esetroot"
50 preserve pixels and the pixmap with "SetCloseDownMode
51 ('RetainPermanent')" and leave root window properties "_XSETROOT_ID" or
52 "ESETROOT_PMAP_ID" ready to released by a KillClient() in a future
53 background change.
54 In these cases the $X connection cannot be used any more since a
56 further background change and consequent KillClient() could occur at
57 any time, perhaps immediately.
58 If a "pixmap" is given then if it contains any allocated pixels
60 (AllocColor() etc) then this should be indicated with the
61 "pixmap_allocated_colors" option. (Allocated pixels are noticed
62 automatically for "pixel" and "color" options.)
63 # AllocColor colours, draw $pixmap with them, then
65 #
66 X11::Protocol::XSetRoot->set_background
67 (X => $X,
68 pixmap => $pixmap,
69 pixmap_allocated_colors => 1);
70 # don't use $X any more
71 The easiest thing is to close an $X connection immediately after a
73 set_background(). Perhaps there could be a return value to say whether
74 a retain was done and thus the connection cannot be used again. Or
75 perhaps in the future if "X11::Protocol" had an explicit "$X->close()"
76 then that could be done here so a closed connection would indicate it
77 cannot be used further.
78 If the root visual is static ("TrueColor" etc) then there's no colour
80 allocation as such (AllocColor() is just a lookup). In this case
81 set_background() knows there's no need for "RetainPermanent" for
82 colours, only for pixmaps.
83 If the "color" or "pixel" options are the screen "black_pixel" or
85 "white_pixel" then those pixels exist permanently in the root colormap
86 and set_background() knows there's no need to "RetainPermanent" for
87 them. If the server has the TOG-CUP extension (see
88 X11::Protocol::Ext::TOG_CUP) then any permanent pixels there are
89 recognised too.
90
92 "XSetRoot" looks for "__SWM_VROOT" using X11::Protocol::WM
93 root_to_virtual_root() and acts on that when applicable. Such a
94 virtual root is used by "amiwm", "swm" and "tvtwm" window managers and
95 the "xscreensaver" program.
96 The enlightenment window manager, however, uses a background window
98 covering the root window. This stops most root window programs from
99 working, including XSetRoot here.
100
102 The "Esetroot" program and various compatible programs such as
103 "fvwm-root" use a separate set of properties from what "xsetroot" uses.
104 The "Esetroot" method records the root pixmap ready for use by programs
105 such as "Eterm", eg. to implement pseudo-transparency (its "Eterm
106 --trans", which the method was designed for).
107 The set_background() option "use_esetroot" uses the "Esetroot" style
109 rather than the default "xsetroot" style. It can be used with the
110 "pixel" or "color" options too and in that case set_background() makes
111 a 1x1 pixmap to give a solid colour.
112 set_background() always deletes and kills (as appropriate) both the
114 "xsetroot" and "Esetroot" properties since both are superseded by a new
115 background.
116 For reference, to use "Eterm --trans" (as of its version 0.9.6 March
118 2011) an "Esetroot" background should be present when "Eterm" starts
119 and it should not be removed later (and not set to "None"). "Eterm"
120 won't notice an initial "Esetroot" while it's running. This means do
121 an "Esetroot" before running "Eterm" and then do all future background
122 changes in "Esetroot" style.
123 The advantage of the "Esetroot" method is that the root pixmap is
125 available for client programs to use in creative ways. If the client
126 draws some of the root pixmap as its own background then it can appear
127 semi-transparent. This doesn't require the SHAPE extension and allows
128 visual effects like shading or dithering too.
129 For comparison, the "xsetroot" style means the root pixmap is not
131 available to client programs. In principle that allows the server to
132 apply it to the hardware and never refer to it again. In practice that
133 might not occur, for example if multiple console "virtual terminals"
134 mean the server must give up the hardware when switched away.
135
137 "X11::Protocol::XSetRoot->set_background (key=>value, ...)"
138 Set the root window background to a pixmap or colour. The
139 key/value parameters are
140 X => X11::Protocol object
142 display => string ":0.0" etc
143 screen => integer, eg. 0
145 root => XID of root window
146 color => string
148 pixel => integer pixel value
149 pixmap => XID of pixmap to display, or "None"
150 pixmap_allocated_colors => boolean, default false
151 use_esetroot => boolean, default false
152 The server is given by an "X" connection object, or a "display"
154 name to connect to, or the default is the "DISPLAY" environment
155 variable.
156 The root window is given by "root" or "screen", or the default is
158 the default screen in $X either per "$X->choose_screen()" or the
159 default from the display name.
160 The background to show is given by a colour name, pixel value, or
162 pixmap. "color" can be anything understood by the server
163 AllocNamedColor(), plus 1 to 4 digit hex
164 blue named colours
166 #RGB hex digits
167 #RRGGBB
168 #RRRGGGBBB
169 #RRRRGGGGBBBB
170 "pixel" is an integer pixel value in the root window colormap.
172 It's automatically recognised as allocated or not (the screen pre-
173 defined black or white and TOG-CUP reserved pixels are permanent
174 and so reckoned not allocated).
175 "pixmap" is an XID integer. set_background() takes ownership of
177 this pixmap and will FreePixmap() once installed. "None" or 0
178 means no pixmap, which gives the server's default root background
179 (usually a black and white weave pattern).
180 "pixmap_allocated_colors" should be true if any of the pixels in
182 "pixmap" were allocated with AllocColor() etc, as opposed to just
183 the screen pre-defined black and white pixels (and any TOG-CUP
184 permanent pixels).
185 "use_esetroot" means use the root window properties in the style of
187 "Esetroot". This allows programs such as "Eterm" to use the root
188 background for "pseudo-transparency" or in other creative ways.
189 When an allocated pixel or a pixmap with allocated pixels is set as
191 the background the "_XSETROOT_ID" mechanism described above means
192 the $X connection could be killed by another "xsetroot" at any
193 time, perhaps immediately, and for that reason $X should not be
194 used any more. The easiest way is to make set_background() the
195 last thing done on $X.
196 Setting an allocated "pixel" or any "pixmap" can only be done on a
198 $X connection as such, not with the "display" option. This is
199 because retaining the colours with the "_XSETROOT_ID" mechanism can
200 only be done from the client connection which created the
201 resources, not a new separate client connection.
202
204 "_XSETROOT_ID"
205 For "xsetroot", if colours in the root window background are
206 allocated by AllocColor() etc then "_XSETROOT_ID" is a pixmap XID
207 which can be killed by KillClient() to free those colours when the
208 root background is replaced. "_XSETROOT_ID" is only a 1x1 dummy
209 pixmap, it's not the actual root background pixmap.
210 "_XROOTPMAP_ID"
212 For "Esetroot" style, this is the current root window background
213 pixmap. It might be set by an "Esetroot" which has run and exited,
214 or it might be set by a window manager or similar which is still
215 running.
216 Client programs can use this to combine the root background into
218 their own window in interesting ways. Listen to "PropertyNotify"
219 on the root window for changes to "_XROOTPMAP_ID". Note that this
220 pixmap belongs to another client so it could be freed at any time.
221 Protocol errors when copying or drawing from it should generally be
222 ignored, or cause a fallback to some default.
223 "ESETROOT_PMAP_ID"
225 For "Esetroot" style, this is the same as "_XROOTPMAP_ID" if that
226 pixmap was created by "Esetroot" and saved by
227 SetCloseDownMode('RetainPermanent'). This should be freed by
228 KillClient() if the background is replaced.
229 The specification
231 <http://www.eterm.org/docs/view.php?doc=ref#trans> advises killing
232 "ESETROOT_PMAP_ID" only when equal to "_XROOTPMAP_ID". Probably
233 it's safer to always kill "ESETROOT_PMAP_ID" if replacing its
234 value, to be sure of not leaking resources. But perhaps if both
235 "ESETROOT_PMAP_ID" and "_XROOTPMAP_ID" exist then they are always
236 equal.
237
239 "DISPLAY"
240 The default X server.
241
243 /etc/X11/rgb.txt on the server, being the usual colour names database
244 for the "color" option above.
245
247 X11::Protocol, X11::Protocol::Ext::TOG_CUP
248 xsetroot(1), Esetroot(1), Eterm(1), fvwm-root(1)
250 <http://www.eterm.org/docs/view.php?doc=ref#trans>
252 <http://www.eterm.org/doc/Eterm_reference.html#trans>
253 <file:///usr/share/doc/eterm/Eterm_reference.html#trans>
254 See examples/view-root.pl for a simple program to display the root
256 window contents.
257
259 <http://user42.tuxfamily.org/x11-protocol-other/index.html>
260
262 Copyright 2010, 2011, 2012, 2013, 2014, 2017 Kevin Ryde
263 X11-Protocol-Other is free software; you can redistribute it and/or
265 modify it under the terms of the GNU General Public License as
266 published by the Free Software Foundation; either version 3, or (at
267 your option) any later version.
268 X11-Protocol-Other is distributed in the hope that it will be useful,
270 but WITHOUT ANY WARRANTY; without even the implied warranty of
271 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
272 General Public License for more details.
273 You should have received a copy of the GNU General Public License along
275 with X11-Protocol-Other. If not, see <http://www.gnu.org/licenses/>.
276perl v5.38.0 2023-07-21 X11::Protocol::XSetRoot(3)