CD Actual 45/cda45.iso/Linux/XFree86-4.0/doc/xtest.TXT

Text File | 2000-03-09 | 11.5 KB | 595 lines

          XTEST Extension Protocol



            Version 2.2
           X Consortium Standard






            Kieron Drake
            UniSoft Ltd.











































Copyright (C) 1992 by UniSoft Group Ltd.

Permission to use, copy, modify, and distribute this docu-
mentation 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 representa-
tions about the suitability for any purpose of the informa-
tion in this document.    This documentation is provided ``as
is'' without express or implied warranty.






Copyright (C) 1992, 1994 X Consortium

Permission is hereby granted, free of charge, to any person
obtaining a copy of this software and associated documenta-
tion files (the ``Software''), to deal in the Software with-
out 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 fol-
lowing 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 PUR-
POSE AND NONINFRINGEMENT.  IN NO EVENT SHALL THE X CONSOR-
TIUM 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 Con-
sortium 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.























1.  Overview

This extension is a minimal set of client and server exten-
sions 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.  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, sim-
pler, case.  A more detailed discussion and justification of
the extension functionality is given in [Drake, 91].

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.

We have also tried to:

o    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.

o    Minimize the changes required in the rest of the
     server.

o    Minimize performance penalties on normal server opera-
     tion.


2.  Description

The functions provided by this extension fall into two
groups:

Client Operations
     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 ``XTEST Exten-
     sion Library'', routines are provided to access the
     internals of two opaque data structures --GCs and
     Visuals-- 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.





                  1





          XTEST Extension Protocol


Server Requests
     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 follow-
     ing:

     o      Access to an otherwise "write-only" server
      resource: the cursor associated with a given win-
      dow

     o      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.

3.  Types

The following types are used in the request and event defi-
nitions in subsequent sections:

FAKE_EVENT_TYPE {KeyPress, KeyRelease, MotionNotify,
ButtonPress, ButtonRelease}


FAKE_EVENT  [type: FAKE_EVENT_TYPE,
        detail: BYTE,
        time: TIME,
        root: WINDOW,
        rootX, rootY: INT16]


CURSOR {CurrentCursor, None} or a cursor as defined by the
X11 Protocol.

4.  Client Operations

These are abstract definitions of functionality.  They refer
to client-side objects such as "GC" and "VISUAL" that are
quoted to denote their abstract nature.  Concrete versions
of these functions are defined only for particular language
bindings.  In some circumstances a particular language bind-
ing may not implement the relevant abstract type or may pro-
vide it as a transparent, rather than opaque, type, with the
result that the corresponding function does not make sense
or is not required, respectively.










                  2





          XTEST Extension Protocol

__
|    XTestSetGContextOfGC

     gc: "GC"
     gid: GCONTEXT
|__


Sets the GCONTEXT within the "GC" gc to have the value spec-
ified by gid.

__
|    XTestSetVisualIDOfVisual

     visual: "VISUAL"
     visualid: VISUALID
|__


Sets the VISUALID within the "VISUAL" visual to have the
value specified by visualid.

__
|    XTestDiscard

     dpy: "CONNECTION"

   =>

     status: BOOL
|__


Discards any requests that are present in the request buffer
associated with the "CONNECTION" dpy.  The status returned
is True if there were one or more requests in the buffer and
False otherwise.

5.  Server Requests

__
|    XTestGetVersion

     clientMajorVersion: CARD16
     clientMinorVersion: CARD16

   =>

     serverMajorVersion: CARD16
     serverMinorVersion: CARD16

     Errors: Length
|__





                  3





          XTEST Extension Protocol


This request can be used to ensure that the server version
of the XTEST extension is usable by the client.  This docu-
ment defines major version two (2), minor version one (1).

__
|    XTestCompareCursor

     window: WINDOW
     cursor-id: CURSOR or CurrentCursor or None

   =>

     same: BOOL

     Errors: Window, Length, Cursor
|__


This request looks up the cursor associated with the window
and compares it with either the null cursor if cursor-id is
None, or the current cursor (that is, the one being dis-
played), or the cursor whose ID is cursor-id, and returns
the result of the comparison in same.

__
|    XTestFakeInput

     events: LISTofFAKE_EVENT

     Errors: Window, Length, Alloc, Value
