X Version 11 (Release 6.1)

XTest(X3xext)

XTest -- Test server with no user intervention.

Synopsis

   #include "Xlibint.h"
   #include "X11/Xproto.h"
   #include "xtestext1.h"
   #include <stdio.h>
   
   int XTestMovePointer (display, device_id, delay,
                        x, y, count)
           Display display;
           int device_id;
           unsigned long delay[];
           int x[];
           int y[];
           unsigned int count;
   

   

   int XTestPressButton (display, device_id, delay, button_number,
                        button_action)
           Display display;
           int device_id;
           unsigned long delay;
           unsigned int button_number;
           unsigned int button_action;
   

   

   int XTestPressKey (display, device_id, delay, keycode, key_action)
           Display display;
           int device_id;
           unsigned long delay;
           unsigned int keycode;
           unsigned int key_action;
   

   

   int XTestFlush (display)
           Display display;
   

   

   int XTestGetInput (display, action_handling)
           Display display;
           int action_handling;

   int XTestStopInput (display)
           Display display;
   
   

   int XTestFakeInput (display, action_list_addr, action_list_size,
                      ack_flag)
           Display display;
   	char action_list_addr;
           int action_list_size;
           int ack_flag;
   

   

   int XTestQueryInputSize (display, size_return)
           Display display;
           unsigned long size_return;
   

   

   int XTestReset (display)
           Display display;
   

   

   int XTestStartSimulation(dpy)
           Display *dpy;
   

   int XTestStopSimulation(dpy)
           Display *dpy;

Description

Support for this extension may be dropped in the future. Developers who wish to write test and control clients should use the XTest(X3xext) extension.

In this description, "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). "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.

This extension adds the following capabilities:

Input actions may be sent from a client to the server to be processed just as if the user had physically performed them. The information provided to the server includes what action should be performed, and how long to delay before processing the action in the server.

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.

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.

Each XTest function will return -1 if there is an error, and 0 otherwise.

Each XTest function can return an error code of BadAccess.

The XTestMovePointer, XTestPressButton and XTestPressKey functions create input actions to be sent to the server. The input actions will be accumulated in a request. When the request is full or the XTestFlush function is called, the input actions will be sent to the server. The server will interpret the input actions as:

XTestMovePointer: the pointer was moved to the specified position(s), with the specified delay before each input action.
XTestPressButton: the specified button was moved as specified.
XTestPressKey: the specified key on the keyboard was moved as specified.

The XTestFlush function will send any remaining input actions to the server and mark the input action buffer as empty.

When the XTestGetInput function is used, the server will begin putting information about user input actions into events to be sent to the client. There are four types of user input actions that are passed from the server to the client. They are:

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.
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.
pointer jumps: This type of input action contains information about the motion of the pointer when the pointer has moved a long distance.
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.

These events can be read via the Xlib XNextEvent(X3xlib) function. The server assigns an event type of TestInputActionType to these events. Passing XTestGetInput an action_handling value of:

0, causes the server to send one user input action in each XTestInputActionType event.
XTestPACKED_ACTIONS, causes the server to pack as many user input actions as possible into a XTestInputActionType event. This will enhance performance.
XTestPACKED_MOTION, causes the server to pack only user input actions associated with moving the pointer, allowing the client to receive button and key motions as they occur.

If XTestEXCLUSIVE is `or'ed in with any action_handling value, the server will send user input actions to the client only. The effect on the server is as if the user had performed no input actions.

If XTestEXCLUSIVE is not used, the server will 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.

When the XTestStopInput function is called the server will stop putting information about user input actions into events. The server will process user input actions normally.

When the XTestFakeInput function is used the server will take the specified input actions and process them as if the user had physically performed them. The types of user input that can be sent are listed in the the XTestGetInput description.

The server can only accept a limited number of input actions. This limit is determined by the XTestQueryInputSize function; the limit is returned in size_return.

For calls to XTestFakeInput that do not reach this limit, set ack_flag to ``XTestFAKE_ACK_NOT_NEEDED''. On the call to XTestFakeInput that reaches this limit, set ack_flag to ``XTestFAKE_ACK_REQUEST''.

When the server receives an ack_flag value of ``XTestFAKE_ACK_REQUEST'' it finishes processing its input action buffer, then sends an event with type XTestFakeAckType to the client. When the client reads this event, the client can resume sending input actions to the server. Since the actual value of the event type may vary depending on how many extensions are included with an X11 implementation, XTestFakeAckType is a variable that is contained in the Xlib part of this extension. It may be referenced as follows:

extern int XTestFakeAckType;

When the XTestReset function is used, the server will set everything having to do with this extension back to its initial state. This function is included to allow a client clean up the server state, such as after a serious error.

XTestStartSimulation is used to start the request process. This call must be made by the client using this extension to register itself with the server as the client which will be sending input. The client making this request will not be excluded from sending test events should the server be grabbed by another client using the XGrabServer(X3xlib) function.

XTestStopSimulation is used to tell the server that this client will no longer be sending test events to the server.

Arguments

ack_flag: Specifies whether the server needs to send an event to indicate that its input action buffer is empty; one of XTestFAKE_ACK_NOT_NEEDED or XTestFAKE_ACK_REQUEST.
action_handling: Specifies to the server what to do with the user input actions. (one of 0, XTestPACKED_MOTION or XTestPACKED_ACTIONS; optionally 'or'ed with XTestEXCLUSIVE).
action_list_addr: Specifies the address of a list of input actions to be sent to the server.
action_list_size: Specifies the size (in bytes) of the list of input actions. It may be no larger than XTestMAX_ACTION_LIST_SIZE bytes.
button_action: Specifies the action to be performed; one of XTestPRESS, XTestRELEASE, or XTestSTROKE.
button_number: Specifies the pointer button for the input action.
count: Specifies the number of `delay, x, y' triplets contained in the delay, x and y arrays.
delay: Specifies the time (in milliseconds) to wait before the input action.
device_id: Specifies which device was supposed to have caused the input action. This is a provision for future support of multiple devices of the same type and should always be set to 0 for this release.
display: Specifies the connection to the X server.
key_action: Specifies the action to be performed. One of XTestPRESS, XTestRELEASE, or XTestSTROKE.
keycode: Specifies the KeyCode for the input action.
size_return: Returns the number of input actions that the server's input action buffer can hold.
x
y: Specifies the x and y coordinates to which the pointer will move. The coordinates are relative to the root window for the specified display.

Predefined values

ack_flag

XTestFAKE_ACK_NOT_NEEDED
XTextFAKE_ACK_REQUEST

action_list_size

XTestMAX_ACTION_LIST_SIZE

action_handling

XTestPACKED_MOTION
XTestPACKED_ACTIONS
XTestEXCLUSIVE

button_action and key_action

XTestPRESS
XTestRELEASE
XTestSTROKE

Diagnostics

BadAccess: indicates that another client has already requested that user input actions be sent.

References

Xlib - C Language X Interface