1XDOTOOL(1)                                                          XDOTOOL(1)
2
3
4

NAME

6       xdotool - command-line X11 automation tool
7

SYNOPSIS

9       xdotool cmd args...
10
11       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

DESCRIPTION

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

KEYBOARD COMMANDS

25       key [options] keystroke [keystroke ...]
26           Options:
27
28           --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
34               See also: "SENDEVENT NOTES" and "WINDOW STACK"
35
36           --clearmodifiers
37               Clear modifiers before sending keystrokes. See CLEARMODIFIERS
38               below.
39
40           --delay milliseconds
41               Delay between keystrokes. Default is 12ms.
42
43           Type a given keystroke. Examples being "alt+r", "Control_L+J",
44           "ctrl+alt+n", "BackSpace".
45
46           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
51           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
55           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
59           Example: Send the keystroke "F2"
60            xdotool key F2
61
62           Example: Send 'a' with an accent over it (not on English keyboards,
63           but still works with xdotool)
64            xdotool key Aacute
65
66           Example: Send ctrl+l and then BackSpace as separate keystrokes:
67            xdotool key ctrl+l BackSpace
68
69           Example: Send ctrl+c to all windows matching title 'gdb' (See
70           "COMMAND CHAINING")
71            xdotool search --name gdb key ctrl+c
72
73       keydown [options] keystroke
74           Same as above, except only keydown (press) events are sent.
75
76       keyup keystroke
77           Same as above, except only keyup (release) events are sent.
78
79       type [options] something to type
80           Options:
81
82           --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
89           --delay milliseconds
90               Delay between keystrokes. Default is 12ms.
91
92           --clearmodifiers
93               Clear modifiers before sending keystrokes. See CLEARMODIFIERS
94               below.
95
96           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
100           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
104           Example: to type 'Hello world!' you would do:
105            xdotool type 'Hello world!'
106

MOUSE COMMANDS

108       mousemove [options] x y OR 'restore'
109           Move the mouse to the specific X and Y coordinates on the screen.
110
111           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
116           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
120           --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
124               "WINDOW STACK" references are valid here, such as %1 and %@.
125               Though, using %@ probably doesn't make sense.
126
127           --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
131               The default is the current screen. If you specify --window, the
132               --screen flag is ignored.
133
134           --polar
135               Use polar coordinates. This makes 'x' an angle (in degrees,
136               0-360, etc) and 'y' the distance.
137
138               Rotation starts at 'up' (0 degrees) and rotates clockwise: 90 =
139               right, 180 = down, 270 = left.
140
141               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
145           --clearmodifiers
146               See CLEARMODIFIERS
147
148           --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
154               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
160       mousemove_relative [options] x y
161           Move the mouse x,y pixels relative to the current position of the
162           mouse cursor.
163
164           --polar
165               Use polar coordinates. This makes 'x' an angle (in degrees,
166               0-360, etc) and 'y' the distance.
167
168               Rotation starts at 'up' (0 degrees) and rotates clockwise: 90 =
169               right, 180 = down, 270 = left.
170
171           --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
177               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
183           --clearmodifiers
184               See CLEARMODIFIERS
185
186       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
190           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
193           --clearmodifiers
194               Clear modifiers before clicking. See CLEARMODIFIERS below.
195
196           --repeat REPEAT
197               Specify how many times to click. Default is 1. For a double-
198               click, use '--repeat 2'
199
200           --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
205           --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
210               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
215       mousedown [options] button
216           Same as click, except only a mouse down is sent.
217
218       mouseup [options] button
219           Same as click, except only a mouse up is sent.
220
221       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
226           This command updates the window stack with the window id of the
227           window directly underneath the mouse.
228
229           --shell
230               This makes getmouselocation output shell data you can eval.
231               Example:
232
233                % xdotool getmouselocation --shell
234                X=880
235                Y=443
236                SCREEN=0
237                WINDOW=16777250
238
239                % eval $(xdotool getmouselocation --shell)
240                % echo $X,$Y
241                714,324
242
243       behave_screen_edge [options] where command ...
244           Bind an action to events when the mouse hits the screen edge or
245           corner.
246
247           Options are:
248
249           --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
255           --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
261           Event timeline
262
263            * 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
269           Valid 'where' values are:
270
271           left
272           top-left
273           top
274           top-right
275           right
276           bottom-left
277           bottom
278           bottom-right
279
280           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
286            # 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
289            # 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

