summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorAlan Coopersmith <alan.coopersmith@sun.com>2007-06-06 16:39:01 -0700
committerAlan Coopersmith <alan.coopersmith@sun.com>2007-06-06 16:39:01 -0700
commitd9514f97f54b47630b645ef44a5d40262a10d33a (patch)
treef50d84efb4002f1a135a2c030e7e061322f4928a
parent68a28875bc7a2cd760f035508997dfd88b3b6cc8 (diff)
Add man pages for XTest*() functions
Converted xorg-docs/Xext/xtestlib.ms to man page formatting
-rw-r--r--Makefile.am2
-rw-r--r--configure.ac4
-rw-r--r--man/Makefile.am81
-rw-r--r--man/XTest.man320
4 files changed, 405 insertions, 2 deletions
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 <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.
+
+