042aae5043
* XKB-Config(7), XKB-Enhancing(7): user-level documentation for XKB configuration; not perfect, but the best available. * xtrans(3): a library actively maintained upstream. * libXmu and libXext: Many libraries are effectively frozen upstream. According to matthieu@, the documentation of libXmu and libXext is among the most valuable of those. Feedback and OK matthieu@.
587 lines
17 KiB
Groff
587 lines
17 KiB
Groff
.\" automatically generated with docbook2mdoc xtest1.xml
|
|
.Dd $Mdocdate: May 10 2019 $
|
|
.Dt XTEST1 3
|
|
.Os
|
|
.Sh NAME
|
|
.Nm xtest1
|
|
.Nd X11 INPUT SYNTHESIS EXTENSION PROPOSAL
|
|
.Sh ABSTRACT
|
|
This is a proposal for an extension to the X11 server and Xlib.
|
|
.Sh INTRODUCTION
|
|
This is a proposal for an extension to the X11 server and Xlib.
|
|
It provides two capabilities:
|
|
.Bl -bullet
|
|
.It
|
|
It allows a client to generate user input actions in the server without
|
|
requiring a user to be present.
|
|
.It
|
|
It also allows a client to control the
|
|
handling of user input actions by the server.
|
|
.El
|
|
.Pp
|
|
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.
|
|
.Pp
|
|
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.
|
|
.Sh CONVENTIONS USED IN THIS DOCUMENT
|
|
The naming conventions used in the Xlib documentation are followed
|
|
with these additions:
|
|
.Bl -bullet
|
|
.It
|
|
The names of all functions defined in this extension begin with 'XTest',
|
|
with the first letter of each additional word capitalized.
|
|
.It
|
|
The names of the protocol request structures follow the Xlib convention
|
|
of 'x<name>Req'.
|
|
.It
|
|
The names of the protocol request minor type codes follow the Xlib convention
|
|
of 'X_<name>'.
|
|
.It
|
|
The names of all other constants defined in this extension begin with 'XTest',
|
|
with the rest of the name in upper case letters.
|
|
.It
|
|
All constants and structures defined in this extension will have their
|
|
values specified in the 'xtestext1.h' file (listed in section 5).
|
|
.El
|
|
.Sh DEFINITION OF TERMS
|
|
.Ss Input Actions
|
|
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).
|
|
.Ss User Input Actions
|
|
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.
|
|
.Sh WHAT DOES THIS EXTENSION DO?
|
|
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.
|
|
.Pp
|
|
This extension adds the following capabilities:
|
|
.Bl -bullet
|
|
.It
|
|
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.
|
|
.It
|
|
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.
|
|
.It
|
|
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.
|
|
.El
|
|
.Sh FUNCTIONS IN THIS EXTENSION
|
|
.Ss High Level Functions
|
|
These functions are built on top of the low level functions described later.
|
|
.Pp
|
|
.Sy XTestMovePointer
|
|
.Pp
|
|
.Ft int
|
|
.Fo XTestMovePointer
|
|
.Fa "Display *display"
|
|
.Fa "int device_id"
|
|
.Fa "unsigned long delay"
|
|
.Fa "int x"
|
|
.Fa "int y"
|
|
.Fa "unsigned int count"
|
|
.Fc
|
|
.Bl -tag -width Ds
|
|
.It display
|
|
Specifies the connection to the X server.
|
|
.It device_id
|
|
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.
|
|
.It delay
|
|
Specifies the time (in milliseconds) to wait before each movement
|
|
of the pointer.
|
|
.It x, y
|
|
Specifies the x and y coordinates to move the pointer to relative to the
|
|
root window for the specified display.
|
|
.It count
|
|
Specifies the number of 'delay, x, y' triplets contained in the
|
|
.Em delay ,
|
|
.Em x
|
|
and
|
|
.Em y
|
|
arrays.
|
|
.El
|
|
.Pp
|
|
The
|
|
.Fn XTestMovePointer
|
|
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.
|
|
.Pp
|
|
The
|
|
.Fn XTestMovePointer
|
|
function will return -1 if there is an error, and 0 otherwise.
|
|
.Pp
|
|
.Sy XTestPressButton
|
|
.Pp
|
|
.Ft int
|
|
.Fo XTestPressButton
|
|
.Fa "Display *display"
|
|
.Fa "int device_id"
|
|
.Fa "unsigned long delay"
|
|
.Fa "unsigned int button_number"
|
|
.Fa "unsigned int button_action"
|
|
.Fc
|
|
.Bl -tag -width Ds
|
|
.It display
|
|
Specifies the connection to the X server.
|
|
.It device_id
|
|
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.
|
|
.It delay
|
|
Specifies the time (in milliseconds) to wait before the input action.
|
|
.It button_number
|
|
Specifies which button is being acted upon.
|
|
.It button_action
|
|
Specifies the action to be performed (one of
|
|
.Em XTestPRESS ,
|
|
.Em XTestRELEASE ,
|
|
or
|
|
.Em XTestSTROKE ) .
|
|
.El
|
|
.Pp
|
|
The
|
|
.Fn XTestPressButton
|
|
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.
|
|
.Pp
|
|
The
|
|
.Fn XTestPressButton
|
|
function will return -1 if there is an error, and 0 otherwise.
|
|
.Pp
|
|
.Sy XTestPressKey
|
|
.Pp
|
|
.Ft int
|
|
.Fo XTestPressKey
|
|
.Fa "Display *display"
|
|
.Fa "int device_id"
|
|
.Fa "unsigned long delay"
|
|
.Fa "unsigned int keycode"
|
|
.Fa "unsigned int key_action"
|
|
.Fc
|
|
.Bl -tag -width Ds
|
|
.It display
|
|
Specifies the connection to the X server.
|
|
.It device_id
|
|
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.
|
|
.It delay
|
|
Specifies the time (in milliseconds) to wait before the input action.
|
|
.It keycode
|
|
Specifies which keycode is being acted upon.
|
|
.It key_action
|
|
Specifies the action to be performed (one of
|
|
.Em XTestPRESS ,
|
|
.Em XTestRELEASE ,
|
|
or
|
|
.Em XTestSTROKE ) .
|
|
.El
|
|
.Pp
|
|
The
|
|
.Fn XTestPressKey
|
|
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.
|
|
.Pp
|
|
The
|
|
.Fn XTestPressKey
|
|
function will return -1 if there is an error, and 0 otherwise.
|
|
.Pp
|
|
.Sy XTestFlush
|
|
.Pp
|
|
.Ft int
|
|
.Fo XTestFlush
|
|
.Fa "Display *display"
|
|
.Fc
|
|
.Bl -tag -width Ds
|
|
.It display
|
|
Specifies the connection to the X server.
|
|
.El
|
|
.Pp
|
|
The
|
|
.Fn XTestFlush
|
|
will send any remaining input actions to the server.
|
|
.Pp
|
|
The
|
|
.Fn XTestFlush
|
|
function will return -1 if there is an error, and 0 otherwise.
|
|
.Ss Low Level Functions
|
|
.Sy XTestGetInput
|
|
.Pp
|
|
.Ft int
|
|
.Fo XTestGetInput
|
|
.Fa "Display *display"
|
|
.Fa "int action_handling"
|
|
.Fc
|
|
.Bl -tag -width Ds
|
|
.It display
|
|
Specifies the connection to the X server.
|
|
.It action_handling
|
|
Specifies to the server what to do with the user input actions.
|
|
(one of
|
|
0,
|
|
.Em XTestPACKED_MOTION
|
|
or
|
|
.Em XTestPACKED_ACTIONS ;
|
|
optionally 'or'ed
|
|
with
|
|
.Em XTestEXCLUSIVE ) .
|
|
.El
|
|
.Pp
|
|
The
|
|
.Fn XTestGetInput
|
|
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
|
|
.Fn XNextEvent Ns fR
|
|
function.
|
|
.Pp
|
|
The server assigns an event type of
|
|
.Em XTestInputActionType
|
|
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,
|
|
.Em XTestInputActionType
|
|
is a variable that will be
|
|
contained in the Xlib
|
|
part of this extension.
|
|
It may be referenced as follows:
|
|
.Pp
|
|
extern int XTestInputActionType;
|
|
.Bl -bullet
|
|
.It
|
|
An
|
|
.Em action_handling
|
|
value of 0 causes the server
|
|
to send one user input action in each
|
|
.Em XTestInputActionType
|
|
event.
|
|
This can sometimes cause performance problems.
|
|
.It
|
|
An
|
|
.Em action_handling
|
|
value of
|
|
.Em XTestPACKED_ACTIONS
|
|
causes the server
|
|
to pack as many user input actions as possible into a
|
|
.Em XTestInputActionType
|
|
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.
|
|
.It
|
|
An
|
|
.Em action_handling
|
|
value of
|
|
.Em XTestPACKED_MOTION
|
|
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.
|
|
.It
|
|
An
|
|
.Em action_handling
|
|
value with
|
|
.Em XTestEXCLUSIVE
|
|
\&'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.
|
|
.It
|
|
An
|
|
.Em action_handling
|
|
value without
|
|
.Em XTestEXCLUSIVE
|
|
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).
|
|
.El
|
|
.Pp
|
|
There are four types of input actions that are passed from the server
|
|
to the client.
|
|
They are:
|
|
.Bl -tag -width Ds
|
|
.It key/button~state~change
|
|
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.
|
|
.It pointer~motions
|
|
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.
|
|
.It pointer~jumps
|
|
This type of input action contains information about the motion of the
|
|
pointer when the pointer has moved a long distance.
|
|
.It delays
|
|
This type of input action is used when the delay between input actions is too
|
|
large to be held in the other input actions.
|
|
.El
|
|
.Pp
|
|
The
|
|
.Fn XTestGetInput
|
|
function will return -1 if there is an error, and 0 otherwise.
|
|
.Pp
|
|
An error code of
|
|
.Em BadAccess
|
|
means that another client
|
|
has already requested that user input actions be sent to it.
|
|
.Pp
|
|
.Sy XTestStopInput
|
|
.Pp
|
|
.Ft int
|
|
.Fo XTestStopInput
|
|
.Fa "Display *display"
|
|
.Fc
|
|
.Bl -tag -width Ds
|
|
.It display
|
|
Specifies the connection to the X server.
|
|
.El
|
|
.Pp
|
|
The
|
|
.Fn XTestStopInput
|
|
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).
|
|
.Pp
|
|
The
|
|
.Fn XTestStopInput
|
|
function will return -1 if there is an error, and 0 otherwise.
|
|
.Pp
|
|
An error code of
|
|
.Em BadAccess
|
|
means that a request
|
|
was made to stop input when input has never been started.
|
|
.Pp
|
|
.Sy XTestFakeInput
|
|
.Pp
|
|
.Ft int
|
|
.Fo XTestFakeInput
|
|
.Fa "Display *display"
|
|
.Fa "char *action_list_addr"
|
|
.Fa "int action_list_size"
|
|
.Fa "int ack_flag"
|
|
.Fc
|
|
.Bl -tag -width Ds
|
|
.It display
|
|
Specifies the connection to the X server.
|
|
.It action_list_addr
|
|
Specifies the address of an list of input actions to be sent to the server.
|
|
.It action_list_size
|
|
Specifies the size (in bytes) of the list of input actions.
|
|
It may be no larger than
|
|
.Em XTestMAX_ACTION_LIST_SIZE
|
|
bytes.
|
|
.It ack_flag
|
|
Specifies whether the server needs to send an event to indicate that its
|
|
input action buffer is empty (one of
|
|
.Em XTestFAKE_ACK_NOT_NEEDED
|
|
or
|
|
.Em XTestFAKE_ACK_REQUEST ) .
|
|
.El
|
|
.Pp
|
|
The
|
|
.Fn XTestFakeInput
|
|
function tells the server to take the specified user input actions and process
|
|
them as if the user had physically performed them.
|
|
.Pp
|
|
The server can only accept a limited number of input actions at one
|
|
time.
|
|
This limit can be determined by the
|
|
.Fn XTestQueryInputSize
|
|
function
|
|
in this extension.
|
|
.Pp
|
|
The client should set
|
|
.Em ack_flag
|
|
to
|
|
.Em XTestFAKE_ACK_NOT_NEEDED
|
|
on calls to
|
|
.Em XTestFakeInput
|
|
that do not reach this limit.
|
|
.Pp
|
|
The client should set
|
|
.Em ack_flag
|
|
to
|
|
.Em XTestFAKE_ACK_REQUEST
|
|
on the call to
|
|
.Em XTestFakeInput
|
|
that reaches this limit.
|
|
.Pp
|
|
When the server sees an
|
|
.Em ack_flag
|
|
value of
|
|
.Em XTestFAKE_ACK_REQUEST
|
|
it finishes processing its input action buffer, then sends an event with
|
|
type
|
|
.Em XTestFakeAckType
|
|
to the client.
|
|
When the client reads this event, it knows that it is safe to resume
|
|
sending input actions to the server.
|
|
.Pp
|
|
Since the actual value of the event type may vary depending on how many
|
|
extensions are included with an X11 implementation,
|
|
.Em XTestFakeAckType
|
|
is a variable that is contained
|
|
in the Xlib part of this extension.
|
|
It may be referenced as follows:
|
|
.Pp
|
|
extern int XTestFakeAckType;
|
|
.Pp
|
|
There are four types of input actions that are passed from the client
|
|
to the server.
|
|
They are:
|
|
.Bl -tag -width Ds
|
|
.It key/button~state~change
|
|
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.
|
|
.It pointer~motions
|
|
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.
|
|
.It pointer~jumps
|
|
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.
|
|
.It delays
|
|
This type of input action is used when the delay between input actions is too
|
|
large to be held in the other input actions.
|
|
.El
|
|
.Pp
|
|
The
|
|
.Fn XTestFakeInput
|
|
function will return -1 if there is an error, and 0 otherwise.
|
|
.Pp
|
|
An error code of \efIBadAccess\efR means that another client has already
|
|
sent user input actions to the server, and the server has not finished
|
|
processing the user input actions.
|
|
.Pp
|
|
.Sy XTestQueryInputSize
|
|
.Pp
|
|
.Ft int
|
|
.Fo XTestQueryInputSize
|
|
.Fa "Display *display"
|
|
.Fa "unsigned long size_return"
|
|
.Fc
|
|
.Bl -tag -width Ds
|
|
.It display
|
|
Specifies the connection to the X server.
|
|
.It size_return
|
|
Returns the number of input actions that the server's input action buffer can
|
|
hold.
|
|
.El
|
|
.Pp
|
|
The
|
|
.Fn XTestQueryInputSize
|
|
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 \efIsize_return\efR.
|
|
.Pp
|
|
The
|
|
.Fn XTestQueryInputSize
|
|
function will return -1 if there is an error, and 0 otherwise.
|
|
.Pp
|
|
.Sy XTestReset
|
|
.Pp
|
|
.Ft int
|
|
.Fo XTestReset
|
|
.Fa "Display *display"
|
|
.Fc
|
|
.Bl -tag -width Ds
|
|
.It display
|
|
Specifies the connection to the X server.
|
|
.El
|
|
.Pp
|
|
The
|
|
.Fn XTestReset
|
|
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.
|
|
.Pp
|
|
The
|
|
.Fn XTestReset
|
|
function will return -1 if there is an error, and 0 otherwise.
|
|
.Sh AUTHORS
|
|
.An -nosplit
|
|
.Sy X Consortium Standard
|
|
.Pp
|
|
Version 1.0
|
|
.An -split
|
|
.An Larry Woestman ,
|
|
Member of Technical Staff
|
|
Hewlett Packard
|
|
Copyright \(co 1993X Consortium
|
|
.Ss Legal Notice
|
|
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:
|
|
.Pp
|
|
The above copyright notice and this permission notice shall be included in all
|
|
copies or substantial portions of the Software.
|
|
.Pp
|
|
THE SOFTWARE IS PROVIDED \(lqAS IS\(rq, 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.
|
|
.Pp
|
|
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.
|
|
.Pp
|
|
X Window System is a trademark of The Open Group.
|