Share theming between labwc and external components

[johanmalm]

Originally posted by @lobre in #3049 (comment)

I’d like to propose a way to share theming from labwc to external components via a new Settings portal backend, tentatively called xdg-desktop-portal-labwc.

First, I understand that major desktop environments drive the full experience and ship large portal implementations, so everything feels consistent. If labwc is used as the compositor inside a DE such as Xfce, then launchers, dialogs, notifications, status bars, etc. will typically be provided by Xfce and should match Xfce’s look. In that scenario, there’s little point in pushing labwc’s internal styling outward; more likely, Xfce would drive labwc’s theming so it integrates well.

The problem I’m trying to solve is different: labwc used as a minimalist, standalone window manager. In that case, labwc effectively becomes “the desktop,” so its theming should drive the overall style of complementary components (dialogs, app runners, status bars, etc.). I’m very new to Wayland, but as I’ve been tinkering with labwc I discovered xdg-desktop-portal. I’m wondering whether a portal approach could be a clean way to expose labwc’s resolved appearance values to other processes—even sandboxed apps.

I know labwc’s homepage says:

Labwc only understands wayland-protocols & wlr-protocols, and it cannot be controlled with dbus, sway/i3/custom-IPC or other technology.

What I’m suggesting is an external piece, outside the compositor: a small xdg-desktop-portal-labwc program that knows how to read (parse) labwc configuration and theming and implements the Settings portal. It could even be a third-party project unrelated to labwc itself. The advantage of using the desktop portal is that even sandboxed apps can reach the Settings interface.

I’m aware that the standardized Settings keys are currently very small:

• org.freedesktop.appearance color-scheme
• org.freedesktop.appearance accent-color
• org.freedesktop.appearance contrast

The spec also says implementations may expose custom keys (though they’re non-standard and undocumented):

“Implementations can provide keys not listed below; they are entirely implementation details that are undocumented. If you are a toolkit and want to use this please open an issue.”

https://flatpak.github.io/xdg-desktop-portal/docs/doc-org.freedesktop.portal.Settings.html

I realized that GTK (the library) itself can use the portal to retrieve custom GNOME GSettings when running on GNOME. Conceptually, something like this happens:

• An app (via GTK) calls the portal:
• org.freedesktop.portal.Settings.Read("org.gnome.desktop.interface", "font-name")
• The portal forwards to the GTK/GNOME backend.
• The backend reads GSettings org.gnome.desktop.interface font-name.
• The value is returned to the app through the portal.

By analogy, a wrapper script (or any thin client) could query the portal to get labwc’s theming. For example:

gdbus call --session \
  --dest org.freedesktop.portal.Desktop \
  --object-path /org/freedesktop/portal/desktop \
  --method org.freedesktop.portal.Settings.ReadOne \
  "org.labwc.theme" "window-active-border-color"

Our backend (xdg-desktop-portal-labwc) would be registered for the Settings portal, understand the org.labwc.theme custom namespace (or also org.labwc.config), read and resolve the current labwc theme, and return the corresponding values over D-Bus. A launcher like wofi could then be wrapped by a small shell script that queries the portal, exports a few color/font variables, and launches wofi with the right flags.

I fully realize this might be overkill, and I’m very open to feedback—especially if this is a bad idea or goes against best practices for Wayland/portals. I’m just starting with Wayland and only recently discovered xdg-desktop-portal, so I know this is more complex than exposing a few environment variables. I’m proposing it to learn from maintainers and users who understand this space better. In particular, if the Settings portal is not appropriate for this kind of theming, I’d be grateful to hear if that gives you better ideas related to that space.

Originally posted by @lobre in #3049 (comment)

[lobre]

@johanmalm

Thanks for creating this separate discussion.

Originally posted by @Consolatis in #3049 (reply in thread)
It has the same issues as applications trying to parse the theme manually. To work correctly it needs the command line args and env vars of the labwc process (as that is what decides on the actual theme files parsed).

The first step in any correctly working variant is some kind of persistence option of labwc which keeps some file up to date. From that point on and using that file as source of truth, other frameworks could be built on top. The only other alternative I see to that is to put custom IPC or even dbus into labwc itself (which I am really not a fan of).

Thanks for clarifying — I see your point about why parsing the theme manually is not enough, since the effective theme depends on the exact command-line args and env vars that Labwc itself was started with. And I understand your suggestion that the “correct” first step would be for Labwc to persist this resolved state itself, so that other frameworks can consume it.

