Search this site

Page 1 of 2  [next]





xdotool 2.20100623.2949 released

The latest release of xdotool includes a few bug fixes, minor improvements, and one major feature addition. All of the tests pass in the test suite (156 tests, 1892 assertions, 126 seconds).

The major feature is the new command chaining. That is, you can use multiple commands from the same xdotool invocation. Any window querying (search, getactivewindow, getwindowfocus) will save the result for use with future commands on the same invocation. For a simple example, we can resize the current window by doing this:

% xdotool getactivewindow windowsize 600 400
You can also activate the first Firefox window found:
% xdotool search --class firefox windowactivate
Or move all gimp windows to a specific desktop and then activate (switch to) gimp:
% xdotool search --class gimp set_desktop_for_window %@ 2 windowactivate %@

# the "%@" means all windows found in the search. The default when you do not
# specify a window is always "%1" aka the first window found by the search.
This idea for this feature came primarily from detailed suggestions by Henning Bekel. Huge thanks for dumping ideas my way :)

In addition, libxdo is now documented with Doxygen and is available here. Remember, if you have a feature request, it can't hurt to ask (or send patches!). If I have time/energy to work on it, I'll do what I can.

Download: xdotool-2.20100623.2949.tar.gz

As usual, if you find problems or have feature requests, please file bugs or send an email to the list. Changelist from previously-announced release:

  - Added 'window stack' and 'command chaining' support. Basically lets you
    include multiple commands on a single xdotool invocation and saves the last
    window result from search, getactivewindow, and getwindowfocus. For example,
    the default window selector is "%1" meaning the first window. 'xdotool
    search --class xterm windowsize 500 500' will resize the first xterm found.
    All commands that take window arguments (as flags or otherwise) now default to
    "%1" if unspecified. See xdotool(1) manpage sections 'COMMAND CHAINING'
    and 'WINDOW STACK' for more details. This feature was suggested (with great
    detail) by Henning Bekel.
  - To simplify command chaining, all options now terminate at the first
    non-option argument. See getopt(3) near 'POSIXLY_CORRECT' for details.
  - Add --sync support to windowsize.
  - Update docs and output to indicate that 'search --title' is deprecated (but
    still functions). Use --name instead.
  - Fix mousemove --screen problem due to bug in XTEST. Reported by
    Philipp Specht,
  - Fix segfault when invoking xdotool with an invalid command.
    Reported by: Bruce Jerrick, Sven Lankes, Daniel Kahn Gillmor, and Thomas
  - Fix bug --clearmodifiers bug caused by an uninitialized value being
    interpreted as the 'modmask' causing us to try to clear invalid modifiers.
    Reported by Hong-Leong Ong on the mailing list.
  - Lots of internal refactoring and documentation improvements.
  - Testing additions for several commands in addition to command chaining.
  - Documented libxdo through xdo.h. Docs can be generated by 'make docs'
    from the xdotool release.
  - libxdo: xdo_window_translate_with_sizehint
  - libxdo: xdo_window_wait_for_size

Headless wrapper for ephemeral X servers

For various projects I'm doing right now, I need an easy way to automatically run code in an X server that may not necessarily be the active display. This code may even run on servers in production that don't have video cards or monitors attached.

For some history on this, check out this post on xvfb and firefox. You can solve the problem in that post by simply launching firefox with the tool below, and your X server will exit when firefox exits.

To solve my need for automated headless Xserver shenanigans, I wrote a script that will wrap execution with a temporary X server of your choosing. For xdotool tests I generally use Xephyr and Xvfb.

What's so special about this script? It picks an unused display number reliably and runs your command with that set as DISPLAY. This is a major win because you don't have to pre-allocate X servers (headless or otherwise) before you start your programs. will pick the first unused display, just as binding a socket to port 0 will pick an unused port. Finally, when your process exits, the xserver and windowmanagers are killed. Example usage:

% ./ firefox
Trying :0

Fatal server error:
Server is already active for display 0
        If this server is no longer running, remove /tmp/.X0-lock
        and start again.

Trying :1
Xvfb looks healthy. Moving on.
Using display: :1
Running: firefox
It does health checks to make sure the X server is actually up and running before continuing.

You can also specify a window manager to run:

% ./ -w openbox-session firefox
Trying :1
Xvfb looks healthy. Moving on.
Using display: :1
Starting window manager: openbox-session
Waiting for window manager 'openbox-session' to be healthy.
... startup messages from openbox ...
openbox-session looks healthy. Moving on.
Running: firefox
The default X server is Xvfb. You can use Xvnc, Xephyr, or any X server. Here we run Xephyr with some options:
% sh -x "Xephyr -ac -screen 1280x720x24" -w openbox-session firefox
Xephyr looks healthy. Moving on.
Using display: :1
Starting window manager: openbox-session
Waiting for window manager 'openbox-session' to be healthy.
openbox-session looks healthy. Moving on.
Running: firefox
Screenshot of what this looks like is here: xephyr-ephemeral-x-example.png

