Skip to main content

Qt Wayland Tablet Improvents

A few weeks ago Qt 6.8 was released, delivering many fixes and improvements for our software. Some of them were contributed by yours truly, and in this post I want to highlight some of them.

They relate to graphics tablet/stylus input on Wayland. Before we go into the fixes let’s have a quick overview of the flow of tablet input events on Wayland:

The genesis of input events is in the kernel driver for the particular tablet, which talks to the hardware (via USB, bluetooth etc). The kernel passes events to userspace via the evdev system. On the userspace side a Wayland compositor reads those events. Most compositors leverage libinput for this, a library that transforms raw evdev events into something more usable for the compositor while applying some cleaning and configuration. The compositor then delivers events to native Wayland applications using the tablet-v2 protocol. For legacy XWayland applications the compositor uses this protocol to send events to XWayland, which translates them into things X11 apps understand. The compositor can apply useful transformations to the input, like which area of the screen the tablet is mapped to, changing the pressure curve of the pen, or binding buttons to keyboard shortcuts.

The application then processes the events, potentially leveraging a UI toolkit like Qt. Qt creates QTabletEvent object for incoming Wayland events and delivers those to all UI elements. In case no UI element reacts to the event Qt will synthesize a mouse event from the tablet event and deliver that to the UI elements. That way most controls like buttons and menus don’t need special code to handle tablet input. Only when doing very low-level input handling or when needing tablet-specific interactions (like reacting to different pressure values) application developers need to explicitly handle tablet events in their code. Most UI toolkits will work somewhat similar to this. If an application doesn’t react to tablet input at all please file a bug against the application.

Qt Wayland had support for tablet input for a few years now, so what exactly needed fixing? The first thing is cursors. In Wayland the application tells the compositor which cursor to use. This can be done either by specifying a surface (i.e. an image) or a named cursor shape. Guess which one Qt used? That’s right: Neither. It just didn’t specify a cursor at all. The result depends on the compositor: KWin would display a cross-hair cursor as a fallback, which is ~okay, but not the cursor the application developer asked for. On other compositors I’ve tested there will be no cursor visible at all, which isn’t okay at all. For Qt 6.8 I implemented the missing cursor support, so now tablets get the same cursor as mouse input (unless of course the application developer wants a different cursor for tablet input).

Another thing that affected mostly non-Plasma users is client-side decorated windows. On Plasma Qt applications usually use the server-side decoration provided by KWin, but e.g. on GNOME Qt is responsible for drawing and handling window decorations. For this Qt features a plugin system so different decorations with different look-and-feels can be swapped out. Unfortunately those decorations didn’t handle tablet input at all, so it wasn’t possible to move around or close windows using a tablet stylus. I fixed this by pretending the tablet input is mouse input to the decorations, which was a simple yet effective solution for the issue. If there is ever a need for decorations to treat tablet input different to mouse input we can revisit this.

Talking about moving windows, a feature most KDE apps have (even if off-by-default these days) is dragging any empty area to move the window. This wasn’t working when using a stylus. Why? For that we need to look at how this works on a Wayland level. The xdg-shell protocol (the one responsible for most application windows) has a move request that asks the compositor to start a move interaction for the window. As part of the request the application must pass a serial, which is a number that corresponds to the last input event the application has received. To avoid applications suddenly deciding to move in the background compositors usually only allow move requests as a result of direct user input, so this serial must match the last input event. Qt wraps this move request inside the QWindow::startSystemMove function. The problem was that Qt didn’t keep track of the serial it received as part of tablet input, so when starting the move it would pass a wrong serial and the compositor (rightfully) refused the move. A few extra lines later the serial was tracked properly and moving windows with a stylus worked, just in time for Nate to disable the feature by default.

The same problem also affected drag-and-drop. When starting a drag with a stylus Qt now passes the correct serial, making drag-and-drop work (at least on the Qt side, there currently is a bug on the KWin side that prevents this from working).

The last fix for today relates to how applications react to the tablet events. Sometimes applications process clicks differently depending on what keyboard modifiers are pressed. For example pressing Ctrl while clicking on files in Dolphin allows to select multiple files. For this to work Qt conveniently delivers the active modifiers with every input event. Alas for tablet input the modifiers got lost along the way, so it wasn’t possible to select multiple files using a stylus. One small fix later it works as expected.

That’s all the Wayland tablet related fixes for today. If you find more issues in Qt/KDE apps related to tablet input on Wayland please report them on bugs.kde.org and I’ll look into them.

That’s not all there is about Wayland tablet improvements though. Fully in the spirit of the “We care about your input!” Goal there are exiting things happening on the KWin/Plasma side that I’ve been involved in. Stay tuned for more!

In my position of Software Platform Engineer at KDE I work on common building blocks for KDE software, like Qt and KDE Frameworks. This work is possible thanks to your generous donations. Check out our end-of-the-year fundraiser if you’d like to see more work like this.

© Nicolas Fella, 2024 MastodonNicolas Fella
Powered by Hugo, theme Anubis.