I have been working on some utility scripts that rely in part on the xdotool program. While debugging one day, I tried running a problematic line from my script in the terminal to see what was really happening. I had coded a syntax error. No surprise. I do that frequently. But something about the error message that xdotool generated struck me as odd. It showed the syntax to invoke the particular xdotool command (getwindowgeometry) as well as the options available for that command. To my surprise, it showed an option that is not documented in the xdotool man page.
I did some further investigating and came to the conclusion that the man page for xdotool is woefully incomplete. Not only does it fail to document some command options, in one case it even fails to document an entire command.
Here’s my compendium of the errors and omissions:
(Note: The following points are based on error messages from xdotool version 3.20160805.1, versus the corresponding man page. My UM version is 24.04.3)
- The --prefix option for the getwindowgeometry command is not documented in the manpage. However it is documented by the program itself if you bungle the command. For example:
$ xdotool getwindowgeometry --dumbledore
getwindowgeometry: unrecognized option '--dumbledore'
Usage: getwindowgeometry \[window=%1\] \[--shell\] \[--prefix <STR>\]
\--shell - output shell variables for use with eval
\--prefix STR - use prefix for shell variables names (max 16 chars)
If no window is given, %1 is used. See WINDOW STACK in xdotool(1)
- The getdisplaygeometry command is not documented in the man page, but it is listed in the output of "xdotool --help". This command writes the display width and height in pixels to stdout:
$ xdotool getdisplaygeometry
1920 1080
- The search command is documented in the man page, but the man page omits two options that are documented by the program itself if you bungle the command (for example xdotool search --dumbledore) The two missing options are --shell and --prefix.
The --shell option outputs the line delimited window ID numbers in a format suitable for using the eval command to assign them to an array variable named "WINDOWS":
$ xdotool search --shell brave
Defaulting to search window name, class, and classname
WINDOWS=(83886081
83886083
81788932
)
The --prefix option can be used with the --shell option to customize the name of the array variable:
$ xdotool search --shell --prefix BRAVE_ brave
Defaulting to search window name, class, and classname
BRAVE_WINDOWS=(83886081
83886083
81788932
)
- The --prefix option for the getmouselocation command is not documented in the manpage. However it is documented by the program itself if you bungle the command. For example:
$ xdotool getmouselocation --dumbledore
getmouselocation: unrecognized option '--dumbledore'
Usage: getmouselocation \[--shell\] \[--prefix <STR>\]
--shell - output shell variables for use with eval
--prefix STR - use prefix for shell variables names (max 16 chars)
The --shell option (documented in the man page) outputs four line-delimited values as variable assignments that can be executed by the eval command:
$ xdotool getmouselocation --shell
X=862
Y=675
SCREEN=0
WINDOW=33554442
The --prefix option can be used with the --shell option to customize the names of the variables:
$ xdotool getmouselocation --shell --prefix MY_
MY_X=1101
MY_Y=734
MY_SCREEN=0
MY_WINDOW=33554442
- The --repeat and --repeat-delay options for the key, keydown, and keyup commands are not documented in the manpage. However they are documented by the program itself if you bungle any of these commands. For example:
$ xdotool key --dumbledore
key: unrecognized option '--dumbledore'
Usage: key \[options\] <keysequence> \[keysequence ...\]
--clearmodifiers - clear active keyboard modifiers during keystrokes
--delay DELAY - Use DELAY milliseconds between keystrokes
--repeat TIMES - How many times to repeat the key sequence
--repeat-delay DELAY - DELAY milliseconds between repetitions
--window WINDOW - send keystrokes to a specific window
Each keysequence can be any number of modifiers and keys, separated by plus (+)
For example: alt+r
-
The man page states that the mousedown command is "Same as [the] click [command], except only a mouse down is sent." This is not true. The mousedown command only recognizes the --window and --clearmodifiers options; whereas the click command also recognizes the --repeat and --delay options.
-
Similarly, the man page states that the mouseup command is "Same as [the] click [command], except only a mouse up is sent." This is not true. The mouseup command only recognizes the --window and --clearmodifiers options; whereas the click command also recognizes the --repeat and --delay options.
-
The mousemove_relative command is documented in the man page, but if you bungle the command, the xdotool error output contains a useful tip: To specify negative numbers, you must precede them with the end-of-options marker (
--) so they won't be parsed as short-form options and cause "unrecognized option" errors. Correct usage example:
$ xdotool mousemove_relative -- -20 -15
- The type command is documented in the man page, but the man page omits three options (--args, --terminator, and --file) that are reflected in the command's error output:
$ xdotool type --dumbledore
type: unrecognized option '--dumbledore'
Usage: type \[--window windowid\] \[--delay milliseconds\] <things to type>
--window <windowid> - specify a window to send keys to
--delay <milliseconds> - delay between keystrokes
--clearmodifiers - reset active modifiers (alt, etc) while typing
--args N - how many arguments to expect in the exec command. This is
useful for ending an exec and continuing with more xdotool commands
--terminator TERM - similar to --args, specifies a terminator that
marks the end of 'exec' arguments. This is useful
for continuing with more xdotool commands.
--file <filepath> - specify a file, the contents of which will be
be typed as if passed as an argument. The filepath
may also be '-' to read from stdin.
The man page states, "With respect to COMMAND CHAINING, this command consumes the remainder of the arguments and types them. [Thus], no commands can chain after ’type’."
This isn't true. The --args option can be used to tell xdotool how many arguments that follow the type command are to be treated as strings and typed; another command can follow the last of these arguments. Example:
$ xdotool type --args 2 "Arg1 " "Arg2 " getdisplaygeometry
Arg1 Arg2 1920 1080
$ Arg1 Arg2
(The string "Arg1 Arg2 " follows the next command prompt because xdotool was typing into the terminal window.)
The --terminator argument allows a variable number of arguments (such as an array variable expansion) as arguments to by typed. The terminator string itself is not typed, but any arguments following it are not typed, but are treated as chained commands:
$ xdotool type --terminator "X" "Arg1 " "Arg2 " "X" getdisplaygeometry
Arg1 Arg2 1920 1080
$ Arg1 Arg2
The --file option allows the type command to type the contents of a text file as if those characters had been typed at the keyboard:
$ echo -n "Hello World!" > sample.txt
$ xdotool type --file sample.txt
Hello World!
- The exec command is documented in the man page, but the man page omits two options (--args and --terminator) that are reflected in the command's error output:
$ xdotool exec --dumbledore
exec: unrecognized option '--dumbledore'
Usage: exec \[options\] command \[arg1 arg2 ...\] \[terminator\]
--sync - only exit when the command given finishes. The default
is to fork a child process and continue.
--args N - how many arguments to expect in the exec command. This is
useful for ending an exec and continuing with more xdotool
commands
--terminator TERM - similar to --args, specifies a terminator that
marks the end of 'exec' arguments. This is useful
for continuing with more xdotool commands.
Unless --args OR --terminator is specified, the exec command is assumed
to be the remainder of the command line.
$
If neither the --args nor --terminator option is used, then exec consumes the remaining arguments on the command line, and cannot chain to any additional xdotool commands. These two options function in a similar way to that described above for the type command, allowing additional xdotool commands to follow on the same command line.
