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

📦

version 31 · 7 versions

31 · debian bookworm, debian trixie, ubuntu jammy, ubuntu noble (latest)
31 · epel 9
31 · epel 10
31 · arch rolling
31 · fedora 43
31 · fedora 44
31 · ubuntu resolute, ubuntu stonking

, in debian bookworm, debian trixie, ubuntu jammy, ubuntu noble

✨ NAME ✨

X11::Protocol::Ext::XFIXES — the miscellaneous "fixes" extension, bestie 💅

(That's the manual page X11::P...XFIXES(3pm) from the User Contributed Perl Documentation, in case you were squinting at the header like "girl what". It's giving abbreviation energy, we move.)

🌸 SYNOPSIS 🌸

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

🦋 DESCRIPTION 🦋

okay so the XFIXES extension adds a bunch of features that are literally conceived as "fixing" the things the core X11 protocol forgot to include, like:

Events for changes to the selection (the cut and paste between clients). 📋
Current cursor image fetching, cursor change events, and cursor naming and hiding. 🖱️
Server-side "region" objects representing a set of rectangles. 🔲

👑 REQUESTS 👑

The following are made available with an init_extension() per EXTENSIONS in X11::Protocol.

my $bool = $X->init_extension('XFIXES');

💖 XFIXES version 1.0 💖

($server_major, $server_minor) = $X->XFixesQueryVersion ($client_major, $client_minor) — negotiate a protocol version with the server. $client_major and $client_minor is what the client would like, and the returned $server_major and $server_minor is what the server will do, which might be less than requested (but not more than).

The current code in this module supports up to 4.0 and automatically negotiates within init_extension(), so direct use of XFixesQueryVersion() is not necessary. Asking for higher than the code supports might be a bad idea. 🙈

($atom, $str) = $X->XFixesChangeSaveSet ($window, $mode, $target, $map) — insert or delete $window (an XID) from the "save set" of resources to be retained on the server when the client disconnects. This is an extended version of the core ChangeSaveSet() request.

$mode is either Insert or Delete.

$target is how to reparent $window on client close-down, either Nearest or Root. The core ChangeSaveSet() is Nearest and means go to the next non-client ancestor window. Root means go to the root window.

$map is either Map or Unmap to apply to $window on close-down. The core ChangeSaveSet() is Map.

$X->XFixesSelectSelectionInput ($window, $selection, $event_mask)> — select XFixesSelectionNotify events (see "EVENTS" below) to be sent to $window when $selection (an atom) changes.

$X->XFixesSelectSelectionInput ($my_window,
                                $X->atom('PRIMARY'),
                                0x07);

$window is given in the resulting XFixesSelectionNotify. It probably works to make it just a root window. Selections are global to the whole server, so the window doesn't implicitly choose a screen or anything.

$event_mask has three bits for which event subtypes should be reported.

SetSelectionOwner — bitpos 0, bitval 0x01
SelectionWindowDestroy — bitpos 1, bitval 0x02
SelectionClientClose — bitpos 2, bitval 0x04

There's no pack function for these yet so just give an integer, for instance 0x07 for all three.

See examples/xfixes-selection.pl for a sample program listening to selection changes with this request. 🎧

$X->XFixesSelectCursorInput ($window, $event_mask)> — select XFixesCursorNotify events (see "EVENTS" below) to be sent to the client.

$window is given in the resulting XFixesSelectionNotify. It probably works to make it just a root window. The cursor image is global and the events are for any change, not merely within $window.

$event_mask has only a single bit, asking for displayed cursor changes.

DisplayCursor — bitpos 0, bitval 0x01

There's no pack function for this yet, just give integer 1 or 0.

($root_x,$root_y, $width,$height, $xhot,$yhot, $serial, $pixels) = $X->XFixesGetCursorImage ()> — return the size and pixel contents of the currently displayed mouse pointer cursor. 🖱️✨

