J
Jarret W. Buse
Guest
Xdotool - Window
The xdotool is a utility used from the terminal or in a script to manually perform keyboard, mouse and window input (see the Xdotool – Keyboard and Xdotool – Mouse article). The commands can also be used to make a script of many xdotool commands to create large tasks. Later articles will cover the xdotool ability to control desktop manipulation.
The syntax for xdotool depends on the command being used. The first, but very powerful command, is 'search'. The syntax is as follows:
search [options] pattern
The search command helps to find specific windows on a system.
There are twelve options available for search which are:
NOTE: To find the class and classname, use the command 'xprop' in a Terminal. Once typed, the mouse cursor changes to allow the user to click on a window. Once selected, 'xprop' displays information about the selected window. The line labeled 'WM_CLASS(STRING)' displays two entries. The first entry is referred to as the Instance or Classname and the second is the Class name. The two may be identical except in case as with Gedit:
WM_CLASS(STRING) = "gedit", "Gedit"
The two names can be different as with Firefox:
WM_CLASS(STRING) = "Navigator", "Firefox"
Here, the Classname is Navigator while the Class name is Firefox. Sometimes, it is best to use the Classname or Class rather than the Name. The Name can return all the child processes as well as can be seen when you open some calculator programs and perform a search with the name of 'calculator'.
xdotool search --name calculator
If you have a program which is generating multiple window Ids and you only have one instance of the application running, you can use the 'maxdepth' option. With the maxdepth option set at 0, you only get the window ID of the top window and no child processes.
The IsViewable state allows for applications which are not 'hidden' windows. Background services are a good example.
The PID number of an application can pinpoint a specific application.
NOTE: The PID can be found in the 'xprop' application under the Terminal in the line '_NET_WM_PID(CARDINAL)'. Other applications like 'htop' can display the same information.
The next option is to specify which screen to search. If your system has only one monitor, then the default screen is '0'.
NOTE: Do not confuse screen with desktop. If your system has multiple monitors, then you have multiple screens.
Instead of specifying a screen, you can designate a specific desktop or workspace to search for a window. For example, to search Workspace 2 you would use '--desktop 2'.
When you perform a search and the display shows numerous matches, you can limit the results to a specific number. The default is zero which displays all matches.
If you specify more than one option for a search, then you can use the '--all' option to require that all the options be true for a match to be made. With the '--any' option, any option can be true to produce a match. For example, I could perform the following:
xdotool search --all --class gedit --classname navigator
Here, the results should show no matches. The gedit application does not have a classname of navigator which is a browser. For a different response, I use the following command:
xdotool search --any --class gedit --classname navigator
The previous command would give me the window ID for Gedit as well as Firefox. The any command allows for a check of all windows to match any, not all, of the the possible matches. Only one criteria must match to generate a window ID.
The 'sync' option stops processing commands until the window is available. This can be helpful if you have a script running many xdotool commands and you are starting applications. It is helpful to know when the application has started and is running before commands are passed to the window.
The next command is 'selectwindow'. The syntax is as follows:
selectwindow
There are no options for this command since it performs one function. When entered, the cursor changes to allow the user to click on a window. You can change workspaces to get to a desired window. The output is the window ID of the selected window.
NOTE: When selecting a window, it is possible to select the desktop and applets.
Many times, you may want to perform an action when a specific event occurs with a window. These events are mainly mouse events, but they do include when the window gets or loses focus. The command syntax is:
behave window_id action command
The first item in the syntax is the window or window ID which has been covered. The next item is the 'action'. The action specifies what event is occurring to the window designated by its ID. There are five events which can be used:
xdotool behave 48234652 mouse-leave mousemove --window 48234652 --polar 0 0
What happens? Well, when the window gains focus, the cursor returns to the center of the window whenever it leaves the window. One way to get out of it requires the user to close the window.
The next command is 'getwindowpid' and the syntax is:
getwindowpid window_id
With this command, we can find the Processor ID (PID) number of a window if we know the window ID.
The next command is 'getwindowname' with the syntax as follows:
getwindowname window_id
By using the window ID, we can find the name or title of a window. For example, if we have two text editors open, a search results in two matches. We can use the window IDs to determine the title so we can then know which window belongs to which ID.
Another command is the 'getwindowgeometry'. The command allows for gaining information about a specific window. The syntax is:
getwindowgeometry options window_id
The geometry results include the x and y coordinate of the the upper-left corner of the window, the window's width and height and the screen number to which the window is located. For example, if I used the following command:
xdotool getwindowgeometry 48234652
Would possibly produce something like the following:
Window 48234652
Position: 358,149 (screen: 0)
Geometry: 566x379
The position shows the x, y coordinates. The geometry shows the width and height. We are also shown the Screen number as well as the window ID.
The command has one option: --shell. This places the information in a columnar fashion with one geometry item per line as follows:
WINDOW=48234652
X=358
Y=149
WIDTH=566
HEIGHT=379
SCREEN=0
The shell output can be used for other utilities such as grep. The output can be searched to produce only the desired results, such as the screen width, as follows:
xdotool getwindowgeometry -shell 48234652 | grep WIDTH=
Commands like these can help produce long scripts and find the information needed to specify which window is to be worked with for each command.
The next command can be used to find the window which has focus, but does not include the desktop or applets, gadgets, etc. The result displayed will be the window ID. The command and its syntax is:
getwindowfocus [options]
The only option is '-f' which allows you to get the window id of the item which has focus, even if it is not a window. The items included are the desktop, applets, gadgets, etc.
The next command is 'windowsize' which allows you to set the size of a window. The syntax is:
windowsize [options] [window_id] width height
Percentages can be used to compare the size to the screen, such as 100% could be used for height and/or width to make the window the full height and/or width of the screen. Using 100% for both height and width will make the window full screen.
There are two options for this command:
xdotool windowsize 37748855 25% 50%
It is also possible to specify the pixel size, such as 500 pixels by 750 pixels:
xdotool windowsize 37748855 500 750
The pixel size and percentages can be mixed, such as a width of 500 pixels and a height of 100%:
xdotool windowsize 37748855 500 100%
The next command is 'windowmove' and the syntax is:
xdotool windowmove [options] [window] x y
This command allows a window to be moved to a specific positon. If either 'x' or 'y' is not replaced with a specific number, but you use the 'x' or 'y' letter, then the current value is used. There are two options:
xdotool windowmove 46137500 100 100
We can then start at the current location and move the same window left 10 pixels (-10) and down 100 pixels:
xdotool windowmove --relative 46137500 -10 100
To move the window down to position 500 but leave the x value the same, the following command could be used:
xdotool windowmove -relative 46137500 x 500
Another command is the 'windowfocus' command to make a specified window the focus:
windowfocus [options] [window_id]
The only option is the –sync option which allows for the command to be carried out before other commands are performed.
NOTE: Be aware that the window has focus to allow keyboard input to it, but it may not be the active window on top of all others.
The next command is 'windowunmap' which makes the window hidden or invisible. The opposite is the 'windowmap' command to make the window visible. Their syntax is:
windowunmap[options] [window_id]
windowmap[options] [window_id]
Each command has one option only, that of '--sync' which allows for the window to be hidden or reappear before more commands are processed.
Another command is 'windowminimize'. This command is not the same as windowunmap since windowunmap makes the window disappear and windowminimize causes the window to be minimized. The syntax is:
windowminimize[options] [window_id]
The command has one option, that of '--sync' which allows for the window to be minimized before more commands are processed.
Another command which can be very useful is 'windowkill'. This command allows a window to be terminated as well as the client controlling it. The syntax is as follows:
windowkill[window_id]
The only parameter to pass to it is the window id of the window that you wish to terminate.
The next command is the 'set_window' command which has the following syntax:
set_window[options] [window_id]
The command allows for changing properties of a specified window. There are six options to determine which property is to be changed for this command:
The xdotool is a utility used from the terminal or in a script to manually perform keyboard, mouse and window input (see the Xdotool – Keyboard and Xdotool – Mouse article). The commands can also be used to make a script of many xdotool commands to create large tasks. Later articles will cover the xdotool ability to control desktop manipulation.
The syntax for xdotool depends on the command being used. The first, but very powerful command, is 'search'. The syntax is as follows:
search [options] pattern
The search command helps to find specific windows on a system.
There are twelve options available for search which are:
- --class class_name – name of the window's class
- --classname classname_name – name of the window's classname
- --name name – title of the window
- --maxdepth N – recursive search for window, default is -1 meaning infinite (all child windows too) and 0 means top windows only, depth of 1 or more can get most windows
- --onlyvisible – results show only windows which are visible which have the IsViewable state
- --pid PID_NUM – process ID number of the window
- --screen N – number of the monitor on which the window is open (0 is first monitor, but defaults to all available screens)
- --desktop N – number of the desktop or workspace
- --limit N – maximum number of results to display. Default is no limit (--limit 0)
- --all – requires that all conditions for a match are met when multiple options are specified
- --any – requires that any condition is true when specifying multiple options
- --sync – halt all commands until previous commands produce results
NOTE: To find the class and classname, use the command 'xprop' in a Terminal. Once typed, the mouse cursor changes to allow the user to click on a window. Once selected, 'xprop' displays information about the selected window. The line labeled 'WM_CLASS(STRING)' displays two entries. The first entry is referred to as the Instance or Classname and the second is the Class name. The two may be identical except in case as with Gedit:
WM_CLASS(STRING) = "gedit", "Gedit"
The two names can be different as with Firefox:
WM_CLASS(STRING) = "Navigator", "Firefox"
Here, the Classname is Navigator while the Class name is Firefox. Sometimes, it is best to use the Classname or Class rather than the Name. The Name can return all the child processes as well as can be seen when you open some calculator programs and perform a search with the name of 'calculator'.
xdotool search --name calculator
If you have a program which is generating multiple window Ids and you only have one instance of the application running, you can use the 'maxdepth' option. With the maxdepth option set at 0, you only get the window ID of the top window and no child processes.
The IsViewable state allows for applications which are not 'hidden' windows. Background services are a good example.
The PID number of an application can pinpoint a specific application.
NOTE: The PID can be found in the 'xprop' application under the Terminal in the line '_NET_WM_PID(CARDINAL)'. Other applications like 'htop' can display the same information.
The next option is to specify which screen to search. If your system has only one monitor, then the default screen is '0'.
NOTE: Do not confuse screen with desktop. If your system has multiple monitors, then you have multiple screens.
Instead of specifying a screen, you can designate a specific desktop or workspace to search for a window. For example, to search Workspace 2 you would use '--desktop 2'.
When you perform a search and the display shows numerous matches, you can limit the results to a specific number. The default is zero which displays all matches.
If you specify more than one option for a search, then you can use the '--all' option to require that all the options be true for a match to be made. With the '--any' option, any option can be true to produce a match. For example, I could perform the following:
xdotool search --all --class gedit --classname navigator
Here, the results should show no matches. The gedit application does not have a classname of navigator which is a browser. For a different response, I use the following command:
xdotool search --any --class gedit --classname navigator
The previous command would give me the window ID for Gedit as well as Firefox. The any command allows for a check of all windows to match any, not all, of the the possible matches. Only one criteria must match to generate a window ID.
The 'sync' option stops processing commands until the window is available. This can be helpful if you have a script running many xdotool commands and you are starting applications. It is helpful to know when the application has started and is running before commands are passed to the window.
The next command is 'selectwindow'. The syntax is as follows:
selectwindow
There are no options for this command since it performs one function. When entered, the cursor changes to allow the user to click on a window. You can change workspaces to get to a desired window. The output is the window ID of the selected window.
NOTE: When selecting a window, it is possible to select the desktop and applets.
Many times, you may want to perform an action when a specific event occurs with a window. These events are mainly mouse events, but they do include when the window gets or loses focus. The command syntax is:
behave window_id action command
The first item in the syntax is the window or window ID which has been covered. The next item is the 'action'. The action specifies what event is occurring to the window designated by its ID. There are five events which can be used:
- mouse-enter – when the cursor enters a window's boundaries
- mouse-leave – when the cursor leaves the window's boundaries
- mouse-click – when the mouse is clicked (released) within the window's boundaries
- focus – when the window gains focus (active window)
- blur – when the window loses focus (another window becomes active)
xdotool behave 48234652 mouse-leave mousemove --window 48234652 --polar 0 0
What happens? Well, when the window gains focus, the cursor returns to the center of the window whenever it leaves the window. One way to get out of it requires the user to close the window.
The next command is 'getwindowpid' and the syntax is:
getwindowpid window_id
With this command, we can find the Processor ID (PID) number of a window if we know the window ID.
The next command is 'getwindowname' with the syntax as follows:
getwindowname window_id
By using the window ID, we can find the name or title of a window. For example, if we have two text editors open, a search results in two matches. We can use the window IDs to determine the title so we can then know which window belongs to which ID.
Another command is the 'getwindowgeometry'. The command allows for gaining information about a specific window. The syntax is:
getwindowgeometry options window_id
The geometry results include the x and y coordinate of the the upper-left corner of the window, the window's width and height and the screen number to which the window is located. For example, if I used the following command:
xdotool getwindowgeometry 48234652
Would possibly produce something like the following:
Window 48234652
Position: 358,149 (screen: 0)
Geometry: 566x379
The position shows the x, y coordinates. The geometry shows the width and height. We are also shown the Screen number as well as the window ID.
The command has one option: --shell. This places the information in a columnar fashion with one geometry item per line as follows:
WINDOW=48234652
X=358
Y=149
WIDTH=566
HEIGHT=379
SCREEN=0
The shell output can be used for other utilities such as grep. The output can be searched to produce only the desired results, such as the screen width, as follows:
xdotool getwindowgeometry -shell 48234652 | grep WIDTH=
Commands like these can help produce long scripts and find the information needed to specify which window is to be worked with for each command.
The next command can be used to find the window which has focus, but does not include the desktop or applets, gadgets, etc. The result displayed will be the window ID. The command and its syntax is:
getwindowfocus [options]
The only option is '-f' which allows you to get the window id of the item which has focus, even if it is not a window. The items included are the desktop, applets, gadgets, etc.
The next command is 'windowsize' which allows you to set the size of a window. The syntax is:
windowsize [options] [window_id] width height
Percentages can be used to compare the size to the screen, such as 100% could be used for height and/or width to make the window the full height and/or width of the screen. Using 100% for both height and width will make the window full screen.
There are two options for this command:
- --usehints – specifies size by row and column, not by pixel size. This option is used for windows such as terminals.
- --sync – requires the resize to be carried out before any following commands are performed.
xdotool windowsize 37748855 25% 50%
It is also possible to specify the pixel size, such as 500 pixels by 750 pixels:
xdotool windowsize 37748855 500 750
The pixel size and percentages can be mixed, such as a width of 500 pixels and a height of 100%:
xdotool windowsize 37748855 500 100%
The next command is 'windowmove' and the syntax is:
xdotool windowmove [options] [window] x y
This command allows a window to be moved to a specific positon. If either 'x' or 'y' is not replaced with a specific number, but you use the 'x' or 'y' letter, then the current value is used. There are two options:
- --sync – the window's size is changed before further commands are performed
- --relative – values are relative to current location
xdotool windowmove 46137500 100 100
We can then start at the current location and move the same window left 10 pixels (-10) and down 100 pixels:
xdotool windowmove --relative 46137500 -10 100
To move the window down to position 500 but leave the x value the same, the following command could be used:
xdotool windowmove -relative 46137500 x 500
Another command is the 'windowfocus' command to make a specified window the focus:
windowfocus [options] [window_id]
The only option is the –sync option which allows for the command to be carried out before other commands are performed.
NOTE: Be aware that the window has focus to allow keyboard input to it, but it may not be the active window on top of all others.
The next command is 'windowunmap' which makes the window hidden or invisible. The opposite is the 'windowmap' command to make the window visible. Their syntax is:
windowunmap[options] [window_id]
windowmap[options] [window_id]
Each command has one option only, that of '--sync' which allows for the window to be hidden or reappear before more commands are processed.
Another command is 'windowminimize'. This command is not the same as windowunmap since windowunmap makes the window disappear and windowminimize causes the window to be minimized. The syntax is:
windowminimize[options] [window_id]
The command has one option, that of '--sync' which allows for the window to be minimized before more commands are processed.
Another command which can be very useful is 'windowkill'. This command allows a window to be terminated as well as the client controlling it. The syntax is as follows:
windowkill[window_id]
The only parameter to pass to it is the window id of the window that you wish to terminate.
The next command is the 'set_window' command which has the following syntax:
set_window[options] [window_id]
The command allows for changing properties of a specified window. There are six options to determine which property is to be changed for this command:
- --name new_name – allows the name of the window to be changed
- --icon-name new_icon_name – sets the title of the window when minimized (depends on Operating System)
- --role new_role – changes the role property of a window. The role property is sometimes used to help distinguish one window from another for parent and child windows
- --classname classname_name – sets the classname of a window
- --class class_name – sets a new class name for the window
- overridedirect value – if the value is set to 0, then the window manager will control the window and all redrawing. If the value is 1, then the window manager will not control it. Some window managers may not accept the change until the window is unmapped and mapped again
