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

FreeBSD Manual Pages

  
 
  

home | help
XDOTOOL(1)							    XDOTOOL(1)

NAME
       xdotool - command-line X11 automation tool

SYNOPSIS
       xdotool cmd args...

DESCRIPTION
       xdotool lets you	programatically	(or manually) simulate keyboard	input
       and mouse activity, move	and resize windows, etc. It does this using
       X11's XTEST extension and other Xlib functions.

       There is	some support for Extended Window Manager Hints (aka EWMH or
       NetWM).	See the	"EXTENDED WINDOW MANAGER HINTS"	section	for more
       information.

KEYBOARD COMMANDS
       key [options] keystroke [keystroke ...]
	   Options:

	   --window window
	       Send keystrokes to a specific window id.	. You can use "WINDOW
	       STACK" references like "%1" and "%@" here. If there is a	window
	       stack, then "%1"	is the default,	otherwise the current window
	       is used.

	       See also: "SENDEVENT NOTES" and "WINDOW STACK"

	   --clearmodifiers
	       Clear modifiers before sending keystrokes. See CLEARMODIFIERS
	       below.

	   --delay milliseconds
	       Delay between keystrokes. Default is 12ms.

	   Type	a given	keystroke. Examples being "alt+r", "Control_L+J",
	   "ctrl+alt+n", "BackSpace".

	   Generally, any valid	X Keysym string	will work. Multiple keys are
	   separated by	'+'. Aliases exist for "alt", "ctrl", "shift",
	   "super", and	"meta" which all map to	Foo_L, such as Alt_L and
	   Control_L, etc.

	   In cases where your keyboard	doesn't	actually have the key you want
	   to type, xdotool will automatically find an unused keycode and use
	   that	to type	the key.

	   With	respect	to "COMMAND CHAINING", this command consumes the
	   remainder of	the arguments or until a new xdotool command is	seen,
	   because no xdotool commands are valid keystrokes.

	   Example: Send the keystroke "F2"
	    xdotool key	F2

	   Example: Send 'a' with an accent over it (not on english keyboards,
	   but still works with	xdotool)
	    xdotool key	Aacute

	   Example: Send ctrl+l	and then BackSpace as separate keystrokes:
	    xdotool key	ctrl+l BackSpace

	   Example: Send ctrl+c	to all windows matching	title 'gdb' (See
	   "COMMAND CHAINING")
	    xdotool search --name gdb key ctrl+c

       keydown [options] keystroke
	   Same	as above, except only keydown events are sent.

       keyup keystroke
	   Same	as above, except only keyup events are sent.

       type [options] something	to type
	   Options:

	   --window windowid
	       Send keystrokes to a specific window id.	See "SENDEVENT NOTES"
	       below. The default, if no window	is given, depends on the
	       window stack. If	the window stack is empty the current window
	       is typed	at using XTEST.	Otherwise, the default is "%1" (see
	       "WINDOW STACK").

	   --delay milliseconds
	       Delay between keystrokes. Default is 12ms.

	   --clearmodifiers
	       Clear modifiers before sending keystrokes. See CLEARMODIFIERS
	       below.

	   Types as if you had typed it. Supports newlines and tabs (ASCII
	   newline and tab). Each keystroke is separated by a delay given by
	   the delay option.

	   With	respect	to "COMMAND CHAINING", this command consumes the
	   remainder of	the arguments and types	them. That is, no commands can
	   chain after 'type'.

	   Example: to type 'Hello world!' you would do:
	    xdotool type 'Hello	world!'

