1<?xml version="1.0" encoding="UTF-8"?>
2<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
3                   "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">
4<!-- lifted from troff+man by doclifter -->
5<refentry id='XTest.man'>
6<!--
7Copyright &copy; 1992 by UniSoft Group Ltd.
8Permission to use, copy, modify, and distribute this documentation for
9any purpose and without fee is hereby granted, provided that the above
10copyright notice and this permission notice appear in all copies.
11UniSoft makes no representations about the suitability for any purpose of
12the information in this document.  This documentation is provided "as is"
13without express or implied warranty.
14
15Copyright &copy; 1992, 1994 X Consortium
16
17Permission is hereby granted, free of charge, to any person obtaining a
18copy of this software and associated documentation files (the "Software"),
19to deal in the Software without restriction, including without limitation
20the rights to use, copy, modify, merge, publish, distribute, sublicense,
21and/or sell copies of the Software, and to permit persons to whom the
22Software is furnished to do so, subject to the following conditions:
23
24The above copyright notice and this permission notice shall be included in
25all copies or substantial portions of the Software.
26
27THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
28IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
29FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL
30THE X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
31WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF
32OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
33SOFTWARE.
34
35Except as contained in this notice, the name of the X Consortium shall not
36be used in advertising or otherwise to promote the sale, use or other
37dealings in this Software without prior written authorization from the
38X Consortium.
39 -->
40
41<!-- edited for DP edits and code consistency w/ core protocol/xlib 4/2/96 -->
42<!-- Converted from xorg-docs/specs/Xext/xtestlib.ms 6/6/07 -->
43 <refentryinfo>
44  <productname>__vendorversion__</productname>
45  <pubdate>6 June 2007</pubdate>
46   <author><firstname>Kieron</firstname><surname>Drake</surname>
47   <affiliation><orgname>UniSoft Ltd.</orgname></affiliation>
48   </author>
49 </refentryinfo>
50<refmeta>
51<refentrytitle>XTest</refentrytitle>
52<manvolnum>__libmansuffix__</manvolnum>
53<refmiscinfo class='source'>__xorgversion__</refmiscinfo>
54<refmiscinfo class='manual'>XTST FUNCTIONS</refmiscinfo>
55</refmeta>
56<refnamediv id='name'>
57<refname>XTestQueryExtension</refname>
58<refname>XTestCompareCursorWithWindow</refname>
59<refname>XTestCompareCurrentCursorWithWindow</refname>
60<refname>XTestFakeKeyEvent</refname>
61<refname>XTestFakeButtonEvent</refname>
62<refname>XTestFakeMotionEvent</refname>
63<refname>XTestFakeRelativeMotionEvent</refname>
64<refname>XTestGrabControl</refname>
65<refname>XTestSetGContextOfGC</refname>
66<refname>XTestSetVisualIDOfVisual</refname>
67<refname>XTestDiscard</refname>
68<refpurpose>XTest extension functions</refpurpose>
69</refnamediv>
70<!-- body begins here -->
71<refsynopsisdiv id='synopsis'>
72<funcsynopsis>
73<funcsynopsisinfo>
74cc [ flag ... ] file ... -lXtst  [ library ... ]
75</funcsynopsisinfo>
76<funcsynopsisinfo>
77#include &lt;X11/extensions/XTest.h&gt;
78</funcsynopsisinfo>
79<funcprototype>
80<funcdef><function>Bool</function> XTestQueryExtension</funcdef>
81<paramdef><parameter>display</parameter></paramdef>
82<paramdef><parameter>event_base_return</parameter></paramdef>
83<paramdef><parameter>error_base_return</parameter></paramdef>
84<paramdef><parameter>major_version_return</parameter></paramdef>
85<paramdef><parameter>minor_version_return</parameter></paramdef>
86</funcprototype>
87<funcsynopsisinfo>
88 Display *display;
89 int *event_base_return;
90 int *error_base_return;
91 int *major_version_return;
92 int *minor_version_return;
93</funcsynopsisinfo>
94<funcprototype>
95<funcdef><function>Bool</function> XTestCompareCursorWithWindow</funcdef>
96<paramdef><parameter>display</parameter></paramdef>
97<paramdef><parameter>window</parameter></paramdef>
98<paramdef><parameter>cursor</parameter></paramdef>
99</funcprototype>
100<funcsynopsisinfo>
101 Display *display;
102 Window window;
103 Cursor cursor;
104</funcsynopsisinfo>
105<funcprototype>
106<funcdef><function>Bool</function> XTestCompareCurrentCursorWithWindow</funcdef>
107<paramdef><parameter>display</parameter></paramdef>
108<paramdef><parameter>window</parameter></paramdef>
109</funcprototype>
110<funcsynopsisinfo>
111 Display *display;
112 Window window;
113</funcsynopsisinfo>
114<funcprototype>
115<funcdef>int <function>XTestFakeKeyEvent</function></funcdef>
116<paramdef><parameter>display</parameter></paramdef>
117<paramdef><parameter>keycode</parameter></paramdef>
118<paramdef><parameter>is_press</parameter></paramdef>
119<paramdef><parameter>delay</parameter></paramdef>
120</funcprototype>
121<funcsynopsisinfo>
122 Display *display;
123 unsigned int keycode;
124 Bool is_press;
125 unsigned long delay;
126</funcsynopsisinfo>
127<funcprototype>
128<funcdef>int <function>XTestFakeButtonEvent</function></funcdef>
129<paramdef><parameter>display</parameter></paramdef>
130<paramdef><parameter>button</parameter></paramdef>
131<paramdef><parameter>is_press</parameter></paramdef>
132<paramdef><parameter>delay</parameter></paramdef>
133</funcprototype>
134<funcsynopsisinfo>
135 Display *display;
136 unsigned int button;
137 Bool is_press;
138 unsigned long delay;
139</funcsynopsisinfo>
140<funcprototype>
141<funcdef>int <function>XTestFakeMotionEvent</function></funcdef>
142<paramdef><parameter>display</parameter></paramdef>
143<paramdef><parameter>screen_number</parameter></paramdef>
144<paramdef><parameter>x</parameter></paramdef>
145<paramdef><parameter>y</parameter></paramdef>
146<paramdef><parameter>delay</parameter></paramdef>
147</funcprototype>
148<funcsynopsisinfo>
149 Display *display;
150 int screen_number;
151 int x, y;
152 unsigned long delay;
153</funcsynopsisinfo>
154<funcprototype>
155<funcdef>int <function>XTestFakeRelativeMotionEvent</function></funcdef>
156<paramdef><parameter>display</parameter></paramdef>
157<paramdef><parameter>screen_number</parameter></paramdef>
158<paramdef><parameter>x</parameter></paramdef>
159<paramdef><parameter>y</parameter></paramdef>
160<paramdef><parameter>delay</parameter></paramdef>
161</funcprototype>
162<funcsynopsisinfo>
163 Display *display;
164 int screen_number;
165 int x, y;
166 unsigned long delay;
167</funcsynopsisinfo>
168<funcprototype>
169<funcdef>int <function>XTestGrabControl</function></funcdef>
170<paramdef><parameter>display</parameter></paramdef>
171<paramdef><parameter>impervious</parameter></paramdef>
172</funcprototype>
173<funcsynopsisinfo>
174 Display *display;
175 Bool impervious;
176</funcsynopsisinfo>
177<funcprototype>
178<funcdef>void <function>XTestSetGContextOfGC</function></funcdef>
179<paramdef><parameter>gc</parameter></paramdef>
180<paramdef><parameter>gid</parameter></paramdef>
181</funcprototype>
182<funcsynopsisinfo>
183 GC gc;
184 GContext gid;
185</funcsynopsisinfo>
186<funcprototype>
187<funcdef>void <function>XTestSetVisualIDOfVisual</function></funcdef>
188<paramdef><parameter>visual</parameter></paramdef>
189<paramdef><parameter>visualid</parameter></paramdef>
190</funcprototype>
191<funcsynopsisinfo>
192 Visual *visual;
193 VisualID visualid;
194</funcsynopsisinfo>
195<funcprototype>
196<funcdef><function>Status</function> XTestDiscard</funcdef>
197<paramdef><parameter>display</parameter></paramdef>
198</funcprototype>
199<funcsynopsisinfo>
200 Display *display;
201</funcsynopsisinfo>
202</funcsynopsis>
203</refsynopsisdiv>
204
205
206<refsect1 id='description'><title>DESCRIPTION</title>
207<para>This extension is a minimal set of client and server extensions
208required to completely test the X11 server with no user intervention.
209This extension is not intended to support general journaling and
210playback of user actions.</para>
211
212<para>The functions provided by this extension fall into two groups:</para>
213<variablelist remap='IP'>
214  <varlistentry>
215  <term><emphasis remap='B'>Client Operations</emphasis></term>
216  <listitem>
217<para>These routines manipulate otherwise hidden client-side behavior.  The
218actual implementation will depend on the details of the actual language
219binding and what degree of request buffering, GContext caching, and so on, is
220provided.  In the C binding, routines are provided
221to access the internals of two opaque data structures
222&mdash; <structname>GC</structname>s
223and
224<structname>Visual</structname>s &mdash;
225and to discard any requests pending within the
226output buffer of a connection.  The exact details can be expected to differ for
227other language bindings.</para>
228  </listitem>
229  </varlistentry>
230  <varlistentry>
231  <term><emphasis remap='B'>Server Requests</emphasis></term>
232  <listitem>
233<para>The first of these requests is similar to that provided in most
234extensions: it allows a client to specify a major and minor version
235number to the server and for the server to respond with major and minor
236versions of its own.  The remaining two requests allow the following:</para>
237 <itemizedlist>
238  <listitem>
239<para>Access to an otherwise <emphasis>write-only</emphasis> server resource:
240the cursor associated with a given window</para>
241  </listitem>
242  <listitem>
243<para>Perhaps most importantly, limited synthesis of input device events,
244almost as if a cooperative user had moved the pointing device
245or pressed a key or button.</para>
246  </listitem>
247 </itemizedlist>
248  </listitem>
249  </varlistentry>
250</variablelist>
251
252<para>All XTEST extension functions and procedures, and all manifest
253constants and macros, will start with the string <emphasis>XTest</emphasis>.
254All operations are classified as
255server/client (Server) or client-only (Client).</para>
256
257<para><function>XTestQueryExtension</function>
258returns
259<returnvalue>True</returnvalue>
260if the specified display supports the XTEST extension, else
261<returnvalue>False</returnvalue>.
262If the extension is supported, *event_base would be set to the event number for
263the first event for this extension and
264*error_base would be set to the error number for the first error for
265this extension.  As no errors or events are defined for this version of the extension,
266the values returned here are not defined (nor useful).
267If the extension is supported, *major_version and *minor_version are set to
268the major and minor version numbers of the extension supported by the
269display.  Otherwise, none of the arguments are set.</para>
270
271
272<para>If the extension is supported,
273<function>XTestCompareCursorWithWindow</function>
274performs a comparison of the cursor
275whose ID is specified by cursor (which may be
276<emphasis remap='B'>None</emphasis>)
277with the cursor of the window specified by window returning
278<returnvalue>True</returnvalue>
279if they are the same and
280<returnvalue>False</returnvalue>
281otherwise.
282If the extension is not supported, then the request is ignored and
283zero is returned.</para>
284
285
286<para>If the extension is supported,
287<function>XTestCompareCurrentCursorWithWindow</function>
288performs a comparison of the current cursor
289with the cursor of the specified window returning
290<returnvalue>True</returnvalue>
291if they are the same and
292<returnvalue>False</returnvalue>
293otherwise.
294If the extension is not supported, then the request is ignored and
295zero is returned.</para>
296
297
298<para>If the extension is supported,
299<function>XTestFakeKeyEvent</function>
300requests the server to simulate either a
301<emphasis remap='B'>KeyPress</emphasis>
302(if is_press is
303<returnvalue>True</returnvalue>)
304or a
305<emphasis remap='B'>KeyRelease</emphasis>
306(if is_press is
307<returnvalue>False</returnvalue>)
308of the key with the specified keycode;
309otherwise, the request is ignored.</para>
310
311<para>If the extension is supported,
312the simulated event will not be processed until delay milliseconds
313after the request is received (if delay is
314<emphasis remap='B'>CurrentTime</emphasis>,
315then this is interpreted as no delay at all).  No other requests from
316this client will be processed until this delay, if any, has expired
317and subsequent processing of the simulated event has been completed.</para>
318
319
320<para>If the extension is supported,
321<function>XTestFakeButtonEvent</function>
322requests the server to simulate either
323a
324<emphasis remap='B'>ButtonPress</emphasis>
325(if is_press is
326<returnvalue>True</returnvalue>)
327or a
328<emphasis remap='B'>ButtonRelease</emphasis>
329(if is_press is
330<returnvalue>False</returnvalue>)
331of the logical button numbered by the specified button;
332otherwise, the request is ignored.</para>
333
334<para>If the extension is supported,
335the simulated event will not be processed until delay milliseconds
336after the request is received (if delay is
337<emphasis remap='B'>CurrentTime</emphasis>,
338then this is interpreted as no delay at all).  No other requests from
339this client will be processed until this delay, if any, has expired
340and subsequent processing of the simulated event has been completed.</para>
341
342
343<para>If the extension is supported,
344<function>XTestFakeMotionEvent</function>
345requests the server to simulate
346a movement of the pointer to the specified position (x, y) on the
347root window of screen_number;
348otherwise, the request is ignored.  If screen_number is -1, the
349current screen (that the pointer is on) is used.</para>
350
351<para>If the extension is supported,
352the simulated event will not be processed until delay milliseconds
353after the request is received (if delay is
354<emphasis remap='B'>CurrentTime</emphasis>,
355then this is interpreted as no delay at all).  No other requests from
356this client will be processed until this delay, if any, has expired
357and subsequent processing of the simulated event has been completed.</para>
358
359
360<para>If the extension is supported,
361<function>XTestFakeRelativeMotionEvent</function>
362requests the server to simulate
363a movement of the pointer by the specified offsets (x, y) relative
364to the current pointer position on screen_number;
365otherwise, the request is ignored.  If screen_number is -1, the
366current screen (that the pointer is on) is used.</para>
367
368<para>If the extension is supported,
369the simulated event will not be processed until delay milliseconds
370after the request is received (if delay is
371<emphasis remap='B'>CurrentTime</emphasis>,
372then this is interpreted as no delay at all).  No other requests from
373this client will be processed until this delay, if any, has expired
374and subsequent processing of the simulated event has been completed.</para>
375
376
377
378<para>If impervious is
379<returnvalue>True</returnvalue>,
380then the executing client becomes impervious to server grabs.
381If impervious is
382<returnvalue>False</returnvalue>,
383then the executing client returns to the normal state of being
384susceptible to server grabs.</para>
385
386
387<para><function>XTestSetGContextOfGC</function>
388sets the GContext within the opaque datatype referenced by gc to
389be that specified by gid.</para>
390
391
392<para><function>XTestSetVisualIDOfVisual</function>
393sets the VisualID within the opaque datatype referenced by visual to
394be that specified by visualid.</para>
395
396
397<para><function>XTestDiscard</function>
398discards any requests within the output buffer for the specified display.
399It returns
400<returnvalue>True</returnvalue>
401if any requests were discarded; otherwise, it returns
402<returnvalue>False</returnvalue>.</para>
403
404</refsect1>
405
406<refsect1 id='return_values'><title>RETURN VALUES</title>
407<para>All routines that have return type Status will return nonzero for
408success and zero for failure.  Even if the XTEST extension is
409supported, the server may withdraw such facilities arbitrarily; in which case
410they will subsequently return zero.</para>
411</refsect1>
412</refentry>
413
414