1X11::Protocol::Ext::XFIUXsEeSr(3C)ontributed Perl DocumeXn1t1a:t:iPornotocol::Ext::XFIXES(3)
2
3
4

NAME

6       X11::Protocol::Ext::XFIXES - miscellaneous "fixes" extension
7

SYNOPSIS

9        use X11::Protocol;
10        my $X = X11::Protocol->new;
11        $X->init_extension('XFIXES')
12          or print "XFIXES extension not available";
13

DESCRIPTION

15       The XFIXES extension adds some features which are conceived as "fixing"
16       omissions in the core X11 protocol, including
17
18       •   Events for changes to the selection (the cut and paste between
19           clients).
20
21       •   Current cursor image fetching, cursor change events, and cursor
22           naming and hiding.
23
24       •   Server-side "region" objects representing a set of rectangles.
25

REQUESTS

27       The following are made available with an "init_extension()" per
28       "EXTENSIONS" in X11::Protocol.
29
30           my $bool = $X->init_extension('XFIXES');
31
32   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
40           The current code in this module supports up to 4.0 and
41           automatically negotiates within "init_extension()", so direct use
42           of "XFixesQueryVersion()" is not necessary.  Asking for higher than
43           the code supports might be a bad idea.
44
45       "($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
51           $mode is either "Insert" or "Delete".
52
53           $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
58           $map is either "Map" or "Unmap" to apply to $window on close-down.
59           The core "ChangeSaveSet()" is "Map".
60
61       $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
65               $X->XFixesSelectSelectionInput ($my_window,
66                                               $X->atom('PRIMARY'),
67                                               0x07);
68
69           $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
74           $event_mask has three bits for which event subtypes should be
75           reported.
76
77                                       bitpos  bitval
78               SetSelectionOwner         0      0x01
79               SelectionWindowDestroy    1      0x02
80               SelectionClientClose      2      0x04
81
82           There's no pack function for these yet so just give an integer, for
83           instance 0x07 for all three.
84
85           See examples/xfixes-selection.pl for a sample program listening to
86           selection changes with this request.
87
88       $X->XFixesSelectCursorInput ($window, $event_mask)>
89           Select "XFixesCursorNotify" events (see "EVENTS" below) to be sent
90           to the client.
91
92           $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
97           $event_mask has only a single bit, asking for displayed cursor
98           changes,
99
100                                bitpos  bitval
101               DisplayCursor      0      0x01
102
103           There's no pack function for this yet, just give integer 1 or 0.
104
105       ($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
110           $root_x,$root_y returned are the pointer location in root window
111           coordinates (similar to "QueryPointer()").
112
113           $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
117           $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
122               my @argb = unpack 'L*', $pixels; # each 0xAARRGGBB
123
124               # 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
130           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
134           The core "CreateCursor()" bitmask always makes alpha=0 transparent
135           or alpha=255 opaque pixels.  The RENDER extension (see
136           X11::Protocol::Ext::RENDER) can make partially transparent cursors.
137
138           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
145           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
152           See examples/xfixes-cursor-image.pl for a sample program getting
153           the cursor image with this request.
154
155   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
161       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
165       "$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
170               my $region = $X->new_rsrc;
171               $X->XFixesCreateRegion ($region, [0,0,10,5], [100,100,1,1]);
172
173       "$X->XFixesCreateRegionFromBitmap ($region, $bitmap)"
174           Create a region initialized from the 1 bits of $bitmap (a pixmap
175           XID).
176
177               my $region = $X->new_rsrc;
178               $X->XFixesCreateRegionFromBitmap ($region, $bitmap);
179
180       "$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
185               my $region = $X->new_rsrc;
186               $X->XFixesCreateRegionFromBitmap ($region, $window, 'Clip');
187
188           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
192       "$X->XFixesCreateRegionFromGC ($region, $gc)"
193           Create a region initialized from the clip mask of $gc (an XID).
194
195               my $region = $X->new_rsrc;
196               $X->XFixesCreateRegionFromGC ($region, $gc);
197
198           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
202       "$X->XFixesCreateRegionFromPicture ($region, $picture)"
203           Create a region initialized from a RENDER $picture (an XID).
204
205               my $region = $X->new_rsrc;
206               $X->XFixesCreateRegionFromBitmap ($region, $picture);
207
208           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
212           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
216       "$X->XFixesDestroyRegion ($region)"
217           Destroy $region.
218
219       "$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
224               $X->XFixesSetRegion ($region, [0,0,20,10], [100,100,5,5])
225
226       "$X->XFixesCopyRegion ($dst, $src)"
227           Copy a region $src to region $dst.
228
229       "$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
235           $dst can be one of the source regions if desired, to change in-
236           place.
237
238       "$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
243               $X-XFixesInvertRegion ($src, [10,10, 200,100], $dst)>
244
245           $dst can be the same as $src to do an "in-place" invert.
246
247       "$X->XFixesTranslateRegion ($region, $dx, $dy)"
248           Move the area covered by $region by an offset $dx and $dy
249           (integers).
250
251       "$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
255       "($bounding, @parts) = $X->XFixesFetchRegion ($region)"
256           Return the rectangles which cover $region.  Each returned element
257           is an arrayref
258
259               [$x,$y,$width,$height]
260
261           The first is a bounding rectangle, and after that the individual
262           rectangles making up the region, in "YX-banded" order.
263
264               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
270       "$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
275           This is similar to the core "SetClipRectangles()", but the
276           rectangles are from $region (and no "ordering" parameter).
277
278       "$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
284           This is similar to "ShapeMask()" (see X11::Protocol::Ext::SHAPE)
285           with operation "Set" and a a region instead of a bitmap.
286
287           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
291       "$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
296           This is similar to "RenderSetPictureClipRectangles()", but the
297           rectangles are from $region.
298
299           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
303       "$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
309       "($atom, $str) = $X->XFixesGetCursorName ($cursor)"
310           Get the name of mouse pointer cursor $cursor (an XID), as set by
311           "XFixesSetCursorName()".
312
313           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
318       "($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
324       "$X->XFixesChangeCursor ($src, $dst)"
325           Change the contents of cursor $dst (an XID) to the contents of
326           cursor $src (an XID).
327
328       "$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
333   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
339           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
343   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
349           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
354   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
363               my $barrier = $X->new_rsrc;
364               $X->XFixesCreatePointerBarrier ($barrier, $X->root,
365                                               100,100, 100,500,
366                                               0);
367
368           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
374           $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
378               PositiveX    1
379               PositiveY    2
380               NegativeX    4
381               NegativeY    8
382
383           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
388           $directions can let the user move the mouse out of some sort of
389           forbidden region but not go back in.
390
391           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
396               device ID                integer
397               "AllDevices"             enum string, 0
398               "AllMasterDevices"       enum string, 1
399
400           It's not necessary to "$X->init_extension('XInputExtension')"
401           before using this barrier request.
402
403           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
407           Touchscreen pad input is not affected by barriers, and
408           "$X->WarpPointer()" can still move the pointer anywhere.
409
410           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
416           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
422       "$X->XFixesDestroyPointerBarrier ($barrier)"
423           Destroy the given barrier (an XID).
424

EVENTS

426       The following events have the usual fields
427
428           name             "XFixes..."
429           synthetic        true if from a SendEvent
430           code             integer opcode
431           sequence_number  integer
432
433       "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
438               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
445           "subtype" is one of
446
447               SetSelectionOwner
448               SelectionWindowDestroy
449               SelectionClientClose
450
451           "time" is when the event was generated, "selection_time" is when
452           the selection was owned.
453
454       "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
460               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
466           "subtype" is "DisplayCursor" when the displayed cursor has changed.
467           This is the only subtype currently.
468
469           "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
473           "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

ERRORS

480       Error type "Region" is a bad $region resource XID in a request (XFIXES
481       2.0 up).
482

SEE ALSO

484       X11::Protocol, X11::Protocol::Ext::SHAPE, X11::Protocol::Ext::RENDER
485
486       /usr/share/doc/x11proto-fixes-dev/fixesproto.txt.gz
487

HOME PAGE

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

LICENSE

492       Copyright 2011, 2012, 2013, 2014, 2016, 2017, 2019 Kevin Ryde
493
494       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
499       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
504       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/>.
506
507
508
509perl v5.32.1                      2021-01-27     X11::Protocol::Ext::XFIXES(3)
Impressum