1XDOTOOL(1) XDOTOOL(1)
2
6 xdotool - command-line X11 automation tool
7
9 xdotool cmd args...
10 Notation: Some documentation uses [window] to denote an optional window
12 argument. This case means that the argument, if not present, will
13 default to "%1". See "WINDOW STACK" for what "%1" means.
14
16 xdotool lets you programmatically (or manually) simulate keyboard input
17 and mouse activity, move and resize windows, etc. It does this using
18 X11's XTEST extension and other Xlib functions.
19 There is some support for Extended Window Manager Hints (aka EWMH or
21 NetWM). See the "EXTENDED WINDOW MANAGER HINTS" section for more
22 information.
23
25 key [options] keystroke [keystroke ...]
26 Options:
27 --window window
29 Send keystrokes to a specific window id. You can use "WINDOW
30 STACK" references like "%1" and "%@" here. If there is a window
31 stack, then "%1" is the default, otherwise the current window
32 is used.
33 See also: "SENDEVENT NOTES" and "WINDOW STACK"
35 --clearmodifiers
37 Clear modifiers before sending keystrokes. See CLEARMODIFIERS
38 below.
39 --delay milliseconds
41 Delay between keystrokes. Default is 12ms.
42 Type a given keystroke. Examples being "alt+r", "Control_L+J",
44 "ctrl+alt+n", "BackSpace".
45 Generally, any valid X Keysym string will work. Multiple keys are
47 separated by '+'. Aliases exist for "alt", "ctrl", "shift",
48 "super", and "meta" which all map to Foo_L, such as Alt_L and
49 Control_L, etc.
50 In cases where your keyboard doesn't actually have the key you want
52 to type, xdotool will automatically find an unused keycode and use
53 that to type the key.
54 With respect to "COMMAND CHAINING", this command consumes the
56 remainder of the arguments or until a new xdotool command is seen,
57 because no xdotool commands are valid keystrokes.
58 Example: Send the keystroke "F2"
60 xdotool key F2
61 Example: Send 'a' with an accent over it (not on English keyboards,
63 but still works with xdotool)
64 xdotool key Aacute
65 Example: Send ctrl+l and then BackSpace as separate keystrokes:
67 xdotool key ctrl+l BackSpace
68 Example: Send ctrl+c to all windows matching title 'gdb' (See
70 "COMMAND CHAINING")
71 xdotool search --name gdb key ctrl+c
72 keydown [options] keystroke
74 Same as above, except only keydown (press) events are sent.
75 keyup keystroke
77 Same as above, except only keyup (release) events are sent.
78 type [options] something to type
80 Options:
81 --window windowid
83 Send keystrokes to a specific window id. See "SENDEVENT NOTES"
84 below. The default, if no window is given, depends on the
85 window stack. If the window stack is empty the current window
86 is typed at using XTEST. Otherwise, the default is "%1" (see
87 "WINDOW STACK").
88 --delay milliseconds
90 Delay between keystrokes. Default is 12ms.
91 --clearmodifiers
93 Clear modifiers before sending keystrokes. See CLEARMODIFIERS
94 below.
95 Types as if you had typed it. Supports newlines and tabs (ASCII
97 newline and tab). Each keystroke is separated by a delay given by
98 the --delay option.
99 With respect to "COMMAND CHAINING", this command consumes the
101 remainder of the arguments and types them. That is, no commands can
102 chain after 'type'.
103 Example: to type 'Hello world!' you would do:
105 xdotool type 'Hello world!'
106
108 mousemove [options] x y OR 'restore'
109 Move the mouse to the specific X and Y coordinates on the screen.
110 You can move the mouse to the previous location if you specify
112 'restore' instead of an X and Y coordinate. Restoring only works if
113 you have moved previously in this same command invocation. Further,
114 it does not work with the --window option.
115 For example, to click the top-left corner of the screen and move
117 the mouse to the original position before you moved it, use this:
118 xdotool mousemove 0 0 click 1 mousemove restore
119 --window WINDOW
121 Specify a window to move relative to. Coordinates 0,0 are at
122 the top left of the window you choose.
123 "WINDOW STACK" references are valid here, such as %1 and %@.
125 Though, using %@ probably doesn't make sense.
126 --screen SCREEN
128 Move the mouse to the specified screen to move to. This is only
129 useful if you have multiple screens and ARE NOT using Xinerama.
130 The default is the current screen. If you specify --window, the
132 --screen flag is ignored.
133 --polar
135 Use polar coordinates. This makes 'x' an angle (in degrees,
136 0-360, etc) and 'y' the distance.
137 Rotation starts at 'up' (0 degrees) and rotates clockwise: 90 =
139 right, 180 = down, 270 = left.
140 The origin defaults to the center of the current screen. If you
142 specify a --window, then the origin is the center of that
143 window.
144 --clearmodifiers
146 See CLEARMODIFIERS
147 --sync
149 After sending the mouse move request, wait until the mouse is
150 actually moved. If no movement is necessary, we will not wait.
151 This is useful for scripts that depend on actions being
152 completed before moving on.
153 Note: We wait until the mouse moves at all, not necessarily
155 that it actually reaches your intended destination. Some
156 applications lock the mouse cursor to certain regions of the
157 screen, so waiting for any movement is better in the general
158 case than waiting for a specific target.
159 mousemove_relative [options] x y
161 Move the mouse x,y pixels relative to the current position of the
162 mouse cursor.
163 --polar
165 Use polar coordinates. This makes 'x' an angle (in degrees,
166 0-360, etc) and 'y' the distance.
167 Rotation starts at 'up' (0 degrees) and rotates clockwise: 90 =
169 right, 180 = down, 270 = left.
170 --sync
172 After sending the mouse move request, wait until the mouse is
173 actually moved. If no movement is necessary, we will not wait.
174 This is useful for scripts that depend on actions being
175 completed before moving on.
176 Note that we wait until the mouse moves at all, not necessarily
178 that it actually reaches your intended destination. Some
179 applications lock the mouse cursor to certain regions of the
180 screen, so waiting for any movement is better in the general
181 case than waiting for a specific target.
182 --clearmodifiers
184 See CLEARMODIFIERS
185 click [options] button
187 Send a click, that is, a mousedown followed by mouseup for the
188 given button with a short delay between the two (currently 12ms).
189 Buttons generally map this way: Left mouse is 1, middle is 2, right
191 is 3, wheel up is 4, wheel down is 5.
192 --clearmodifiers
194 Clear modifiers before clicking. See CLEARMODIFIERS below.
195 --repeat REPEAT
197 Specify how many times to click. Default is 1. For a double-
198 click, use '--repeat 2'
199 --delay MILLISECONDS
201 Specify how long, in milliseconds, to delay between clicks.
202 This option is not used if the --repeat flag is set to 1
203 (default).
204 --window WINDOW
206 Specify a window to send a click to. See "SENDEVENT NOTES"
207 below for caveats. Uses the current mouse position when
208 generating the event.
209 The default, if no window is given, depends on the window
211 stack. If the window stack is empty the current window is typed
212 at using XTEST. Otherwise, the default is "%1" (see "WINDOW
213 STACK").
214 mousedown [options] button
216 Same as click, except only a mouse down is sent.
217 mouseup [options] button
219 Same as click, except only a mouse up is sent.
220 getmouselocation [--shell]
222 Outputs the x, y, screen, and window id of the mouse cursor. Screen
223 numbers will be nonzero if you have multiple monitors and are not
224 using Xinerama.
225 This command updates the window stack with the window id of the
227 window directly underneath the mouse.
228 --shell
230 This makes getmouselocation output shell data you can eval.
231 Example:
232 % xdotool getmouselocation --shell
234 X=880
235 Y=443
236 SCREEN=0
237 WINDOW=16777250
238 % eval $(xdotool getmouselocation --shell)
240 % echo $X,$Y
241 714,324
242 behave_screen_edge [options] where command ...
244 Bind an action to events when the mouse hits the screen edge or
245 corner.
246 Options are:
248 --delay MILLISECONDS
250 Delay in milliseconds before running the command. This allows
251 you to require a given edge or corner to be held for a short
252 period before your command will run. If you leave the edge or
253 corner before the delay expires then the time will reset.
254 --quiesce MILLISECONDS
256 Delay in milliseconds before the next command will run. This
257 helps prevent accidentally running your command extra times;
258 especially useful if you have a very short --delay (like the
259 default of 0).
260 Event timeline
262 * Mouse hits an edge or corner.
264 * If delay is nonzero, the mouse must stay in this edge or corner until delay time expires.
265 * If still in the edge/corner, trigger.
266 * If quiesce is nonzero, then there is a cool-down period where the next
267 trigger cannot occur
268 Valid 'where' values are:
270 left
272 top-left
273 top
274 top-right
275 right
276 bottom-left
277 bottom
278 bottom-right
279 Examples:
281 # Activate google-chrome when you move the mouse to the bottom-
282 left corner:
283 xdotool behave_screen_edge bottom-left \
284 search --class google-chrome windowactivate
285 # Go to the next workspace (right). Known to work in GNOME (metacity and compiz)
287 xdotool behave_screen_edge --delay 500 bottom-right key XF86Forward
288 # Activate firefox and do a web search in a new tab for text in your clipboard
290 xdotool behave_screen_edge --delay 1000 top-left \
291 search --classname Navigator \
292 windowactivate --sync key --delay 250 ctrl+t ctrl+k ctrl+v Return
293
295 search [options] pattern
296 Search for windows with titles, names, or classes with a regular
297 expression pattern. The output is line-delimited list of X window
298 identifiers. If you are using "COMMAND CHAINING", the search
299 command will only write window ids to stdout if it is the last (or
300 only) command in the chain; otherwise, it is silent.
301 The result is saved to the window stack for future chained
303 commands. See "WINDOW STACK" and "COMMAND CHAINING" for details.
304 Patterns are POSIX extended regular expressions (ERE), e. g.
306 "Chrom(e|ium)$" for windows ending in "Chrome" or "Chromium". See
307 regex(7) for syntax details. Matches are case-insensitive.
308 The default options are "--name --class --classname --role" (unless
310 you specify one or more of --name, --class, --classname, or
311 --role).
312 The options available are:
314 --class
316 Match against the window class.
317 --classname
319 Match against the window classname.
320 --role
322 Match against the window role.
323 --maxdepth N
325 Set recursion/child search depth. Default is -1, meaning
326 infinite. 0 means no depth, only root windows will be searched.
327 If you only want toplevel windows, set maxdepth of 1 (or 2,
328 depending on how your window manager does decorations).
329 --name
331 Match against the window name. This is the same string that is
332 displayed in the window titlebar.
333 --onlyvisible
335 Show only visible windows in the results. This means ones with
336 map state IsViewable.
337 --pid PID
339 Match windows that belong to a specific process id. This may
340 not work for some X applications that do not set this metadata
341 on its windows.
342 --screen N
344 Select windows only on a specific screen. Default is to search
345 all screens. Only meaningful if you have multiple displays and
346 are not using Xinerama.
347 --desktop N
349 Only match windows on a certain desktop. 'N' is a number. The
350 default is to search all desktops.
351 --limit N
353 Stop searching after finding N matching windows. Specifying a
354 limit will help speed up your search if you only want a few
355 results.
356 The default is no search limit (which is equivalent to '--limit
358 0')
359 --title
361 DEPRECATED. See --name.
362 --all
364 Require that all conditions be met. For example:
365 xdotool search --all --pid 1424 --name "Hello World"
367 This will match only windows that have "Hello World" as a name
369 and are owned by pid 1424.
370 --any
372 Match windows that match any condition (logically, 'or'). This
373 is on by default. For example:
374 xdotool search --any --pid 1424 --name "Hello World"
376 This will match any windows owned by pid 1424 or windows with
378 name "Hello World"
379 --sync
381 Block until there are results. This is useful when you are
382 launching an application and want to wait until the application
383 window is visible. For example:
384 google-chrome &
386 xdotool search --sync --onlyvisible --class "google-chrome"
387 selectwindow
389 Get the window id (for a client) by clicking on it. Useful for
390 having scripts query you humans for what window to act on. For
391 example, killing a window by clicking on it:
392 xdotool selectwindow windowkill
394 behave window action command ...
396 Bind an action to an event on a window. This lets you run
397 additional xdotool commands whenever a matched event occurs.
398 The command run as a result of the behavior is run with %1 being
400 the window that was acted upon. Examples follow after the event
401 list.
402 The following are valid events:
404 mouse-enter
406 Fires when the mouse enters a window. This is similar to 'mouse
407 over' events in javascript, if that helps.
408 mouse-leave
410 Fires when the mouse leaves a window. This is the opposite of
411 'mouse-enter'
412 mouse-click
414 Fires when the mouse is clicked. Specifically, when the mouse
415 button is released.
416 focus
418 Fires when the window gets input focus.
419 blur
421 Fires when the window loses focus.
422 Examples:
424 # Print the cursor location whenever the mouse enters a currently-visible
426 # window:
427 xdotool search --onlyvisible . behave %@ mouse-enter getmouselocation
428 # Print the window title and pid whenever an xterm gets focus
430 xdotool search --class xterm behave %@ focus getwindowname getwindowpid
431 # Emulate focus-follows-mouse
433 xdotool search . behave %@ mouse-enter windowfocus
434 getwindowpid [window]
436 Output the PID owning a given window. This requires effort from the
437 application owning a window and may not work for all windows. This
438 uses _NET_WM_PID property of the window. See "EXTENDED WINDOW
439 MANAGER HINTS" below for more information.
440 If no window is given, the default is '%1'. If no windows are on
442 the stack, then this is an error. See "WINDOW STACK" for more
443 details.
444 Example: Find the PID for all xterms:
446 xdotool search --class xterm getwindowpid %@
447 getwindowname [window]
449 Output the name of a given window, also known as the title. This is
450 the text displayed in the window's titlebar by your window manager.
451 If no window is given, the default is '%1'. If no windows are on
453 the stack, then this is an error. See "WINDOW STACK" for more
454 details.
455 getwindowgeometry [options] [window]
457 Output the geometry (location and position) of a window. The values
458 include: x, y, width, height, and screen number.
459 --shell
461 Output values suitable for 'eval' in a shell.
462 getwindowfocus [-f]
464 Prints the window id of the currently focused window. Saves the
465 result to the window stack. See "WINDOW STACK" for more details.
466 If the current window has no WM_CLASS property, we assume it is not
468 a normal top-level window and traverse up the parents until we find
469 a window with a WM_CLASS set and return that window id.
470 If you really want the window currently having focus and don't care
472 if it has a WM_CLASS setting, then use 'getwindowfocus -f'
473 windowsize [options] [window] width height
475 Set the window size of the given window. If no window is given, %1
476 is the default. See "WINDOW STACK" and "COMMAND CHAINING" for more
477 details.
478 Percentages are valid for width and height. They are relative to
480 the geometry of the screen the window is on. For example, to make a
481 window the full width of the screen, but half height:
482 xdotool windowsize I<window> 100% 50%
484 Percentages are valid with --usehints and still mean pixel-width
486 relative to the screen size.
487 The options available are:
489 --usehints
491 Use window sizing hints (when available) to set width and
492 height. This is useful on terminals for setting the size based
493 on row/column of text rather than pixels.
494 --sync
496 After sending the window size request, wait until the window is
497 actually resized. If no change is necessary, we will not wait.
498 This is useful for scripts that depend on actions being
499 completed before moving on.
500 Note: Because many window managers may ignore or alter the
502 original resize request, we will wait until the size changes
503 from its original size, not necessary to the requested size.
504 Example: To set a terminal to be 80x24 characters, you would use:
506 xdotool windowsize --usehints some_windowid 80 24
507 windowmove [options] [window] x y
509 Move the window to the given position. If no window is given, %1 is
510 the default. See "WINDOW STACK" and "COMMAND CHAINING" for more
511 details.
512 If the given x coordinate is literally 'x', then the window's
514 current x position will be unchanged. The same applies for 'y'.
515 Examples:
517 xdotool getactivewindow windowmove 100 100 # Moves to 100,100
519 xdotool getactivewindow windowmove x 100 # Moves to x,100
520 xdotool getactivewindow windowmove 100 y # Moves to 100,y
521 xdotool getactivewindow windowmove 100 y # Moves to 100,y
522 Percentages are valid for width and height. They are relative to
524 the geometry of the screen the window is on. For example, to make a
525 window the full width of the screen, but half height:
526 xdotool windowmove I<window> 100% 50%
528 --sync
530 After sending the window move request, wait until the window is
531 actually moved. If no movement is necessary, we will not wait.
532 This is useful for scripts that depend on actions being
533 completed before moving on.
534 --relative
536 Make movement relative to the current window position.
537 windowfocus [options] [window]
539 Focus a window. If no window is given, %1 is the default. See
540 "WINDOW STACK" and "COMMAND CHAINING" for more details.
541 Uses XSetInputFocus which may be ignored by some window managers or
543 programs.
544 --sync
546 After sending the window focus request, wait until the window
547 is actually focused. This is useful for scripts that depend on
548 actions being completed before moving on.
549 windowmap [options] [window]
551 Map a window. In X11 terminology, mapping a window means making it
552 visible on the screen. If no window is given, %1 is the default.
553 See "WINDOW STACK" and "COMMAND CHAINING" for more details.
554 --sync
556 After requesting the window map, wait until the window is
557 actually mapped (visible). This is useful for scripts that
558 depend on actions being completed before moving on.
559 windowminimize [options] [window]
561 Minimize a window. In X11 terminology, this is called 'iconify.'
562 If no window is given, %1 is the default. See "WINDOW STACK" and
563 "COMMAND CHAINING" for more details.
564 --sync
566 After requesting the window minimize, wait until the window is
567 actually minimized. This is useful for scripts that depend on
568 actions being completed before moving on.
569 windowraise [window_id=%1]
571 Raise the window to the top of the stack. This may not work on all
572 window managers. If no window is given, %1 is the default. See
573 "WINDOW STACK" and "COMMAND CHAINING" for more details.
574 windowreparent [source_window] destination_window
576 Reparent a window. This moves the source_window to be a child
577 window of destination_window. If no source is given, %1 is the
578 default. "WINDOW STACK" window references (like %1) are valid for
579 both source_window and destination_window See "WINDOW STACK" and
580 "COMMAND CHAINING" for more details.
581 windowclose [window]
583 Close a window. This action will destroy the window, but will not
584 try to kill the client controlling it. If no window is given, %1 is
585 the default. See "WINDOW STACK" and "COMMAND CHAINING" for more
586 details.
587 windowquit [window]
589 Close a window gracefully. This action sends a request, allowing
590 the application to apply close confirmation mechanics. If no window
591 is given, %1 is the default. See "WINDOW STACK" and "COMMAND
592 CHAINING" for more details.
593 windowkill [window]
595 Kill a window. This action will destroy the window and kill the
596 client controlling it. If no window is given, %1 is the default.
597 See WINDOW STACK and "COMMAND CHAINING" for more details.
598 windowunmap [options] [window_id=%1]
600 Unmap a window, making it no longer appear on your screen. If no
601 window is given, %1 is the default. See "WINDOW STACK" and "COMMAND
602 CHAINING" for more details.
603 --sync
605 After requesting the window unmap, wait until the window is
606 actually unmapped (hidden). This is useful for scripts that
607 depend on actions being completed before moving on.
608 set_window [options] [windowid=%1]
610 Set properties about a window. If no window is given, %1 is the
611 default. See "WINDOW STACK" and "COMMAND CHAINING" for more
612 details.
613 Options:
615 --name newname
617 Set window WM_NAME (the window title, usually)
618 --icon-name newiconname
620 Set window WM_ICON_NAME (the window title when minimized,
621 usually)
622 --role newrole
624 Set window WM_WINDOW_ROLE
625 --classname newclassname
627 Set window class name (not to be confused with window class)
628 --class newclass
630 Set window class (not to be confused with window class name)
631 --urgency value
633 Set window urgency hint. If the value is 1, the window will be
634 marked urgent, and the window manager will somehow highlight it
635 for the user's attention. If the value is 0, the window will
636 be marked non-urgent.
637 --overrideredirect value
639 Set window's override_redirect value. This value is a hint to
640 the window manager for whether or not it should be managed. If
641 the redirect value is 0, then the window manager will draw
642 borders and treat this window normally. If the value is 1, the
643 window manager will ignore this window.
644 If you change this value, your window manager may not notice
646 the change until the window is mapped again, so you may want to
647 issue 'windowunmap' and 'windowmap' to make the window manager
648 take note.
649
651 These commands follow the EWMH standard. See the section "EXTENDED
652 WINDOW MANAGER HINTS" for more information.
653 windowactivate [options] [window]
655 Activate the window. This command is different from windowfocus: if
656 the window is on another desktop, we will switch to that desktop.
657 It also uses a different method for bringing the window up. I
658 recommend trying this command before using windowfocus, as it will
659 work on more window managers.
660 If no window is given, %1 is the default. See "WINDOW STACK" and
662 "COMMAND CHAINING" for more details.
663 --sync
665 After sending the window activation, wait until the window is
666 actually activated. This is useful for scripts that depend on
667 actions being completed before moving on.
668 getactivewindow
670 Output the current active window. This command is often more
671 reliable than getwindowfocus. The result is saved to the window
672 stack. See "WINDOW STACK" for more details.
673 windowstate [--add PROPERTY] [--remove PROPERTY] [--toggle PROPERTY]
675 [window]
676 Change a property on a window.
677 Some properties may have no effect some windows or in some window
679 managers.
680 Properties can be any of:
682 MODAL - makes the window into a modal
684 STICKY - makes the window appear on all workspaces
685 MAXIMIZED_VERT - sizes the window maximized vertically
686 MAXIMIZED_HORZ - sizes the window maximized horizontally
687 ABOVE - Show window above all others (always on top)
688 BELOW - Show window below all others
689 SKIP_TASKBAR - hides the window from the taskbar
690 SKIP_PAGER - hides the window from the window pager
691 FULLSCREEN - makes window fullscreen
692 HIDDEN - unmaps the window
693 SHADED - rolls the window up
694 DEMANDS_ATTENTION - marks window urgent or needing attention
695 This feature requires a window manager which supports EWMH. Most
697 window managers probably support this :)
698 getwindowclassname [window]
700 Prints the class name for the window.
701 set_num_desktops number
703 Changes the number of desktops or workspaces.
704 get_num_desktops
706 Output the current number of desktops.
707 get_desktop_viewport [--shell]
709 Report the current viewport's position. If --shell is given, the
710 output is friendly to shell eval.
711 Viewports are sometimes used instead of 'virtual desktops' on some
713 window managers. A viewport is simply a view on a very large
714 desktop area.
715 set_desktop_viewport x y
717 Move the viewport to the given position. Not all requests will be
718 obeyed - some windowmangers only obey requests that align to
719 workspace boundaries, such as the screen size.
720 For example, if your screen is 1280x800, you can move to the 2nd
722 workspace by doing:
723 xdotool set_desktop_viewport 1280 0
724 set_desktop [options] desktop_number
726 Change the current view to the specified desktop.
727 --relative
729 Use relative movements instead of absolute. This lets you move
730 relative to the current desktop.
731 get_desktop
733 Output the current desktop in view.
734 set_desktop_for_window [window] desktop_number
736 Move a window to a different desktop. If no window is given, %1 is
737 the default. See "WINDOW STACK" and "COMMAND CHAINING" for more
738 details.
739 get_desktop_for_window [window]
741 Output the desktop currently containing the given window. Move a
742 window to a different desktop. If no window is given, %1 is the
743 default. See WINDOW STACK and "COMMAND CHAINING" for more details.
744
746 exec [options] command [...]
747 Execute a program. This is often useful when combined with
748 behave_screen_edge to do things like locking your screen.
749 Options:
751 --sync
753 Block until the child process exits. The child process exit
754 status is then passed to the parent process (xdotool) which
755 copies it.
756 Examples:
758 # Lock the screen when the mouse sits in the top-right corner
759 xdotool behave_screen_edge --delay 1000 top-right \
760 exec gnome-screensaver-command --lock
761 # Substitute 'xscreensaver-command -lock' if you use that program.
762 # The following will fail to move the mouse because we use '--sync' and
764 # /bin/false exits nonzero:
765 xdotool exec --sync /bin/false mousemove 0 0
766 # This succeeds, though, since we do not use --sync on the exec command.
768 xdotool exec /bin/false mousemove 0 0
769 sleep seconds
771 Sleep for a specified period. Fractions of seconds (like 1.3, or
772 0.4) are valid, here.
773
775 xdotool can read a list of commands via stdin or a file if you want. A
776 script will fail when any command fails.
777 Truthfully, 'script' mode isn't fully fleshed out and may fall below
779 your expectations. If you have suggestions, please email the list or
780 file a bug (See CONTACT).
781 Scripts can use positional arguments (Represented by $1, $2, ...) and
783 environment variables (like $HOME or $WINDOWID). Quoting arguments
784 should work as expected.
785 Scripts are processed for parameter and environment variable expansion
787 and then run as if you had invoked xdotool with the entire script on
788 one line (using COMMAND CHAINING).
789 • Read commands from a file:
791 xdotool filename
793 • Read commands from stdin:
795 xdotool -
797 • Read commands from a redirected file
799 xdotool - < myfile
801 You can also write scripts that only execute xdotool. Example:
803 #!/usr/local/bin/xdotool
805 search --onlyvisible --classname $1
806 windowsize %@ $2 $3
808 windowraise %@
809 windowmove %1 0 0
811 windowmove %2 $2 0
812 windowmove %3 0 $3
813 windowmove %4 $2 $3
814 This script will take all windows matched by the classname query given
816 by arg1 ($1) and sizes/moves them into a 2x2 grid with windows sized by
817 the 2nd and 3rd parameters.
818 Here's an example usage:
820 % ./myscript xterm 600 400
822 Running it like this will take 4 visible xterms, raise them, and move
824 them into a 2x2 tile grid with each window 600x400 pixels in size.
825
827 Any command taking the --clearmodifiers flag will attempt to clear any
828 active input modifiers during the command and restore them afterwards.
829 For example, if you were to run this command:
831 xdotool key a
832 The result would be 'a' or 'A' depending on whether or not you were
834 holding the shift key on your keyboard. Often it is undesirable to have
835 any modifiers active, so you can tell xdotool to clear any active
836 modifiers.
837 The order of operations if you hold shift while running 'xdotool key
839 --clearmodifiers a' is this:
840 1. Query for all active modifiers (finds shift, in this case)
842 2. Try to clear shift by sending 'key up' for the shift key
843 3. Runs normal 'xdotool key a'
844 4. Restore shift key by sending 'key down' for shift
845 The --clearmodifiers flag can currently clear of the following:
847 • any key in your active keymap that has a modifier associated with
849 it. (See xmodmap(1)'s 'xmodmap -pm' output)
850 • mouse buttons (1, 2, 3, 4, and 5)
852 • caps lock
854
856 If you are trying to send key input to a specific window, and it does
857 not appear to be working, then it's likely your application is ignoring
858 the events xdotool is generating. This is fairly common.
859 Sending keystrokes to a specific window uses a different API than
861 simply typing to the active window. If you specify 'xdotool type
862 --window 12345 hello' xdotool will generate key events and send them
863 directly to window 12345. However, X11 servers will set a special flag
864 on all events generated in this way (see XEvent.xany.send_event in
865 X11's manual). Many programs observe this flag and reject these events.
866 It is important to note that for key and mouse events, we only use
868 XSendEvent when a specific window is targeted. Otherwise, we use XTEST.
869 Some programs can be configured to accept events even if they are
871 generated by xdotool. Seek the documentation of your application for
872 help.
873 Specific application notes (from the author's testing): * Firefox 3
875 seems to ignore all input when it does not have focus. * xterm can be
876 configured while running with ctrl+leftclick, 'Allow SendEvents' *
877 gnome-terminal appears to accept generated input by default.
878
880 Certain commands (search, getactivewindow, getwindowfocus) will find
881 windows for you. These results generally printed to stdout, but they
882 are also saved to memory for future use during the lifetime of the
883 xdotool process. See "COMMAND CHAINING" for more information.
884 The only modifications support for the window stack are to replace it.
886 That is, two of two sequential searches, only the last one's results
887 will be the window stack.
888
890 xdotool supports running multiple commands on a single invocation.
891 Generally, you'll start with a search command (see "WINDOW STACK") and
892 then perform a set of actions on those results.
893 To query the window stack, you can use special notation "%N" where N is
895 a number or the '@' symbol. If %N is given, the Nth window will be
896 selected from the window stack. Generally you will only want the first
897 window or all windows. Note that the order of windows in the window
898 stack corresponds to the window stacking order, i.e. the bottom-most
899 window will be reported first (see XQueryTree(3)). Thus the order of
900 the windows in the window stack may not be consistent across
901 invocations.
902 The notation described above is used as the "window" argument for any
904 given command.
905 For example, to resize all xterms to 80x24:
907 xdotool search --class xterm -- windowsize --usehints %@ 80 24
909 Resize move the current window:
911 xdotool getactivewindow windowmove 0 0
913 In all cases, the default window argument, if omitted, will default to
915 "%1". It is obviously an error if you omit the window argument and the
916 window stack is empty. If you try to use the window stack and it is
917 empty, it is also an error.
918 To activate the first firefox window found:
920 xdotool search --class firefox windowactivate
922 These would error:
924 xdotool windowactivate
926 xdotool windowactivate %1
927 xdotool windowactivate %@
928 When xdotool exits, the current window stack is lost.
930 Additionally, commands that modify the "WINDOW STACK" will not print
932 the results if they are not the last command. For example:
933 # Output the active window:
935 % xdotool getactivewindow
936 20971533
937 # Output the pid of the active window, but not the active window id:
939 % xdotool getactivewindow getwindowpid
940 4686
941
943 The following pieces of the EWMH standard are supported:
944 _NET_SUPPORTED
946 Asks the window manager what is supported
947 _NET_CURRENT_DESKTOP
949 Query and set the current desktop. Support for this enables these
950 commands: "set_desktop", "get_desktop".
951 _NET_WM_DESKTOP
953 Query and set what desktop a window is living in. Support for this
954 enables these commands: "set_desktop_for_window",
955 "get_desktop_for_window".
956 _NET_ACTIVE_WINDOW
958 Allows you to query and set the active window by asking the window
959 manager to bring it forward. Support for this enables these
960 commands: "windowactivate", "getactivewindow".
961 _NET_WM_PID
963 This feature is application dependent, not window-manager
964 dependent. Query the PID owning a given window. Support for this
965 enables these commands: "getwindowpid".
966
968 xdotool (and libxdo) will try to function under all circumstances.
969 However, there may be some cases where functionality is not provided by
970 your X server or by your window manager. In these cases, xdotool will
971 try to detect and tell you if an action requires a feature not
972 currently supported by your system.
973 For window-manager specific features, see "EXTENDED WINDOW MANAGER
975 HINTS".
976 XTEST
978 If your X server does not support XTEST, then some typing and mouse
979 movement features may not work. Specifically, typing and mouse
980 actions that act on the "current window" (window 0 in libxdo) are
981 unlikely to work.
982 In most cases, XTEST is a feature you can enable on your X server
984 if it is not enabled by default.
985 You can see the list of supported X extensions by typing 'xdpyinfo'
987 and looking the text 'number of extensions: ...'
988
990 Typing unusual symbols under non-us keybindings is known to
991 occasionally send the wrong character.
992
994 xprop(1), xwininfo(1),
995 Project site: <http://www.semicomplete.com/projects/xdotool>
997 Source code and Issues: <https://github.com/jordansissel/xdotool>
999 EWMH specification:
1001 <http://standards.freedesktop.org/wm-spec/wm-spec-1.3.html>
1002
1004 Please send questions to xdotool-users@googlegroups.com. File bugs and
1005 feature requests at the following URL:
1006 <https://github.com/jordansissel/xdotool/issues>
1008 Alternately, if you prefer email, feel free to file bugs by emailing
1010 the list. What works for you :)
1011
1013 xdotool was written by Jordan Sissel.
1014 This manual page was written originally by Daniel Kahn Gillmor
1016 <dkg@fifthhorseman.net> for the Debian project (but may be used by
1017 others). It is maintained by Jordan Sissel.
1018 Patches, ideas, and other contributions by many, nice folks. See the
1020 CHANGELIST file for who provided what.
1021 2023-01-21 XDOTOOL(1)