Provided by: xdotool_2.20100701.2961-3ubuntu1_i386 bug

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)

       ·   Read commands from a file:

            xdotool filename

       ·   Read commands from stdin:

            xdotool -

       ·   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:

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

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

       ·   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
       window or all windows.  Note that the order of windows in the window
       stack corresponds to the window stacking order, i.e. the bottom-most
       window will be reported first (see XQueryTree(3)). Thus the order of
       the windows in the window stack may not be consistent across
       invocations.

       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-23                        XDOTOOL(1)