jpayne@68: <?xml version="1.0" encoding="UTF-8" ?>
jpayne@68: <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
jpayne@68:                    "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd"
jpayne@68: [
jpayne@68: <!ENTITY % defs SYSTEM "defs.ent"> %defs;
jpayne@68: ]>
jpayne@68: 
jpayne@68: 
jpayne@68: <!-- lifted from troff+ms+XMan by doclifter -->
jpayne@68: <book id="xtestlib">
jpayne@68: 
jpayne@68: <bookinfo>
jpayne@68:    <title>XTEST Extension Library</title>
jpayne@68:    <subtitle>X Consortium Standard</subtitle>
jpayne@68:    <releaseinfo>X Version 11, Release &fullrelvers;</releaseinfo>
jpayne@68:    <releaseinfo>Version 2.2</releaseinfo>
jpayne@68:    <authorgroup>
jpayne@68:       <author>
jpayne@68:          <firstname>Kieron</firstname><surname>Drake</surname>
jpayne@68:          <affiliation><orgname>UniSoft Ltd.</orgname></affiliation>
jpayne@68:       </author>
jpayne@68:    </authorgroup>
jpayne@68:    <copyright><year>1992</year><holder>UniSoft Group Ltd.</holder></copyright>
jpayne@68: 
jpayne@68: <legalnotice>
jpayne@68: <para>
jpayne@68: Permission to use, copy, modify, and distribute this documentation for
jpayne@68: any purpose and without fee is hereby granted, provided that the above
jpayne@68: copyright notice and this permission notice appear in all copies.  UniSoft
jpayne@68: makes no representations about the suitability for any purpose of the
jpayne@68: information in this document.  This documentation is provided
jpayne@68: &ldquo;as is&rdquo; without express or implied warranty.
jpayne@68: </para>
jpayne@68: </legalnotice>
jpayne@68: 
jpayne@68: <legalnotice>
jpayne@68: <para role="multiLicensing">Copyright © 1992,1994 X Consortium</para>
jpayne@68: <para>
jpayne@68: Permission is hereby granted, free of charge, to any person obtaining a copy
jpayne@68: of this software and associated documentation files
jpayne@68: (the &ldquo;Software&rdquo;), to deal in the Software without restriction,
jpayne@68: including without limitation the rights to use, copy, modify, merge, publish,
jpayne@68: distribute, sublicense, and/or sell copies of the Software, and to permit
jpayne@68: persons to whom the Software is furnished to do so, subject to the following
jpayne@68: conditions:
jpayne@68: </para>
jpayne@68: <para>
jpayne@68: The above copyright notice and this permission notice shall be included in all
jpayne@68: copies or substantial portions of the Software.
jpayne@68: </para>
jpayne@68: <para>
jpayne@68: THE SOFTWARE IS PROVIDED &ldquo;AS IS&rdquo;, WITHOUT WARRANTY OF ANY KIND,
jpayne@68: EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
jpayne@68: MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN
jpayne@68: NO EVENT SHALL THE X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
jpayne@68: LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
jpayne@68: OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
jpayne@68: THE SOFTWARE.
jpayne@68: </para>
jpayne@68: <para>
jpayne@68: Except as contained in this notice, the name of the X Consortium shall not
jpayne@68: be used in advertising or otherwise to promote the sale, use or other dealings
jpayne@68: in this Software without prior written authorization from the X Consortium.
jpayne@68: </para>
jpayne@68: <para>X Window System is a trademark of The Open Group.</para>
jpayne@68: </legalnotice>
jpayne@68: </bookinfo>
jpayne@68: 
jpayne@68: <chapter id='Overview'>
jpayne@68: <title>Overview</title>
jpayne@68: 
jpayne@68: <para>
jpayne@68: This extension is a minimal set of client and server extensions
jpayne@68: required to completely test the X11 server with no user intervention.
jpayne@68: </para>
jpayne@68: 
jpayne@68: <para>
jpayne@68: This extension is not intended to support general journaling and
jpayne@68: playback of user actions.  This is a difficult area [XTrap, 89] as it attempts
jpayne@68: to synchronize synthetic user interactions with their effects; it is at the
jpayne@68: higher level of dialogue recording/playback rather than at the strictly lexical
jpayne@68: level.  We are interested only in the latter, simpler, case.  A more detailed
jpayne@68: discussion and justification of the extension functionality is given in
jpayne@68: [Drake, 91].
jpayne@68: </para>
jpayne@68: 
jpayne@68: <para>
jpayne@68: We are aiming only to provide a minimum set of facilities that
jpayne@68: solve immediate testing and validation problems.  The testing extension
jpayne@68: itself needs testing, where possible, and so should be as simple as possible.
jpayne@68: </para>
jpayne@68: 
jpayne@68: <para>We have also tried to:</para>
jpayne@68: <itemizedlist mark='bullet'>
jpayne@68:   <listitem>
jpayne@68:     <para>
jpayne@68: Confine the extension to an appropriate high level
jpayne@68: within the server to minimize portability problems.  In practice this
jpayne@68: means that the extension should be at the DIX level or use the
jpayne@68: DIX/DDX interface, or both.  This has effects, in particular, on the
jpayne@68: level at which "input synthesis" can occur.
jpayne@68:     </para>
jpayne@68:   </listitem>
jpayne@68:   <listitem>
jpayne@68:     <para>
jpayne@68: Minimize the changes required in the rest of the server.
jpayne@68:     </para>
jpayne@68:   </listitem>
jpayne@68:   <listitem>
jpayne@68:     <para>
jpayne@68: Minimize performance penalties on normal server operation.
jpayne@68:     </para>
jpayne@68:   </listitem>
jpayne@68: </itemizedlist>
jpayne@68: </chapter>
jpayne@68: 
jpayne@68: <chapter id='Description'>
jpayne@68: <title>Description</title>
jpayne@68: 
jpayne@68: <para>The functions provided by this extension fall into two groups:</para>
jpayne@68: 
jpayne@68: <itemizedlist>
jpayne@68:     <listitem>
jpayne@68:       <para>Client Operations</para>
jpayne@68:       <para>
jpayne@68: These routines manipulate otherwise hidden client-side behavior.
jpayne@68: The actual implementation will depend on the details of the actual language
jpayne@68: binding and what degree of request buffering, GContext caching, and so on, is
jpayne@68: provided.  In the C binding, defined in section 7, routines are provided
jpayne@68: to access the internals of two opaque data structures -
jpayne@68: <symbol role='Pn'>GC</symbol>s
jpayne@68: and
jpayne@68: <function>Visual</function>s - and to discard any requests pending within the
jpayne@68: output buffer of a connection.  The exact details can be expected to differ for
jpayne@68: other language bindings.
jpayne@68:       </para>
jpayne@68:     </listitem>
jpayne@68:     <listitem>
jpayne@68:       <para>Server Requests</para>
jpayne@68:       <para>
jpayne@68: The first of these requests is similar to that provided in most
jpayne@68: extensions: it allows a client to specify a major and minor version
jpayne@68: number to the server and for the server to respond with major and minor
jpayne@68: versions of its own.  The remaining two requests allow the following:
jpayne@68:       </para>
jpayne@68:     </listitem>
jpayne@68:     <listitem>
jpayne@68:       <itemizedlist>
jpayne@68:         <listitem>
jpayne@68:           <para>
jpayne@68: Access to an otherwise "write-only" server resource: the
jpayne@68: cursor associated with a given window
jpayne@68:           </para>
jpayne@68:         </listitem>
jpayne@68:         <listitem>
jpayne@68:           <para>
jpayne@68: Perhaps most importantly, limited synthesis of input
jpayne@68: device events, almost as if a cooperative user had moved the pointing device
jpayne@68: or pressed a key or button.
jpayne@68:           </para>
jpayne@68:         </listitem>
jpayne@68:       </itemizedlist>
jpayne@68:     </listitem>
jpayne@68: </itemizedlist>
jpayne@68: </chapter>
jpayne@68: 
jpayne@68: <chapter id='C_Language_Binding'>
jpayne@68: <title>C Language Binding</title>
jpayne@68: 
jpayne@68: <para>
jpayne@68: The C functions either provide direct access to the protocol and add no
jpayne@68: additional semantics to those defined in section 5 or they correspond
jpayne@68: directly to the abstract descriptions of client operations in section 4.
jpayne@68: </para>
jpayne@68: 
jpayne@68: <para>
jpayne@68: All XTEST extension functions and procedures, and all manifest constants
jpayne@68: and macros, will start with the string "XTest".  All operations are
jpayne@68: classified as server/client (Server) or client-only (Client).
jpayne@68: All routines that have return type Status will return nonzero for
jpayne@68: "success" and zero for "failure."  Even if the XTEST extension is
jpayne@68: supported, the server may withdraw such facilities arbitrarily; in which case
jpayne@68: they will subsequently return zero.
jpayne@68: </para>
jpayne@68: 
jpayne@68: <para>
jpayne@68: The include file for this extension is
jpayne@68: &lt;<symbol role='Pn'>X11/extensions/XTest.h</symbol>&gt;.
jpayne@68: </para>
jpayne@68: 
jpayne@68: <funcsynopsis id='XTestQueryExtension'>
jpayne@68: <funcprototype>
jpayne@68: <funcdef>Bool<function> XTestQueryExtension</function></funcdef>
jpayne@68: <paramdef>Display<parameter> *display</parameter></paramdef>
jpayne@68: <paramdef>int<parameter> *event_base</parameter></paramdef>
jpayne@68: <paramdef>int<parameter> *error_base</parameter></paramdef>
jpayne@68: <paramdef>int<parameter> *major_version</parameter></paramdef>
jpayne@68: <paramdef>int<parameter> *minor_version</parameter></paramdef>
jpayne@68: </funcprototype>
jpayne@68: </funcsynopsis>
jpayne@68: 
jpayne@68: <para>
jpayne@68: <xref linkend='XTestQueryExtension' xrefstyle='select: title'/>
jpayne@68: returns
jpayne@68: <function>True</function>
jpayne@68: if the specified display supports the XTEST extension, else
jpayne@68: <function>False</function>
jpayne@68: If the extension is supported, *event_base would be set to the event number
jpayne@68: for the first event for this extension and *error_base would be set to the
jpayne@68: error number for the first error for this extension.  As no errors or
jpayne@68: events are defined for this version of the extension, the values returned
jpayne@68: here are not defined (nor useful).  If the extension is supported,
jpayne@68: *major_version and *minor_version are set to the major and minor version
jpayne@68: numbers of the extension supported by the display.  Otherwise, none of
jpayne@68: the arguments are set.
jpayne@68: </para>
jpayne@68: 
jpayne@68: <funcsynopsis id='XTestCompareCursorWithWindow'>
jpayne@68: <funcprototype>
jpayne@68: <funcdef>Bool<function> XTestCompareCursorWithWindow</function></funcdef>
jpayne@68: <paramdef>Display<parameter> *display</parameter></paramdef>
jpayne@68: <paramdef>Window<parameter> *window</parameter></paramdef>
jpayne@68: <paramdef>Cursor<parameter> cursor</parameter></paramdef>
jpayne@68: </funcprototype>
jpayne@68: </funcsynopsis>
jpayne@68: 
jpayne@68: <para>If the extension is supported,
jpayne@68: <xref linkend='XTestCompareCursorWithWindow' xrefstyle='select: title'/>
jpayne@68: performs a comparison of the cursor whose ID is specified by cursor (which
jpayne@68: may be
jpayne@68: <function>None</function>
jpayne@68: with the cursor of the window specified by window returning
jpayne@68: <function>True</function>
jpayne@68: if they are the same and
jpayne@68: <function>False</function>
jpayne@68: otherwise.  If the extension is not supported, then the request is ignored and
jpayne@68: zero is returned.
jpayne@68: </para>
jpayne@68: 
jpayne@68: <funcsynopsis id='XTestCompareCurrentCursorWithWindow'>
jpayne@68: <funcprototype>
jpayne@68: <funcdef>Bool<function>XTestCompareCurrentCursorWithWindow</function></funcdef>
jpayne@68: <paramdef>Display<parameter> *display</parameter></paramdef>
jpayne@68: <paramdef>Window<parameter> window</parameter></paramdef>
jpayne@68: </funcprototype>
jpayne@68: </funcsynopsis>
jpayne@68: 
jpayne@68: <para>If the extension is supported,
jpayne@68: <xref linkend='XTestCompareCurrentCursorWithWindow' xrefstyle='select: title'/>
jpayne@68: performs a comparison of the current cursor with the cursor of the specified
jpayne@68: window returning
jpayne@68: <function>True</function>
jpayne@68: if they are the same and
jpayne@68: <function>False</function>
jpayne@68: otherwise.  If the extension is not supported, then the request is ignored and
jpayne@68: zero is returned.
jpayne@68: </para>
jpayne@68: 
jpayne@68: <funcsynopsis id='XTestFakeKeyEvent'>
jpayne@68: <funcprototype>
jpayne@68: <funcdef><function>XTestFakeKeyEvent</function></funcdef>
jpayne@68: <paramdef>Display<parameter> *display</parameter></paramdef>
jpayne@68: <paramdef>unsigned int<parameter> keycode</parameter></paramdef>
jpayne@68: <paramdef>Bool<parameter> is_press</parameter></paramdef>
jpayne@68: <paramdef>unsigned long<parameter> delay</parameter></paramdef>
jpayne@68: </funcprototype>
jpayne@68: </funcsynopsis>
jpayne@68: 
jpayne@68: <para>If the extension is supported,
jpayne@68: <xref linkend='XTestFakeKeyEvent' xrefstyle='select: title'/>
jpayne@68: requests the server to simulate either a
jpayne@68: <function>KeyPress</function>
jpayne@68: (if is_press is
jpayne@68: <function>True</function>
jpayne@68: or a
jpayne@68: <function>KeyRelease</function>
jpayne@68: (if is_press is
jpayne@68: <function>False</function>
jpayne@68: of the key with the specified keycode; otherwise, the request is ignored.
jpayne@68: </para>
jpayne@68: 
jpayne@68: <para>
jpayne@68: If the extension is supported, the simulated event will not be processed
jpayne@68: until delay milliseconds after the request is received (if delay is
jpayne@68: <function>CurrentTime</function>
jpayne@68: then this is interpreted as no delay at all).  No other requests from
jpayne@68: this client will be processed until this delay, if any, has expired
jpayne@68: and subsequent processing of the simulated event has been completed.
jpayne@68: </para>
jpayne@68: 
jpayne@68: <funcsynopsis id='XTestFakeButtonEvent'>
jpayne@68: <funcprototype>
jpayne@68: <funcdef><function>XTestFakeButtonEvent</function></funcdef>
jpayne@68: <paramdef>Display<parameter> *display</parameter></paramdef>
jpayne@68: <paramdef>unsigned int<parameter> button</parameter></paramdef>
jpayne@68: <paramdef>Bool<parameter> is_press</parameter></paramdef>
jpayne@68: <paramdef>unsigned long<parameter> delay</parameter></paramdef>
jpayne@68: </funcprototype>
jpayne@68: </funcsynopsis>
jpayne@68: 
jpayne@68: <para>If the extension is supported,
jpayne@68: <xref linkend='XTestFakeButtonEvent' xrefstyle='select: title'/>
jpayne@68: requests the server to simulate either a
jpayne@68: <function>ButtonPress</function>
jpayne@68: (if is_press is
jpayne@68: <function>True</function>
jpayne@68: or a
jpayne@68: <function>ButtonRelease</function>
jpayne@68: (if is_press is
jpayne@68: <function>False</function>
jpayne@68: of the logical button numbered by the specified button; otherwise, the
jpayne@68: request is ignored.
jpayne@68: </para>
jpayne@68: 
jpayne@68: <para>If the extension is supported,
jpayne@68: the simulated event will not be processed until delay milliseconds
jpayne@68: after the request is received (if delay is
jpayne@68: <function>CurrentTime</function>
jpayne@68: then this is interpreted as no delay at all).  No other requests from
jpayne@68: this client will be processed until this delay, if any, has expired
jpayne@68: and subsequent processing of the simulated event has been completed.
jpayne@68: </para>
jpayne@68: 
jpayne@68: <funcsynopsis id='XTestFakeMotionEvent'>
jpayne@68: <funcprototype>
jpayne@68: <funcdef><function>XTestFakeMotionEvent</function></funcdef>
jpayne@68: <paramdef>Display<parameter> *display</parameter></paramdef>
jpayne@68: <paramdef>int<parameter> screen_number</parameter></paramdef>
jpayne@68: <paramdef>int<parameter> x</parameter></paramdef>
jpayne@68: <paramdef>int<parameter> y</parameter></paramdef>
jpayne@68: <paramdef>unsigned long<parameter> delay</parameter></paramdef>
jpayne@68: </funcprototype>
jpayne@68: </funcsynopsis>
jpayne@68: 
jpayne@68: <para>If the extension is supported,
jpayne@68: <xref linkend='XTestFakeMotionEvent' xrefstyle='select: title'/>
jpayne@68: requests the server to simulate a movement of the pointer to the specified
jpayne@68: position (x, y) on the root window of screen_number; otherwise, the request
jpayne@68: is ignored.  If screen_number is -1, the current screen (that the pointer
jpayne@68: is on) is used.
jpayne@68: </para>
jpayne@68: 
jpayne@68: <para>
jpayne@68: If the extension is supported, the simulated event will not be processed
jpayne@68: until delay milliseconds after the request is received (if delay is
jpayne@68: <function>CurrentTime</function>
jpayne@68: then this is interpreted as no delay at all).  No other requests from
jpayne@68: this client will be processed until this delay, if any, has expired
jpayne@68: and subsequent processing of the simulated event has been completed.
jpayne@68: </para>
jpayne@68: 
jpayne@68: <funcsynopsis id='XTestFakeRelativeMotionEvent'>
jpayne@68: <funcprototype>
jpayne@68: <funcdef><function>XTestFakeRelativeMotionEvent</function></funcdef>
jpayne@68: <paramdef>Display<parameter> *display</parameter></paramdef>
jpayne@68: <paramdef>int<parameter> screen_number</parameter></paramdef>
jpayne@68: <paramdef>int<parameter> x</parameter></paramdef>
jpayne@68: <paramdef>int<parameter> y</parameter></paramdef>
jpayne@68: <paramdef>unsigned long<parameter> delay</parameter></paramdef>
jpayne@68: </funcprototype>
jpayne@68: </funcsynopsis>
jpayne@68: 
jpayne@68: <para>
jpayne@68: If the extension is supported,
jpayne@68: <xref linkend='XTestFakeRelativeMotionEvent' xrefstyle='select: title'/>
jpayne@68: requests the server to simulate a movement of the pointer by the specified
jpayne@68: offsets (x, y) relative to the current pointer position on screen_number;
jpayne@68: otherwise, the request is ignored.  If screen_number is -1, the
jpayne@68: current screen (that the pointer is on) is used.
jpayne@68: </para>
jpayne@68: 
jpayne@68: <para>
jpayne@68: If the extension is supported, the simulated event will not be processed
jpayne@68: until delay milliseconds after the request is received (if delay is
jpayne@68: <function>CurrentTime</function>
jpayne@68: then this is interpreted as no delay at all).  No other requests from
jpayne@68: this client will be processed until this delay, if any, has expired
jpayne@68: and subsequent processing of the simulated event has been completed.
jpayne@68: </para>
jpayne@68: 
jpayne@68: <funcsynopsis id='XTestGrabControl'>
jpayne@68: <funcprototype>
jpayne@68: <funcdef><function>XTestGrabControl</function></funcdef>
jpayne@68: <paramdef>Display<parameter> *display</parameter></paramdef>
jpayne@68: <paramdef>Bool<parameter> impervious</parameter></paramdef>
jpayne@68: </funcprototype>
jpayne@68: </funcsynopsis>
jpayne@68: 
jpayne@68: <para>If impervious is
jpayne@68: <function>True</function>
jpayne@68: then the executing client becomes impervious to server grabs.  If impervious is
jpayne@68: <function>False</function>
jpayne@68: then the executing client returns to the normal state of being susceptible
jpayne@68: to server grabs.
jpayne@68: </para>
jpayne@68: 
jpayne@68: <funcsynopsis id='XTestSetGContextOfGC'>
jpayne@68: <funcprototype>
jpayne@68: <funcdef>Bool<function> XTestSetGContextOfGC</function></funcdef>
jpayne@68: <paramdef>GC<parameter> gc</parameter></paramdef>
jpayne@68: <paramdef>GContext<parameter> gid</parameter></paramdef>
jpayne@68: </funcprototype>
jpayne@68: </funcsynopsis>
jpayne@68: 
jpayne@68: <para>
jpayne@68: <xref linkend='XTestSetGContextOfGC' xrefstyle='select: title'/>
jpayne@68: sets the GContext within the opaque datatype referenced by gc to
jpayne@68: be that specified by gid.
jpayne@68: </para>
jpayne@68: 
jpayne@68: <funcsynopsis id='XTestSetVisualIDOfVisual'>
jpayne@68: <funcprototype>
jpayne@68: <funcdef><function>XTestSetVisualIDOfVisual</function></funcdef>
jpayne@68: <paramdef>Visual<parameter> *visual</parameter></paramdef>
jpayne@68: <paramdef>VisualID<parameter> visualid</parameter></paramdef>
jpayne@68: </funcprototype>
jpayne@68: </funcsynopsis>
jpayne@68: 
jpayne@68: <para>
jpayne@68: <xref linkend='XTestSetVisualIDOfVisual' xrefstyle='select: title'/>
jpayne@68: sets the VisualID within the opaque datatype referenced by visual to
jpayne@68: be that specified by visualid.
jpayne@68: </para>
jpayne@68: 
jpayne@68: <funcsynopsis id='XTestDiscard'>
jpayne@68: <funcprototype>
jpayne@68: <funcdef>Bool<function> XTestDiscard</function></funcdef>
jpayne@68: <paramdef>Display<parameter> *display</parameter></paramdef>
jpayne@68: </funcprototype>
jpayne@68: </funcsynopsis>
jpayne@68: 
jpayne@68: <para>
jpayne@68: <xref linkend='XTestDiscard' xrefstyle='select: title'/>
jpayne@68: discards any requests within the output buffer for the specified display.
jpayne@68: It returns
jpayne@68: <function>True</function>
jpayne@68: if any requests were discarded; otherwise, it returns
jpayne@68: <function>False</function>
jpayne@68: </para>
jpayne@68: </chapter>
jpayne@68: 
jpayne@68: <chapter id='References'>
jpayne@68: <title>References</title>
jpayne@68: 
jpayne@68: <para>
jpayne@68: Annicchiarico, D., et al., <emphasis remap='I'>XTrap: The XTrap
jpayne@68: Architecture</emphasis>.
jpayne@68: Digital Equipment Corporation, July 1991.
jpayne@68: </para>
jpayne@68: 
jpayne@68: <para>
jpayne@68: Drake, K. J., <emphasis remap='I'>Some Proposals for a Minimum X11
jpayne@68: Testing Extension</emphasis>.
jpayne@68: UniSoft Ltd., June 1991.
jpayne@68: </para>
jpayne@68: 
jpayne@68: </chapter>
jpayne@68: </book>