Theme mode API

[dhardy]

The (minimal) documentation for WindowEvent::ThemeChanged does not clarify whether apps should query the theme on startup or simply wait for a ThemeChanged event.

From a quick look at the code, I think the only way to determine the theme at startup is via a platform-specific is_dark_mode function. This is problematic in three ways: (1) lack of documentation, (2) API is only partially cross-platform, (3) is_dark_mode has a completely different (and less flexible) API to ThemeChanged(theme).

Suggestion 1: always send ThemeChanged on start if the theme is not Theme::Light (or whatever the default theme is called), and document this.

Suggestion 2: add a Window::theme method.

Related: #1217

[JMS55]

I did some research on detecting light/dark mode on linux. Basically, you have to get the current theme, and see if it ends in -dark (just a convention, I'm sure some themes break it. There is no better way unfortunately).

• Gnome - gsettings get org.gnome.desktop.interface
• KDE - Something to do with kreadconfig I believe (Uses QT over gtk, I'm unsure if the breeze dark variant (default dark theme for KDE) theme name ends in -dark)
• Xfce - Something to do with xfconf-query I believe
• Cinnamon - Uses gsettings like gnome. I don't know the exact key.
• Pantheon - Unknown
• Mate - Uses gsettings like gnome. I don't know the exact key.

As you can see, it's kinda a mess. I would either:

1. Support only Gnome/KDE, assuming Gnome unless the kreadconfig program is present. This is kinda brittle, and if a winit app is isolated with Flatpak or something, probably going to fail.
2. Add a WINIT_THEME=dark/light environment variable, and leave it up to the user to set it with their own scripts.

[OvermindDL1]

I'm unsure how useful just detecting if using a 'dark theme' would be on KDE (and perhaps Gnome and related ones?). A theme can be anything, and there are ones that even do odd things like have a dark style system but really bright windows that are well used. The proper way would be to read the actual theme data and use or at least expose to the user the proper theme values for things like background color and text color and the 200+ other settings. As I recall Windows also had very detailed theme settings like that as well. Just having dark or light mode would not be sufficient to be able to make something that 'fits in'. Even just among, say, dark themes some use a dark slate gray like I do, some use a very dark blue like my wife, some use a very dark purple like a friend of mine, etc...

In addition KDE (and I'm pretty sure Gnome as well) can set per-application or even per-window themes (fantastic for, say, running things as root or distinguish window themes based on whether related for work or play or so).

And don't forget that theme changes can happen in real-time with KDE as well.

[JMS55]

Here's my proposal for how to determine light/dark (And I agree the event should always be sent on startup):

• Windows: Continue with whatever winit is already doing I assume, I haven't looked at it.

• macOS Mojave or later: Subscribe to when NSApplication.effectiveAppearance changes. Check if NSAppearance.Name contains dark as a case-insensitive substring.

• Linux: Either only send once on startup, or poll every X milliseconds in a background thread or something. Detect linux desktop by searching for case-insensitive substring in $XDG_CURRENT_DESKTOP. Probably doesn't work when sandboxed in a flatpak.

  • Gnome: Call gsettings get org.gnome.desktop.interface gtk-theme, and check if it contains dark as a case-insensitive substring.
  • KDE: Call kreadconfig5 --group General --key ColorScheme, and check if it contains dark as a case-insensitive substring.

• All other cases (older OS version, shelling out to a command failed, substring not found, etc): Default to light.

---

As you can see, for Linux there is no good option. At best, you can support a subset of desktop environments (too many to maintain support for realistically), and when not sandboxed.

[JMS55]

I've just found out about https://github.com/elementary/os/wiki/Dark-Style-Preference, which looks like it would be perfect. Desktops set prefers dark/light, and then apps get notified when it changes, and choose whether to render with a dark, light, or other theme.

Unfortunately, only elementary os supports it right now, as it's not an official spec.

[JMS55]

An update on this:

• Windows 10+: Check the registry key HKEY_CURRENT_USER\Software\Microsoft\Windows\CurrentVersion\Themes\Personalize\AppsUseLightTheme.
• macOS Mojave+: Check NSApplication.effectiveAppearance.Name for the substring dark.
• Linux (gnome 42+, elementary os 6+, eventually KDE): Check the dbus key org.freedesktop.appearance.color-scheme.
• Web: Check the media key prefers-color-scheme.
• Android/IOS: Didn't look into it.

---

Where the system API exists, winit should return Some(Dark/Light). Where the system API doesn't exist, or where Linux returns default, winit should return None.

Apps are free to follow the system preference or ignore it, it's only a preference.

[OvermindDL1]

Just for some information on the org.freedesktop.appearance.color-scheme bit, this is not a pre-existing standard thing, rather it was developed by I think gnome first and is looked favorably upon by KDE and others that it looks like they will support it "fairly soon(tm)", so just because you may not see it in your DBUS viewer right now doesn't mean it won't exist in (short) time. Though optimally it would be nice to get a color scheme from things like KDE that support it rather than 'just' light/dark if possible, but that's a good fallback regardless.

[akhilman]

Can we have the API to force a dark/light mode from application itself? Or even better a way to provide own colours for decoration.

[JMS55]

Can we have the API to force a dark/light mode from application itself? Or even better a way to provide own colours for decoration.

I assume you're talking about macOS/Windows decorations. Linux (wayland) has no standard decorations - you have to draw them yourself, so you could make them anything you want. Someone with more knowledge of the relevant platform API's would have to comment on whether it's possible or not.

[Be-ing]

There is a dark-light crate which does only this. Linux support is in progress using the new XDG Desktop Portal dbus API with fallbacks to checking if the theme name has "dark" in it.

I propose considering removing ThemeChanged from winit's public API. This is not trivial to implement cross platform and seems to me to be tangential to the purpose of winit. Dark versus light mode is a system setting, not a per-window setting, even if Windows exposes it in its windowing event loop.

[madsmtm]

A problem with the dark-light crate is that it requires checking continually whether the theme has changed.

[Be-ing]

There is an open issue for providing a callback to notify of changes to light/dark mode in dark-light.

[edfloreshz]

I'll get on that as soon as I'm done with this 👍🏼

[dvc94ch]

interesting that winit considered this feature in scope. the flutter engine also provides access to other related options that winit may want to expose in the future too (although I've not looked into how it's implemented for each platform):

• always use 24 hour format
• text scale factor

which together with platform brightness gets grouped into a UserSettings struct and various settings grouped into an AccessibilityFeatures struct:

• accessible navigation
• invert colors
• disable animations
• bold text
• reduce motion
• high contrast

also related is a LocaleChanged event.

[bluz71]

Can we have the API to force a dark/light mode from application itself? Or even better a way to provide own colours for decoration.

Yes, will this issue provide the ability to force light or dark modes for applications that use winit?

I created this Alacritty issue asking to set light or dark at the application level rather than just using the global desktop preference. In my case I use a light desktop but I much prefer a dark theme just for the terminal. The Alacritty maintainer (@chrisduerr) referred to this upstream issue since it appears Alacritty can't set light or dark on macOS or Windows by itself.

Hopefully this issue will look at getting (aka detecting theme type) and setting (per application light/dark mode configuration).

Best regards.

[Doomsdayrs]

The proper way to check for dark / light is via an XDG portal call.

https://flatpak.github.io/xdg-desktop-portal/

Read ( "org.freedesktop.apperance", "color-scheme", INTEGER )

Then there is a signal for SettingsChanged and you can sync with that.

Doc

org.freedesktop.appearance color-scheme u

Indicates the system's preferred color scheme. Supported values are:

0: No preference
1: Prefer dark appearance
2: Prefer light appearance

Unknown values should be treated as 0 (no preference).

[d2weber]

In Linux, with freedesktop portal supported, the color theme preference as well as changes can be detected using zbus.
A similar implementation can be found in ashpd.

[kchibisov]

Using side channels like dbus is out of scope as of now.

[BlackHoleFox]

Can you elaborate how its a side channel? FreeDesktop portals are the DE-independent standard for this type of GUI interaction/requests.

[kchibisov]

dbus is a side channel, it's coming from neither Wayland nor X11 directly. You can use it in your code just fine without any help from winit.

[edfloreshz]

A problem with the dark-light crate is that it requires checking continually whether the theme has changed.

Just FYI, there's an open PR that implements a way to provide a closure to handle changes in the color scheme.