I use this script to run my xdotool tests. Additionally, parallelizing test execution can often lead to faster tests. Wrapping each test run with ensure that each test suite runs in a clean environment, untainted by any previous test, allowing me to run all test suites in parallel. Prior to writing this script, I would run each test suite in serial on the same X server instance.

I use a similar technique at work to start ephemeral X servers for running WebDriver tests in hadoop. Each mapper starts its own X server, safely, and kills it when it is completed. This is implemented in java, instead of shell, since the mappers all launch from java and mapreduce launch differently than a standard command would in your shell.

Code lives here:
xdotool tests: xdotool/t

XSendEvent + LD_PRELOAD == win

As far as feature requests come, for xdotool, one of the more common ones is to have the ability to send key or mouse events to a specific window, not just the active one. XTEST (what xdotool uses for key/mouse currently) doesn't let you specify a window to send events. XSendEvent(3) lets you send hand-crafted events to a specific window, but most applications ignore these sent events.

The XEvent struct has a member 'send_event' which is true if the event came from an XSendEvent call and false otherwise. Programs like firefox and xterm (by default) ignore many events that have 'send_event' set to true.


Writing a custom shared library that overrides the default XNextEvent and XPeekEvent functions allows us to force 'send_event' to always be false, so an application with this library loaded will happily handle keyboard/mouse events generated with XSendEvent. I already have a helpful project that lets me write such a shared library: liboverride.

#include <stdio.h>
#include <X11/Xlib.h>

