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(), as
33 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 what's
69 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 XTestFakeInput().
178 • 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 • 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 GrabServer Imperviousness
190 "$X->XTestGrabControl ($impervious)"
191 Control the current client's behaviour during a GrabServer() by
192 another client.
193 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 If $impervious is 0 then the current client behaves as normal. Its
198 requests wait during any GrabServer() by another client.
199
201 X11::Protocol, X11::Protocol::Ext::XInputExtension
202 xdotool(1), X11::GUITest, Xlib XTestQueryExtension(3)
204 /usr/share/doc/x11proto-xext-dev/xtest.txt.gz,
206 /usr/share/X11/doc/hardcopy/Xext/xtest.PS.gz
207
209 <http://user42.tuxfamily.org/x11-protocol-other/index.html>
210
212 Copyright 2011, 2012, 2013, 2014, 2017 Kevin Ryde
213 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 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 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/>.
226perl v5.38.0 2023-07-21 X11::Protocol::Ext::XTEST(3)