xdotool

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

           --window windowid
               Send keystrokes to a specific window id. See SENDEVENT below.

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

           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.

           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

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

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

           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.

           --clearmodifiers
               See CLEARMODIFIERS

       click [options] button
           Send mousedown followed by mouseup for the given button

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

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

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

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

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

WINDOW COMMANDS
       search [options] somestring
           Search  for windows with titles, names, or classes matching
           somestring.  The output is line-delimited list of X window
           identifiers

           The options available are:

           --class
               Match against the window class

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

           --onlyvisible
               Show only visible windows in the results.

           --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
               Match against the window title (what's displayed in the titlebar
               of the window)

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

       getwindowfocus [-f]
           Prints the window id of the currently focused window.

           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] windowid width height
           Set the window size of the given window

           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.

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

       windowmove windowid x y
           Move the window to the given position

       windowfocus windowid
           Focus the window

       windowmap window_id
           Map a window. In X11 terminology, mapping a window means making it
           visible on the screen.

       windowraise window_id
           Raise the window to the top of the stack. This may not work on all
           window managers.

       windowunmap window_id
           Unmap a window, making it no longer appear on your screen.

       set_window [options] windowid
           Set properties about a window.

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

       getactivewindow
           Output the current active window. This command is often more reliable
           than getwindowfocus.

       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_id desktop_number
           Move a window to a different desktop.

       get_desktop_for_window window_id
           Output the desktop currently containing the given window.

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

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

       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.

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

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

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

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

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>

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