1X11::Protocol::Ext::XTEUSsTe(r3)Contributed Perl DocumenXt1a1t:i:oPnrotocol::Ext::XTEST(3)
2
3
4

NAME

6       X11::Protocol::Ext::XTEST - synthetic user input and more
7

SYNOPSIS

9        use X11::Protocol;
10        my $X = X11::Protocol->new;
11        $X->init_extension('XTEST')
12          or print "XTEST extension not available";
13
14        $X->XTestFakeInput (name   => 'ButtonPress',
15                            detail => 3);  # physical button 3
16        $X->XTestFakeInput (name   => 'ButtonRelease',
17                            detail => 3);
18

DESCRIPTION

20       The XTEST extension provides
21
22       •   Synthetic keyboard and mouse pointer actions.
23
24       •   Displayed cursor comparisons.
25
26       •   Test programs continuing during "GrabServer" by other clients.
27
28       These things help exercise library or server features which would
29       otherwise require user interaction.
30

REQUESTS

32       The following requests are made available with an "init_extension()",
33       as per "EXTENSIONS" in X11::Protocol.
34
35           my $is_available = $X->init_extension('XTEST');
36
37       "($server_major, $server_minor) = $X->XTestGetVersion ($client_major,
38       $client_minor)"
39           Negotiate a protocol version with the server.  $client_major and
40           $client_minor is what the client would like.  The returned
41           $server_major and $server_minor is what the server will do.
42
43           The current code supports up to 2.1.  The intention would be to
44           automatically negotiate in "init_extension()" if/when necessary.
45
46   Cursor Comparisons
47       "$is_same = $X->XTestCompareCursor ($window, $cursor)"
48           Return true if the cursor attribute of $window is equal to $cursor.
49           $cursor can be
50
51           •   XID (an integer) of a cursor.
52
53           •   "None" (or 0).
54
55           •   "CurrentCursor" (or 1) for the currently displayed cursor.
56
57           This can be used to check that the cursor attribute of some $window
58           is a desired setting, for example
59
60               $desired_cursor = $X->new_rsrc;
61               $X->CreateGlyphCursor ($desired_cursor, ...);
62
63               $X->XTestCompareCursor ($window, $desired_cursor)
64                 or die "Oops, $window doesn't have desired cursor";
65
66           Or alternatively, construct a window with a particular cursor and
67           use "CurrentCursor" to check that what's currently displayed is as
68           desired, for example to see if a "GrabPointer()" is displaying
69           what's intended,
70
71               my $test_window = $X->new_rsrc;
72               $X->CreateWindow ($test_window, ...,
73                                 cursor => $desired_cursor);
74
75               $X->XTestCompareCursor ($test_window, "CurrentCursor");
76                 or die "Oops, currently displayed cursor is not as desired";
77
78   Simulated Input
79       "$X->XTestFakeInput (name=>...)"
80       "$X->XTestFakeInput ([ name=>... ])"
81       "$X->XTestFakeInput ([ name=>], [name=>], ...)"
82           Simulate user input for button presses, key presses, and pointer
83           movement.
84
85           An input action is specified as an event packet using fields
86           similar to "$X->pack_event()".
87
88           "XTestFakeInput()" is always a single user action, so for example a
89           button press and button release are two separate "XTestFakeInput()"
90           requests.  For the core events a single event packet is enough to
91           describe an input but some extensions such as "XInputExtension" may
92           require more.
93
94           Button Press and Release
95               The argument fields are
96
97                   name       "ButtonPress" or "ButtonRelease"
98                   detail     physical button number (1 upwards)
99                   time       milliseconds delay before event, default 0
100
101               For example to fake a physical button 3 press
102
103                   $X->XTestFakeInput (name   => 'ButtonPress',
104                                       detail => 3);
105
106               "detail" is the physical button number, before the core
107               protocol "SetPointerMapping()" translation is applied.  To
108               simulate a logical button it's necessary to check
109               "GetPointerMapping()" to see which physical button, if any,
110               corresponds.
111
112               Be careful when faking a "ButtonPress" as it might be important
113               to fake a matching "ButtonRelease" too.  On the X.org server
114               circa 1.9.x after a synthetic press the physical mouse doesn't
115               work to generate a release and the button is left hung
116               (presumably in its normal implicit pointer grab).
117
118           Key Press and Release
119               The argument fields are
120
121                   name       "KeyPress" or "KeyRelease"
122                   detail     keycode (integer)
123                   time       milliseconds delay before event, default 0
124
125           Mouse Pointer Movement
126               Mouse pointer motion can be induced with the following.  The
127               effect is similar to a "WarpPointer()".
128
129                   name       "MotionNotify"
130                   root       XID of root window, default "None" for current
131                   root_x     \ pointer position to move to
132                   root_y     /
133                   detail     flag 0=absolute, 1=relative, default 0
134                   time       milliseconds delay before event, default 0
135
136               "root" is the root window (integer XID) to move on.  The
137               default "None" (or 0) means the screen the pointer is currently
138               on.
139
140                   $X->XTestFakeInput (name   => 'MotionNotify',
141                                       root_x => 123,
142                                       root_y => 456);
143
144               "detail" can be 1 to move relative to the current mouse
145               position.
146
147                   $X->XTestFakeInput (name   => 'MotionNotify',
148                                       root_x => 10,
149                                       root_y => -20,
150                                       detail => 1); # relative motion
151
152           Other Events
153               Extension events can be faked after an "init_extension()" so
154               they're recognised by "$X->pack_event()".  It's up to the
155               server or extension which events can actually be simulated.
156
157               If an extension input requires more than one event packet to
158               describe then pass multiple arrayrefs.  For example
159               "DeviceMotion" (from "XInputExtension") may need further
160               "DeviceValuator" packets,
161
162                   $X->XTestFakeInput ([ name => 'DeviceMotion', ... ],
163                                       [ name => 'DeviceValuator', ... ],
164                                       [ name => 'DeviceValuator',  ... ]);
165
166           For all events "time" is how long in milliseconds the server should
167           wait before playing the event.  The default is 0 for no delay.  No
168           further requests are processed from the current client during the
169           delay, so a sequence of "XTestFakeInput()" with delays will execute
170           sequentially with one delay after another.
171
172           Generally the event fields from a "$X->{'event_handler'}" function
173           cannot be passed directly to "XTestFakeInput()" to replay it.  In
174           particular,
175
176           •   "time" from an event is a timestamp, so would have to be zeroed
177               or adjusted to a relative time for a delay in
178               "XTestFakeInput()".
179
180           •   For "MotionNotify", "detail" from an event is the hint
181               mechanism, so would have to be zeroed for the absolute/relative
182               flag in "XTestFakeInput()".
183
184           •   For "ButtonPress" and "ButtonRelease", "detail" from an event
185               is a logical button number after "SetPointerMapping()"
186               transformation, whereas "XFakeInput()" takes a physical number.
187               A reverse lookup through the "GetPointerMapping()" table would
188               be needed.
189
190   GrabServer Imperviousness
191       "$X->XTestGrabControl ($impervious)"
192           Control the current client's behaviour during a "GrabServer()" by
193           another client.
194
195           If $impervious is 1 then the current client can continue to make
196           requests, ie. it's impervious to server grabs by other clients.
197
198           If $impervious is 0 then the current client behaves as normal.  Its
199           requests wait during any "GrabServer()" by another client.
200

SEE ALSO

202       X11::Protocol, X11::Protocol::Ext::XInputExtension
203
204       xdotool(1), X11::GUITest, Xlib XTestQueryExtension(3)
205
206       /usr/share/doc/x11proto-xext-dev/xtest.txt.gz,
207       /usr/share/X11/doc/hardcopy/Xext/xtest.PS.gz
208

HOME PAGE

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

LICENSE

213       Copyright 2011, 2012, 2013, 2014, 2017 Kevin Ryde
214
215       X11-Protocol-Other is free software; you can redistribute it and/or
216       modify it under the terms of the GNU General Public License as
217       published by the Free Software Foundation; either version 3, or (at
218       your option) any later version.
219
220       X11-Protocol-Other is distributed in the hope that it will be useful,
221       but WITHOUT ANY WARRANTY; without even the implied warranty of
222       MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
223       General Public License for more details.
224
225       You should have received a copy of the GNU General Public License along
226       with X11-Protocol-Other.  If not, see <http://www.gnu.org/licenses/>.
227
228
229
230perl v5.34.0                      2022-01-21      X11::Protocol::Ext::XTEST(3)
Impressum