MOUSE COMMANDS
       mousemove [options] x y
	   Move	the mouse to the specific X and	Y coordinates on the screen.

	   --window WINDOW
	       Specify a window	to move	relative to. Coordinates 0,0 are at
	       the top left of the window you choose.

	       "WINDOW STACK" references are valid here, such as %1 and	%@.
	       Though, using %@	probably doesn't make sense.

	   --screen SCREEN
	       Move the	mouse to the specified screen to move to. This is only
	       useful if you have multiple screens and ARE NOT using Xinerama.

	       The default is the current screen. If you specify --window, the
	       --screen	flag is	ignored.

	   --polar
	       Use polar coordinates. This makes 'x' an	angle (in degrees,
	       0-360, etc) and 'y' the distance.

	       Rotation	starts at 'up' (0 degrees) and rotates clockwise: 90 =
	       right, 180 = down, 270 =	left.

	       The origin defaults to the center of the	current	screen.	If you
	       specify a --window, then	the origin is the center of that
	       window.

	   --clearmodifiers
	       See CLEARMODIFIERS

	   --sync
	       After sending the mouse move request, wait until	the mouse is
	       actually	moved. If no movement is necessary, we will not	wait.
	       This is useful for scripts that depend on actions being
	       completed before	moving on.

	       Note: We	wait until the mouse moves at all, not necessarily
	       that it actually	reaches	your intended destination. Some
	       applications lock the mouse cursor to certain regions of	the
	       screen, so waiting for any movement is better in	the general
	       case than waiting for a specific	target.

       mousemove_relative [options] x y
	   Move	the mouse x,y pixels relative to the current position of the
	   mouse cursor.

	   --polar
	       Use polar coordinates. This makes 'x' an	angle (in degrees,
	       0-360, etc) and 'y' the distance.

	       Rotation	starts at 'up' (0 degrees) and rotates clockwise: 90 =
	       right, 180 = down, 270 =	left.

	   --sync
	       After sending the mouse move request, wait until	the mouse is
	       actually	moved. If no movement is necessary, we will not	wait.
	       This is useful for scripts that depend on actions being
	       completed before	moving on.

	       Note that we wait until the mouse moves at all, not necessarily
	       that it actually	reaches	your intended destination. Some
	       applications lock the mouse cursor to certain regions of	the
	       screen, so waiting for any movement is better in	the general
	       case than waiting for a specific	target.

	   --clearmodifiers
	       See CLEARMODIFIERS

       click [options] button
	   Send	a click, that is, a mousedown followed by mouseup for the
	   given button	with a short delay between the two (currently 12ms).

	   Buttons generally map this way: Left	mouse is 1, middle is 2, right
	   is 3, wheel up is 4,	wheel down is 5.

	   --clearmodifiers
	       Clear modifiers before clicking.	See CLEARMODIFIERS below.

	   --window WINDOW
	       Specify a window	to send	a click	to. See	"SENDEVENT NOTES"
	       below for caveats. Uses the current mouse position when
	       generating the event.

	       The default, if no window is given, depends on the window
	       stack. If the window stack is empty the current window is typed
	       at using	XTEST. Otherwise, the default is "%1" (see "WINDOW
	       STACK").

       mousedown [options] button
	   Same	as click, except only a	mouse down is sent.

       mouseup [options] button
	   Same	as click, except only a	mouse up is sent.

       getmouselocation	[--shell]
	   Outputs the x, y, and screen	location of the	mouse cursor. Screen
	   numbers will	be nonzero if you have multiple	monitors and are not
	   using Xinerama.

	   --shell
	       This makes getmouselocation output shell	data you can eval.
	       Example:

		% xdotool getmouselocation --shell
		X=880
		Y=443
		SCREEN=0

		% eval $(xdotool getmouselocation --shell)
		% echo $X,$Y
		714,324

WINDOW COMMANDS
       search [options]	pattern
	   Search for windows with titles, names, or classes with a regular
	   expression pattern. The output is line-delimited list of X window
	   identifiers.	If you are using "COMMAND CHAINING", the search
	   command will	only write window ids to stdout	if it is the last (or
	   only) command in the	chain; otherwise, it is	silent.

	   The result is saved to the window stack for future chained
	   commands. See "WINDOW STACK"	and "COMMAND CHAINING" for details.

	   The options available are:

	   --class
	       Match against the window	class.

	   --classname
	       Match against the window	classname.

	   --maxdepth N
	       Set recursion/child search depth. Default is -1,	meaning
	       infinite. 0 means no depth, aka no results. If you only want
	       toplevel	windows, set maxdepth of 1.

	   --name
	       Match against the window	name. This is the same string that is
	       displayed in the	window titlebar.

	   --onlyvisible
	       Show only visible windows in the	results. This means ones with
	       map state IsViewable.

	   --pid PID
	       Match windows that belong to a specific process id. This	may
	       not work	for some X applications	that do	not set	this metadata
	       on its windows.

	   --screen N
	       Select windows only on a	specific screen. Default is to search
	       all screens. Only meaningful if you have	multiple displays and
	       are not using Xinerama.

	   --title
	       DEPRECATED. See --name.

	   --all
	       Require that all	conditions be met. For example:

		xdotool	search --all --pid 1424	--name "Hello World"

	       This will match only windows that have "Hello World" as a name
	       and are owned by	pid 1424.

	   --any
	       Match windows that match	any condition (logically, 'or'). This
	       is on by	default. For example:

		xdotool	search --any --pid 1424	--name "Hello World"

	       This will match any windows owned by pid	1424 or	windows	with
	       name "Hello World"

	   The default options are "--name --class --classname"

       getwindowpid [window=%1]
	   Output the PID owning a given window. This requires effort from the
	   application owning a	window and may not work	for all	windows. This
	   uses	_NET_WM_PID property of	the window. See	"EXTENDED WINDOW
	   MANAGER HINTS" below	for more information.

	   If no window	is given, the default is '%1'. If no windows are on
	   the stack, then this	is an error. See "WINDOW STACK"	for more
	   details.

	   Example: Find the PID for all xterms:
	    xdotool search --class xterm getwindowpid %@

       getwindowfocus [-f]
	   Prints the window id	of the currently focused window. Saves the
	   result to the window	stack. See "WINDOW STACK" for more details.

	   If the current window has no	WM_CLASS property, we assume it	is not
	   a normal top-level window and traverse up the parents until we find
	   a window with a WM_CLASS set	and return that	window id.

	   If you really want the window currently having focus	and don't care
	   if it has a WM_CLASS	setting, then use 'getwindowfocus -f'

       windowsize [options] [window=%1]	width height
	   Set the window size of the given window. If no window is given, %1
	   is the default.  See	"WINDOW	STACK" and "COMMAND CHAINING" for more
	   details.

	   The options available are:

	   --usehints
	       Use window sizing hints (when available)	to set width and
	       height.	This is	useful on terminals for	setting	the size based
	       on row/column of	text rather than pixels.

	   --sync
	       After sending the window	size request, wait until the window is
	       actually	resized. If no change is necessary, we will not	wait.
	       This is useful for scripts that depend on actions being
	       completed before	moving on.

	       Note: Because many window managers may ignore or	alter the
	       original	resize request,	we will	wait until the size changes
	       from its	original size, not necessary to	the requested size.

	   Example: To set a terminal to be 80x24 characters, you would	use:
	    xdotool windowsize --usehints some_windowid	80 24

       windowmove [options] [window=%1]	x y
	   Move	the window to the given	position. If no	window is given, %1 is
	   the default.	See "WINDOW STACK" and "COMMAND	CHAINING" for more
	   details.

	   --sync
	       After sending the window	move request, wait until the window is
	       actually	moved. If no movement is necessary, we will not	wait.
	       This is useful for scripts that depend on actions being
	       completed before	moving on.

       windowfocus [options] [window=%1]
	   Focus a window. If no window	is given, %1 is	the default. See
	   "WINDOW STACK" and "COMMAND CHAINING" for more details.

	   Uses	XSetInputFocus which may be ignored by some window managers or
	   programs.

	   --sync
	       After sending the window	focus request, wait until the window
	       is actually focused. This is useful for scripts that depend on
	       actions being completed before moving on.

       windowmap [options] [window=%1]
	   Map a window. In X11	terminology, mapping a window means making it
	   visible on the screen. If no	window is given, %1 is the default.
	   See "WINDOW STACK" and "COMMAND CHAINING" for more details.

	   --sync
	       After requesting	the window map,	wait until the window is
	       actually	mapped (visible). This is useful for scripts that
	       depend on actions being completed before	moving on.

       windowraise [window_id=%1]
	   Raise the window to the top of the stack. This may not work on all
	   window managers. If no window is given, %1 is the default. See
	   "WINDOW STACK" and "COMMAND CHAINING" for more details.

       windowunmap [options] [window_id=%1]
	   Unmap a window, making it no	longer appear on your screen. If no
	   window is given, %1 is the default. See "WINDOW STACK" and "COMMAND
	   CHAINING" for more details.

	   --sync
	       After requesting	the window unmap, wait until the window	is
	       actually	unmapped (hidden). This	is useful for scripts that
	       depend on actions being completed before	moving on.

       set_window [options] [windowid=%1]
	   Set properties about	a window. If no	window is given, %1 is the
	   default. See	"WINDOW	STACK" and "COMMAND CHAINING" for more
	   details.

	   Options:

	   --name newname
	       Set window WM_NAME (the window title, usually)

	   --icon-name newiconname
	       Set window WM_ICON_NAME (the window title when minimized,
	       usually)

	   --role newrole
	       Set window WM_WINDOW_ROLE

	   --classname newclassname
	       Set window class	name (not to be	confused with window class)

	   --class newclass
	       Set window class	(not to	be confused with window	class name)

DESKTOP	AND WINDOW COMMANDS
       These commands follow the EWMH standard.	See the	section	"EXTENDED
       WINDOW MANAGER HINTS" for more information.

       windowactivate [options]	[window=%1]
	   Activate the	window.	This command is	different from windowfocus: if
	   the window is on another desktop, we	will switch to that desktop.
	   It also uses	a different method for bringing	the window up. I
	   recommend trying this command before	using windowfocus, as it will
	   work	on more	window managers.

	   If no window	is given, %1 is	the default. See "WINDOW STACK"	and
	   "COMMAND CHAINING" for more details.

	   --sync
	       After sending the window	activation, wait until the window is
	       actually	activated. This	is useful for scripts that depend on
	       actions being completed before moving on.

       getactivewindow
	   Output the current active window. This command is often more
	   reliable than getwindowfocus. The result is saved to	the window
	   stack. See "WINDOW STACK" for more details.

       set_num_desktops	number
	   Changes the number of desktops or workspaces.

       get_num_desktops
	   Output the current number of	desktops.

       set_desktop desktop_number
	   Change the current view to the specified desktop.

       get_desktop
	   Output the current desktop in view.

       set_desktop_for_window [window=%1] desktop_number
	   Move	a window to a different	desktop. If no window is given,	%1 is
	   the default.	See "WINDOW STACK" and "COMMAND	CHAINING" for more
	   details.

       get_desktop_for_window [window=%1]
	   Output the desktop currently	containing the given window. Move a
	   window to a different desktop. If no	window is given, %1 is the
	   default. See	WINDOW STACK and "COMMAND CHAINING" for	more details.

SCRIPTS
       xdotool can read	a list of commands via stdin or	a file if you want. A
       script will fail	when any command fails.

       Truthfully, 'script' mode isn't very well fleshed out and may fall
       below your expectations.	If you have suggestions, please	email the list
       or file a bug (See CONTACT)

       o   Read	commands from a	file:

	    xdotool filename

       o   Read	commands from stdin:

	    xdotool -

       o   Read	commands from a	redirected file

	    xdotool - <	myfile

       You can also write scripts that only execute xdotool. Example:

	#!/usr/local/bin/xdotool
	windowactivate $WINDOWID
	mousemove -window $WINDOWID 50 50
	click 1
	click 1

       All commands are	run as if you had typed	'xdotool <line>' via /bin/sh.
       This means any shell magic should work here, too, including the use of
       environment variables. For above, here's	how you'd set the value	of
       WINDOWID:

	% WINDOWID=1234	./myscript

CLEARMODIFIERS
       Any command taking the --clearmodifiers flag will attempt to clear any
       active input modifiers during the command and restore them afterwards.

       For example, if you were	to run this command:
	xdotool	key a

       The result would	be 'a' or 'A' depending	on whether or not you were
       holding the shift key on	your keyboard. Often it	is undesirable to have
       any modifiers active, so	you can	tell xdotool to	clear any active
       modifiers.

       The order of operations if you hold shift while running 'xdotool	key
       --clearmodifiers	a' is this:

       1. Query	for all	active modifiers (finds	shift, in this case)
       2. Try to clear shift by	sending	'key up' for the shift key
       3. Runs normal 'xdotool key a'
       4. Restore shift	key by sending 'key down' for shift

       The --clearmodifiers flag can currently clear of	the following:

       o   any key in your active keymap that has a modifier associated	with
	   it.	(See xmodmap(1)'s 'xmodmap -pm'	output)

       o   mouse buttons (1, 2,	3, 4, and 5)

       o   caps	lock

SENDEVENT NOTES
       If you are trying to send key input to a	specific window, and it	does
       not appear to be	working, then it's likely your application is ignoring
       the events xdotool is generating. This is fairly	common.

       Sending keystrokes to a specific	window uses a different	API than
       simply typing to	the active window. If you specify 'xdotool type
       --window	12345 hello' xdotool will generate key events and send them
       directly	to window 12345.  However, X11 servers will set	a special flag
       on all events generated in this way (see	XEvent.xany.send_event in
       X11's manual). Many programs observe this flag and reject these events.

       It is important to note that for	key and	mouse events, we only use
       XSendEvent when a specific window is targeted. Otherwise, we use	XTEST.

       Some programs can be configured to accept events	even if	they are
       generated by xdotool. Seek the documentation of your application	for
       help.

       Specific	application notes (from	the author's testing): * Firefox 3
       seems to	ignore all input when it does not have focus.  * xterm can be
       configured while	running	with ctrl+leftclick, 'Allow SendEvents'	*
       gnome-terminal appears to accept	generated input	by default.

WINDOW STACK
       Certain commands	(search, getactivewindow, getwindowfocus) will find
       windows for you.	These results generally	printed	to stdout, but they
       are also	saved to memory	for future use during the lifetime of the
       xdotool process.	See "COMMAND CHAINING" for more	information.

       The only	modifications support for the window stack are to replace it.
       That is,	two of two sequential searches,	only the last one's results
       will be the window stack.

COMMAND	CHAINING
       xdotool supports	running	multiple commands on a single invocation.
       Generally, you'll start with a search command (see "WINDOW STACK") and
       then perform a set of actions on	those results.

       To query	the window stack, you can use special notation "%N" where N is
       a number	or the '@' symbol. If %N is given, the Nth window will be
       selected	from the window	stack. Generally you will only want the	first
       one as the order	of the windows in the stack is unreliable (See
       XQueryTree for ordering details).  If you specify '%@' then all windows
       in the stack will be used.

       The notation described above is used as the "window" argument for any
       given command.

       For example, to resize all xterms to 80x24:

	xdotool	search --class xterm --	windowsize --usehints 80 24

       Resize move the current window:

	xdotool	getactivewindow	windowmove 0 0

       In all cases, the default window	argument, if omitted, will default to
       "%1". It	is obviously an	error if you omit the window argument and the
       window stack is empty. If you try to use	the window stack and it	is
       empty, it is also an error.

       To activate the first firefox window found:

	xdotool	search --class firefox windowactivate

       These would error:

	xdotool	windowactivate
	xdotool	windowactivate %1
	xdotool	windowactivate %@

       When xdotool exits, the current window stack is lost.

       Additinally, commands that modify the "WINDOW STACK" will not print the
       results if they are not the last	command. For example:

	# Output the active window:
	% xdotool getactivewindow
	20971533

	# Output the pid of the	active window, but not the active window id:
	% xdotool getactivewindow getwindowpid
	4686

EXTENDED WINDOW	MANAGER	HINTS
       The following pieces of the EWMH	standard are supported:

       _NET_SUPPORTED
	   Asks	the window manager what	is supported

       _NET_CURRENT_DESKTOP
	   Query and set the current desktop. Support for this enables these
	   commands: "set_desktop", "get_desktop".

       _NET_WM_DESKTOP
	   Query and set what desktop a	window is living in. Support for this
	   enables these commands: "set_desktop_for_window",
	   "get_desktop_for_window".

       _NET_ACTIVE_WINDOW
	   Allows you to query and set the active window by asking the window
	   manager to bring it forward.	Support	for this enables these
	   commands: "windowactivate", "getactivewindow".

       _NET_WM_PID
	   This	feature	is application dependent, not window-manager
	   dependent. Query the	PID owning a given window. Support for this
	   enables these commands: "getwindowpid".

SEE ALSO
       xprop(1), xwininfo(1),

       Project site: <http://www.semicomplete.com/projects/xdotool>

       Google Code: <http://semicomplete.googlecode.com/>

       EWMH specification:
       <http://standards.freedesktop.org/wm-spec/wm-spec-1.3.html>

CONTACT
       Please send questions to	xdotool-users@googlegroups.com.	File bugs and
       feature requests	at the following URL:

       <http://code.google.com/p/semicomplete/issues/list>

       Alternately, if you prefer email, feel free to file bugs	by emailing
       the list.  What works for you :)

AUTHOR
       xdotool was written by Jordan Sissel.

       This manual page	was written originally by Daniel Kahn Gillmor
       <dkg@fifthhorseman.net> for the Debian project (but may be used by
       others).	It is maintained by Jordan Sissel.

				  2010-06-19			    XDOTOOL(1)

NAME | SYNOPSIS | DESCRIPTION | KEYBOARD COMMANDS | MOUSE COMMANDS | WINDOW COMMANDS | DESKTOP AND WINDOW COMMANDS | SCRIPTS | CLEARMODIFIERS | SENDEVENT NOTES | WINDOW STACK | COMMAND CHAINING | EXTENDED WINDOW MANAGER HINTS | SEE ALSO | CONTACT | AUTHOR

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=xdotool&sektion=1&manpath=FreeBSD+8.1-RELEASE+and+Ports>

home | help