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(), as
33       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 what's
69           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 XTestFakeInput().
178
179           •   For "MotionNotify", "detail" from an event is the hint
180               mechanism, so would have to be zeroed for the absolute/relative
181               flag in XTestFakeInput().
182
183           •   For "ButtonPress" and "ButtonRelease", "detail" from an event
184               is a logical button number after SetPointerMapping()
185               transformation, whereas XFakeInput() takes a physical number.
186               A reverse lookup through the GetPointerMapping() table would be
187               needed.
188
189   GrabServer Imperviousness
190       "$X->XTestGrabControl ($impervious)"
191           Control the current client's behaviour during a GrabServer() by
192           another client.
193
194           If $impervious is 1 then the current client can continue to make
195           requests, ie. it's impervious to server grabs by other clients.
196
197           If $impervious is 0 then the current client behaves as normal.  Its
198           requests wait during any GrabServer() by another client.
199

SEE ALSO

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

HOME PAGE

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

LICENSE

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