$root_x,$root_y returned are the pointer location in root window coordinates (similar to QueryPointer()).

$width,$height is the size of the cursor image. $xhot,$yhot is the "hotspot" position within that, which is the pixel which follows the pointer location.

$pixels is a byte string of packed ARGB pixel values. Each is 32-bits in client byte order, with $width many in each row and $height such rows and no padding in between, so a total 4*$width*$height bytes. This can be unpacked with for instance

my @argb = unpack 'L*', $pixels; # each 0xAARRGGBB

# top left pixel is in $argb[0]
my $alpha = ($argb[0] >> 24) & 0xFF;  # each value
my $red   = ($argb[0] >> 16) & 0xFF;  # 0 to 255
my $green = ($argb[0] >> 8)  & 0xFF;
my $blue  =  $argb[0]        & 0xFF;

The alpha transparency is pre-multiplied into the RGB components, so if the alpha is zero (transparent) then the components are zero too.

The core CreateCursor() bitmask always makes alpha=0 transparent or alpha=255 opaque pixels. The RENDER extension (see X11::Protocol::Ext::RENDER) can make partially transparent cursors. 🧚

There's no direct way to get the image of a cursor by its XID (except something dodgy like a GrabPointer() to make it the displayed cursor). Usually cursor XIDs are only ever created by a client itself so no need to read back (and the cursor XID can't be read out of an arbitrary window — though the XTEST extension can do some comparing, per X11::Protocol::Ext::XTEST).

For reference, in the X.org server circa version 1.11, the server may start up with no cursor at all, and when that happens an attempt to XFixesGetCursorImage() gives a Cursor error. In practice this probably only happens using a bare Xvfb or similar, since in normal use xdm or the window manager will almost certainly have set a cursor. 💀

See examples/xfixes-cursor-image.pl for a sample program getting the cursor image with this request.

🌈 XFIXES version 2.0 🌈

A region object on the server represents a set of rectangles, each x,y,width,height, with positive or negative x,y, and the set possibly made of disconnected sections, etc. (Basically a server-side copy of the Xlib region code, see XCreateRegion(3).)

Each rectangle might be just 1x1 for a single pixel, so a region can represent any bitmap, but it's geared towards the sort of rectangle arithmetic which arises from overlapping rectangular windows etc.

$X->XFixesCreateRegion ($region, $rect...) — create $region (a new XID) as a region and set it to the union of the given rectangles, or empty if none. Each $rect is an arrayref [$x,$y,$width,$height].

my $region = $X->new_rsrc;
$X->XFixesCreateRegion ($region, [0,0,10,5], [100,100,1,1]);

$X->XFixesCreateRegionFromBitmap ($region, $bitmap) — create a region initialized from the 1 bits of $bitmap (a pixmap XID).

my $region = $X->new_rsrc;
$X->XFixesCreateRegionFromBitmap ($region, $bitmap);

$X->XFixesCreateRegionFromWindow ($region, $window, $kind) — create a region initialized from the shape of $window (an XID). $kind is either Bounding or Clip as per the SHAPE extension (see X11::Protocol::Ext::SHAPE).

my $region = $X->new_rsrc;
$X->XFixesCreateRegionFromBitmap ($region, $window, 'Clip');

There's no need to $X->init_extension('SHAPE') before using this request. Any shape is just on the server and results in a $region of either a single rectangle or set of rectangles for a shape.

$X->XFixesCreateRegionFromGC ($region, $gc) — create a region initialized from the clip mask of $gc (an XID).

my $region = $X->new_rsrc;
$X->XFixesCreateRegionFromGC ($region, $gc);

The region is relative to the GC clip_x_origin and clip_y_origin, ie. those offsets are not applied to the X,Y in the region.

$X->XFixesCreateRegionFromPicture ($region, $picture) — create a region initialized from a RENDER $picture (an XID).

my $region = $X->new_rsrc;
$X->XFixesCreateRegionFromBitmap ($region, $picture);

