1X11::Protocol::Ext::XTEUSsTe(r3)Contributed Perl DocumenXt1a1t:i:oPnrotocol::Ext::XTEST(3)
2
6 X11::Protocol::Ext::XTEST - synthetic user input and more
7
9 use X11::Protocol;
10 my $X = X11::Protocol->new;
11 $X->init_extension('XTEST')
12 or print "XTEST extension not available";
13 $X->XTestFakeInput (name => 'ButtonPress',
15 detail => 3); # physical button 3
16 $X->XTestFakeInput (name => 'ButtonRelease',
17 detail => 3);
18
20 The XTEST extension provides
21 • Synthetic keyboard and mouse pointer actions.
23 • Displayed cursor comparisons.
25 • Test programs continuing during "GrabServer" by other clients.
27 These things help exercise library or server features which would
29 otherwise require user interaction.
30
32 The following requests are made available with an "init_extension()",
33 as per "EXTENSIONS" in X11::Protocol.
34 my $is_available = $X->init_extension('XTEST');
36 "($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 The current code supports up to 2.1. The intention would be to
44 automatically negotiate in "init_extension()" if/when necessary.
45 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 • XID (an integer) of a cursor.
52 • "None" (or 0).
54 • "CurrentCursor" (or 1) for the currently displayed cursor.
56 This can be used to check that the cursor attribute of some $window
58 is a desired setting, for example
59 $desired_cursor = $X->new_rsrc;
61 $X->CreateGlyphCursor ($desired_cursor, ...);
62 $X->XTestCompareCursor ($window, $desired_cursor)
64 or die "Oops, $window doesn't have desired cursor";
65 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 my $test_window = $X->new_rsrc;
72 $X->CreateWindow ($test_window, ...,
73 cursor => $desired_cursor);
74 $X->XTestCompareCursor ($test_window, "CurrentCursor");
76 or die "Oops, currently displayed cursor is not as desired";
77 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 An input action is specified as an event packet using fields
86 similar to "$X->pack_event()".
87 "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 Button Press and Release
95 The argument fields are
96 name "ButtonPress" or "ButtonRelease"
98 detail physical button number (1 upwards)
99 time milliseconds delay before event, default 0
100 For example to fake a physical button 3 press
102 $X->XTestFakeInput (name => 'ButtonPress',
104 detail => 3);
105 "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 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 Key Press and Release
119 The argument fields are
120 name "KeyPress" or "KeyRelease"
122 detail keycode (integer)
123 time milliseconds delay before event, default 0
124 Mouse Pointer Movement
126 Mouse pointer motion can be induced with the following. The
127 effect is similar to a "WarpPointer()".
128 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 "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 $X->XTestFakeInput (name => 'MotionNotify',
141 root_x => 123,
142 root_y => 456);
143 "detail" can be 1 to move relative to the current mouse
145 position.
146 $X->XTestFakeInput (name => 'MotionNotify',
148 root_x => 10,
149 root_y => -20,
150 detail => 1); # relative motion
151 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 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 $X->XTestFakeInput ([ name => 'DeviceMotion', ... ],
163 [ name => 'DeviceValuator', ... ],
164 [ name => 'DeviceValuator', ... ]);
165 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 Generally the event fields from a "$X->{'event_handler'}" function
173 cannot be passed directly to "XTestFakeInput()" to replay it. In
174 particular,
175 • "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 • 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 • 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 GrabServer Imperviousness
191 "$X->XTestGrabControl ($impervious)"
192 Control the current client's behaviour during a "GrabServer()" by
193 another client.
194 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 If $impervious is 0 then the current client behaves as normal. Its
199 requests wait during any "GrabServer()" by another client.
200
202 X11::Protocol, X11::Protocol::Ext::XInputExtension
203 xdotool(1), X11::GUITest, Xlib XTestQueryExtension(3)
205 /usr/share/doc/x11proto-xext-dev/xtest.txt.gz,
207 /usr/share/X11/doc/hardcopy/Xext/xtest.PS.gz
208
210 <http://user42.tuxfamily.org/x11-protocol-other/index.html>
211
213 Copyright 2011, 2012, 2013, 2014, 2017 Kevin Ryde
214 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 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 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/>.
227perl v5.36.0 2022-07-22 X11::Protocol::Ext::XTEST(3)