X11::Protocol::Ext::XTEST(3)
NAME
X11::Protocol::Ext::XTEST - synthetic user input and more
SYNOPSIS
use X11::Protocol;
my $X = X11::Protocol->new;
$X->init_extension('XTEST')
or print "XTEST extension not available";
$X->XTestFakeInput (name => 'ButtonPress',
detail => 3); # physical button 3
$X->XTestFakeInput (name => 'ButtonRelease',
detail => 3);
DESCRIPTION
The XTEST extension provides
o Synthetic keyboard and mouse pointer actions.
o Displayed cursor comparisons.
o Test programs continuing during "GrabServer" by other clients.
These things help exercise library or server features which would
otherwise require user interaction.
REQUESTS
The following requests are made available with an "init_extension()",
as per "EXTENSIONS" in X11::Protocol.
my $is_available = $X->init_extension('XTEST');
"($server_major, $server_minor) = $X->XTestGetVersion ($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.
The current code supports up to 2.1. The intention would be to
automatically negotiate in "init_extension()" if/when necessary.
Cursor Comparisons
"$is_same = $X->XTestCompareCursor ($window, $cursor)"
Return true if the cursor attribute of $window is equal to $cursor.
$cursor can be
o XID (an integer) of a cursor.
o "None" (or 0).
o "CurrentCursor" (or 1) for the currently displayed cursor.
This can be used to check that the cursor attribute of some $window
is a desired setting, for example
$desired_cursor = $X->new_rsrc;
$X->CreateGlyphCursor ($desired_cursor, ...);
$X->XTestCompareCursor ($window, $desired_cursor)
or die "Oops, $window doesn't have desired cursor";
Or alternatively, construct a window with a particular cursor and
use "CurrentCursor" to check that what's currently displayed is as
desired, for example to see if a "GrabPointer()" is displaying
what's intended,
my $test_window = $X->new_rsrc;
$X->CreateWindow ($test_window, ...,
cursor => $desired_cursor);
$X->XTestCompareCursor ($test_window, "CurrentCursor");
or die "Oops, currently displayed cursor is not as desired";
Simulated Input
"$X->XTestFakeInput (name=>...)"
"$X->XTestFakeInput ([ name=>... ])"
"$X->XTestFakeInput ([ name=>], [name=>], ...)"
Simulate user input for button presses, key presses, and pointer
movement.
An input action is specified as an event packet using fields
similar to "$X->pack_event()".
"XTestFakeInput()" is always a single user action, so for example a
button press and button release are two separate "XTestFakeInput()"
requests. For the core events a single event packet is enough to
describe an input but some extensions such as "XInputExtension" may
require more.
Button Press and Release
The argument fields are
name "ButtonPress" or "ButtonRelease"
detail physical button number (1 upwards)
time milliseconds delay before event, default 0
For example to fake a physical button 3 press
$X->XTestFakeInput (name => 'ButtonPress',
detail => 3);
"detail" is the physical button number, before the core
protocol "SetPointerMapping()" translation is applied. To
simulate a logical button it's necessary to check
"GetPointerMapping()" to see which physical button, if any,
corresponds.
Be careful when faking a "ButtonPress" as it might be important
to fake a matching "ButtonRelease" too. On the X.org server
circa 1.9.x after a synthetic press the physical mouse doesn't
work to generate a release and the button is left hung
(presumably in its normal implicit pointer grab).
Key Press and Release
The argument fields are
name "KeyPress" or "KeyRelease"
detail keycode (integer)
time milliseconds delay before event, default 0
Mouse Pointer Movement
Mouse pointer motion can be induced with the following. The
effect is similar to a "WarpPointer()".
name "MotionNotify"
root XID of root window, default "None" for current
root_x \ pointer position to move to
root_y /
detail flag 0=absolute, 1=relative, default 0
time milliseconds delay before event, default 0
"root" is the root window (integer XID) to move on. The
default "None" (or 0) means the screen the pointer is currently
on.
$X->XTestFakeInput (name => 'MotionNotify',
root_x => 123,
root_y => 456);
"detail" can be 1 to move relative to the current mouse
position.
$X->XTestFakeInput (name => 'MotionNotify',
root_x => 10,
root_y => -20,
detail => 1); # relative motion
Other Events
Extension events can be faked after an "init_extension()" so
they're recognised by "$X->pack_event()". It's up to the
server or extension which events can actually be simulated.
If an extension input requires more than one event packet to
describe then pass multiple arrayrefs. For example
"DeviceMotion" (from "XInputExtension") may need further
"DeviceValuator" packets,
$X->XTestFakeInput ([ name => 'DeviceMotion', ... ],
[ name => 'DeviceValuator', ... ],
[ name => 'DeviceValuator', ... ]);
For all events "time" is how long in milliseconds the server should
wait before playing the event. The default is 0 for no delay. No
further requests are processed from the current client during the
delay, so a sequence of "XTestFakeInput()" with delays will execute
sequentially with one delay after another.
Generally the event fields from a "$X->{'event_handler'}" function
cannot be passed directly to "XTestFakeInput()" to replay it. In
particular,
o "time" from an event is a timestamp, so would have to be zeroed
or adjusted to a relative time for a delay in
"XTestFakeInput()".
o For "MotionNotify", "detail" from an event is the hint
mechanism, so would have to be zeroed for the absolute/relative
flag in "XTestFakeInput()".
o For "ButtonPress" and "ButtonRelease", "detail" from an event
is a logical button number after "SetPointerMapping()"
transformation, whereas "XFakeInput()" takes a physical number.
A reverse lookup through the "GetPointerMapping()" table would
be needed.
GrabServer Imperviousness
"$X->XTestGrabControl ($impervious)"
Control the current client's behaviour during a "GrabServer()" by
another client.
If $impervious is 1 then the current client can continue to make
requests, ie. it's impervious to server grabs by other clients.
If $impervious is 0 then the current client behaves as normal. Its
requests wait during any "GrabServer()" by another client.
SEE ALSO
X11::Protocol(3), X11::Protocol::Ext::XInputExtension(3)
xdotool(1), X11::GUITest, Xlib XTestQueryExtension(3)
/usr/share/doc/x11proto-xext-dev/xtest.txt.gz,
/usr/share/X11/doc/hardcopy/Xext/xtest.PS.gz
HOME PAGE
<http://user42.tuxfamily.org/x11-protocol-other/index.html>
LICENSE
Copyright 2011, 2012, 2013, 2014 Kevin Ryde
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/>.
perl v5.28.1 2014-01-18 X11::Protocol::Ext::XTEST(3)
x11-protocol-other 30 - Generated Mon Feb 18 18:27:03 CST 2019