The region is relative to the picture clip_x_origin and clip_y_origin, ie. those offsets are not applied to the X,Y in the region.

Picture objects are from the RENDER extension (see X11::Protocol::Ext::RENDER). This request always exists, but is not useful without RENDER.

$X->XFixesDestroyRegion ($region) — destroy $region. bye bestie 👋
$X->XFixesSetRegion ($region, $rect...) — set $region to the union of the given rectangles, or empty if none. Each $rect is an arrayref [$x,$y,$width,$height], as per XFixesCreateRegion() above.

$X->XFixesSetRegion ($region, [0,0,20,10], [100,100,5,5])

$X->XFixesCopyRegion ($dst, $src) — copy a region $src to region $dst.
$X->XFixesUnionRegion ($src1, $src2, $dst)
$X->XFixesIntersectRegion ($src1, $src2, $dst)
$X->XFixesSubtractRegion ($src1, $src2, $dst) — set region $dst to respectively the union or intersection of $src1 and $src2, or the subtraction $src1 - $src2.

$dst can be one of the source regions if desired, to change in-place.

$X->XFixesInvertRegion ($src, $rect, $dst) — set region $dst to the inverse of $src bounded by rectangle $rect, ie. $rect subtract $src. $rect is an arrayref [$x,$y,$width,$height].

$X-XFixesInvertRegion ($src, [10,10, 200,100], $dst)>

$dst can be the same as $src to do an "in-place" invert.

$X->XFixesTranslateRegion ($region, $dx, $dy) — move the area covered by $region by an offset $dx and $dy (integers).
$X->XFixesRegionExtents ($dst, $src) — set region $dst to the rectangular bounds of region $src. If $src is empty then $dst is set to empty.
($bounding, @parts) = $X->XFixesFetchRegion ($region) — return the rectangles which cover $region. Each returned element is an arrayref

[$x,$y,$width,$height]

The first is a bounding rectangle, and after that the individual rectangles making up the region, in "YX-banded" order.

my ($bounding, @rects) = $X->XFixesFetchRegion ($region);
print "bounded by ",join(',',@$bounding);
foreach my $rect (@rects) {
  print "  rect part ",join(',',@$rect);
}

$X->XFixesSetGCClipRegion ($gc, $clip_x_origin, $clip_y_origin, $region) — set the clip mask of $gc (an XID) to $region (an XID), and set the clip origin to $clip_x_origin,$clip_x_origin.

…to be continued, bestie 💖 part 2 is loading, don't go anywhere

This is giving exactly like the core SetClipRectangles(), bestie, except the rectangles come from $region instead — and there's no ordering parameter at all. We love a simplified signature. ✨

$X->XFixesSetWindowShapeRegion ($window, $kind, $x_offset, $y_offset, $region) — sets the shape mask of $window (an XID) to $region, offset by $x_offset,$y_offset into the window. 🎀 $kind is a ShapeKind, so it's either "Bounding" or "Clip".

This is basically ShapeMask() from X11::Protocol::Ext::SHAPE, but with operation "Set" and a region instead of a bitmap. Iconic.

You do not need to $X->init_extension('SHAPE') before using this request. If SHAPE isn't available on the server then presumably this request gives an error reply — so like, don't @ me, ask the server. 💀

$X->XFixesSetPictureClipRegion ($picture, $clip_x_origin, $clip_y_origin, $region) — sets the clip mask of RENDER $picture (an XID) to $region, and sets the clip origin to $clip_x_origin,$clip_x_origin.

Very RenderSetPictureClipRectangles(), except the rectangles come from $region. Same vibe, different source.

Picture objects come from the RENDER extension (peep X11::Protocol::Ext::RENDER). The request always exists, but it's not useful without RENDER. It's giving "exists but does nothing for you" energy. 🦋

