We have been working on and using custom Qt theming in Fedora Workstation for many years now. By custom Qt theming, I’m talking about the QGnomePlatform and Adwaita-qt projects. If you haven’t heard of them, you can read my recent blog post explaining what they are. While these projects are in some ways better than what Qt upstream has to offer, there were also drawbacks/issues and that’s why I decided to make a final decision and discontinue both projects. The issues are explained in the aforementioned blog post, but one of the main drawbacks is that we are in this development alone and not working directly in the upstream makes it less attractive for other contributors. It’s also not used by default anywhere other than Fedora, so it’s not properly tested by other developers working on Qt applications using different distributions. These reasons led me to submit a Fedora 39 feature to remove our custom Qt theming in Fedora Workstation in favor of Qt’s defaults. The only problem is that if we just go with Qt’s default, we would go backwards a bit. This is because upstream Qt does not provide any decent client-side window decorations (problem #1), and the QGtkTheme in Qt5 (QGnomePlatform equivalent) is a bit behind its Qt6 version with many improvements and integration goodies (problem #2) recently made by Axel Spoerl of the Qt Group, whom I met during this year’s KDE Akademy.
Solution to problem #1
QGnomePlatform used to be our solution to this problem, as QGnomePlatform implemented it’s own version of the QWaylandAbstractDecoration plugin. This was a GTK 3-like decoration plugin that used Adwaita-qt for button rendering and QGnomePlatform bits (e.g. GSettings configuration) to get the titlebar layout. Since we are going to remove QGnomePlatform, we needed an alternative. So I started working on the QAdwaitaDecorations project. This is supposed to be a an intermediate step as I would like to have a proper GNOME/Gtk decorations directly in Qt upstream, but since I was in a hurry to get everything done in time for Fedora 39, we have this for now. QAdwaitaDecorations plugin is based on the decorations we have in QGnomePlatform, but there is no dependency on GTK or Glib (e.g. GSettings) or on Adwaita-qt. We use xdg-desktop-portal to get the titlebar layout and do our own drawing instead. This decoration plugin should also have now a GTK 4-like style so the buttons and colors of the decorations are different.
Below is a screenshot of Wireshark (Qt6) using QAdwaitaDecorations plugin + QGtkTheme + Fusion:
Solution to problem #2
Since Qt5 is no longer actively developed, the only possible solution is to backport all QGtkTheme improvements from Qt6, so I did that + modified some of those changes to avoid breaking binary compatibility. This results in about ~15 related backports to Qt5 so far, and it seems to work pretty well. I also made sure that Fedora 38 and older will still use QGnomePlatform by default, so we don’t change the behavior for existing users. Also, a small change to our QtWayland package was needed to make it use the new decoration plugin by default.
Future plans
As mentioned, I would really like to have everything directly in Qt upstream (talking about QAdwaitaDecorations). That way we get other contributions and thus fixes/improvements for free and a lot more users. Another thing is that QGnomePlatform supports things that are not yet supported/implemented in QGtkTheme, like support for xdg-desktop-portal instead of just relying on GSettings. Not to mention that GTK 4 has been around for a while, and both QGnomePlatform and QGtkTheme are still GTK 3 based. I will definitely try to make some of these things happen for Fedora 40, but knowing myself, it’s better not to make any promises, as things usually don’t go according to plan.
I decided to write this post to explain everything I can about these two projects. There have been discussions and people demanding these projects should not be used by default in Fedora. As part of this, some issues were raised and it might not be clear which component might be responsible for what. I ended up constantly defending these projects in many discussions and ended up being exhausted by doing so over and over, so take this as an explainer to shed some light.
Brief introduction to QGnomePlatform and Adwaita-qt
To give you some context before I go into details, you can think about Adwaita-qt as the UI representation and QGnomePlatform as the integration between GNOME and Qt. QGnomePlatform applies your GNOME configuration and behavior to Qt apps, together with some integration bits, like dialogs or client-side decorations. Adwaita-qt is responsible for the style of the app itself, including the style of all visible parts (widgets/buttons).
QGnomePlatform
What is QGnomePlatform?
QGnomePlatform is a Qt Platform Theme (part of Qt Platform Abstraction API), where such a plugin is responsible for the app integration into the desktop environment. It is designed to provide integration between Qt apps and the GNOME platform. To explain in an example. Without any platform integration, Qt apps running on GNOME would use default styling and configuration so your fonts, icon theme, dialogs would not fit into the desktop. Also in the case of QGnomePlatform you would not have GNOME-like client-side decorations.
What QGnomePlatform provides?
QGnomePlatform provides the following integration for Qt apps running in GNOME:
Font configuration *
Icon theme *
Cursor size and cursor theme *
Static hints (like double-click time, long-press time etc.) *
Dialogs:
File dialog (both using GTK3 * and native dialog using xdg-desktop-portal)
Font dialog using GTK3 *
Color dialog using GTK3 *
Client-side decorations
Support for Settings portal from xdg-desktop-portal settings
Unlike the built-in GTK3 theme that can get everything only from GSettings
Brings support for light/dark theme switching introduced in GNOME 42
Use Adwaita-qt theme by default (elephant in the room) and Adwaita color palette
Also provides support for additional themes, like Kvantum
Support for Cinnamon desktop
* these can also be provided by built-in GTK3 platform theme in Qt itself (just for comparison what QGnomePlatform does extra)
Issues QGnomePlatform gets wrongly blamed for
Client-side decorations
As stated above, QGnomePlatform provides an implementation of CSD. It’s actually the only Qt CSD implementation I’m aware of, excluding the reference implementation provided by QtWayland, named Bradient. Below is a screenshot comparing QGnomePlatform (left) and Bradient (right).
I saw many times people complaining about missing shadows support and resizing issues. The truth is that officially there was no proper shadows support in the Qt API until I introduced it with Qt 6.2. That’s the reason we don’t have it for Qt5, unless you are a Fedora user, where this support has been backported and enabled in QGnomePlatform build. I also fixed all kinds of CSD related issues in QtWayland.ven though Qt has proper support for shadows in Qt6 now, the reference implementation doesn’t use them.
Misplaced popups/menus
This has nothing to do with Qt platform theme or CSD implementation, because it was actually a bug in QtWayland. Unfortunately this fix is only in Qt 6 and cannot be backported officially to Qt 5 as it would break KDE Plasma. I managed to at least patch QtWayland in Fedora and Flatpak KDE runtime, where I modified this patch to not affect KDE Plasma at all.
What can QGnomePlatform be blamed for?
Forcing Adwaita-qt color palette
QGnomePlatform sets Adwaita-qt color palette to each Qt app so applications can use QPalette API to get access to colors used in the style itself. This can be for example useful when an app creates custom widgets that would not get styled by the QStyle itself. This creates a problem for KDE applications using the KColorScheme API.
Examples of this issue:
The reason is that KColorScheme and QPalette are out of sync and there might be color roles that are in KColorScheme, but not in QPalette. If an app requests a color from KColorScheme that’s not in QPalette, KColorScheme will default to Breeze style and a color that’s not going to fit the Adwaita-qt style will be provided, causing the app to mix light and dark colors.
I think this is the most visible and user-facing issue we currently have and get blamed for so I would like to fix this as soon as possible.
Adwaita-qt
Adwaita-qt is a Qt style for widgets. Qt style is again part of Qt Platform Abstraction. You can think of it as a theme for your application. It’s what changes the visualization of your widgets like buttons, checkboxes etc. and it’s the only thing that changes the appearance of the application itself. For comparison, the screenshot below is Adwaita-qt (light) and the second one is the Qt’s default Fusion style used on Linux used without any QGnomePlatform influence so basically what you would get by default.
I can also add that Adwaita-qt supports HighContrast variants, which are useful for visually impaired people.
What issues can Adwaita-qt be blamed for?
I already mentioned the color mismatch issue which is not really Adwaita-qt’s fault. There are of course issues in Adwaita-qt itself and it’s far from being perfect. The whole style needs a complete overhaul, because the last one was done in 2019 and the Adwaita theme changed a lot recently with GTK4. Another issue is that while the majority of common widgets are styled just fine, there are still some widgets that are rarely used and might have issues with this style.
Another issue is that apps that customize standard widgets (e.g. through CSS), might get into trouble. Below is a screenshot of Wireshark (pure Qt app) compared to Breeze in KDE.
Another example can be seen in the Black Chocobo app, which uses some customization:
Below is Black Chocobo using Fusion style.
Should QGnomePlatform get removed/replaced?
Definitely not. It has many benefits and extras compared to Qt’s default platform and most importantly gives you CSD support. Once I fix the color mismatch issue, there shouldn’t be anything users should complain about. Obviously, this would not be an issue when Breeze is used instead of Adwaita-qt, but still an issue when Fusion is used so it would still need to be addressed. You can see a screenshot below showing Fusion style used in combination with GNOME set to dark theme:
Should Adwaita-qt get removed/replaced?
Maybe. It depends on the alternatives. Obviously using Breeze would get rid of all the widget issues one might experience with Adwaita-qt, however, it is problematic to ship it by default due to bringing dependencies on KDE Frameworks and Plasma breeze style. With the default Fusion style you will also get many widget issues fixed, but you still need to set the color palette through QGnomePlatform in case you want Fusion to be “dark” and fit into the desktop, otherwise you will always end up using the default “light” variant no matter what configuration you set in GNOME.
Conclusion
I hope that this post is useful for those observing issues with Qt apps under GNOME, and will help them to understand which component is responsible for what, as well as the issues involved. In case you are interested and would like to either contribute a patch or report an issue, here are links to QGnomePlatform and Adwaita-qt repositories.
In the past we used to have a completely different project to cover HighContrast variants of GTK Adwaita theme. This was all implemented as Highcontrast-qt, a project nobody has touched for 6 years. You can imagine how it looks like these days when you compare it to what we have now. I think even GTK variant of HighContrast was a completely separate theme back then, while today days it’s just Adwaita with a different set of colors.
Since GTK made the new HighContrast theme with just few modifications to the original Adwaita theme, I decided to use same approach and have Adwaita-qt to provide all four variants as well (Adwaita, Adwaita-dark, HighContrast and HighContrastInverse). While this looks like a simple thing to do, as you just need to add additional color palette, it was a pain to do it in Adwaita-qt. The reason is that Adwaita-qt is full of hardcoded color definitions, where all of them were randomly taken from GTK Adwaita stylesheets. Everytime something changed in GTK Adwaita, we would have to manually pick the change and replace the changed color value on our side. This was not really sustainable, especially when I wanted to have four different variants.
To improve this situation and make my life easier, I decided to bundle GTK stylesheets for Adwaita theme, have it processed and write a simple parser to make everything automated. And I did exactly that. I included the stylesheets and wrote some definitions myself so I can let them processed with sassc (GTK uses SASS for theming) and have all my definitions substituted for simple parsing. I no longer have to pick all base colors manually, all of them are being parsed for all four variants and same goes for basic styling of Buttons, CheckBoxes and Radio Buttons, where each of them have all kind of possible states (active, hovered, checked etc.) and use not only a simple color, but also gradients. You can imagine how hard it was to hardcode all values for each state. The parser I wrote is really basic and simple with use of regular expressions as the code I’m trying to process is not that complex.
The code I try to process is either a simple definition:
I think this is a big step forward for Adwaita-qt and it will allow me to more quicky respond on changes happening in GTK Adwaita/HighContrast theme. I can also imagine this being extended in the future to support some additional variants, like modified Adwaita theme you can find in Ubuntu (at least if the stylesheet is similar enough). As mentioned, Adwaita-qt now supports four variants and they should be on par with GTK 4.4, at least when it comes to colors and style for most used widgets, because there are still places in Adwaita-qt which need some extra work. Anyway, this all is now released as Adwaita-qt 1.4.0 and I will be updating Flathub and Fedora builds to it soon.
For those who don’t know, Fedora Media Writer is a tool to create bootable live USB drive with your favorite flavor of Fedora. It is written in C++ with UI written in QML and it is supported on Linux, Windows and Mac OS X. It was developed by Martin Bříza, my former collegue from Red Hat, who did an amazing job in the past. Fedora Media Writer (FMW) primarily targets Fedora Workstation and therefore the UI looks like a GNOME app using Adwaita theme. Unfortunately the Adwaita theme changed over time and originally FMW was written using QtQuickControls 1 (deprecated these days) so it needed an UI overhaul.
I started working on FMW during the summer, slowly migrating it to QtQuickControls 2. The original UI had lots of custom QML widgets, basically standard widgets with Adwaita skin on it. I still wanted FMW to use Adwaita theme, because Qt doesn’t have any native QML components for Windows, Mac OSX or GNOME and writing those would require lots of work. Therefore I decided to write a new QQC2 based Adwaita theme which can be used on all platforms. To avoid duplicating half of the code we already have in Adwaita-qt (a QStyle to make QWidgets look like Adwaita), like information about widget sizes and colors, I reworked Adwaita-qt to provide a library so it can be used by projects like this and so they don’t need to update everytime Adwaita changes. It was more work than I anticipated because it needed quite a lot of changes to separate things into library and also to make it build and work on all platforms where I want to use FMW. Good news is that the work is now done and I made a pre-release of Adwaita-qt. The library for now provides information about widget sizes, color palette and colors used by all widgets, but I plan to extend this in future with addition of Adwaita-qt rendering part allowing the library to render basic widgets for you. That’s something I would like to use for example in QGnomePlatform (GNOME platform theme) to render buttons in window decorations. With a lot of information being already said about Adwaita-qt, the work on QQC2 Adwaita theme was an interesting experience and probably the most enjoyable one, because everytime you write a new component and port the app to use it, you see the result of your work and the app slowly migrating towards a more modern UI makes you happy with the result. I don’t know what more to say about the QQC2 Adwaita theme as it’s basically QML variant of widgets we have in Adwaita-qt, with difference that it should look exactly the same on all platforms thanks to using Adwaita-qt. In past with QQC1 all the colors were derived from system QPalette making it slightly different on all platforms. If you wonder why the QQC2 theme is not part of Adwaita-qt, where it will most likely end up, then it’s because it’s not complete yet and contains only components used in FMW itself. Anyway, I have finished the port to QQC2 this week with some late fixes and after I spent a week updating all build systems (Windows, Github CI, Mac OSX) to properly build and produce builds for you to test since I made a new pre-release yesterday \o/.
The work on this port is most likely not 100% finished as I expect some minor issues to appear here and there, but I tried to make this 1:1 copy of the previous version so don’t expect any major changes. I will be glad if you try it and let me know what you think. Thank you and especially big thanks goes to Martin Bříza for his help during the development and for the work he did on this project in the past.
Fedora Workstation is all about Gnome and it has been since the beginning, but that doesn’t mean we don’t care about Qt applications, the opposite is true. Many users use Qt applications, even on Gnome, mainly because many KDE/Qt applications don’t have adequate replacement written in Gtk or they are just used to them and don’t really have reason to switch to another one.
For Qt integration, there is some sort of Gnome support in Qt itself, which includes a platform theme reading Gnome configuration, like fonts and icons. This platform theme also provides native file dialogs, but don’t expect native look of Qt applications. There used to be a gtk2 style, which used gtk calls directly to render natively looking Qt widgets, but it was moved from qtbase to qt5-styleplugins, because it cannot be used today in combination with gtk3.
For reasons mentioned above, we have been working on a Qt style to make Qt applications look natively in Gnome. This style is named adwaita-qt and from the name you can guess that it makes Qt applications look like Gtk applications with Adwaita style. Adwaita-qt is actually not a new project, it’s been there for years and it was developed by Martin Bříza. Unfortunately, Martin left Red Hat long time ago and since then a new version of Gnome’s Adwaita was released, completely changing colors and made the Adwaita theme look more modern. Being the one who takes care of these things nowadays, I started slowly updating adwaita-qt to make it look like the current Gnome Adwaita theme and voilà, a new version was released after 3 months of intermittent work. You can see the results here:
Isn’t it beatiful? The theme is far from being perfect and there will definitely be still some minor issues, but writting a Qt style is far from being an easy task as the QStyle class is quite complex. If you find any issue, you can open a bug and I will try to fix it. You can also send me patches if you decide to fix something yourself (I will be happy for that). The repository is hosted on GitHub under FedoraQt/adwaita-qt.
And of course it was a lie, the screenshots above are the old version of adwaita-qt (for comparison), the new ones are actually here:
Following blog post from Patrick Griffis about new themes support in Flatpak, we started working on supporting this new feature too. Currently wherever you start a Qt application, it would always look like a KDE application or something would be missing, like icons so you would end up with bad experience and mixed feelings. This is going to change now as we now support Gnome in form of icons, widget style and Qt platform theme and with this, when you run a Qt application in Gnome, it will look definitely better and more natively than before. We packaged regular adwaita icons which are used by default in Gnome as extension of freedesktop runtime. For widget style we use adwaita-qt style, which is a Qt style attempting to look like Gtk’s adwaita and the most important part putting this all together is QGnomePlatform, a Qt platform theme which reads your Gnome configuration and applies it to running Qt applications. QGnomePlatform also enforces Qt apps to use adwaita icons and adwaita-qt style by default so that’s another reason why it is important. Both adwaita-qt and QGnomePlatform projects are by the way authored by Martin Bříza, a collegue of mine from Red Hat so if you meet him in person somewhere buy him a beer for that he cares about Qt integration in Gnome :). Now coming to a question how to install this and make it work. Basically all you need to do is install following extensions and you shold be done:
Your Qt apps running in flatpak should then automatically pick up all of these extensions without any further modification, same way it does automatically when you run it outside the sandbox. Simply done!. I’m also aware that there are more Gtk themes, like adwaita-dark or high-contrast, both are also available in form of Qt style and we will probably package them later, but at this point it is mostly proof of concept that this can be done and works nicely. You can follow our wiki page if you want more information about runtimes, repository with applications and so on and from me it’s all for now.
Btw. below you can see okular running in flatpak and using adwaita-qt style with adwaita icons.
