diff options
| -rw-r--r-- | configure.ac | 6 | ||||
| -rw-r--r-- | man/.gitignore | 7 | ||||
| -rw-r--r-- | man/Makefile.am | 51 | ||||
| -rw-r--r-- | man/XTest.man | 320 | ||||
| -rw-r--r-- | man/XTest.xml | 414 |
5 files changed, 455 insertions, 343 deletions
diff --git a/configure.ac b/configure.ac index e7877bc..41a6d6e 100644 --- a/configure.ac +++ b/configure.ac @@ -33,6 +33,12 @@ AM_CONFIG_HEADER(config.h) AC_PROG_CC AC_PROG_LIBTOOL +# Check for xmlto for man page conversion +# (only needed by people building tarballs) +AC_ARG_VAR([XMLTO], [Path to xmlto command]) +AC_PATH_PROG([XMLTO], [xmlto]) +AM_CONDITIONAL([HAVE_XMLTO], [test "x$XMLTO" != "x"]) + # Check for dependencies PKG_CHECK_MODULES(XTST, x11 xext recordproto xextproto inputproto) diff --git a/man/.gitignore b/man/.gitignore new file mode 100644 index 0000000..74c6b15 --- /dev/null +++ b/man/.gitignore @@ -0,0 +1,7 @@ +shadows.DONE +*.3 +*~ +*.man +*.__libmansuffix__ +Makefile +Makefile.in diff --git a/man/Makefile.am b/man/Makefile.am index 274d706..318e137 100644 --- a/man/Makefile.am +++ b/man/Makefile.am @@ -28,16 +28,30 @@ libmandir = $(LIB_MAN_DIR) LIB_MAN_DIR_SUFFIX = $(LIB_MAN_DIR:@mandir@/man%=%) -libman_PRE = XTest.man +libman_xml = XTest.xml -BUILT_SOURCES = shadows.DONE +XTest_manpages = \ + XTestQueryExtension \ + XTestCompareCursorWithWindow \ + XTestCompareCurrentCursorWithWindow \ + XTestFakeKeyEvent \ + XTestFakeButtonEvent \ + XTestFakeMotionEvent \ + XTestFakeRelativeMotionEvent \ + XTestGrabControl \ + XTestSetGContextOfGC \ + XTestSetVisualIDOfVisual \ + XTestDiscard + +libman_PRE = $(XTest_manpages:%=%.man) -EXTRA_DIST = $(libman_PRE) +EXTRA_DIST = $(libman_PRE) $(libman_xml) CLEANFILES = $(libman_DATA) $(BUILT_SOURCES) -libman_DATA = $(libman_PRE:man=@LIB_MAN_SUFFIX@) \ - $(XTest_shadows:=.@LIB_MAN_SUFFIX@) +MAINTAINERCLEANFILES = $(libman_PRE) + +libman_DATA = $(libman_PRE:man=@LIB_MAN_SUFFIX@) SED = sed @@ -58,24 +72,15 @@ SUFFIXES = .$(LIB_MAN_SUFFIX) .man .man.$(LIB_MAN_SUFFIX): sed $(MAN_SUBSTS) < $< > $@ -# Generate man page shadow files (Replaces InstallManPageAliases from Imake) +# Generate nroff sources from DocBook/xml -XTest_shadows = \ - XTestQueryExtension \ - XTestCompareCursorWithWindow \ - XTestCompareCurrentCursorWithWindow \ - XTestFakeKeyEvent \ - XTestFakeButtonEvent \ - XTestFakeMotionEvent \ - XTestFakeRelativeMotionEvent \ - XTestGrabControl \ - XTestSetGContextOfGC \ - XTestSetVisualIDOfVisual \ - XTestDiscard +dist-hook: $(libman_PRE) -shadows.DONE: - -rm -f $(XTest_shadows:=.@LIB_MAN_SUFFIX@) - (for i in $(XTest_shadows:=.@LIB_MAN_SUFFIX@) ; do \ - echo .so man$(LIB_MAN_DIR_SUFFIX)/XTest.$(LIB_MAN_SUFFIX) > $$i; \ - done) +if HAVE_XMLTO +$(libman_PRE): $(libman_xml) + $(XMLTO) man $(libman_xml) + for m in $(XTest_manpages); do \ + mv -f $$m.__libmansuffix__ $$m.man ; \ + done +endif HAVE_XMLTO diff --git a/man/XTest.man b/man/XTest.man deleted file mode 100644 index be43f8c..0000000 --- a/man/XTest.man +++ /dev/null @@ -1,320 +0,0 @@ -.\" Copyright \(co 1992 by UniSoft Group Ltd. -.\" -.\" 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. -.\" -.\" Copyright \(co 1992, 1994 X Consortium -.\" -.\" 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: -.\" -.\" The above copyright notice and this permission notice shall be included in -.\" all copies or substantial portions of the Software. -.\" -.\" 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. -.\" -.\" 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. -.\" -.\" edited for DP edits and code consistency w/ core protocol/xlib 4/2/96 -.\" Converted from xorg-docs/Xext/xtestlib.ms 6/6/07 -.\" $Xorg: xtestlib.ms,v 1.3 2000/08/17 19:42:37 cpqbld Exp $ -.TH XTest __libmansuffix__ __xorgversion__ "XTST FUNCTIONS" -.SH NAME -XTestQueryExtension, XTestCompareCursorWithWindow, XTestCompareCurrentCursorWithWindow, XTestFakeKeyEvent, XTestFakeButtonEvent, XTestFakeMotionEvent, XTestFakeRelativeMotionEvent, XTestGrabControl, XTestSetGContextOfGC, XTestSetVisualIDOfVisual, XTestDiscard \- XTest extension functions -.SH SYNOPSIS -.HP -\fBcc\fR [ \fIflag\fR ... ] \fIfile\fR ... \fB-lXtst \fR [ \fIlibrary\fR ... ] -.HP -.B #include <X11/extensions/XTest.h> -.HP -Bool -XTestQueryExtension(\fIdisplay\fP\^, \fIevent_base\fP\^, \fIerror_base\fP\^, \fImajor_version\fP\^, \fIminor_version\fP\^) -.IP - Display *\fIdisplay\fP\^; - int *\fIevent_base\fP\^; /* RETURN */ - int *\fIerror_base\fP\^; /* RETURN */ - int *\fImajor_version\fP\^; /* RETURN */ - int *\fIminor_version\fP\^; /* RETURN */ -.HP -Bool -XTestCompareCursorWithWindow(\fIdisplay\fP\^, \fIwindow\fP\^, \fIcursor\fP\^) -.IP - Display *\fIdisplay\fP\^; - Window \fIwindow\fP\^; - Cursor \fIcursor\fP\^; -.HP -Bool -XTestCompareCurrentCursorWithWindow(\fIdisplay\fP\^, \fIwindow\fP\^) -.IP - Display *\fIdisplay\fP\^; - Window \fIwindow\fP\^; -.HP -int -XTestFakeKeyEvent(\fIdisplay\fP\^, \fIkeycode\fP\^, \fIis_press\fP\^, \fIdelay\fP\^) -.IP - Display *\fIdisplay\fP\^; - unsigned int \fIkeycode\fP\^; - Bool \fIis_press\fP\^; - unsigned long \fIdelay\fP\^; -.HP -int -XTestFakeButtonEvent(\fIdisplay\fP\^, \fIbutton\fP\^, \fIis_press\fP\^, \fIdelay\fP\^) -.IP - Display *\fIdisplay\fP\^; - unsigned int \fIbutton\fP\^; - Bool \fIis_press\fP\^; - unsigned long \fIdelay\fP\^; -.HP -int -XTestFakeMotionEvent(\fIdisplay\fP\^, \fIscreen_number\fP\^, \fIx\fP\^, \ -\fIy\fP\^, \fIdelay\fP\^) -.IP - Display *\fIdisplay\fP\^; - int \fIscreen_number\fP\^; - int \fIx\fP\^, \fIy\fP\^; - unsigned long \fIdelay\fP\^; -.HP -int -XTestFakeRelativeMotionEvent(\fIdisplay\fP\^, \fIscreen_number\fP\^, \ -\fIx\fP\^, \fIy\fP\^, \fIdelay\fP\^) -.IP - Display *\fIdisplay\fP\^; - int \fIscreen_number\fP\^; - int \fIx\fP\^, \fIy\fP\^; - unsigned long \fIdelay\fP\^; -.HP -int -XTestGrabControl(\fIdisplay\fP\^, \fIimpervious\fP\^) -.IP - Display *\fIdisplay\fP\^; - Bool \fIimpervious\fP\^; -.HP -void -XTestSetGContextOfGC(\fIgc\fP\^, \fIgid\fP\^) -.IP - GC \fIgc\fP\^; - GContext \fIgid\fP\^; -.HP -void -XTestSetVisualIDOfVisual(\fIvisual\fP\^, \fIvisualid\fP\^) -.IP - Visual *\fIvisual\fP\^; - VisualID \fIvisualid\fP\^; -.HP -Status -XTestDiscard(\fIdisplay\fP\^) -.IP - Display *\fIdisplay\fP\^; -.SH DESCRIPTION -.LP -This extension is a minimal set of client and server extensions -required to completely test the X11 server with no user intervention. -This extension is not intended to support general journaling and -playback of user actions. -.LP -The functions provided by this extension fall into two groups: -.IP "\fBClient Operations\fP" .5i -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, routines are provided -to access the internals of two opaque data structures -.BR \*- GC s -and -.BR Visual 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. -.IP "\fBServer Requests\fP" .5i -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: -.RS -.IP \(bu 5 -Access to an otherwise \*Qwrite-only\*U server resource: the cursor -associated with a given window -.IP \(bu 5 -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. -.RE -.LP -All XTEST extension functions and procedures, and all manifest -constants and macros, will start with the string \*QXTest\*U. -All operations are classified as -server/client (Server) or client-only (Client). -.FD 0 -.FN -.LP -.B XTestQueryExtension -returns -.B True -if the specified display supports the XTEST extension, else -.BR False . -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. -.sp -.LP -If the extension is supported, -.BR XTestCompareCursorWithWindow -performs a comparison of the cursor -whose ID is specified by cursor (which may be -.BR None ) -with the cursor of the window specified by window returning -.BR True -if they are the same and -.BR False -otherwise. -If the extension is not supported, then the request is ignored and -zero is returned. -.sp -.LP -If the extension is supported, -.BR XTestCompareCurrentCursorWithWindow -performs a comparison of the current cursor -with the cursor of the specified window returning -.BR True -if they are the same and -.BR False -otherwise. -If the extension is not supported, then the request is ignored and -zero is returned. -.sp -.LP -If the extension is supported, -.BR XTestFakeKeyEvent -requests the server to simulate either a -.BR KeyPress -(if is_press is -.BR True ) -or a -.BR KeyRelease -(if is_press is -.BR False ) -of the key with the specified keycode; -otherwise, the request is ignored. -.LP -If the extension is supported, -the simulated event will not be processed until delay milliseconds -after the request is received (if delay is -.BR CurrentTime , -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. -.sp -.LP -If the extension is supported, -.BR XTestFakeButtonEvent -requests the server to simulate either -a -.BR ButtonPress -(if is_press is -.BR True ) -or a -.BR ButtonRelease -(if is_press is -.BR False ) -of the logical button numbered by the specified button; -otherwise, the request is ignored. -.LP -If the extension is supported, -the simulated event will not be processed until delay milliseconds -after the request is received (if delay is -.BR CurrentTime , -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. -.sp -.LP -If the extension is supported, -.BR XTestFakeMotionEvent -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. -.LP -If the extension is supported, -the simulated event will not be processed until delay milliseconds -after the request is received (if delay is -.BR CurrentTime , -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. -.sp -.LP -If the extension is supported, -.BR XTestFakeRelativeMotionEvent -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. -.LP -If the extension is supported, -the simulated event will not be processed until delay milliseconds -after the request is received (if delay is -.BR CurrentTime , -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. -.sp - -.LP -If impervious is -.BR True , -then the executing client becomes impervious to server grabs. -If impervious is -.BR False , -then the executing client returns to the normal state of being -susceptible to server grabs. -.sp -.LP -.BR XTestSetGContextOfGC -sets the GContext within the opaque datatype referenced by gc to -be that specified by gid. -.sp -.LP -.BR XTestSetVisualIDOfVisual -sets the VisualID within the opaque datatype referenced by visual to -be that specified by visualid. -.sp -.LP -.BR XTestDiscard -discards any requests within the output buffer for the specified display. -It returns -.BR True -if any requests were discarded; otherwise, it returns -.BR False . - -.SH RETURN VALUES -All routines that have return type Status will return nonzero for -\*Qsuccess\*U and zero for \*Qfailure.\*U Even if the XTEST extension is -supported, the server may withdraw such facilities arbitrarily; in which case -they will subsequently return zero. - - diff --git a/man/XTest.xml b/man/XTest.xml new file mode 100644 index 0000000..a80ab22 --- /dev/null +++ b/man/XTest.xml @@ -0,0 +1,414 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" + "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd"> +<!-- lifted from troff+man by doclifter --> +<refentry id='XTest.man'> +<!-- +Copyright © 1992 by UniSoft Group Ltd. +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. + +Copyright © 1992, 1994 X Consortium + +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: + +The above copyright notice and this permission notice shall be included in +all copies or substantial portions of the Software. + +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. + +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. + --> + +<!-- edited for DP edits and code consistency w/ core protocol/xlib 4/2/96 --> +<!-- Converted from xorg-docs/specs/Xext/xtestlib.ms 6/6/07 --> +<!-- $Xorg: xtestlib.ms,v 1.3 2000/08/17 19:42:37 cpqbld Exp $ --> + <refentryinfo> + <productname>__vendorversion__</productname> + <pubdate>6 June 2007</pubdate> + <author><firstname>Kieron</firstname><surname>Drake</surname> + <affiliation><orgname>UniSoft Ltd.</orgname></affiliation> + </author> + </refentryinfo> +<refmeta> +<refentrytitle>XTest</refentrytitle> +<manvolnum>__libmansuffix__</manvolnum> +<refmiscinfo class='source'>__xorgversion__</refmiscinfo> +<refmiscinfo class='manual'>XTST FUNCTIONS</refmiscinfo> +</refmeta> +<refnamediv id='name'> +<refname>XTestQueryExtension</refname> +<refname>XTestCompareCursorWithWindow</refname> +<refname>XTestCompareCurrentCursorWithWindow</refname> +<refname>XTestFakeKeyEvent</refname> +<refname>XTestFakeButtonEvent</refname> +<refname>XTestFakeMotionEvent</refname> +<refname>XTestFakeRelativeMotionEvent</refname> +<refname>XTestGrabControl</refname> +<refname>XTestSetGContextOfGC</refname> +<refname>XTestSetVisualIDOfVisual</refname> +<refname>XTestDiscard</refname> +<refpurpose>XTest extension functions</refpurpose> +</refnamediv> +<!-- body begins here --> +<refsynopsisdiv id='synopsis'> +<funcsynopsis> +<funcsynopsisinfo> +cc [ flag ... ] file ... -lXtst [ library ... ] +</funcsynopsisinfo> +<funcsynopsisinfo> +#include <X11/extensions/XTest.h> +</funcsynopsisinfo> +<funcprototype> +<funcdef><function>Bool</function> XTestQueryExtension</funcdef> +<paramdef><parameter>display</parameter></paramdef> +<paramdef><parameter>event_base</parameter></paramdef> +<paramdef><parameter>error_base</parameter></paramdef> +<paramdef><parameter>major_version</parameter></paramdef> +<paramdef><parameter>minor_version</parameter></paramdef> +</funcprototype> +<funcsynopsisinfo> + Display *display; + int *event_base; + int *error_base; + int *major_version; + int *minor_version; +</funcsynopsisinfo> +<funcprototype> +<funcdef><function>Bool</function> XTestCompareCursorWithWindow</funcdef> +<paramdef><parameter>display</parameter></paramdef> +<paramdef><parameter>window</parameter></paramdef> +<paramdef><parameter>cursor</parameter></paramdef> +</funcprototype> +<funcsynopsisinfo> + Display *display; + Window window; + Cursor cursor; +</funcsynopsisinfo> +<funcprototype> +<funcdef><function>Bool</function> XTestCompareCurrentCursorWithWindow</funcdef> +<paramdef><parameter>display</parameter></paramdef> +<paramdef><parameter>window</parameter></paramdef> +</funcprototype> +<funcsynopsisinfo> + Display *display; + Window window; +</funcsynopsisinfo> +<funcprototype> +<funcdef>int <function>XTestFakeKeyEvent</function></funcdef> +<paramdef><parameter>display</parameter></paramdef> +<paramdef><parameter>keycode</parameter></paramdef> +<paramdef><parameter>is_press</parameter></paramdef> +<paramdef><parameter>delay</parameter></paramdef> +</funcprototype> +<funcsynopsisinfo> + Display *display; + unsigned int keycode; + Bool is_press; + unsigned long delay; +</funcsynopsisinfo> +<funcprototype> +<funcdef>int <function>XTestFakeButtonEvent</function></funcdef> +<paramdef><parameter>display</parameter></paramdef> +<paramdef><parameter>button</parameter></paramdef> +<paramdef><parameter>is_press</parameter></paramdef> +<paramdef><parameter>delay</parameter></paramdef> +</funcprototype> +<funcsynopsisinfo> + Display *display; + unsigned int button; + Bool is_press; + unsigned long delay; +</funcsynopsisinfo> +<funcprototype> +<funcdef>int <function>XTestFakeMotionEvent</function></funcdef> +<paramdef><parameter>display</parameter></paramdef> +<paramdef><parameter>screen_number</parameter></paramdef> +<paramdef><parameter>x</parameter></paramdef> +<paramdef><parameter>y</parameter></paramdef> +<paramdef><parameter>delay</parameter></paramdef> +</funcprototype> +<funcsynopsisinfo> + Display *display; + int screen_number; + int x, y; + unsigned long delay; +</funcsynopsisinfo> +<funcprototype> +<funcdef>int <function>XTestFakeRelativeMotionEvent</function></funcdef> +<paramdef><parameter>display</parameter></paramdef> +<paramdef><parameter>screen_number</parameter></paramdef> +<paramdef><parameter>x</parameter></paramdef> +<paramdef><parameter>y</parameter></paramdef> +<paramdef><parameter>delay</parameter></paramdef> +</funcprototype> +<funcsynopsisinfo> + Display *display; + int screen_number; + int x, y; + unsigned long delay; +</funcsynopsisinfo> +<funcprototype> +<funcdef>int <function>XTestGrabControl</function></funcdef> +<paramdef><parameter>display</parameter></paramdef> +<paramdef><parameter>impervious</parameter></paramdef> +</funcprototype> +<funcsynopsisinfo> + Display *display; + Bool impervious; +</funcsynopsisinfo> +<funcprototype> +<funcdef>void <function>XTestSetGContextOfGC</function></funcdef> +<paramdef><parameter>gc</parameter></paramdef> +<paramdef><parameter>gid</parameter></paramdef> +</funcprototype> +<funcsynopsisinfo> + GC gc; + GContext gid; +</funcsynopsisinfo> +<funcprototype> +<funcdef>void <function>XTestSetVisualIDOfVisual</function></funcdef> +<paramdef><parameter>visual</parameter></paramdef> +<paramdef><parameter>visualid</parameter></paramdef> +</funcprototype> +<funcsynopsisinfo> + Visual *visual; + VisualID visualid; +</funcsynopsisinfo> +<funcprototype> +<funcdef><function>Status</function> XTestDiscard</funcdef> +<paramdef><parameter>display</parameter></paramdef> +</funcprototype> +<funcsynopsisinfo> + Display *display; +</funcsynopsisinfo> +</funcsynopsis> +</refsynopsisdiv> + + +<refsect1 id='description'><title>DESCRIPTION</title> +<para>This extension is a minimal set of client and server extensions +required to completely test the X11 server with no user intervention. +This extension is not intended to support general journaling and +playback of user actions.</para> + +<para>The functions provided by this extension fall into two groups:</para> +<variablelist remap='IP'> + <varlistentry> + <term><emphasis remap='B'>Client Operations</emphasis></term> + <listitem> +<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, routines are provided +to access the internals of two opaque data structures +— <structname>GC</structname>s +and +<structname>Visual</structname>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> + </varlistentry> + <varlistentry> + <term><emphasis remap='B'>Server Requests</emphasis></term> + <listitem> +<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> + <itemizedlist> + <listitem> +<para>Access to an otherwise <emphasis>write-only</emphasis> 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> + </varlistentry> +</variablelist> + +<para>All XTEST extension functions and procedures, and all manifest +constants and macros, will start with the string <emphasis>XTest</emphasis>. +All operations are classified as +server/client (Server) or client-only (Client).</para> + +<para><function>XTestQueryExtension</function> +returns +<returnvalue>True</returnvalue> +if the specified display supports the XTEST extension, else +<returnvalue>False</returnvalue>. +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> + + +<para>If the extension is supported, +<function>XTestCompareCursorWithWindow</function> +performs a comparison of the cursor +whose ID is specified by cursor (which may be +<emphasis remap='B'>None</emphasis>) +with the cursor of the window specified by window returning +<returnvalue>True</returnvalue> +if they are the same and +<returnvalue>False</returnvalue> +otherwise. +If the extension is not supported, then the request is ignored and +zero is returned.</para> + + +<para>If the extension is supported, +<function>XTestCompareCurrentCursorWithWindow</function> +performs a comparison of the current cursor +with the cursor of the specified window returning +<returnvalue>True</returnvalue> +if they are the same and +<returnvalue>False</returnvalue> +otherwise. +If the extension is not supported, then the request is ignored and +zero is returned.</para> + + +<para>If the extension is supported, +<function>XTestFakeKeyEvent</function> +requests the server to simulate either a +<emphasis remap='B'>KeyPress</emphasis> +(if is_press is +<returnvalue>True</returnvalue>) +or a +<emphasis remap='B'>KeyRelease</emphasis> +(if is_press is +<returnvalue>False</returnvalue>) +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 +<emphasis remap='B'>CurrentTime</emphasis>, +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> + + +<para>If the extension is supported, +<function>XTestFakeButtonEvent</function> +requests the server to simulate either +a +<emphasis remap='B'>ButtonPress</emphasis> +(if is_press is +<returnvalue>True</returnvalue>) +or a +<emphasis remap='B'>ButtonRelease</emphasis> +(if is_press is +<returnvalue>False</returnvalue>) +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 +<emphasis remap='B'>CurrentTime</emphasis>, +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> + + +<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 +<emphasis remap='B'>CurrentTime</emphasis>, +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> + + +<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 +<emphasis remap='B'>CurrentTime</emphasis>, +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> + + + +<para>If impervious is +<returnvalue>True</returnvalue>, +then the executing client becomes impervious to server grabs. +If impervious is +<returnvalue>False</returnvalue>, +then the executing client returns to the normal state of being +susceptible to server grabs.</para> + + +<para><function>XTestSetGContextOfGC</function> +sets the GContext within the opaque datatype referenced by gc to +be that specified by gid.</para> + + +<para><function>XTestSetVisualIDOfVisual</function> +sets the VisualID within the opaque datatype referenced by visual to +be that specified by visualid.</para> + + +<para><function>XTestDiscard</function> +discards any requests within the output buffer for the specified display. +It returns +<returnvalue>True</returnvalue> +if any requests were discarded; otherwise, it returns +<returnvalue>False</returnvalue>.</para> + +</refsect1> + +<refsect1 id='return_values'><title>RETURN VALUES</title> +<para>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> +</refsect1> +</refentry> + |