void hack_send_event(XEvent *ev) {
  switch (ev->type) {
    case KeyPress: case KeyRelease: case ButtonPress: case ButtonRelease:
      ev->xany.send_event = False;

override(`XNextEvent', `
    real_func(display, event_return);
This small bit of liboverride code will give me a shared library I can preload with LD_PRELOAD. Doing so will ensure that send_event is false for any key or mouse button events.

Works well. Now that we have a reliable way to allow XSendEvent I think it's worth putting this into xdotool.

keynav with xinerama support

This is the same post I made to the keynav-users mailing list

I just finished working on the xinerama portion of multi-screen support for keynav.

If someone is interested, I could use some help testing. It's working for me, and there are a few odd behaviors that I'm not sure are the best. Let me know if you test it.

No new official release yet, but if you want to test, svn can be fetched with:
svn checkout

- Include support for multiple screens.
  * When 'start' happens, the region will be the size of the current display
    (wherever the mouse is)
  * Moving the region outside of the current display will move it to the next
    display (right or left). This currently only works with Xinerama.
  * History works as expected (move to the right display, history-back goes to
    the previous display, etc)
  * When multiple Screen (non-xinerama) are found, XGrabKey on all root windows.
  * Screens are sorted, if possible, from left-to-right based on x-coordinate
    origin. This unfortuntely means, for now, only left-to-right monitor
    configurations are known to be supported.

keynav in Xinerama

I've got a dual-head setup now that has unequal resolutions. Keynav kind of sucks when this situation occurs, so I'm adding multiple-screen and Xinerama support to keynav. I'll update here when it's done.

xdotool desktop features

I spent a while tonight reading up on extended window manager hints. It's not a very well thought-through standard, but many window managers implement it nonetheless.

Tonight I added 7 new commands to xdotool (not yet in a release):

  • get and set the number of desktops
  • get and set the currently active desktop
  • get and set the desktop for a specific window (set == move it to a new desktop)
  • activate a window
The first 3 should be pretty straight forward. For fun, I told Gnome2 to create 50 workspaces, and it didn't barf. The taskbar pager looked a little funny as it was sprawling with little desktop views, but it works :)

The last is window activation. It will jump you to the window and give it focus. If the window is on a different desktop, it jumps to that desktop and then activates the window. I've tested exactly that behavior (firefox lives on a separate desktop or workspace) in Gnome2 and ion-3, and it works.

Example: Jump to firefox:

./xdotool windowactivate $(./xdotool search -title "Mozilla Firefox")
Example: Trying to do bad things in Gnome2
% ./xdotool set_num_desktops 5000
% ./xdotool get_num_desktops
Example: Move firefox to another desktop
# Find firefox's X Window ID
% MOZWIN=$(./xdotool search --title "Mozilla Firefox")

# Find the desktop containing firefox.
% ./xdotool get_desktop_for_window $MOZWIN

# How many desktops do we have?
% ./xdotool get_num_desktops

# Move firefox to desktop 3 (index starts at 0)
% ./xdotool set_desktop_for_window $MOZWIN 3

# Show me that firefox has moved to desktop 3
% ./xdotool get_desktop_for_window $MOZWIN

# Show me the current desktop
% ./xdotool get_desktop

# Activate firefox's window (taking us to Firefox's desktop)
% ./xdotool windowactivate $MOZWIN

# Show that we're now on the same desktop as firefox
% ./xdotool get_desktop
I'll put out a new release after I have a chance to tidy up the code a bit.

Do we need another window manager?

I've been doing various Xlib projects off and on for a few years, but none of them have been window manager projects because I was using a WM that pleased me: Ion. Many years later, after following ion from ion 1, 2, and now 3, the author decided to apply some user unfriendly licensing terms to newer releases of ion-3. This license change combined with the author's efforts to require distributions to comply with this license has resulted in most platforms dropping the ion-3 package from its distribution because nobody wants to deal with assholes.

I'm not going to get into a discussion about my opinions about the license. Just know that it inconveniences me, and if you know me, you know that I tend to solve problems of inconvenience with new software tools. That means I need a new window manager.

I've tested other window managers, but none fit me as well as ion did.

A few weeks ago I started on a window manager project tentatively called tsawm which implements features I like in ion but without the angry-author problems ion has. I started working on it initially in C, since that's where I use xlib, but C has some drawbacks. A nontrivial percentage of what I perceive to be window manager behavior is basically managing some heirarchy of data (frames, client windows, titles, some state). I started looking at Perl's X11::Protocol and Python's xlib module. Python's xlib module is pretty neat, in that it's a pure-python implementation of the X11 protocol.

Somewhat arbitrarily, I started prototyping to see if writing a window manager in python was possible. Yes, it is. So that's where I'm at today.

I've mostly been hacking things together while learning more about window managing in X, but what I have so far is promising: screenshot.

It's not pretty, but finishing this will help me get past the drama and problems that ion and its author bring. Sorry tuomov, I still love ion, but any licenses that keep me (directly or indirectly) from getting shit done aren't acceptable.

xdotool project page posted

I've gotten enough positive feedback about xdotool to convince me to put up a real project page for it. You can view it here at /projects/xdotool

xdo updates: window operations and searching

Today's efforts are summarized best by:
% ./xdotool search "Mozilla Firefox"
% xwininfo -id 31457484 | egrep 'Width|Height' | paste - -
  Width: 1278     Height: 1008
% ./xdotool windowsize `./xdotool search "Mozilla Firefox"` 500 500
% xwininfo -id 31457484 | egrep 'Width|Height' | paste - -
  Width: 500      Height: 500
This new 'search' command will walk the list of windows in X and basically output any windows with a matching title, name, or class. In this case, I have 1 "browser" window open under firefox that has "Mozilla Firefox" in the title. So I then resize it to 500x500, trivially.

Longer summary of today is that I added 4 new functions to xdotool:

  • windowsize <windowid> <width> <height>
  • windowfocus <windowid>
  • windowmove <windowid> <x> <y>
  • search <regexp>
Thanks to valgrind, I also fixed the crashes in Linux. Was due to an off-by-one bug. Sweet tool: valgrind.

Turns out XTEST works as I'd expect, and this example will do what you think, and switch to the 2nd console (assuming you're running one).

% ./xdotool key "ctrl+alt+F2"

Goal: Focus the first window found that is a local xterm (ie; not ssh'd anywhere). My xterms have title with 'host(pwd) - activity' in them. So if my local host is 'snack' I can do:

# Look for xterms starting with 'snack(' and focus the first one
./xdotool search '^snack\(' | head -1 | xargs ./xdotool windowfocus
And magically one of the xterms running a shell locally is focused. I can see this being pretty useful.

Today's code: navmacro-20070622.tar.gz.

xdo "beta" release

I've been working furiously on xdo the past few days. Good times :)

The result so far is as follows:

  • xdo is now a library, so you can simply call xdo_click(...) and it will handle all the hard stuff for you for the case that you want to use this in your own code.
  • xdotool is the commandline interface to the xdo api.
  • navmacro (bad name) is a very small gtk launcher. Basically it's an input box that runs the contents when you hit enter
I include a sample script 'ffsp' which is short for 'firefox searchbar paste'. It works on my system, but obviously on other systems you'll need to tweak it. The basics are there.

So right now, I can do this:

  1. Select a piece of text in an xterm
  2. Activate navmacro and type 'ffsp' and hit enter
  3. Enjoy the fact that firefox has been told to search for the contents of my clipboard
'ffsp' is located in my $HOME/bin/ so I execute it like any other shell script or program.

Interested in the code? Download navmacro-20070620.tar.gz.

Note: navmacro works on my ubuntu and freebsd systems just fine. However, xdotool crashes at the end when I do free(xdo->charcodes) only on my Ubuntu system. Uncertain why, I'm way too tired to debug.