NAME

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

SYNOPSIS

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

DESCRIPTION

The XFIXES extension adds some extra features conceived as "fixing" omissions in the core X11 protocol, including

Events for changes to the selection (the cut and paste between clients).
Current cursor image fetching, events for cursor change, 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, 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.

                        bitpos  bitval
SetSelectionOwner         0      0x01
SelectionWindowDestroy    1      0x02
SelectionClientClose      2      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,

                 bitpos  bitval
DisplayCursor      0      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 is 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 that 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 for each row and $height such rows, no padding in between, for 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 $blue  =  $argb[0]        & 0xFF;  # 0 to 255
my $green = ($argb[0] >> 8)  & 0xFF;  # components
my $red   = ($argb[0] >> 16) & 0xFF;
my $alpha = ($argb[0] >> 24) & 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 makes only alpha=0 full-transparent or alpha=255 full-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 they can't be read back out of an arbitrary window, though the XTEST extension can do some comparing, see X11::Protocol::Ext::XTEST).

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. Since each rectangle might be simply 1x1 a region can represent any bitmap, but is geared towards the sort of rectangle sets arising from overlapping rectangular window areas 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');

It's not necessary to $X->init_extension('SHAPE') before using this request, the shape as such is just on the server and results in whatever rectangular or non-rectangular $region.

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

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

This is similar to the core SetClipRectangles, but the rectangles are from $region (and no "ordering" parameter).

$X->XFixesSetWindowShapeRegion ($window, $kind, $x_offset, $y_offset, $region)

Set the shape mask of $window (an XID) to $region, at offset $x_offset,$y_offset into the window. $kind is a ShapeKind, either "Bounding" or "Clip".

This is similar to ShapeMask() (see X11::Protocol::Ext::SHAPE) with operation "Set" and a a region instead of a bitmap.

It's not necessary to $X->init_extension('SHAPE') before using this request. If SHAPE is not available at all on the server then presumably this request gives an error reply.

$X->XFixesSetPictureClipRegion ($picture, $clip_x_origin, $clip_y_origin, $region)

Set the clip mask of RENDER $picture (an XID) to $region, and set the clip origin to $clip_x_origin,$clip_x_origin.

This is similar to RenderSetPictureClipRectangles, but the rectangles are from $region.

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

$X->XFixesSetCursorName ($cursor, $str)

Set a name for cursor object $cursor (an XID). The name string $str is interned as an atom within the server and therefore should consist only of latin-1 characters. (Perhaps in the future that might be enforced here, or wide chars converted.)

($atom, $str) = $X->XFixesGetCursorName ($cursor)

Get the name of mouse pointer cursor $cursor (an XID), as set by XFixesSetCursorName.

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

($x,$y, $width,$height, $xhot,$yhot, $serial, $pixels, $atom, $str) = $X->XFixesGetCursorImageAndName ()

Get the image and name of the current mouse pointer cursor. The return is per XFixesGetCursorImage plus XFixesGetCursorName described above.

$X->XFixesChangeCursor ($src, $dst)

Change the contents of cursor $dst (an XID) to the contents of cursor $src (an XID).

$X->XFixesChangeCursorByName ($src, $dst_str)

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

XFIXES version 3.0

$X->XFixesExpandRegion ($src, $dst, $left,$right,$top,$bottom)

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

It doesn't matter how $src is expressed as rectangles, the effect is as if each pixel in $src was individually expanded and the union of the result taken.

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 hide/show 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. If a client disconnects or is killed then any hides it has are undone.

XFIXES version 5.0

Code waiting to be tested!

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", in 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 cursor changes to something it has already fetched with XFixesGetCursorImage.

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. In an $X->pack_event(), cursor_name is optional and the field is set if given.

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

To install X11::Protocol::Other, copy and paste the appropriate command in to your terminal.

cpanm

cpanm X11::Protocol::Other

CPAN shell

perl -MCPAN -e shell
install X11::Protocol::Other

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)