Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
X11::Protocol::Ext::XTUser3Contributed Perl DocumeX11::Protocol::Ext::XTEST(3)

NAME
       X11::Protocol::Ext::XTEST - synthetic user input	and more

SYNOPSIS
	use X11::Protocol;
	my $X =	X11::Protocol->new;
	$X->init_extension('XTEST')
	  or print "XTEST extension not	available";

	$X->XTestFakeInput (name   => 'ButtonPress',
			    detail => 3);  # physical button 3
	$X->XTestFakeInput (name   => 'ButtonRelease',
			    detail => 3);

DESCRIPTION
       The XTEST extension provides

       o   Synthetic keyboard and mouse	pointer	actions.

       o   Displayed cursor comparisons.

       o   Test	programs continuing during "GrabServer"	by other clients.

       These things help exercise library or server features which would
       otherwise require user interaction.

REQUESTS
       The following requests are made available with an "init_extension()",
       as per "EXTENSIONS" in X11::Protocol.

	   my $is_available = $X->init_extension('XTEST');

       "($server_major,	$server_minor) = $X->XTestGetVersion ($client_major,
       $client_minor)"
	   Negotiate a protocol	version	with the server.  $client_major	and
	   $client_minor is what the client would like.	 The returned
	   $server_major and $server_minor is what the server will do.

	   The current code supports up	to 2.1.	 The intention would be	to
	   automatically negotiate in "init_extension()" if/when necessary.

   Cursor Comparisons
       "$is_same = $X->XTestCompareCursor ($window, $cursor)"
	   Return true if the cursor attribute of $window is equal to $cursor.
	   $cursor can be

	   o   XID (an integer)	of a cursor.

	   o   "None" (or 0).

	   o   "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";

   Simulated Input
       "$X->XTestFakeInput (name=>...)"
       "$X->XTestFakeInput ([ name=>...	])"
       "$X->XTestFakeInput ([ name=>], [name=>], ...)"
	   Simulate user input for button presses, key presses,	and pointer
	   movement.

	   An input action is specified	as an event packet using fields
	   similar to "$X->pack_event()".

	   "XTestFakeInput()" is always	a single user action, so for example a
	   button press	and button release are two separate "XTestFakeInput()"
	   requests.  For the core events a single event packet	is enough to
	   describe an input but some extensions such as "XInputExtension" may
	   require more.

	   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,

	   o   "time" from an event is a timestamp, so would have to be	zeroed
	       or adjusted to a	relative time for a delay in
	       "XTestFakeInput()".

	   o   For "MotionNotify", "detail" from an event is the hint
	       mechanism, so would have	to be zeroed for the absolute/relative
	       flag in "XTestFakeInput()".

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

   GrabServer Imperviousness
       "$X->XTestGrabControl ($impervious)"
	   Control the current client's	behaviour during a "GrabServer()" by
	   another client.

	   If $impervious is 1 then the	current	client can continue to make
	   requests, ie. it's impervious to server grabs by other clients.

	   If $impervious is 0 then the	current	client behaves as normal.  Its
	   requests wait during	any "GrabServer()" by another client.

SEE ALSO
       X11::Protocol, X11::Protocol::Ext::XInputExtension

       xdotool(1), X11::GUITest, Xlib XTestQueryExtension(3)

       /usr/share/doc/x11proto-xext-dev/xtest.txt.gz,
       /usr/share/X11/doc/hardcopy/Xext/xtest.PS.gz

HOME PAGE
       <http://user42.tuxfamily.org/x11-protocol-other/index.html>

LICENSE
       Copyright 2011, 2012, 2013, 2014	Kevin Ryde

       X11-Protocol-Other is free software; you	can redistribute it and/or
       modify it under the terms of the	GNU General Public License as
       published by the	Free Software Foundation; either version 3, or (at
       your option) any	later version.

       X11-Protocol-Other is distributed in the	hope that it will be useful,
       but WITHOUT ANY WARRANTY; without even the implied warranty of
       MERCHANTABILITY or FITNESS FOR A	PARTICULAR PURPOSE.  See the GNU
       General Public License for more details.

       You should have received	a copy of the GNU General Public License along
       with X11-Protocol-Other.	 If not, see <http://www.gnu.org/licenses/>.

perl v5.24.1			  2014-01-18	  X11::Protocol::Ext::XTEST(3)

NAME | SYNOPSIS | DESCRIPTION | REQUESTS | SEE ALSO | HOME PAGE | LICENSE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=X11::Protocol::Ext::XTEST&sektion=3&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help