979 lines
27 KiB
XML
979 lines
27 KiB
XML
<?xml version="1.0" encoding="UTF-8" ?>
|
|
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
|
|
"http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">
|
|
|
|
|
|
<article id="xtest1">
|
|
|
|
<articleinfo>
|
|
<title>X11 INPUT SYNTHESIS EXTENSION PROPOSAL</title>
|
|
<subtitle>X Consortium Standard</subtitle>
|
|
<releaseinfo>Version 1.0</releaseinfo>
|
|
<authorgroup>
|
|
<author>
|
|
<firstname>Larry</firstname><surname>Woestman</surname>
|
|
<affiliation><jobtitle>Member of Technical Staff</jobtitle>
|
|
<orgname>Hewlett Packard</orgname></affiliation>
|
|
</author>
|
|
</authorgroup>
|
|
<copyright><year>1993</year><holder>X Consortium</holder></copyright>
|
|
|
|
<legalnotice>
|
|
<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>
|
|
</legalnotice>
|
|
|
|
<abstract>
|
|
<para>
|
|
This is a proposal for an extension to the X11 server and Xlib.
|
|
</para>
|
|
</abstract>
|
|
|
|
</articleinfo>
|
|
|
|
<sect1 id="introduction">
|
|
<title>Introduction</title>
|
|
<para>
|
|
This is a proposal for an extension to the X11 server and Xlib.
|
|
It provides two capabilities:
|
|
</para>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
It allows a client to generate user input actions in the server without
|
|
requiring a user to be present.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
It also allows a client to control the
|
|
handling of user input actions by the server.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
|
|
<para>
|
|
The capability
|
|
to allow a client to generate user input actions in the server
|
|
will be used by some of the X Testing Consortium Xlib tests.
|
|
Both capabilities will be used by the X Testing Consortium client exerciser
|
|
program.
|
|
These capabilities may also be useful in other programs.
|
|
</para>
|
|
|
|
<para>
|
|
This extension requires modification to device-dependent code in the
|
|
server. Therefore it is not a 'portable' extension as defined by the
|
|
X11 Server Extensions document. However, the majority of the code
|
|
and functionality of this extension will be implementation-independent.
|
|
</para>
|
|
|
|
</sect1>
|
|
|
|
<sect1 id="conventions_used_in_this_document">
|
|
<title>Conventions Used In This Document</title>
|
|
|
|
<para>
|
|
The naming conventions used in the Xlib documentation are followed
|
|
with these additions:
|
|
</para>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
The names of all functions defined in this extension begin with 'XTest',
|
|
with the first letter of each additional word capitalized.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
The names of the protocol request structures follow the Xlib convention
|
|
of 'x<name>Req'.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
The names of the protocol request minor type codes follow the Xlib convention
|
|
of 'X_<name>'.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
The names of all other constants defined in this extension begin with 'XTest',
|
|
with the rest of the name in upper case letters.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
All constants and structures defined in this extension will have their
|
|
values specified in the 'xtestext1.h' file (listed in section 5).
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
|
|
</sect1>
|
|
<sect1 id="definition_of_terms">
|
|
<title>Definition Of Terms</title>
|
|
|
|
<sect2 id="input_actions">
|
|
<title>Input Actions</title>
|
|
<para>
|
|
Input actions are pointer movements, button presses and releases,
|
|
and key presses and releases. They can be generated by a user or by a client
|
|
(using functions in this extension).
|
|
</para>
|
|
</sect2>
|
|
|
|
<sect2 id="user_input_actions">
|
|
<title>User Input Actions</title>
|
|
<para>
|
|
User input actions are input actions that are generated by the user
|
|
moving a pointing device (typically a mouse), pressing and releasing buttons on
|
|
the pointing device, and pressing and releasing keys on the keyboard.
|
|
</para>
|
|
</sect2>
|
|
|
|
</sect1>
|
|
|
|
<sect1 id="what_does_this_extension_do">
|
|
<title>What Does This Extension Do?</title>
|
|
<para>
|
|
Without this extension, user input actions are processed by the server,
|
|
and are converted into normal X events that are sent to the
|
|
appropriate client or clients.
|
|
</para>
|
|
|
|
<para>
|
|
This extension adds the following capabilities:
|
|
</para>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
Input actions may be sent from a client to the server to be
|
|
processed just as if the user had physically performed them.
|
|
The input actions are provided to the server in the form of X protocol
|
|
requests defined by this extension.
|
|
The information provided to the server includes what action should be
|
|
performed, and how long to delay before processing the action in the server.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
User input actions may be diverted to a client before being processed by the
|
|
server.
|
|
The effect on the server is as if the user had performed no input action.
|
|
The user input actions are provided to the client in the form of X events
|
|
defined by this extension.
|
|
The information provided to the client includes what user input action
|
|
occurred and the delay between this user input action and the previous user
|
|
input action.
|
|
The client may then do anything it wishes with this information.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
User input actions may be copied, with one copy going to the server in the
|
|
normal way, and the other copy being sent to a client as described above.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
|
|
</sect1>
|
|
<sect1 id="functions_in_this_extension">
|
|
<title>Functions In This Extension</title>
|
|
|
|
<sect2 id="high_level_functions">
|
|
<title>High Level Functions</title>
|
|
|
|
<para>
|
|
These functions are built on top of the low level functions described later.
|
|
</para>
|
|
|
|
<sect3 id="xtestmovepointer">
|
|
<title>XTestMovePointer</title>
|
|
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>int <function>XTestMovePointer</function></funcdef>
|
|
<paramdef>Display <parameter>*display</parameter></paramdef>
|
|
<paramdef>int <parameter>device_id</parameter></paramdef>
|
|
<paramdef>unsigned long <parameter>delay</parameter></paramdef>
|
|
<paramdef>int <parameter>x</parameter></paramdef>
|
|
<paramdef>int <parameter>y</parameter></paramdef>
|
|
<paramdef>unsigned int <parameter>count</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>display</term>
|
|
<listitem>
|
|
<para>
|
|
Specifies the connection to the X server.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>device_id</term>
|
|
<listitem>
|
|
<para>
|
|
Specifies which pointer device was supposed to have caused the input action.
|
|
This is a provision for future support of multiple (distinguishable) pointer
|
|
devices, and should always be set to 0 for now.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>delay</term>
|
|
<listitem>
|
|
<para>
|
|
Specifies the time (in milliseconds) to wait before each movement
|
|
of the pointer.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>x, y</term>
|
|
<listitem>
|
|
<para>
|
|
Specifies the x and y coordinates to move the pointer to relative to the
|
|
root window for the specified display.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>count</term>
|
|
<listitem>
|
|
<para>
|
|
Specifies the number of 'delay, x, y' triplets contained in the
|
|
<emphasis>delay</emphasis>,
|
|
<emphasis>x</emphasis> and
|
|
<emphasis>y</emphasis> arrays.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
|
|
<para>
|
|
The
|
|
<function>XTestMovePointer</function>
|
|
function creates input actions to be sent to the the server.
|
|
The input actions will be accumulated in a request defined by this extension
|
|
until the request is full or the XTestFlush function is called.
|
|
They will then be sent to the server.
|
|
When the input actions are sent to the server, the input actions will cause
|
|
the server to think that the pointer was moved to the specified position(s),
|
|
with the specified delay before each input action.
|
|
</para>
|
|
<para>
|
|
The
|
|
<function>XTestMovePointer</function>
|
|
function will return -1 if there is an error, and 0 otherwise.
|
|
</para>
|
|
</sect3>
|
|
|
|
<sect3 id="xtestpressbutton">
|
|
<title>XTestPressButton</title>
|
|
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>int <function>XTestPressButton</function></funcdef>
|
|
<paramdef>Display <parameter>*display</parameter></paramdef>
|
|
<paramdef>int <parameter>device_id</parameter></paramdef>
|
|
<paramdef>unsigned long <parameter>delay</parameter></paramdef>
|
|
<paramdef>unsigned int <parameter>button_number</parameter></paramdef>
|
|
<paramdef>unsigned int <parameter>button_action</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
|
|
|
|
<!-- .VL 15 -->
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>display</term>
|
|
<listitem>
|
|
<para>
|
|
Specifies the connection to the X server.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>device_id</term>
|
|
<listitem>
|
|
<para>
|
|
Specifies which button device was supposed to have caused the input action.
|
|
This is a provision for future support of multiple (distinguishable) button
|
|
devices, and should always be set to 0 for now.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>delay</term>
|
|
<listitem>
|
|
<para>
|
|
Specifies the time (in milliseconds) to wait before the input action.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>button_number</term>
|
|
<listitem>
|
|
<para>
|
|
Specifies which button is being acted upon.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>button_action</term>
|
|
<listitem>
|
|
<para>
|
|
Specifies the action to be performed (one of
|
|
<emphasis>XTestPRESS</emphasis>,
|
|
<emphasis>XTestRELEASE</emphasis>, or
|
|
<emphasis>XTestSTROKE</emphasis>).
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
|
|
<para>
|
|
The
|
|
<function>XTestPressButton</function>
|
|
function creates input actions to be sent to the the server.
|
|
The input actions will be accumulated in a request defined by this extension
|
|
until the request is full or the XTestFlush function is called.
|
|
They will then be sent to the server.
|
|
When the input actions are sent to the server, the input actions will cause
|
|
the server to think that the specified button was moved as specified.
|
|
</para>
|
|
<para>
|
|
The
|
|
<function>XTestPressButton</function>
|
|
function will return -1 if there is an error, and 0 otherwise.
|
|
</para>
|
|
</sect3>
|
|
|
|
<sect3 id="xtestpresskey">
|
|
<title>XTestPressKey</title>
|
|
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>int <function>XTestPressKey</function></funcdef>
|
|
<paramdef>Display <parameter>*display</parameter></paramdef>
|
|
<paramdef>int <parameter>device_id</parameter></paramdef>
|
|
<paramdef>unsigned long <parameter>delay</parameter></paramdef>
|
|
<paramdef>unsigned int <parameter>keycode</parameter></paramdef>
|
|
<paramdef>unsigned int <parameter>key_action</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
|
|
<!-- .VL 12 -->
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>display</term>
|
|
<listitem>
|
|
<para>
|
|
Specifies the connection to the X server.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>device_id</term>
|
|
<listitem>
|
|
<para>
|
|
Specifies which keyboard device was supposed to have caused the input action.
|
|
This is a provision for future support of multiple (distinguishable) keyboard
|
|
devices, and should always be set to 0 for now.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>delay</term>
|
|
<listitem>
|
|
<para>
|
|
Specifies the time (in milliseconds) to wait before the input action.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>keycode</term>
|
|
<listitem>
|
|
<para>
|
|
Specifies which keycode is being acted upon.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>key_action</term>
|
|
<listitem>
|
|
<para>
|
|
Specifies the action to be performed (one of
|
|
<emphasis>XTestPRESS</emphasis>,
|
|
<emphasis>XTestRELEASE</emphasis>, or
|
|
<emphasis>XTestSTROKE</emphasis>).
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
|
|
|
|
<para>
|
|
The
|
|
<function>XTestPressKey</function>
|
|
function creates input actions to be sent to the the server.
|
|
The input actions will be accumulated in a request defined by this extension
|
|
until the request is full or the XTestFlush function is called.
|
|
They will then be sent to the server.
|
|
When the input actions are sent to the server, the input actions will cause
|
|
the server to think that the specified key on the keyboard was moved as
|
|
specified.
|
|
</para>
|
|
|
|
<para>
|
|
The
|
|
<function>XTestPressKey</function>
|
|
function will return -1 if there is an error, and 0 otherwise.
|
|
</para>
|
|
|
|
</sect3>
|
|
<sect3 id="xtestflush">
|
|
<title>XTestFlush</title>
|
|
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>int <function>XTestFlush</function></funcdef>
|
|
<paramdef>Display <parameter>*display</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
|
|
<!-- .VL 9 -->
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>display</term>
|
|
<listitem>
|
|
<para>
|
|
Specifies the connection to the X server.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
|
|
<para>
|
|
The
|
|
<function>XTestFlush</function>
|
|
will send any remaining input actions to the server.
|
|
</para>
|
|
|
|
<para>
|
|
The
|
|
<function>XTestFlush</function>
|
|
function will return -1 if there is an error, and 0 otherwise.
|
|
</para>
|
|
|
|
</sect3>
|
|
</sect2>
|
|
|
|
<!-- .H 2 Low~Level~Functions -->
|
|
<sect2 id="low_level_functions">
|
|
<title>Low Level Functions</title>
|
|
|
|
<!-- .H 3 XTestGetInput -->
|
|
<sect3 id="xtestgetinput">
|
|
<title>XTestGetInput</title>
|
|
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>int <function>XTestGetInput</function></funcdef>
|
|
<paramdef>Display <parameter>*display</parameter></paramdef>
|
|
<paramdef>int <parameter>action_handling</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>display</term>
|
|
<listitem>
|
|
<para>
|
|
Specifies the connection to the X server.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>action_handling</term>
|
|
<listitem>
|
|
<para>
|
|
Specifies to the server what to do with the user input actions. (one of
|
|
0, <emphasis>XTestPACKED_MOTION</emphasis> or
|
|
<emphasis>XTestPACKED_ACTIONS</emphasis>; optionally 'or'ed
|
|
with <emphasis>XTestEXCLUSIVE</emphasis>).
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
|
|
|
|
<para>
|
|
The
|
|
<function>XTestGetInput</function>
|
|
function tells the server to begin putting information about user input actions
|
|
into events to be sent to the client that called this function. These events
|
|
can be read via the Xlib <function>XNextEvent</function>fR function.
|
|
</para>
|
|
|
|
<para>
|
|
The server assigns an event type of
|
|
<emphasis>XTestInputActionType</emphasis> to these events
|
|
to distinguish them from other events.
|
|
Since the actual value of the event type may vary depending on how many
|
|
extensions are included with an X11 implementation,
|
|
<emphasis>XTestInputActionType</emphasis> is a variable that will be
|
|
contained in the Xlib
|
|
part of this extension. It may be referenced as follows:
|
|
</para>
|
|
|
|
<para>
|
|
extern int XTestInputActionType;
|
|
</para>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
An <emphasis>action_handling</emphasis> value of 0 causes the server
|
|
to send one user input action in each
|
|
<emphasis>XTestInputActionType</emphasis> event.
|
|
This can sometimes cause performance problems.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
An <emphasis>action_handling</emphasis> value of
|
|
<emphasis>XTestPACKED_ACTIONS</emphasis> causes the server
|
|
to pack as many user input actions as possible into a
|
|
<emphasis>XTestInputActionType</emphasis> event.
|
|
This is needed if user input actions are happening rapidly (such as
|
|
when the user moves the pointer) to keep performance at a reasonable level.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
An <emphasis>action_handling</emphasis> value of
|
|
<emphasis>XTestPACKED_MOTION</emphasis> causes the server
|
|
to pack only user input actions associated with moving the pointer.
|
|
This allows the
|
|
client to receive button and key motions as they happen without waiting for the
|
|
event to fill up, while still keeping performance at a reasonable level.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
An <emphasis>action_handling</emphasis> value with
|
|
<emphasis>XTestEXCLUSIVE</emphasis> 'or'ed in
|
|
causes the server to send user input actions only to the client.
|
|
The effect on the server is as if the user had performed no input actions.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
An <emphasis>action_handling</emphasis> value without
|
|
<emphasis>XTestEXCLUSIVE</emphasis>
|
|
causes the server to copy user input actions, sending one copy to the
|
|
client, and handling the other copy normally (as it would if this extension
|
|
were not installed).
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
|
|
<para>
|
|
There are four types of input actions that are passed from the server
|
|
to the client. They are:
|
|
</para>
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>key/button~state~change</term>
|
|
<listitem>
|
|
<para>
|
|
This type of input action contains the keycode of the key or button that
|
|
changed state;
|
|
whether the key or button is up or down,
|
|
and the time delay between this input action and the previous input action.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>pointer~motions</term>
|
|
<listitem>
|
|
<para>
|
|
This type of input action contains information about the motion of the
|
|
pointer when the pointer has only moved a short distance.
|
|
If the pointer has moved a long distance,
|
|
the pointer jump input action is used.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>pointer~jumps</term>
|
|
<listitem>
|
|
<para>
|
|
This type of input action contains information about the motion of the
|
|
pointer when the pointer has moved a long distance.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>delays</term>
|
|
<listitem>
|
|
<para>
|
|
This type of input action is used when the delay between input actions is too
|
|
large to be held in the other input actions.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
|
|
<para>
|
|
The
|
|
<function>XTestGetInput</function>
|
|
function will return -1 if there is an error, and 0 otherwise.
|
|
</para>
|
|
<para>
|
|
An error code of <emphasis>BadAccess</emphasis> means that another client
|
|
has already requested that user input actions be sent to it.
|
|
</para>
|
|
|
|
</sect3>
|
|
|
|
<!-- .H 3 XTestStopInput -->
|
|
<sect3 id="xteststopinput">
|
|
<title>XTestStopInput</title>
|
|
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>int <function>XTestStopInput</function></funcdef>
|
|
<paramdef>Display <parameter>*display</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
|
|
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>display</term>
|
|
<listitem>
|
|
<para>
|
|
Specifies the connection to the X server.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
|
|
<para>
|
|
The
|
|
<function>XTestStopInput</function>
|
|
function tells the server to stop putting information about user input actions
|
|
into events.
|
|
The server will process user input actions normally (as it would
|
|
if this extension were not in the server).
|
|
</para>
|
|
|
|
<para>
|
|
The
|
|
<function>XTestStopInput</function>
|
|
function will return -1 if there is an error, and 0 otherwise.
|
|
</para>
|
|
|
|
<para>
|
|
An error code of <emphasis>BadAccess</emphasis> means that a request
|
|
was made to stop input when input has never been started.
|
|
</para>
|
|
|
|
</sect3>
|
|
|
|
<!-- .H 3 XTestFakeInput -->
|
|
<sect3 id="xtestfakeinput">
|
|
<title>XTestFakeInput</title>
|
|
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>int <function>XTestFakeInput</function></funcdef>
|
|
<paramdef>Display <parameter>*display</parameter></paramdef>
|
|
<paramdef>char <parameter>*action_list_addr</parameter></paramdef>
|
|
<paramdef>int <parameter>action_list_size</parameter></paramdef>
|
|
<paramdef>int <parameter>ack_flag</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
|
|
|
|
<!-- .VL 18 -->
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>display</term>
|
|
<listitem>
|
|
<para>
|
|
Specifies the connection to the X server.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>action_list_addr</term>
|
|
<listitem>
|
|
<para>
|
|
Specifies the address of an list of input actions to be sent to the server.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>action_list_size</term>
|
|
<listitem>
|
|
<para>
|
|
Specifies the size (in bytes) of the list of input actions.
|
|
It may be no larger than <emphasis>XTestMAX_ACTION_LIST_SIZE</emphasis> bytes.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>ack_flag</term>
|
|
<listitem>
|
|
<para>
|
|
Specifies whether the server needs to send an event to indicate that its
|
|
input action buffer is empty (one of
|
|
<emphasis>XTestFAKE_ACK_NOT_NEEDED</emphasis> or
|
|
<emphasis>XTestFAKE_ACK_REQUEST</emphasis>).
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
|
|
<para>
|
|
The
|
|
<function>XTestFakeInput</function>
|
|
function tells the server to take the specified user input actions and process
|
|
them as if the user had physically performed them.
|
|
</para>
|
|
|
|
<para>
|
|
The server can only accept a limited number of input actions at one
|
|
time. This limit can be determined by the
|
|
<function>XTestQueryInputSize</function> function
|
|
in this extension.
|
|
</para>
|
|
|
|
<para>
|
|
The client should set <emphasis>ack_flag</emphasis> to
|
|
<emphasis>XTestFAKE_ACK_NOT_NEEDED</emphasis>
|
|
on calls to <emphasis>XTestFakeInput</emphasis> that do not reach this limit.
|
|
</para>
|
|
|
|
<para>
|
|
The client should set <emphasis>ack_flag</emphasis> to
|
|
<emphasis>XTestFAKE_ACK_REQUEST</emphasis>
|
|
on the call to <emphasis>XTestFakeInput</emphasis> that reaches this limit.
|
|
</para>
|
|
|
|
<para>
|
|
When the server sees an <emphasis>ack_flag</emphasis> value of
|
|
<emphasis>XTestFAKE_ACK_REQUEST</emphasis>
|
|
it finishes processing its input action buffer, then sends an event with
|
|
type <emphasis>XTestFakeAckType</emphasis> to the client.
|
|
When the client reads this event, it knows that it is safe to resume
|
|
sending input actions to the server.
|
|
</para>
|
|
|
|
<para>
|
|
Since the actual value of the event type may vary depending on how many
|
|
extensions are included with an X11 implementation,
|
|
<emphasis>XTestFakeAckType</emphasis> is a variable that is contained
|
|
in the Xlib part of this extension. It may be referenced as follows:
|
|
</para>
|
|
|
|
<para>
|
|
extern int XTestFakeAckType;
|
|
</para>
|
|
|
|
<para>
|
|
There are four types of input actions that are passed from the client
|
|
to the server. They are:
|
|
</para>
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>key/button~state~change</term>
|
|
<listitem>
|
|
<para>
|
|
This type of input action contains the keycode of the key or button that
|
|
is to change state;
|
|
whether the key or button is to be up or down,
|
|
and the time to delay before changing the state of the key or button.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>pointer~motions</term>
|
|
<listitem>
|
|
<para>
|
|
This type of input action contains information about the motion of the
|
|
pointer when the pointer is to be moved a short distance,
|
|
and the time to delay before moving the pointer.
|
|
If the pointer is to be moved a long distance,
|
|
the pointer jump input action must be used.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>pointer~jumps</term>
|
|
<listitem>
|
|
<para>
|
|
This type of input action contains information about the motion of the
|
|
pointer when the pointer is to be moved a long distance,
|
|
and the time to delay before moving the pointer.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>delays</term>
|
|
<listitem>
|
|
<para>
|
|
This type of input action is used when the delay between input actions is too
|
|
large to be held in the other input actions.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
|
|
|
|
<para>
|
|
The
|
|
<function>XTestFakeInput</function>
|
|
function will return -1 if there is an error, and 0 otherwise.
|
|
</para>
|
|
|
|
<para>
|
|
An error code of \fIBadAccess\fR means that another client has already
|
|
sent user input actions to the server, and the server has not finished
|
|
processing the user input actions.
|
|
</para>
|
|
|
|
</sect3>
|
|
|
|
<!-- .H 3 XTestQueryInputSize -->
|
|
<sect3 id="xtestqueryinputsize">
|
|
<title>XTestQueryInputSize</title>
|
|
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>int <function>XTestQueryInputSize</function></funcdef>
|
|
<paramdef>Display <parameter>*display</parameter></paramdef>
|
|
<paramdef>unsigned long <parameter>size_return</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>display</term>
|
|
<listitem>
|
|
<para>
|
|
Specifies the connection to the X server.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>size_return</term>
|
|
<listitem>
|
|
<para>
|
|
Returns the number of input actions that the server's input action buffer can
|
|
hold.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
|
|
<para>
|
|
The
|
|
<function>XTestQueryInputSize</function>
|
|
function asks the server to return the number of input actions that it can hold
|
|
in its input action buffer in the unsigned long pointed to by \fIsize_return\fR.
|
|
</para>
|
|
<para>
|
|
The
|
|
<function>XTestQueryInputSize</function>
|
|
function will return -1 if there is an error, and 0 otherwise.
|
|
</para>
|
|
</sect3>
|
|
|
|
<!-- .H 3 XTestReset -->
|
|
<sect3 id="xtestreset">
|
|
<title>XTestReset</title>
|
|
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>int <function>XTestReset</function></funcdef>
|
|
<paramdef>Display <parameter>*display</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>display</term>
|
|
<listitem>
|
|
<para>
|
|
Specifies the connection to the X server.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
|
|
<para>
|
|
The
|
|
<function>XTestReset</function>
|
|
function tells the server to set everything having to do with this extension
|
|
back to its initial state. After this call the server will act as if this
|
|
extension were not installed until one of the extension functions is called by
|
|
a client. This function is not normally needed, but is included in case a
|
|
client wishes to clean up the server state, such as after a serious error.
|
|
</para>
|
|
|
|
<para>
|
|
The
|
|
<function>XTestReset</function>
|
|
function will return -1 if there is an error, and 0 otherwise.
|
|
</para>
|
|
|
|
</sect3>
|
|
</sect2>
|
|
</sect1>
|
|
|
|
<!-- .H 1 'xtestext1.h'~File~Listing -->
|
|
<!-- .so xtestext1.h -->
|
|
<!-- .TC 1 1 4 -->
|
|
</article>
|