$X->XFixesSetCursorName ($cursor, $str) — sets a name for the cursor object $cursor (an XID). The name string $str gets interned as an atom in the server, so it has to be a byte string of latin-1 characters. (Perhaps in the future that might be enforced here, or wide chars converted — TBD, no cap.)
($atom, $str) = $X->XFixesGetCursorName ($cursor) — gets the name of the mouse pointer cursor $cursor (an XID), the way it was set by XFixesSetCursorName().

The returned $atom is the name atom (an integer) and $str is the name string (which is literally the atom's name). If there's no name for $cursor then $atom is the string "None" (or 0 if there's no $X->{'do_interp'}) and $str is empty "". Sad little empty string. 😭

($x,$y, $width,$height, $xhot,$yhot, $serial, $pixels, $atom, $str) = $X->XFixesGetCursorImageAndName () — gets the image and the name of the current mouse pointer cursor. The return is per XFixesGetCursorImage() plus XFixesGetCursorName() described above. Two for one, we ate. 🍓
$X->XFixesChangeCursor ($src, $dst) — changes the contents of cursor $dst (an XID) to the contents of cursor $src (an XID).
$X->XFixesChangeCursorByName ($src, $dst_str) — changes the contents of any cursors with name $dst_str (a string) to the contents of cursor $src. If there's no cursors with name $dst_str then do nothing. Literally nothing, just vibes. 🙈

✨ XFIXES version 3.0 ✨

$X->XFixesExpandRegion ($src, $dst, $left,$right,$top,$bottom) — sets region $dst (an XID) to the rectangles of region $src, with each rectangle expanded by $left, $right, $top, $bottom many pixels in those respective directions.

Notice it doesn't matter how $src is expressed as rectangles — the effect is as if each individual pixel in $src was expanded and the union of the result taken. Glow-up for every single pixel, honestly. ✨

🌈 XFIXES version 4.0 🌈

$X->XFixesHideCursor ($window)
$X->XFixesShowCursor ($window)

Hide or show the mouse pointer cursor while it's in $window (an XID) or any subwindow of $window.

This hiding for each window is a per-client setting. If more than one client requests hiding then the cursor remains hidden until all of them "show" again. And if a client disconnects or is killed then its hides are automatically undone — the server cleans up after you, so generous. 🫶

👑 XFIXES version 5.0 👑

$X->XFixesCreatePointerBarrier ($barrier, $drawable, $x1,$y1, $x2,$y2, $directions)
$X->XFixesCreatePointerBarrier ($barrier, $drawable, $x1,$y1, $x2,$y2, $directions, $deviceid...)

Creates $barrier (a new XID) as a barrier object which prevents user mouse pointer movement across a line between points "$x1,$y1" and "$x2,$y2". For example:

my $barrier = $X->new_rsrc;
$X->XFixesCreatePointerBarrier ($barrier, $X->root,
                                100,100, 100,500,
                                0);

X,Y coordinates are screen coordinates on the screen of $drawable. The line must be horizontal or vertical, so either "$x1==$x2" or "$y1==$y2" (but not both — pick a lane, bestie). A horizontal barrier is across the top edge of the line pixels, a vertical barrier is along the left edge of the line pixels.

$directions is an integer OR of the following bits, for which directions to allow some movement across the line. A value 0 means no movement across is allowed.

PositiveX    1
PositiveY    2
NegativeX    4
NegativeY    8

For example on a horizontal line, value 8 would allow the pointer to move through the line in the negative Y direction (up the screen), and movement in the positive Y direction (down the screen) would still be forbidden. One-way mouse door, so real.

$directions can let the user move the mouse out of some sort of forbidden region but not go back in. Sneaky. 😈

Optional $deviceid arguments are X Input Extension 2.0 devices the barrier should apply to (see X11::Protocol::Ext::XInputExtension). With no arguments the barrier is just for the core protocol mouse pointer. Each argument can be

device ID                integer
"AllDevices"             enum string, 0
"AllMasterDevices"       enum string, 1

You do not need to $X->init_extension('XInputExtension') before using this barrier request. Slay.

The user can move the mouse pointer to go around a barrier line, but by putting lines together a region can be constructed keeping the pointer inside or outside, or even a maze to trick the user! Main character energy, honestly. 👑

Touchscreen pad input is not affected by barriers, and $X->WarpPointer() can still move the pointer anywhere. No barrier can stop a warp, lowkey.

One intended use is when a Xinerama screen (see X11::Protocol::Ext::XINERAMA) is made from monitors of different pixel sizes, so parts of the logical screen extent are off the edge of one of the smaller monitors. Barriers can prevent the user losing the mouse in one of those dead regions. Cute little mouse fence. 🎀

For reference, some X.org server versions prior to some time around version 1.14 did not accept $deviceid arguments in the request and gave a "Length" error on attempting to pass them. Those servers might have given an "Implementation" error anyway (for barrier feature not yet implemented). So if you're on ancient X.org, that's the tea. 💀

$X->XFixesDestroyPointerBarrier ($barrier) — destroys the given barrier (an XID). Bye bestie. 👋

💖 EVENTS 💖

The following events have the usual fields:

name             "XFixes..."
synthetic        true if from a SendEvent
code             integer opcode
sequence_number  integer

XFixesSelectionNotify — this is sent to the client when selected by XFixesSelectSelectionInput above. It reports changes to the selection. The event-specific fields are:

subtype         enum string
window          XID
owner           XID of owner window, or "None"
selection       atom integer
time            integer, server timestamp
selection_time  integer, server timestamp

"subtype" is one of

SetSelectionOwner
SelectionWindowDestroy
SelectionClientClose

"time" is when the event was generated, "selection_time" is when the selection was owned.

XFixesCursorNotify — this is sent to the client when selected by XFixesSelectCursorInput() above. It reports when the currently displayed mouse pointer cursor has changed. It has the following event-specific fields:

subtype         enum string, currently always "DisplayCursor"
window          XID
cursor_serial   integer
time            integer, server timestamp
cursor_name     atom or "None" (XFIXES 2.0 up)

"subtype" is "DisplayCursor" when the displayed cursor has changed. This is the only subtype currently.

"cursor_serial" is a serial number as per XFixesGetCursorImage(). A client can use this to notice when the displayed cursor is something it has already fetched with XFixesGetCursorImage(). Very "wait, I've seen that cursor before" of it.

"cursor_name" is the atom of the name given to the cursor by XFixesSetCursorName, or string "None" if no name. This field is new in XFIXES 2.0 and is present in the event unpack only if the server does XFIXES 2.0 or higher. For $X->pack_event(), "cursor_name" is optional and the field is set if given.

💀 ERRORS 💀

Error type Region is a bad $region resource XID in a request (XFIXES 2.0 up). That's it, that's the error. Check your region XIDs, bestie. 🫠

🌸 SEE ALSO 🌸

X11::Protocol, X11::Protocol::Ext::SHAPE, X11::Protocol::Ext::RENDER

/usr/share/doc/x11proto-fixes-dev/fixesproto.txt.gz

🦋 HOME PAGE 🦋

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

🎀 LICENSE 🎀

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

And that's a wrap on the page, bestie! This whole thing comes to you courtesy of perl v5.28.1, dated 2019-08-26, and it's the man page for X11::P...XFIXES(3pm) — go forth and shape some windows, hide some cursors, and build a maze for your mouse. 💅✨🦋

📦 where this page comes from

debian bookworm: libx11-protocol-other-perl 31-1 · GPL-3.0-or-later
debian trixie: libx11-protocol-other-perl 31-1 · GPL-3.0-or-later
ubuntu jammy: libx11-protocol-other-perl 31-1 · GPL-3.0-or-later
ubuntu noble: libx11-protocol-other-perl 31-1 · GPL-3.0-or-later
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-10-14: a language model's rewrite of the original, under its terms