From d9514f97f54b47630b645ef44a5d40262a10d33a Mon Sep 17 00:00:00 2001 From: Alan Coopersmith Date: Wed, 6 Jun 2007 16:39:01 -0700 Subject: Add man pages for XTest*() functions Converted xorg-docs/Xext/xtestlib.ms to man page formatting --- Makefile.am | 2 +- configure.ac | 4 +- man/Makefile.am | 81 ++++++++++++++ man/XTest.man | 320 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 4 files changed, 405 insertions(+), 2 deletions(-) create mode 100644 man/Makefile.am create mode 100644 man/XTest.man diff --git a/Makefile.am b/Makefile.am index 20760d4..ec888f5 100644 --- a/Makefile.am +++ b/Makefile.am @@ -19,7 +19,7 @@ # TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR # PERFORMANCE OF THIS SOFTWARE. -SUBDIRS = src +SUBDIRS = src man pkgconfigdir = $(libdir)/pkgconfig pkgconfig_DATA = xtst.pc diff --git a/configure.ac b/configure.ac index 554ab13..e7877bc 100644 --- a/configure.ac +++ b/configure.ac @@ -43,9 +43,11 @@ LINT_FLAGS="${LINT_FLAGS} ${XTST_CFLAGS}" AC_SUBST(XTST_CFLAGS) AC_SUBST(XTST_LIBS) - + +XORG_MANPAGE_SECTIONS XORG_RELEASE_VERSION AC_OUTPUT([Makefile + man/Makefile src/Makefile xtst.pc]) diff --git a/man/Makefile.am b/man/Makefile.am new file mode 100644 index 0000000..274d706 --- /dev/null +++ b/man/Makefile.am @@ -0,0 +1,81 @@ +# +# Copyright 2007 Sun Microsystems, Inc. All rights reserved. +# +# Permission to use, copy, modify, distribute, and sell this software and its +# documentation for any purpose is hereby granted without fee, provided that +# the above copyright notice appear in all copies and that both that +# copyright notice and this permission notice appear in supporting +# documentation. +# +# 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 OPEN GROUP 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 copyright holders 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 copyright holders. +# + +libmandir = $(LIB_MAN_DIR) + +LIB_MAN_DIR_SUFFIX = $(LIB_MAN_DIR:@mandir@/man%=%) + +libman_PRE = XTest.man + +BUILT_SOURCES = shadows.DONE + +EXTRA_DIST = $(libman_PRE) + +CLEANFILES = $(libman_DATA) $(BUILT_SOURCES) + +libman_DATA = $(libman_PRE:man=@LIB_MAN_SUFFIX@) \ + $(XTest_shadows:=.@LIB_MAN_SUFFIX@) + +SED = sed + +# Strings to replace in man pages +XORGRELSTRING = @PACKAGE_STRING@ + XORGMANNAME = X Version 11 + +MAN_SUBSTS = \ + -e 's/__xorgversion__/"$(XORGRELSTRING)" "$(XORGMANNAME)"/' \ + -e 's/__xservername__/Xorg/g' \ + -e 's/__xconfigfile__/xorg.conf/g' \ + -e 's/__appmansuffix__/$(APP_MAN_SUFFIX)/g' \ + -e 's/__libmansuffix__/$(LIB_MAN_SUFFIX)/g' \ + -e 's/__filemansuffix__/$(FILE_MAN_SUFFIX)/g' + +SUFFIXES = .$(LIB_MAN_SUFFIX) .man + +.man.$(LIB_MAN_SUFFIX): + sed $(MAN_SUBSTS) < $< > $@ + +# Generate man page shadow files (Replaces InstallManPageAliases from Imake) + +XTest_shadows = \ + XTestQueryExtension \ + XTestCompareCursorWithWindow \ + XTestCompareCurrentCursorWithWindow \ + XTestFakeKeyEvent \ + XTestFakeButtonEvent \ + XTestFakeMotionEvent \ + XTestFakeRelativeMotionEvent \ + XTestGrabControl \ + XTestSetGContextOfGC \ + XTestSetVisualIDOfVisual \ + XTestDiscard + +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) + diff --git a/man/XTest.man b/man/XTest.man new file mode 100644 index 0000000..be43f8c --- /dev/null +++ b/man/XTest.man @@ -0,0 +1,320 @@ +.\" 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 +.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. + + -- cgit v1.2.3