Mercurial > repos > rliterman > csp2

comparison CSP2/CSP2_env/env-d9b9114564458d9d-741b3de822f2aaca6c6caa4325c4afce/share/doc/libXtst/xtestlib.xml @ 68:5028fdace37b

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
planemo upload commit 2e9511a184a1ca667c7be0c6321a36dc4e3d116d
author jpayne
date Tue, 18 Mar 2025 16:23:26 -0400
parents
children
comparison
equal deleted inserted replaced
67:0e9998148a16 68:5028fdace37b
1 <?xml version="1.0" encoding="UTF-8" ?>
2 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
3 "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd"
4 [
5 <!ENTITY % defs SYSTEM "defs.ent"> %defs;
6 ]>
7
8
9 <!-- lifted from troff+ms+XMan by doclifter -->
10 <book id="xtestlib">
11
12 <bookinfo>
13 <title>XTEST Extension Library</title>
14 <subtitle>X Consortium Standard</subtitle>
15 <releaseinfo>X Version 11, Release &fullrelvers;</releaseinfo>
16 <releaseinfo>Version 2.2</releaseinfo>
17 <authorgroup>
18 <author>
19 <firstname>Kieron</firstname><surname>Drake</surname>
20 <affiliation><orgname>UniSoft Ltd.</orgname></affiliation>
21 </author>
22 </authorgroup>
23 <copyright><year>1992</year><holder>UniSoft Group Ltd.</holder></copyright>
24
25 <legalnotice>
26 <para>
27 Permission to use, copy, modify, and distribute this documentation for
28 any purpose and without fee is hereby granted, provided that the above
29 copyright notice and this permission notice appear in all copies. UniSoft
30 makes no representations about the suitability for any purpose of the
31 information in this document. This documentation is provided
32 &ldquo;as is&rdquo; without express or implied warranty.
33 </para>
34 </legalnotice>
35
36 <legalnotice>
37 <para role="multiLicensing">Copyright © 1992,1994 X Consortium</para>
38 <para>
39 Permission is hereby granted, free of charge, to any person obtaining a copy
40 of this software and associated documentation files
41 (the &ldquo;Software&rdquo;), to deal in the Software without restriction,
42 including without limitation the rights to use, copy, modify, merge, publish,
43 distribute, sublicense, and/or sell copies of the Software, and to permit
44 persons to whom the Software is furnished to do so, subject to the following
45 conditions:
46 </para>
47 <para>
48 The above copyright notice and this permission notice shall be included in all
49 copies or substantial portions of the Software.
50 </para>
51 <para>
52 THE SOFTWARE IS PROVIDED &ldquo;AS IS&rdquo;, WITHOUT WARRANTY OF ANY KIND,
53 EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
54 MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN
55 NO EVENT SHALL THE X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
56 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
57 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
58 THE SOFTWARE.
59 </para>
60 <para>
61 Except as contained in this notice, the name of the X Consortium shall not
62 be used in advertising or otherwise to promote the sale, use or other dealings
63 in this Software without prior written authorization from the X Consortium.
64 </para>
65 <para>X Window System is a trademark of The Open Group.</para>
66 </legalnotice>
67 </bookinfo>
68
69 <chapter id='Overview'>
70 <title>Overview</title>
71
72 <para>
73 This extension is a minimal set of client and server extensions
74 required to completely test the X11 server with no user intervention.
75 </para>
76
77 <para>
78 This extension is not intended to support general journaling and
79 playback of user actions. This is a difficult area [XTrap, 89] as it attempts
80 to synchronize synthetic user interactions with their effects; it is at the
81 higher level of dialogue recording/playback rather than at the strictly lexical
82 level. We are interested only in the latter, simpler, case. A more detailed
83 discussion and justification of the extension functionality is given in
84 [Drake, 91].
85 </para>
86
87 <para>
88 We are aiming only to provide a minimum set of facilities that
89 solve immediate testing and validation problems. The testing extension
90 itself needs testing, where possible, and so should be as simple as possible.
91 </para>
92
93 <para>We have also tried to:</para>
94 <itemizedlist mark='bullet'>
95 <listitem>
96 <para>
97 Confine the extension to an appropriate high level
98 within the server to minimize portability problems. In practice this
99 means that the extension should be at the DIX level or use the
100 DIX/DDX interface, or both. This has effects, in particular, on the
101 level at which "input synthesis" can occur.
102 </para>
103 </listitem>
104 <listitem>
105 <para>
106 Minimize the changes required in the rest of the server.
107 </para>
108 </listitem>
109 <listitem>
110 <para>
111 Minimize performance penalties on normal server operation.
112 </para>
113 </listitem>
114 </itemizedlist>
115 </chapter>
116
117 <chapter id='Description'>
118 <title>Description</title>
119
120 <para>The functions provided by this extension fall into two groups:</para>
121
122 <itemizedlist>
123 <listitem>
124 <para>Client Operations</para>
125 <para>
126 These routines manipulate otherwise hidden client-side behavior.
127 The actual implementation will depend on the details of the actual language
128 binding and what degree of request buffering, GContext caching, and so on, is
129 provided. In the C binding, defined in section 7, routines are provided
130 to access the internals of two opaque data structures -
131 <symbol role='Pn'>GC</symbol>s
132 and
133 <function>Visual</function>s - and to discard any requests pending within the
134 output buffer of a connection. The exact details can be expected to differ for
135 other language bindings.
136 </para>
137 </listitem>
138 <listitem>
139 <para>Server Requests</para>
140 <para>
141 The first of these requests is similar to that provided in most
142 extensions: it allows a client to specify a major and minor version
143 number to the server and for the server to respond with major and minor
144 versions of its own. The remaining two requests allow the following:
145 </para>
146 </listitem>
147 <listitem>
148 <itemizedlist>
149 <listitem>
150 <para>
151 Access to an otherwise "write-only" server resource: the
152 cursor associated with a given window
153 </para>
154 </listitem>
155 <listitem>
156 <para>
157 Perhaps most importantly, limited synthesis of input
158 device events, almost as if a cooperative user had moved the pointing device
159 or pressed a key or button.
160 </para>
161 </listitem>
162 </itemizedlist>
163 </listitem>
164 </itemizedlist>
165 </chapter>
166
167 <chapter id='C_Language_Binding'>
168 <title>C Language Binding</title>
169
170 <para>
171 The C functions either provide direct access to the protocol and add no
172 additional semantics to those defined in section 5 or they correspond
173 directly to the abstract descriptions of client operations in section 4.
174 </para>
175
176 <para>
177 All XTEST extension functions and procedures, and all manifest constants
178 and macros, will start with the string "XTest". All operations are
179 classified as server/client (Server) or client-only (Client).
180 All routines that have return type Status will return nonzero for
181 "success" and zero for "failure." Even if the XTEST extension is
182 supported, the server may withdraw such facilities arbitrarily; in which case
183 they will subsequently return zero.
184 </para>
185
186 <para>
187 The include file for this extension is
188 &lt;<symbol role='Pn'>X11/extensions/XTest.h</symbol>&gt;.
189 </para>
190
191 <funcsynopsis id='XTestQueryExtension'>
192 <funcprototype>
193 <funcdef>Bool<function> XTestQueryExtension</function></funcdef>
194 <paramdef>Display<parameter> *display</parameter></paramdef>
195 <paramdef>int<parameter> *event_base</parameter></paramdef>
196 <paramdef>int<parameter> *error_base</parameter></paramdef>
197 <paramdef>int<parameter> *major_version</parameter></paramdef>
198 <paramdef>int<parameter> *minor_version</parameter></paramdef>
199 </funcprototype>
200 </funcsynopsis>
201
202 <para>
203 <xref linkend='XTestQueryExtension' xrefstyle='select: title'/>
204 returns
205 <function>True</function>
206 if the specified display supports the XTEST extension, else
207 <function>False</function>
208 If the extension is supported, *event_base would be set to the event number
209 for the first event for this extension and *error_base would be set to the
210 error number for the first error for this extension. As no errors or
211 events are defined for this version of the extension, the values returned
212 here are not defined (nor useful). If the extension is supported,
213 *major_version and *minor_version are set to the major and minor version
214 numbers of the extension supported by the display. Otherwise, none of
215 the arguments are set.
216 </para>
217
218 <funcsynopsis id='XTestCompareCursorWithWindow'>
219 <funcprototype>
220 <funcdef>Bool<function> XTestCompareCursorWithWindow</function></funcdef>
221 <paramdef>Display<parameter> *display</parameter></paramdef>
222 <paramdef>Window<parameter> *window</parameter></paramdef>
223 <paramdef>Cursor<parameter> cursor</parameter></paramdef>
224 </funcprototype>
225 </funcsynopsis>
226
227 <para>If the extension is supported,
228 <xref linkend='XTestCompareCursorWithWindow' xrefstyle='select: title'/>
229 performs a comparison of the cursor whose ID is specified by cursor (which
230 may be
231 <function>None</function>
232 with the cursor of the window specified by window returning
233 <function>True</function>
234 if they are the same and
235 <function>False</function>
236 otherwise. If the extension is not supported, then the request is ignored and
237 zero is returned.
238 </para>
239
240 <funcsynopsis id='XTestCompareCurrentCursorWithWindow'>
241 <funcprototype>
242 <funcdef>Bool<function>XTestCompareCurrentCursorWithWindow</function></funcdef>
243 <paramdef>Display<parameter> *display</parameter></paramdef>
244 <paramdef>Window<parameter> window</parameter></paramdef>
245 </funcprototype>
246 </funcsynopsis>
247
248 <para>If the extension is supported,
249 <xref linkend='XTestCompareCurrentCursorWithWindow' xrefstyle='select: title'/>
250 performs a comparison of the current cursor with the cursor of the specified
251 window returning
252 <function>True</function>
253 if they are the same and
254 <function>False</function>
255 otherwise. If the extension is not supported, then the request is ignored and
256 zero is returned.
257 </para>
258
259 <funcsynopsis id='XTestFakeKeyEvent'>
260 <funcprototype>
261 <funcdef><function>XTestFakeKeyEvent</function></funcdef>
262 <paramdef>Display<parameter> *display</parameter></paramdef>
263 <paramdef>unsigned int<parameter> keycode</parameter></paramdef>
264 <paramdef>Bool<parameter> is_press</parameter></paramdef>
265 <paramdef>unsigned long<parameter> delay</parameter></paramdef>
266 </funcprototype>
267 </funcsynopsis>
268
269 <para>If the extension is supported,
270 <xref linkend='XTestFakeKeyEvent' xrefstyle='select: title'/>
271 requests the server to simulate either a
272 <function>KeyPress</function>
273 (if is_press is
274 <function>True</function>
275 or a
276 <function>KeyRelease</function>
277 (if is_press is
278 <function>False</function>
279 of the key with the specified keycode; otherwise, the request is ignored.
280 </para>
281
282 <para>
283 If the extension is supported, the simulated event will not be processed
284 until delay milliseconds after the request is received (if delay is
285 <function>CurrentTime</function>
286 then this is interpreted as no delay at all). No other requests from
287 this client will be processed until this delay, if any, has expired
288 and subsequent processing of the simulated event has been completed.
289 </para>
290
291 <funcsynopsis id='XTestFakeButtonEvent'>
292 <funcprototype>
293 <funcdef><function>XTestFakeButtonEvent</function></funcdef>
294 <paramdef>Display<parameter> *display</parameter></paramdef>
295 <paramdef>unsigned int<parameter> button</parameter></paramdef>
296 <paramdef>Bool<parameter> is_press</parameter></paramdef>
297 <paramdef>unsigned long<parameter> delay</parameter></paramdef>
298 </funcprototype>
299 </funcsynopsis>
300
301 <para>If the extension is supported,
302 <xref linkend='XTestFakeButtonEvent' xrefstyle='select: title'/>
303 requests the server to simulate either a
304 <function>ButtonPress</function>
305 (if is_press is
306 <function>True</function>
307 or a
308 <function>ButtonRelease</function>
309 (if is_press is
310 <function>False</function>
311 of the logical button numbered by the specified button; otherwise, the
312 request is ignored.
313 </para>
314
315 <para>If the extension is supported,
316 the simulated event will not be processed until delay milliseconds
317 after the request is received (if delay is
318 <function>CurrentTime</function>
319 then this is interpreted as no delay at all). No other requests from
320 this client will be processed until this delay, if any, has expired
321 and subsequent processing of the simulated event has been completed.
322 </para>
323
324 <funcsynopsis id='XTestFakeMotionEvent'>
325 <funcprototype>
326 <funcdef><function>XTestFakeMotionEvent</function></funcdef>
327 <paramdef>Display<parameter> *display</parameter></paramdef>
328 <paramdef>int<parameter> screen_number</parameter></paramdef>
329 <paramdef>int<parameter> x</parameter></paramdef>
330 <paramdef>int<parameter> y</parameter></paramdef>
331 <paramdef>unsigned long<parameter> delay</parameter></paramdef>
332 </funcprototype>
333 </funcsynopsis>
334
335 <para>If the extension is supported,
336 <xref linkend='XTestFakeMotionEvent' xrefstyle='select: title'/>
337 requests the server to simulate a movement of the pointer to the specified
338 position (x, y) on the root window of screen_number; otherwise, the request
339 is ignored. If screen_number is -1, the current screen (that the pointer
340 is on) is used.
341 </para>
342
343 <para>
344 If the extension is supported, the simulated event will not be processed
345 until delay milliseconds after the request is received (if delay is
346 <function>CurrentTime</function>
347 then this is interpreted as no delay at all). No other requests from
348 this client will be processed until this delay, if any, has expired
349 and subsequent processing of the simulated event has been completed.
350 </para>
351
352 <funcsynopsis id='XTestFakeRelativeMotionEvent'>
353 <funcprototype>
354 <funcdef><function>XTestFakeRelativeMotionEvent</function></funcdef>
355 <paramdef>Display<parameter> *display</parameter></paramdef>
356 <paramdef>int<parameter> screen_number</parameter></paramdef>
357 <paramdef>int<parameter> x</parameter></paramdef>
358 <paramdef>int<parameter> y</parameter></paramdef>
359 <paramdef>unsigned long<parameter> delay</parameter></paramdef>
360 </funcprototype>
361 </funcsynopsis>
362
363 <para>
364 If the extension is supported,
365 <xref linkend='XTestFakeRelativeMotionEvent' xrefstyle='select: title'/>
366 requests the server to simulate a movement of the pointer by the specified
367 offsets (x, y) relative to the current pointer position on screen_number;
368 otherwise, the request is ignored. If screen_number is -1, the
369 current screen (that the pointer is on) is used.
370 </para>
371
372 <para>
373 If the extension is supported, the simulated event will not be processed
374 until delay milliseconds after the request is received (if delay is
375 <function>CurrentTime</function>
376 then this is interpreted as no delay at all). No other requests from
377 this client will be processed until this delay, if any, has expired
378 and subsequent processing of the simulated event has been completed.
379 </para>
380
381 <funcsynopsis id='XTestGrabControl'>
382 <funcprototype>
383 <funcdef><function>XTestGrabControl</function></funcdef>
384 <paramdef>Display<parameter> *display</parameter></paramdef>
385 <paramdef>Bool<parameter> impervious</parameter></paramdef>
386 </funcprototype>
387 </funcsynopsis>
388
389 <para>If impervious is
390 <function>True</function>
391 then the executing client becomes impervious to server grabs. If impervious is
392 <function>False</function>
393 then the executing client returns to the normal state of being susceptible
394 to server grabs.
395 </para>
396
397 <funcsynopsis id='XTestSetGContextOfGC'>
398 <funcprototype>
399 <funcdef>Bool<function> XTestSetGContextOfGC</function></funcdef>
400 <paramdef>GC<parameter> gc</parameter></paramdef>
401 <paramdef>GContext<parameter> gid</parameter></paramdef>
402 </funcprototype>
403 </funcsynopsis>
404
405 <para>
406 <xref linkend='XTestSetGContextOfGC' xrefstyle='select: title'/>
407 sets the GContext within the opaque datatype referenced by gc to
408 be that specified by gid.
409 </para>
410
411 <funcsynopsis id='XTestSetVisualIDOfVisual'>
412 <funcprototype>
413 <funcdef><function>XTestSetVisualIDOfVisual</function></funcdef>
414 <paramdef>Visual<parameter> *visual</parameter></paramdef>
415 <paramdef>VisualID<parameter> visualid</parameter></paramdef>
416 </funcprototype>
417 </funcsynopsis>
418
419 <para>
420 <xref linkend='XTestSetVisualIDOfVisual' xrefstyle='select: title'/>
421 sets the VisualID within the opaque datatype referenced by visual to
422 be that specified by visualid.
423 </para>
424
425 <funcsynopsis id='XTestDiscard'>
426 <funcprototype>
427 <funcdef>Bool<function> XTestDiscard</function></funcdef>
428 <paramdef>Display<parameter> *display</parameter></paramdef>
429 </funcprototype>
430 </funcsynopsis>
431
432 <para>
433 <xref linkend='XTestDiscard' xrefstyle='select: title'/>
434 discards any requests within the output buffer for the specified display.
435 It returns
436 <function>True</function>
437 if any requests were discarded; otherwise, it returns
438 <function>False</function>
439 </para>
440 </chapter>
441
442 <chapter id='References'>
443 <title>References</title>
444
445 <para>
446 Annicchiarico, D., et al., <emphasis remap='I'>XTrap: The XTrap
447 Architecture</emphasis>.
448 Digital Equipment Corporation, July 1991.
449 </para>
450
451 <para>
452 Drake, K. J., <emphasis remap='I'>Some Proposals for a Minimum X11
453 Testing Extension</emphasis>.
454 UniSoft Ltd., June 1991.
455 </para>
456
457 </chapter>
458 </book>