1X11::Protocol::XSetRootU(s3e)r Contributed Perl DocumentaXt1i1o:n:Protocol::XSetRoot(3)
2
3
4

NAME

6       X11::Protocol::XSetRoot -- set root window background
7

SYNOPSIS

9        use X11::Protocol::XSetRoot;
10        X11::Protocol::XSetRoot->set_background (color => 'green');
11
12        # 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

DESCRIPTION

19       This module sets the X root window background in the style of the
20       "xsetroot" program.
21
22       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
26           X11::Protocol::XSetRoot->set_background
27                                      (color => 'green');
28
29           X11::Protocol::XSetRoot->set_background
30                                      (color => '#FF0000'); # red
31
32       A pattern can be set with a pixmap.  A pixmap the size of the screen
33       can give a full background picture.
34
35           # 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
41       set_background() takes ownership of the given $pixmap and frees it with
42       FreePixmap() once put into the window background.
43
44       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
48   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
55       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
59       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
64           # 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
72       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
79       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
84       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

Virtual Root

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
97       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

Esetroot

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
108       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
113       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
117       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
124       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
130       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

FUNCTIONS

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
141               X        => X11::Protocol object
142               display  => string ":0.0" etc
143
144               screen   => integer, eg. 0
145               root     => XID of root window
146
147               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
153           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
157           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
161           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
165               blue              named colours
166               #RGB              hex digits
167               #RRGGBB
168               #RRRGGGBBB
169               #RRRRGGGGBBBB
170
171           "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
176           "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
181           "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
186           "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
190           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
197           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

ROOT WINDOW PROPERTIES

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
211       "_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
217           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
224       "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
230           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

ENVIRONMENT

239       "DISPLAY"
240           The default X server.
241

FILES

243       /etc/X11/rgb.txt on the server, being the usual colour names database
244       for the "color" option above.
245

SEE ALSO

247       X11::Protocol, X11::Protocol::Ext::TOG_CUP
248
249       xsetroot(1), Esetroot(1), Eterm(1), fvwm-root(1)
250
251       <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
255       See examples/view-root.pl for a simple program to display the root
256       window contents.
257

HOME PAGE

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

LICENSE

262       Copyright 2010, 2011, 2012, 2013, 2014, 2017 Kevin Ryde
263
264       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
269       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
274       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/>.
276
277
278
279perl v5.38.0                      2023-07-21        X11::Protocol::XSetRoot(3)
Impressum