Still, just to finish my thinking on the portal side, I wondered about a slightly modified version of the idea:

• Labwc could export the effective theme at startup via an environment variable (say LABWC_THEME).
• A companion process could be launched from Labwc’s autostart script, inheriting that variable. This process would know how to parse themes, and it would also know which theme is actually active, thanks to the env var.
• Instead of being D-Bus activatable, this companion would run as a long-lived service. It would register as the org.freedesktop.impl.portal.Settings backend, so that when xdg-desktop-portal forwards Settings requests, they go straight to this process.
• Applications would then get consistent answers through the standard portal API, without Labwc itself ever needing to implement D-Bus.

The appeal here is that Labwc stays D-Bus-free, while minimalist setups could still provide a functioning Settings portal. The drawback, of course, is that this model goes against the usual “D-Bus activation” pattern for portal backends. I haven’t seen any real examples of long-lived portal backends, so this might be a dead end in practice.

So yes — I agree that the persistent file solution you suggested is the more realistic way forward (even if I don’t find it super appealing). But I wanted to at least put this “companion service” variant on the table, even if only as a thought experiment, before dropping the idea.

[lobre]

Right, it’s not just the selected theme. With themerc-override and --merge-config, you are saying that it can pull pieces from multiple themes, and Labwc’s internals weren’t written to be reused as a library for that resolution. This is understandable and would potentially need some rewrites. And I did not see the Reconfigure coming, but effectively, for a small long-running portal backend started by autostart with predefined environment variables, it makes it hard for this helper process to follow along when changes occur.

But without the persisted theme state file I don't really see how it can parse everything the same way labwc does and how to keep it up to date on Reconfigure.

So on Reconfigure, Labwc could re-emit the environment variables with updated values, and respawn the backend so it can reparse theme/prefs and reconcile. I don't know how hard this would be, and how practical it is for Labwc to respawn something on Reconfigure that was started from autostart. But that idea would keep using environment variables instead of a state file.

Labwc tends to push standardization when a piece is missing rather than adding custom IPC. I like that approach. The snag here is that if we try to fix this “the Wayland way” with a small protocol extension, adoption is likely weak because the app-facing norm for preferences seems to be the Settings portal (said lightly with my beginner standpoint), but that assumes a settings daemon, which Labwc doesn’t have.

For full DE sessions, they might solve it differently anyway: the DE owns settings in its daemon (gsettings/xfconf/…), and then drives Labwc (and triggers Reconfigure). That way, they can keep using the Settings portal as it is designed to be, with their settings daemon supporting that.

In the “Labwc alone” setup, there still isn’t an obvious channel for live updates to other long-lived processes.

A state file is effectively the other option. Labwc writes a small snapshot of current prefs/state, and tools read it. It would be dedicated to short-lived tools such as wofi, which relaunch each time, and which could read the state file when they do. It feels to me kind of like using the filesystem as a poor version of D-Bus. In the same vein, as we said in the other discussion, each theme/setting option (or a subset) could also be exposed as a set of environment variables.

And of course, those ideas do not work very well for long-lived processes such as status bars, as they would have to watch or poll for a state file, or respawn for detection of updated environment variables, which is hard without having a signal that something changed.

I was expecting to find a design that would be more robust and Wayland-friendly, but this is harder than I expected.

[Consolatis]

And of course, those ideas do not work very well for long-lived processes such as status bars, as they would have to watch or poll for a state file, or respawn for detection of updated environment variables, which is hard without having a signal that something changed.

I think this might work with inotify.

[lobre]

By reflecting on this whole story, I’m now wondering whether there are already ideas or experiences around how desktop environments are expected to integrate with Labwc. I touched on this in earlier messages, but I realize I don’t actually know if Labwc has been designed with easy integration in mind—especially when it comes to theming, but also in terms of playing well as part of a larger environment.

Up to now, I had assumed that desktop environments would take the lead on configuration and theming, driving Labwc’s settings and handling reconfiguration. But I’m not sure if that’s really the intended or likely approach.

If you shift the perspective a little, a desktop environment can be seen as an orchestrator of consistency: coordinating the compositor, dialogs, status bars, notifications, and so on, to respect a shared visual identity. In that sense, the compositor is just one piece among others, and the DE ensures that everything aligns with a common graphical charter.

