• XID (an integer) of a cursor.
• "None" (or 0).
• "CurrentCursor" (or 1) for the currently displayed cursor.

This can be used to check that the cursor attribute of some $window is a desired setting, for example

    $desired_cursor = $X->new_rsrc;
    $X->CreateGlyphCursor ($desired_cursor, ...);
    $X->XTestCompareCursor ($window, $desired_cursor)
      or die "Oops, $window doesn't have desired cursor";

Or alternatively, construct a window with a particular cursor and use "CurrentCursor" to check that what's currently displayed is as desired, for example to see if a "GrabPointer()" is displaying what's intended,

    my $test_window = $X->new_rsrc;
    $X->CreateWindow ($test_window, ...,
                      cursor => $desired_cursor);
    $X->XTestCompareCursor ($test_window, "CurrentCursor");
      or die "Oops, currently displayed cursor is not as desired";

Button Press and Release

The argument fields are

    name       "ButtonPress" or "ButtonRelease"
    detail     physical button number (1 upwards)
    time       milliseconds delay before event, default 0
    

For example to fake a physical button 3 press

    $X->XTestFakeInput (name   => 'ButtonPress',
                        detail => 3);
    

"detail" is the physical button number, before the core protocol "SetPointerMapping()" translation is applied. To simulate a logical button it's necessary to check "GetPointerMapping()" to see which physical button, if any, corresponds.

Be careful when faking a "ButtonPress" as it might be important to fake a matching "ButtonRelease" too. On the X.org server circa 1.9.x after a synthetic press the physical mouse doesn't work to generate a release and the button is left hung (presumably in its normal implicit pointer grab).

Key Press and Release

The argument fields are

    name       "KeyPress" or "KeyRelease"
    detail     keycode (integer)
    time       milliseconds delay before event, default 0
    

Mouse Pointer Movement

Mouse pointer motion can be induced with the following. The effect is similar to a "WarpPointer()".

    name       "MotionNotify"
    root       XID of root window, default "None" for current
    root_x     \ pointer position to move to
    root_y     /
    detail     flag 0=absolute, 1=relative, default 0
    time       milliseconds delay before event, default 0
    

"root" is the root window (integer XID) to move on. The default "None" (or 0) means the screen the pointer is currently on.

    $X->XTestFakeInput (name   => 'MotionNotify',
                        root_x => 123,
                        root_y => 456);
    

"detail" can be 1 to move relative to the current mouse position.

    $X->XTestFakeInput (name   => 'MotionNotify',
                        root_x => 10,
                        root_y => -20,
                        detail => 1); # relative motion
    

Other Events

Extension events can be faked after an "init_extension()" so they're recognised by "$X->pack_event()". It's up to the server or extension which events can actually be simulated.

If an extension input requires more than one event packet to describe then pass multiple arrayrefs. For example "DeviceMotion" (from "XInputExtension") may need further "DeviceValuator" packets,

    $X->XTestFakeInput ([ name => 'DeviceMotion', ... ],
                        [ name => 'DeviceValuator', ... ],
                        [ name => 'DeviceValuator',  ... ]);
    

For all events "time" is how long in milliseconds the server should wait before playing the event. The default is 0 for no delay. No further requests are processed from the current client during the delay, so a sequence of "XTestFakeInput()" with delays will execute sequentially with one delay after another.

Generally the event fields from a "$X->{'event_handler'}" function cannot be passed directly to "XTestFakeInput()" to replay it. In particular,

• "time" from an event is a timestamp, so would have to be zeroed or adjusted to a relative time for a delay in "XTestFakeInput()".
• For "MotionNotify", "detail" from an event is the hint mechanism, so would have to be zeroed for the absolute/relative flag in "XTestFakeInput()".
• For "ButtonPress" and "ButtonRelease", "detail" from an event is a logical button number after "SetPointerMapping()" transformation, whereas "XFakeInput()" takes a physical number. A reverse lookup through the "GetPointerMapping()" table would be needed.