Xdotool - Desktop


Jarret W. Buse

Xdotool - Desktop

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, Xdotool – Mouse and Xdotool – Window articles). The commands can also be used to make a script of many xdotool commands to create large tasks.

The syntax for xdotool depends on the command being used. The first command we'll discuss is 'windowactivate'. The syntax is as follows:

windowactivate [options] [window]

The 'windowactivate' command has one option:

  • sync – wait until the window is activated before more commands are processed

The 'windowactivate' command causes the specified window to come to the front as well as moving to the workspace on which the window is located.

For example, to switch to the text editor, which has a window ID of 46137500 and is on another workspace, I would use the following command:

xdotool windowactivate 46137500

The next command returns the window ID of the active window. The command is 'getactivewindow' and it has no parameters or options.

If my current active window has a window ID of 44040199 and the 'getactivewindow' command is run, I would receive the same window ID back. The command is as follows:

xdotool getactivewindow

The next two commands go together and they are 'get_num_desktops' and 'set_num_desktops'. The 'get_num_desktops' has no parameters or options and simply returns the number of desktops enabled on your system as shown:

xdotool get_num_desktops

In my case, I have four desktops, and the result of the command is '4'.

The 'set_num_desktops' has no options but has the following syntax:

set_num_desktops number

The number you specify is how many desktops you wish to have on your system. For example, if you want to have eight desktops, you use the following:

xdotool set_num_desktops 8

The next two commands work with the viewports. Before I continue, let's look at the difference between a workspace and viewport.

Basically, the workspace and viewport are the same thing. On a system with Ubuntu running the Compiz window manager, the 'workspaces', are actually referred to as viewports. On other systems, the workspace is not called a viewport. Now, on a system with viewports, the desktop refers to all the viewports as one desktop. On a system which allows for moving from desktop to desktop, but reports only a single desktop with the command 'get_num_desktops' is using viewports. One example of a system using viewports is Ubuntu, which will be switching to Mir in future releases.

Now, if we wanted to move to a specific desktop, you would use the 'set_desktop' command with the following syntax:

set_desktop [options] desktop_number-1

The option is a single option to move relative to the current desktop or workspace:

  • --relative number
To move to desktop 3 would require the following:

xdotool set_desktop 2

NOTE: The first workspace is numbered 0, so you need to subtract one from the desired workspace number.

To move relative from the current workspace, specify how many to move to the right. If you are on workspace 2 and wish to move to workspace 4, the following would be used:

xdotool set_desktop --relative 2

NOTE: Negative numbers are said to be allowed, but some versions of xdotool do not allow negative numbers or at least give an error. Test negative numbers before you implement scripts with negative numbers.

To determine which desktop is currently active, use the 'get_desktop' command. The command has no parameters or options and returns the number of the current desktop or workspace. The value is assuming the first desktop is numbered 0, so a one needs to be added to the result.

Now that we have been able to manuever around the desktops, what if we need to move a window around the various workspaces?

The command to use is 'set_desktop_for_window' and has the following syntax:

set_desktop_for_window [window_ID] desktop_number-1

The first item we need is the window ID. Once we have a window ID, we need the desktop number to which we will move the window minus 1. Suppose we have a window in workspace 3 with a window ID of 39845895 and we wish to move it to workspace 1. The command would be:

xdotool set_desktop_for_window 39845895 0

If we have a window, but do not know which desktop it is on, we can use the 'get_desktop_for_window' command. The syntax is:

get_desktop_for_window [window_ID]

For example, we have the same window as in the previous example with a window ID of 39845895. We could use the following command to find which workspace it was located, but we need to add one to it since the first workspace is numbered zero.

xdotool get_desktop_for_window 39845895

The two viewport commands are: 'get_desktop_viewport' and 'set_desktop_viewport'. The syntax for each is as follows:

get_desktop_viewport [options]
set_desktop__viewport x y

The command 'get_desktop_viewport' has only one option:

  • --shell – shows the output in a column viewport
The output of the command is the X and Y coordinates of the top left pixel of the current viewport. Let's look at an example where a monitor has a resolution of 1366X768. The viewports are arranged in two rows and four columns. The width of the whole desktop is 5464X1536, but remember that the size of each viewport is 1366X768. If the current viewport were the second in row one, the output would be X=2732 Y=0.

If you wanted to move from one viewport to the second in the first row, you would need the following command:

xdotool set_desktop_viewport 2732 0

The second viewport in row two would require the following command:

xdotool set_desktop_viewport 2732 768

NOTE: On systems with multiple monitors that act as extensions of each other, used as a single viewport would require the addition of all the monitor resolutions to find the size of one viewport.


  • slide.jpg
    50.5 KB · Views: 148,148