With that in mind, in more minimal setups (without a full desktop environment), maybe it makes more sense to think about the orchestration of multiple components rather than trying to make Labwc itself the driver of theming and settings. Perhaps Labwc should stay simple and avoid overengineering, leaving the complexity to an orchestration layer that can tie it together with other graphical components. Just thoughts for now.

But I would be interested to know: Are there already desktop environments integrating Labwc? And if so, do you know how they approach configuration and global theming with Labwc?

[johanmalm]

I think there are fundamentally three approaches in terms of where the main theme can be held for others to follow:

1. Client toolkit (like Gtk, KDE or Kvantum)

Whilst these are hard to parse accurately for anything other than basic foreground/background colors, it may be the best option for a uniform looking desktop.

• https://github.com/labwc/labwc-gtktheme
• See half way through https://youtu.be/AU_M3n_FS-E

2. Compositor

Whilst it's relatively easy to patch a compositor to communicate its settings, it's likely to only be useful for quite a hacky setup using some shell script wrappers for clients like make, wmenu, etc. Gtk and Qt are unlikely to be influenced by these.

3. Independent

E.g. pywal

I think the whole use-case needs to be considered here. What are we actually trying to achieve? For example, would the aim be to set a theme in once place and for that to take affect on Qt/Gtk clients as well as the compositor and independent desktop components?

[lobre]

@johanmalm

I believe the story is more nuanced than it might seem. From my readings over the past few weeks, I would distinguish two layers in Linux graphical theming:

1. Preferences layer: Abstracted settings that allow the user to declare broad intentions—theme selection, accent color, icon set, fonts, and so on. This largely aligns with the settings standardized in the XDG Settings portal.

2. Implementation layer: The detailed definitions of how borders, buttons, or backgrounds should look. These vary depending on the graphical toolkit. But we can say it is the theme engine of each toolkit/UI application.

We can almost see the "preferences layer" as a really thin abstraction layer over the "implementation layer", which has all the details.

As you mentioned, major toolkits such as GTK and KDE rely on both layers to deliver a consistent desktop experience. When an application uses GTK, the client library reads global preferences (via gsettings and the settings daemon) to determine the current theme, dark/light mode, and related settings (preferences layer). It then parses the actual chosen theme, which specifies implementation details before drawing the UI (implementation layer).

With GTK4 and libadwaita, however, the implementation layer is essentially frozen: the theme is hard-coded. Still, the preferences layer remains relevant, as it controls elements like accent color.

KDE is similar in behavior to Gtk without libadwaita.

So things work smoothly when all applications share the same toolkit since the implementation layer is unified. But mixing toolkits complicates matters: you usually choose one toolkit as your “main” UX driver and then configure others to imitate it for consistency. This article describes two common strategies:

• Modify GTK and Qt styles separately with the tools listed below for each toolkit and aim for choosing similarly looking themes (style, colors, icons, cursors, fonts).

• Use a special theme engine, which intermediates the modification of the other graphical toolkit to match your main toolkit.

Moving beyond mainstream toolkits, minimalist window manager setups often involve applications with their own lightweight theming engines. This includes compositors like Labwc, as well as launchers, notification systems, and dialog utilities. The principle remains: one component can act as the UX driver, and others can attempt to follow its lead.

Instead of imitating a “main” driver (for example, Labwc trying to parse the current GTK theme), some setups introduce an orchestrator above the rest, serving as the style authority. It defines a common representation of the theme and generates configurations for all subcomponents. As you stated, tools such as Pywal use this approach.

Currently, for the preferences layer, Labwc has no integration with popular settings daemons such as gsettings—which can be a good thing—but it also doesn’t use the XDG Settings portal. This is more debatable, as syncing with user preferences (e.g., dark/light mode or accent color) could be valuable before applying its own theme.

However, for the implementation layer:

Labwc can act as a follower, driven by an external orchestrator (Pywal + reconfigure) or try to imitate another component (e.g., GTK with labwc-gtktheme which is done externally). Here, nothing to change inside Labwc.

Or it can be the driver, in which case it needs a way to expose its theming details so other components can align with it.

An ideal—though perhaps unrealistic—future would involve expanding the preferences layer to include richer theme attributes (secondary colors, border colors, padding, etc.). If every engine respected such an abstraction, we could achieve a consistent experience without toolkits having to imitate one another.

For now, however, Linux desktops lack a standard solution.