1X11::Protocol::Ext::XFIUXsEeSr(3C)ontributed Perl DocumeXn1t1a:t:iPornotocol::Ext::XFIXES(3)
2
6 X11::Protocol::Ext::XFIXES - miscellaneous "fixes" extension
7
9 use X11::Protocol;
10 my $X = X11::Protocol->new;
11 $X->init_extension('XFIXES')
12 or print "XFIXES extension not available";
13
15 The XFIXES extension adds some features which are conceived as "fixing"
16 omissions in the core X11 protocol, including
17 • Events for changes to the selection (the cut and paste between
19 clients).
20 • Current cursor image fetching, cursor change events, and cursor
22 naming and hiding.
23 • Server-side "region" objects representing a set of rectangles.
25
27 The following are made available with an init_extension() per
28 "EXTENSIONS" in X11::Protocol.
29 my $bool = $X->init_extension('XFIXES');
31 XFIXES version 1.0
33 "($server_major, $server_minor) = $X->XFixesQueryVersion
34 ($client_major, $client_minor)"
35 Negotiate a protocol version with the server. $client_major and
36 $client_minor is what the client would like, the returned
37 $server_major and $server_minor is what the server will do, which
38 might be less than requested (but not more than).
39 The current code in this module supports up to 4.0 and
41 automatically negotiates within init_extension(), so direct use of
42 XFixesQueryVersion() is not necessary. Asking for higher than the
43 code supports might be a bad idea.
44 "($atom, $str) = $X->XFixesChangeSaveSet ($window, $mode, $target,
46 $map)"
47 Insert or delete $window (an XID) from the "save set" of resources
48 to be retained on the server when the client disconnects. This is
49 an extended version of the core ChangeSaveSet() request.
50 $mode is either "Insert" or "Delete".
52 $target is how to reparent $window on client close-down, either
54 "Nearest" or "Root". The core ChangeSaveSet() is "Nearest" and
55 means go to the next non-client ancestor window. "Root" means go
56 to the root window.
57 $map is either "Map" or "Unmap" to apply to $window on close-down.
59 The core ChangeSaveSet() is "Map".
60 $X->XFixesSelectSelectionInput ($window, $selection, $event_mask)>
62 Select "XFixesSelectionNotify" events (see "EVENTS" below) to be
63 sent to $window when $selection (an atom) changes.
64 $X->XFixesSelectSelectionInput ($my_window,
66 $X->atom('PRIMARY'),
67 0x07);
68 $window is given in the resulting "XFixesSelectionNotify". It
70 probably works to make it just a root window. Selections are
71 global to the whole server, so the window doesn't implicitly choose
72 a screen or anything.
73 $event_mask has three bits for which event subtypes should be
75 reported.
76 bitpos bitval
78 SetSelectionOwner 0 0x01
79 SelectionWindowDestroy 1 0x02
80 SelectionClientClose 2 0x04
81 There's no pack function for these yet so just give an integer, for
83 instance 0x07 for all three.
84 See examples/xfixes-selection.pl for a sample program listening to
86 selection changes with this request.
87 $X->XFixesSelectCursorInput ($window, $event_mask)>
89 Select "XFixesCursorNotify" events (see "EVENTS" below) to be sent
90 to the client.
91 $window is given in the resulting "XFixesSelectionNotify". It
93 probably works to make it just a root window. The cursor image is
94 global and the events are for any change, not merely within
95 $window.
96 $event_mask has only a single bit, asking for displayed cursor
98 changes,
99 bitpos bitval
101 DisplayCursor 0 0x01
102 There's no pack function for this yet, just give integer 1 or 0.
104 ($root_x,$root_y, $width,$height, $xhot,$yhot, $serial, $pixels) =
106 $X->XFixesGetCursorImage ()>
107 Return the size and pixel contents of the currently displayed mouse
108 pointer cursor.
109 $root_x,$root_y returned are the pointer location in root window
111 coordinates (similar to QueryPointer()).
112 $width,$height is the size of the cursor image. $xhot,$yhot is the
114 "hotspot" position within that, which is the pixel which follows
115 the pointer location.
116 $pixels is a byte string of packed "ARGB" pixel values. Each is
118 32-bits in client byte order, with $width many in each row and
119 $height such rows and no padding in between, so a total
120 "4*$width*$height" bytes. This can be unpacked with for instance
121 my @argb = unpack 'L*', $pixels; # each 0xAARRGGBB
123 # top left pixel is in $argb[0]
125 my $alpha = ($argb[0] >> 24) & 0xFF; # each value
126 my $red = ($argb[0] >> 16) & 0xFF; # 0 to 255
127 my $green = ($argb[0] >> 8) & 0xFF;
128 my $blue = $argb[0] & 0xFF;
129 The alpha transparency is pre-multiplied into the RGB components,
131 so if the alpha is zero (transparent) then the components are zero
132 too.
133 The core CreateCursor() bitmask always makes alpha=0 transparent or
135 alpha=255 opaque pixels. The RENDER extension (see
136 X11::Protocol::Ext::RENDER) can make partially transparent cursors.
137 There's no direct way to get the image of a cursor by its XID
139 (except something dodgy like a GrabPointer() to make it the
140 displayed cursor). Usually cursor XIDs are only ever created by a
141 client itself so no need to read back (and the cursor XID can't be
142 read out of an arbitrary window -- though the XTEST extension can
143 do some comparing, per X11::Protocol::Ext::XTEST).
144 For reference, in the X.org server circa version 1.11, the server
146 may start up with no cursor at all, and when that happens an
147 attempt to XFixesGetCursorImage() gives a "Cursor" error. In
148 practice this probably only happens using a bare Xvfb or similar,
149 since in normal use xdm or the window manager will almost certainly
150 have set a cursor.
151 See examples/xfixes-cursor-image.pl for a sample program getting
153 the cursor image with this request.
154 XFIXES version 2.0
156 A region object on the server represents a set of rectangles, each
157 x,y,width,height, with positive or negative x,y, and the set possibly
158 made of disconnected sections, etc. (Basically a server-side copy of
159 the Xlib region code, see XCreateRegion(3).)
160 Each rectangle might be just 1x1 for a single pixel, so a region can
162 represent any bitmap, but it's geared towards the sort of rectangle
163 arithmetic which arises from overlapping rectangular windows etc.
164 "$X->XFixesCreateRegion ($region, $rect...)"
166 Create $region (a new XID) as a region and set it to the union of
167 the given rectangles, or empty if none. Each $rect is an arrayref
168 "[$x,$y,$width,$height]".
169 my $region = $X->new_rsrc;
171 $X->XFixesCreateRegion ($region, [0,0,10,5], [100,100,1,1]);
172 "$X->XFixesCreateRegionFromBitmap ($region, $bitmap)"
174 Create a region initialized from the 1 bits of $bitmap (a pixmap
175 XID).
176 my $region = $X->new_rsrc;
178 $X->XFixesCreateRegionFromBitmap ($region, $bitmap);
179 "$X->XFixesCreateRegionFromWindow ($region, $window, $kind)"
181 Create a region initialized from the shape of $window (an XID).
182 $kind is either "Bounding" or "Clip" as per the SHAPE extension
183 (see X11::Protocol::Ext::SHAPE).
184 my $region = $X->new_rsrc;
186 $X->XFixesCreateRegionFromBitmap ($region, $window, 'Clip');
187 There's no need to "$X->init_extension('SHAPE')" before using this
189 request. Any shape is just on the server and results in a $region
190 of either a single rectangle or set of rectangles for a shape.
191 "$X->XFixesCreateRegionFromGC ($region, $gc)"
193 Create a region initialized from the clip mask of $gc (an XID).
194 my $region = $X->new_rsrc;
196 $X->XFixesCreateRegionFromGC ($region, $gc);
197 The region is relative to the GC "clip_x_origin" and
199 "clip_y_origin", ie. those offsets are not applied to the X,Y in
200 the region.
201 "$X->XFixesCreateRegionFromPicture ($region, $picture)"
203 Create a region initialized from a RENDER $picture (an XID).
204 my $region = $X->new_rsrc;
206 $X->XFixesCreateRegionFromBitmap ($region, $picture);
207 The region is relative to the picture "clip_x_origin" and
209 "clip_y_origin", ie. those offsets are not applied to the X,Y in
210 the region.
211 Picture objects are from the RENDER extension (see
213 X11::Protocol::Ext::RENDER). This request always exists, but is
214 not useful without RENDER.
215 "$X->XFixesDestroyRegion ($region)"
217 Destroy $region.
218 "$X->XFixesSetRegion ($region, $rect...)"
220 Set $region to the union of the given rectangles, or empty if none.
221 Each $rect is an arrayref "[$x,$y,$width,$height]", as per
222 XFixesCreateRegion() above.
223 $X->XFixesSetRegion ($region, [0,0,20,10], [100,100,5,5])
225 "$X->XFixesCopyRegion ($dst, $src)"
227 Copy a region $src to region $dst.
228 "$X->XFixesUnionRegion ($src1, $src2, $dst)"
230 "$X->XFixesIntersectRegion ($src1, $src2, $dst)"
231 "$X->XFixesSubtractRegion ($src1, $src2, $dst)"
232 Set region $dst to respectively the union or intersection of $src1
233 and $src2, or the subtraction $src1 - $src2.
234 $dst can be one of the source regions if desired, to change in-
236 place.
237 "$X->XFixesInvertRegion ($src, $rect, $dst)"
239 Set region $dst to the inverse of $src bounded by rectangle $rect,
240 ie. $rect subtract $src. $rect is an arrayref
241 "[$x,$y,$width,$height]".
242 $X-XFixesInvertRegion ($src, [10,10, 200,100], $dst)>
244 $dst can be the same as $src to do an "in-place" invert.
246 "$X->XFixesTranslateRegion ($region, $dx, $dy)"
248 Move the area covered by $region by an offset $dx and $dy
249 (integers).
250 "$X->XFixesRegionExtents ($dst, $src)"
252 Set region $dst to the rectangular bounds of region $src. If $src
253 is empty then $dst is set to empty.
254 "($bounding, @parts) = $X->XFixesFetchRegion ($region)"
256 Return the rectangles which cover $region. Each returned element
257 is an arrayref
258 [$x,$y,$width,$height]
260 The first is a bounding rectangle, and after that the individual
262 rectangles making up the region, in "YX-banded" order.
263 my ($bounding, @rects) = $X->XFixesFetchRegion ($region);
265 print "bounded by ",join(',',@$bounding);
266 foreach my $rect (@rects) {
267 print " rect part ",join(',',@$rect);
268 }
269 "$X->XFixesSetGCClipRegion ($gc, $clip_x_origin, $clip_y_origin,
271 $region)"
272 Set the clip mask of $gc (an XID) to $region (an XID), and set the
273 clip origin to $clip_x_origin,$clip_x_origin.
274 This is similar to the core SetClipRectangles(), but the rectangles
276 are from $region (and no "ordering" parameter).
277 "$X->XFixesSetWindowShapeRegion ($window, $kind, $x_offset, $y_offset,
279 $region)"
280 Set the shape mask of $window (an XID) to $region, at offset
281 $x_offset,$y_offset into the window. $kind is a ShapeKind, either
282 "Bounding" or "Clip".
283 This is similar to ShapeMask() (see X11::Protocol::Ext::SHAPE) with
285 operation "Set" and a a region instead of a bitmap.
286 It's not necessary to "$X->init_extension('SHAPE')" before using
288 this request. If SHAPE is not available on the server then
289 presumably this request gives an error reply.
290 "$X->XFixesSetPictureClipRegion ($picture, $clip_x_origin,
292 $clip_y_origin, $region)"
293 Set the clip mask of RENDER $picture (an XID) to $region, and set
294 the clip origin to $clip_x_origin,$clip_x_origin.
295 This is similar to RenderSetPictureClipRectangles(), but the
297 rectangles are from $region.
298 Picture objects are from the RENDER extension (see
300 X11::Protocol::Ext::RENDER). The request always exists, but is not
301 useful without RENDER.
302 "$X->XFixesSetCursorName ($cursor, $str)"
304 Set a name for cursor object $cursor (an XID). The name string
305 $str is interned as an atom in the server and therefore be a byte
306 string of latin-1 characters. (Perhaps in the future that might be
307 enforced here, or wide chars converted.)
308 "($atom, $str) = $X->XFixesGetCursorName ($cursor)"
310 Get the name of mouse pointer cursor $cursor (an XID), as set by
311 XFixesSetCursorName().
312 The returned $atom is the name atom (an integer) and $str is the
314 name string (which is the atom's name). If there's no name for
315 $cursor then $atom is string "None" (or 0 if no
316 "$X->{'do_interp'}") and $str is empty "".
317 "($x,$y, $width,$height, $xhot,$yhot, $serial, $pixels, $atom, $str) =
319 $X->XFixesGetCursorImageAndName ()"
320 Get the image and name of the current mouse pointer cursor. The
321 return is per XFixesGetCursorImage() plus XFixesGetCursorName()
322 described above.
323 "$X->XFixesChangeCursor ($src, $dst)"
325 Change the contents of cursor $dst (an XID) to the contents of
326 cursor $src (an XID).
327 "$X->XFixesChangeCursorByName ($src, $dst_str)"
329 Change the contents of any cursors with name $dst_str (a string) to
330 the contents of cursor $src. If there's no cursors with name
331 $dst_str then do nothing.
332 XFIXES version 3.0
334 "$X->XFixesExpandRegion ($src, $dst, $left,$right,$top,$bottom)"
335 Set region $dst (an XID) to the rectangles of region $src, with
336 each rectangle expanded by $left, $right, $top, $bottom many pixels
337 in those respective directions.
338 Notice it doesn't matter how $src is expressed as rectangles, the
340 effect is as if each individual pixel in $src was expanded and the
341 union of the result taken.
342 XFIXES version 4.0
344 "$X->XFixesHideCursor ($window)"
345 "$X->XFixesShowCursor ($window)"
346 Hide or show the mouse pointer cursor while it's in $window (an
347 XID) or any subwindow of $window.
348 This hiding for each window is a per-client setting. If more than
350 one client requests hiding then the cursor remains hidden until all
351 of them "show" again. If a client disconnects or is killed then
352 its hides are automatically undone.
353 XFIXES version 5.0
355 "$X->XFixesCreatePointerBarrier ($barrier, $drawable, $x1,$y1, $x2,$y2,
356 $directions)"
357 "$X->XFixesCreatePointerBarrier ($barrier, $drawable, $x1,$y1, $x2,$y2,
358 $directions, $deviceid...)"
359 Create $barrier (a new XID) as a barrier object which prevents user
360 mouse pointer movement across a line between points "$x1,$y1" and
361 "$x2,$y2". For example
362 my $barrier = $X->new_rsrc;
364 $X->XFixesCreatePointerBarrier ($barrier, $X->root,
365 100,100, 100,500,
366 0);
367 X,Y coordinates are screen coordinates on the screen of $drawable.
369 The line must be horizontal or vertical, so either "$x1==$x2" or
370 "$y1==$y2" (but not both). A horizontal barrier is across the top
371 edge of the line pixels, a vertical barrier is along the left edge
372 of the line pixels.
373 $directions is an integer OR of the follow bits for which
375 directions to allow some movement across the line. A value 0 means
376 no movement across is allowed.
377 PositiveX 1
379 PositiveY 2
380 NegativeX 4
381 NegativeY 8
382 For example on a horizontal line, value 8 would allow the pointer
384 to move through the line in the negative Y direction (up the
385 screen), and movement in the positive Y direction (down the screen)
386 would still be forbidden.
387 $directions can let the user move the mouse out of some sort of
389 forbidden region but not go back in.
390 Optional $deviceid arguments are X Input Extension 2.0 devices the
392 barrier should apply to (see X11::Protocol::Ext::XInputExtension).
393 With no arguments the barrier is just for the core protocol mouse
394 pointer. Each argument can be
395 device ID integer
397 "AllDevices" enum string, 0
398 "AllMasterDevices" enum string, 1
399 It's not necessary to "$X->init_extension('XInputExtension')"
401 before using this barrier request.
402 The user can move the mouse pointer to go around a barrier line but
404 by putting lines together a region can be constructed keeping the
405 pointer inside or outside, or even a maze to trick the user!
406 Touchscreen pad input is not affected by barriers, and
408 "$X->WarpPointer()" can still move the pointer anywhere.
409 One intended use is when a Xinerama screen (see
411 X11::Protocol::Ext::XINERAMA) is made from monitors of different
412 pixel sizes so parts of the logical screen extent are off the edge
413 of one of the smaller monitors. Barriers can prevent the user
414 losing the mouse in one of those dead regions.
415 For reference, some X.org server versions prior to some time around
417 version 1.14 did not accept $deviceid arguments in the request and
418 gave a "Length" error on attempting to pass them. Those servers
419 might have given an "Implementation" error anyway (for barrier
420 feature not yet implemented).
421 "$X->XFixesDestroyPointerBarrier ($barrier)"
423 Destroy the given barrier (an XID).
424
426 The following events have the usual fields
427 name "XFixes..."
429 synthetic true if from a SendEvent
430 code integer opcode
431 sequence_number integer
432 "XFixesSelectionNotify"
434 This is sent to the client when selected by
435 "XFixesSelectSelectionInput" above. It reports changes to the
436 selection. The event-specific fields are
437 subtype enum string
439 window XID
440 owner XID of owner window, or "None"
441 selection atom integer
442 time integer, server timestamp
443 selection_time integer, server timestamp
444 "subtype" is one of
446 SetSelectionOwner
448 SelectionWindowDestroy
449 SelectionClientClose
450 "time" is when the event was generated, "selection_time" is when
452 the selection was owned.
453 "XFixesCursorNotify"
455 This is sent to the client when selected by
456 XFixesSelectCursorInput() above. It reports when the currently
457 displayed mouse pointer cursor has changed. It has the following
458 event-specific fields,
459 subtype enum string, currently always "DisplayCursor"
461 window XID
462 cursor_serial integer
463 time integer, server timestamp
464 cursor_name atom or "None" (XFIXES 2.0 up)
465 "subtype" is "DisplayCursor" when the displayed cursor has changed.
467 This is the only subtype currently.
468 "cursor_serial" is a serial number as per XFixesGetCursorImage().
470 A client can use this to notice when the displayed cursor is
471 something it has already fetched with XFixesGetCursorImage().
472 "cursor_name" is the atom of the name given to the cursor by
474 "XFixesSetCursorName", or string "None" if no name. This field is
475 new in XFIXES 2.0 and is present in the event unpack only if the
476 server does XFIXES 2.0 or higher. For "$X->pack_event()",
477 "cursor_name" is optional and the field is set if given.
478
480 Error type "Region" is a bad $region resource XID in a request (XFIXES
481 2.0 up).
482
484 X11::Protocol, X11::Protocol::Ext::SHAPE, X11::Protocol::Ext::RENDER
485 /usr/share/doc/x11proto-fixes-dev/fixesproto.txt.gz
487
489 <http://user42.tuxfamily.org/x11-protocol-other/index.html>
490
492 Copyright 2011, 2012, 2013, 2014, 2016, 2017, 2019 Kevin Ryde
493 X11-Protocol-Other is free software; you can redistribute it and/or
495 modify it under the terms of the GNU General Public License as
496 published by the Free Software Foundation; either version 3, or (at
497 your option) any later version.
498 X11-Protocol-Other is distributed in the hope that it will be useful,
500 but WITHOUT ANY WARRANTY; without even the implied warranty of
501 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
502 General Public License for more details.
503 You should have received a copy of the GNU General Public License along
505 with X11-Protocol-Other. If not, see <http://www.gnu.org/licenses/>.
506perl v5.36.0 2023-01-20 X11::Protocol::Ext::XFIXES(3)