WINDOW COMMANDS

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
302           The result is saved to the window stack for future chained
303           commands. See "WINDOW STACK" and "COMMAND CHAINING" for details.
304
305           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
309           The default options are "--name --class --classname --role" (unless
310           you specify one or more of --name, --class, --classname, or
311           --role).
312
313           The options available are:
314
315           --class
316               Match against the window class.
317
318           --classname
319               Match against the window classname.
320
321           --role
322               Match against the window role.
323
324           --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
330           --name
331               Match against the window name. This is the same string that is
332               displayed in the window titlebar.
333
334           --onlyvisible
335               Show only visible windows in the results. This means ones with
336               map state IsViewable.
337
338           --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
343           --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
348           --desktop N
349               Only match windows on a certain desktop. 'N' is a number. The
350               default is to search all desktops.
351
352           --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
357               The default is no search limit (which is equivalent to '--limit
358               0')
359
360           --title
361               DEPRECATED. See --name.
362
363           --all
364               Require that all conditions be met. For example:
365
366                xdotool search --all --pid 1424 --name "Hello World"
367
368               This will match only windows that have "Hello World" as a name
369               and are owned by pid 1424.
370
371           --any
372               Match windows that match any condition (logically, 'or'). This
373               is on by default. For example:
374
375                xdotool search --any --pid 1424 --name "Hello World"
376
377               This will match any windows owned by pid 1424 or windows with
378               name "Hello World"
379
380           --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
385                google-chrome &
386                xdotool search --sync --onlyvisible --class "google-chrome"
387
388       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
393            xdotool selectwindow windowkill
394
395       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
399           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
403           The following are valid events:
404
405           mouse-enter
406               Fires when the mouse enters a window. This is similar to 'mouse
407               over' events in javascript, if that helps.
408
409           mouse-leave
410               Fires when the mouse leaves a window. This is the opposite of
411               'mouse-enter'
412
413           mouse-click
414               Fires when the mouse is clicked. Specifically, when the mouse
415               button is released.
416
417           focus
418               Fires when the window gets input focus.
419
420           blur
421               Fires when the window loses focus.
422
423           Examples:
424
425            # Print the cursor location whenever the mouse enters a currently-visible
426            # window:
427            xdotool search --onlyvisible . behave %@ mouse-enter getmouselocation
428
429            # Print the window title and pid whenever an xterm gets focus
430            xdotool search --class xterm behave %@ focus getwindowname getwindowpid
431
432            # Emulate focus-follows-mouse
433            xdotool search . behave %@ mouse-enter windowfocus
434
435       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
441           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
445           Example: Find the PID for all xterms:
446            xdotool search --class xterm getwindowpid %@
447
448       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
452           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
456       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
460           --shell
461               Output values suitable for 'eval' in a shell.
462
463       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
467           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
471           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
474       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
479           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
483            xdotool windowsize I<window> 100% 50%
484
485           Percentages are valid with --usehints and still mean pixel-width
486           relative to the screen size.
487
488           The options available are:
489
490           --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
495           --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
501               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
505           Example: To set a terminal to be 80x24 characters, you would use:
506            xdotool windowsize --usehints some_windowid 80 24
507
508       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
513           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
516           Examples:
517
518            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
523           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
527            xdotool windowmove I<window> 100% 50%
528
529           --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
535           --relative
536               Make movement relative to the current window position.
537
538       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
542           Uses XSetInputFocus which may be ignored by some window managers or
543           programs.
544
545           --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
550       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
555           --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
560       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
565           --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
570       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
575       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
582       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
588       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
594       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
599       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
604           --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
609       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
614           Options:
615
616           --name newname
617               Set window WM_NAME (the window title, usually)
618
619           --icon-name newiconname
620               Set window WM_ICON_NAME (the window title when minimized,
621               usually)
622
623           --role newrole
624               Set window WM_WINDOW_ROLE
625
626           --classname newclassname
627               Set window class name (not to be confused with window class)
628
629           --class newclass
630               Set window class (not to be confused with window class name)
631
632           --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
638           --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
645               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

DESKTOP AND WINDOW COMMANDS

651       These commands follow the EWMH standard. See the section "EXTENDED
652       WINDOW MANAGER HINTS" for more information.
653
654       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
661           If no window is given, %1 is the default. See "WINDOW STACK" and
662           "COMMAND CHAINING" for more details.
663
664           --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
669       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
674       windowstate [--add PROPERTY] [--remove PROPERTY] [--toggle PROPERTY]
675       [window]
676           Change a property on a window.
677
678           Some properties may have no effect some windows or in some window
679           managers.
680
681           Properties can be any of:
682
683           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
696           This feature requires a window manager which supports EWMH. Most
697           window managers probably support this :)
698
699       getwindowclassname [window]
700           Prints the class name for the window.
701
702       set_num_desktops number
703           Changes the number of desktops or workspaces.
704
705       get_num_desktops
706           Output the current number of desktops.
707
708       get_desktop_viewport [--shell]
709           Report the current viewport's position. If --shell is given, the
710           output is friendly to shell eval.
711
712           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
716       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
721           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
725       set_desktop [options] desktop_number
726           Change the current view to the specified desktop.
727
728           --relative
729               Use relative movements instead of absolute. This lets you move
730               relative to the current desktop.
731
732       get_desktop
733           Output the current desktop in view.
734
735       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
740       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

