Back to Blog home

What's new with the Wayland platform plugin in Qt 5.12?

Published on Friday December 14, 2018 by Johan Helsing in Dev Loop Qt Linux Wayland Qt 5.12 | Comments

Wayland is a display server protocol used on modern Linux systems, the Qt Wayland platform plugin lets Qt applications run on Wayland display servers (compositors).

Continuing the trend from the Qt 5.11 release, the Qt 5.12 release contains a substantial amount of improvements.

Window decorations

Old window decorations Old window decorations

We've received quite a few complaints about the looks of our window decorations over the last few years. The message is usually: "They are ugly and don't look native."

On Wayland, window decorations are supposed to be drawn by the client by default. Consequently, Qt's window decorations will probably never look identical to what other toolkits draw. I.e. there is no "native" look with client-side decorations. That is, however, no excuse for them to be ugly.

In 5.12, I've updated our default decoration plugin so it looks like something from this decade. It still won't be "native" looking, but it looks closer much closer to what the other toolkits draw.

New window decorations New window decorations

The default window background color is now used for the decorations, so it should follow your Qt theme quite nicely.

Window with dark theme Decorations follow the theme of the window.

Furthermore, we've now also added support for support for the Wayland extension, xdg-decoration unstable v1. Compositors implementing this extension can now tell Qt clients that decorations will be drawn server-side instead of client-side. I.e. the decorations for Qt applications and other toolkits can be identical after all. This is also good news for people running tiling compositors. It's no longer needed to set the environment variable QT_WAYLAND_DISABLE_WINDOWDECORATION on compositors that implement this extension. Toggling window decorations at runtime is now also possible.

server-side window dsecorations The server-side-decoration QtWayland Compositor example. The bar at the top with the close button is drawn and handled by the compositor.

xdg-shell stable

On Wayland, the shell extension is the part of the protocol that gives meaning to surfaces, i.e. it communicates things like: This surface is a popup-menu, this is a toplevel window, this is its window title and application id, this is how it should be maximized, resized minimized etc.

In other words, a pretty important part of the protocol. The problem is that, while Wayland has been stable for many years, there has been no stable shell extension for the desktop. wl-shell is considered deprecated, and development has continued with the unstable xdg-shell. Unstable protocols have backwards incompatible changes in every release, this means that when a new version is released, it's essentially a new, although similar, protocol. If we were to simply update our code to the protocol described in the new version, Qt clients would stop working on compositors not supporting the new version.

We've solved this by using a plugin architecture for loading a shell integration at runtime depending on what the compositor supports. In other words, each time a new breaking version of xdg-shell is released, we create a new plugin for it. The exciting news this time, is that xdg-shell finally turned stable in December last year, and with it broke backwards compatibility for the last time.

Consequently, Qt 5.12 adds the last and final shell plugin for xdg-shell. This means we can finally deprecate the old unstable xdg-shell plugins and concentrate on making the one stable plugin great.

High DPI cursors

Giant cursor

Support for high DPI cursors has been added. Cursors are now also loaded lazily to significantly reduce the memory footprint on embedded devices that don't really need them.

Handling maximization and fullscreen on xdg-shell

Implementing fullscreen and maximization properly on xdg-shell required a huge refactor in how resizing works in Qt Wayland. That refactor is now in place, and Qt applications on all supported versions of xdg-shell should now properly switch between fullscreen, maximized and windowed mode.

Forcing a logical DPI of 96

window with tiny fonts Sometimes compositors report 1px=1mm (a DPI of 25.4) when they don't have better data available, causing physical DPI to be unreliable.

Quite a few things in Qt depend on the logical DPI, most notably point sized fonts. Previously, we've calculated the logical DPI using the physical size and resolution of the screen. This works great in most cases, but sometimes the physical dimensions that compositors provide are wrong, which usually results in tiny unreadable fonts. So in Qt 5.12, we switched to forcing a DPI of 96 by default. The old behaviour can still be restored by setting QT_WAYLAND_FORCE_DPI=physical in the environment.

Fractional scaling

Support for xdg-output unstable v1 was added. It's a protocol extension for communicating additional information about screens and is needed to implement fractional window scaling on the compositor side. Read the details in David Edmundsons blog post.

Subscribe to Our Blog

Stay up to date with the latest marketing, sales and service tips and news.

The blog comment system has been migrated to a new platform. If you face any issues, please let us know via feedback@qt.io.