dogtail 1.0.0

dogtail 1.0

After more than five years of continuous experimentation and development, we are excited to finally release Dogtail 1.0—a Wayland-enabled version of Dogtail! How did we achieve this? It was made possible by the gnome-ponytail-daemon, originally crafted by Olivier Fourdan. This tool allows us to perform actions in a Wayland GNOME session in a similar way to how we have been doing so with X functions.

How does it work in brief?

The core functionality relies on the Screen Cast and Remote Desktop API, enabling us to “connect” to either a specific window or the entire screen to simulate user input actions like key presses, typing, and—most importantly—mouse actions on specific coordinates. Ponytail uses the window list from org.gnome.Shell.Introspect to identify windows. Dogtail then ensures the correct window is connected via the Remote Desktop API, allowing input actions to be accurately executed within it.

On the AT-SPI tree and accessibility’s “introspection” side, not much has changed—input has primarily been the challenge on Wayland. The main difference is that only “local” window coordinates are known for UI items. To address this, we always connect to the specific window we’re working with, and Ponytail’s connectWindow ensures these local coordinates are translated to global ones internally.

What does this mean for users?

Dogtail handles all of this logic seamlessly, so in practical use, the user doesn’t need to worry about coordinate types or window connections. In fact, the vast majority of our tests work identically in both X and Wayland sessions using the Dogtail API. When running on an X session, Dogtail will use the traditional X functions to handle input and operate as it always has.

A long journey to 1.0

We began working on the Wayland-enabled version over five years ago (originally available in the devel/wayland branch). It has taken all this time to ensure the solution is robust and reliable enough to warrant a 1.0 release. This version includes all the Wayland-related developments and other changes (like the GTK4 support tweaks mentioned below) and has been extensively tested. Importantly, it is backward compatible with the entire Dogtail API that has been available so far. This release includes all modules from the 0.9.x series, most notably the “procedural” module, which we plan to deprecate in favor of a completely “tree-based” approach in Dogtail 2.0.

That release will also involve significant cleanup, major code refactoring, and a transition from pyatspi to directly introspected atspi. It will also contain updated code examples and Dogtail’s unittests should pass with GitLab pipelines re-enabled.

For more details on these upcoming changes, see issue #29.

1.0+ Important: Handling GTK4 Application Windows in Dogtail

For GTK4 applications, disabling window shadows is essential to ensure accurate positioning by Dogtail. With shadows disabled, we encounter a consistent coordinate offset, which we’ve preconfigured as dogtail.config.gtk4Offset. In the case of working with fullscreen windows, the offset is 0, and we manage to detect that on-the-fly both in X11 and Wayland sessions. However, this process requires python-xlib, even for Wayland sessions, leveraging Xwayland to ascertain resolution information, as no more direct method we’ve found is currently available for Wayland.

When window shadows are active, the perceived offset can vary significantly, influenced by factors such as the specific application, window size, and scaling settings. To ensure consistent behavior across applications, disabling shadows is recommended.

Disabling Shadows in GTK4:

To disable window shadows, add the following CSS to your GTK4 configuration (~/.config/gtk-4.0/gtk.css):

window, .popover, .tooltip {
    box-shadow: none;
}