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