MISCELLANEOUS COMMANDS

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
750           Options:
751
752           --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
757           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
763            # 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
767            # This succeeds, though, since we do not use --sync on the exec command.
768            xdotool exec /bin/false mousemove 0 0
769
770       sleep seconds
771           Sleep for a specified period. Fractions of seconds (like 1.3, or
772           0.4) are valid, here.
773

SCRIPTS

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
778       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
782       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
786       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
790       •   Read commands from a file:
791
792            xdotool filename
793
794       •   Read commands from stdin:
795
796            xdotool -
797
798       •   Read commands from a redirected file
799
800            xdotool - < myfile
801
802       You can also write scripts that only execute xdotool. Example:
803
804        #!/usr/local/bin/xdotool
805        search --onlyvisible --classname $1
806
807        windowsize %@ $2 $3
808        windowraise %@
809
810        windowmove %1 0 0
811        windowmove %2 $2 0
812        windowmove %3 0 $3
813        windowmove %4 $2 $3
814
815       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
819       Here's an example usage:
820
821        % ./myscript xterm 600 400
822
823       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

CLEARMODIFIERS

827       Any command taking the --clearmodifiers flag will attempt to clear any
828       active input modifiers during the command and restore them afterwards.
829
830       For example, if you were to run this command:
831        xdotool key a
832
833       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
838       The order of operations if you hold shift while running 'xdotool key
839       --clearmodifiers a' is this:
840
841       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
846       The --clearmodifiers flag can currently clear of the following:
847
848       •   any key in your active keymap that has a modifier associated with
849           it.  (See xmodmap(1)'s 'xmodmap -pm' output)
850
851       •   mouse buttons (1, 2, 3, 4, and 5)
852
853       •   caps lock
854

SENDEVENT NOTES

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
860       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
867       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
870       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
874       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

WINDOW STACK

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

COMMAND CHAINING

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
894       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
903       The notation described above is used as the "window" argument for any
904       given command.
905
906       For example, to resize all xterms to 80x24:
907
908        xdotool search --class xterm -- windowsize --usehints %@ 80 24
909
910       Resize move the current window:
911
912        xdotool getactivewindow windowmove 0 0
913
914       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
919       To activate the first firefox window found:
920
921        xdotool search --class firefox windowactivate
922
923       These would error:
924
925        xdotool windowactivate
926        xdotool windowactivate %1
927        xdotool windowactivate %@
928
929       When xdotool exits, the current window stack is lost.
930
931       Additionally, commands that modify the "WINDOW STACK" will not print
932       the results if they are not the last command. For example:
933
934        # Output the active window:
935        % xdotool getactivewindow
936        20971533
937
938        # Output the pid of the active window, but not the active window id:
939        % xdotool getactivewindow getwindowpid
940        4686
941

EXTENDED WINDOW MANAGER HINTS

943       The following pieces of the EWMH standard are supported:
944
945       _NET_SUPPORTED
946           Asks the window manager what is supported
947
948       _NET_CURRENT_DESKTOP
949           Query and set the current desktop. Support for this enables these
950           commands: "set_desktop", "get_desktop".
951
952       _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
957       _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
962       _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

SUPPORTED FEATURES

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
974       For window-manager specific features, see "EXTENDED WINDOW MANAGER
975       HINTS".
976
977       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
983           In most cases, XTEST is a feature you can enable on your X server
984           if it is not enabled by default.
985
986           You can see the list of supported X extensions by typing 'xdpyinfo'
987           and looking the text 'number of extensions: ...'
988

BUGS

990       Typing unusual symbols under non-us keybindings is known to
991       occasionally send the wrong character.
992

SEE ALSO

994       xprop(1), xwininfo(1),
995
996       Project site: <http://www.semicomplete.com/projects/xdotool>
997
998       Source code and Issues: <https://github.com/jordansissel/xdotool>
999
1000       EWMH specification:
1001       <http://standards.freedesktop.org/wm-spec/wm-spec-1.3.html>
1002

CONTACT

1004       Please send questions to xdotool-users@googlegroups.com. File bugs and
1005       feature requests at the following URL:
1006
1007       <https://github.com/jordansissel/xdotool/issues>
1008
1009       Alternately, if you prefer email, feel free to file bugs by emailing
1010       the list.  What works for you :)
1011

AUTHOR

1013       xdotool was written by Jordan Sissel.
1014
1015       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
1019       Patches, ideas, and other contributions by many, nice folks. See the
1020       CHANGELIST file for who provided what.
1021
1022
1023
1024                                  2023-01-21                        XDOTOOL(1)
Impressum