diff options
Diffstat (limited to 'lib/libXtst/specs/xtestlib.xml')
| -rw-r--r-- | lib/libXtst/specs/xtestlib.xml | 467 |
1 files changed, 467 insertions, 0 deletions
diff --git a/lib/libXtst/specs/xtestlib.xml b/lib/libXtst/specs/xtestlib.xml new file mode 100644 index 000000000..e1773459a --- /dev/null +++ b/lib/libXtst/specs/xtestlib.xml @@ -0,0 +1,467 @@ +<?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 +“as is” 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 “Software”), 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 “AS IS”, 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 +<<symbol role='Pn'>X11/extensions/XTest.h</symbol>>. +</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> |