|__


This request simulates the limited set of core protocol
events within the set FAKE_EVENT_TYPE.    Only the following
event fields, defined in FAKE_EVENT, are interpreted:

type      This must be one of KeyPress, KeyRelease,
      MotionNotify, ButtonPress, or ButtonRelease, or
      else a Value error occurs.

detail      For key events, this field is interpreted as the
      physical keycode.  If the keycode is less than
      min-keycode or greater than max-keycode, as
      returned in the connection setup, then a Value
      error occurs.  For button events, this field is
      interpreted as the physical (or core) button,
      meaning it will be mapped to the corresponding
      logical button according to the most recent Set-
      PointerMapping request.  If the button number is
      less than one or greater than the number of physi-
      cal buttons, then a Value error occurs.  For
      motion events, if this field is True, then rootX
      and rootY are relative distances from the current



                  4





          XTEST Extension Protocol


      pointer location; if this field is False, then
      they are absolute positions.

time      This is either CurrentTime (meaning no delay) or
      the delay in milliseconds that the server should
      wait before simulating this event.  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 com-
      pleted.

root      In the case of motion events this field is the ID
      of the root window on which the new motion is to
      take place.  If None is specified, the root window
      of the screen the pointer is currently on is used
      instead.  If this field is not a valid window,
      then a Window error occurs.

rootX & rootY
      In the case of motion events these fields indicate
      relative distance or absolute pointer coordinates,
      according to the setting of detail.  If the speci-
      fied coordinates are off-screen, the closest on-
      screen coordinates will be substituted.

When the simulated event(s) are processed, they cause event
propagation, passive grab activation, and so on, just as if
the corresponding input device action had occurred.  How-
ever, motion events might not be recorded in the motion his-
tory buffer.

For the currently supported event types, the event list must
have length one, otherwise a BadLength error occurs.

__
|    XTestGrabControl

     impervious: BOOL
|__


If impervious is True, then the executing client becomes
impervious to server grabs; that is, it can continue execut-
ing requests even if another client grabs the server.  If
impervious is False, then the executing client returns to
the normal state of being susceptible to server grabs.











                  5





          XTEST Extension Protocol


6.  Encoding

Please refer to the X11 Protocol Encoding document as this
document uses conventions established there.

The name of this extension is ``XTEST''.

6.1.  New Types


FAKE_EVENT_TYPE
       2     KeyPress
       3     KeyRelease
       4     ButtonPress
       5     ButtonRelease
       6     MotionNotify


NOTE that the above values are defined to be the same as
those for the corresponding core protocol event types.

6.2.  Requests


XTestGetVersion
  1  CARD8         opcode
  1  0             xtest opcode
  2  2             request length
  1  CARD8         client major version
  1             unused
  2  CARD16         client minor version


 =>
  1  1             Reply
  1  CARD8         server major version
  2  CARD16         sequence number
  4  0             reply length
  2  CARD16         server minor version
  22             unused



XTestCompareCursor
  1  CARD8         opcode
  1  1             xtest opcode
  2  3             request length
  4  WINDOW         window
  4  CURSOR         cursor-id
     0           None
     1           CurrentCursor


 =>



                  6





          XTEST Extension Protocol


  1  1             Reply
  1  BOOL         cursors are the same
  2  CARD16         sequence number
  4  0             reply length
  24             unused



XTestFakeInput
  1  CARD8         opcode
  1  2             xtest opcode
  2  1+(1*8)         request length
  1  FAKE_EVENT_TYPE     fake device event type
  1  BYTE         detail: button or keycode
  2             unused
  4  TIME         delay (milliseconds)
     0           CurrentTime
  4  WINDOW         root window for MotionNotify
     0           None
  8             unused
  2  INT16         x position for MotionNotify
  2  INT16         y position for MotionNotify
  8             unused



XTestGrabControl
  1  CARD8         opcode
  1  3             xtest opcode
  2  2             request length
  1  BOOL         impervious
  3             unused


7.  References

Annicchiarico, D., et al., XTrap: The XTrap Architecture.
     Digital Equipment Corporation, July 1991.

Drake, K. J., Some Proposals for a Minimum X11 Testing
     Extension.  UniSoft Ltd., June 1991.
















                  7