Discussion: Dark mode for applications

[sylveon]

Discussion: Dark mode for applications

Currently, reliably detecting dark mode in Win32 applications requires either reading the registry or using undocumented methods from uxtheme.dll.

I strongly suggest to document those two existing methods:

• ShouldAppsUseDarkMode:
  • This allows apps to detect whether the dark theme is used for apps.
  • Particularly useful to follow system settings, like Microsoft Edge and UWP-based apps do.
  • Changes to this can be detected by listening for WM_SETTINGCHANGE.
• ShouldSystemUseDarkMode:
  • This allows apps to detect whether the taskbar, start menu and other system shell elements uses the dark theme or not.
  • Particularly useful for determining if a white or black notification area icon should be used. OneDrive already does this.
  • Changes to this can be detected by listening for WM_SETTINGCHANGE.

This will allow existing apps to easily implement dark theme support, and to follow system settings without relying on workarounds. A WinRT API should probably be exposed (the two settings and an event to listen for changes) as well, but some applications are already tentatively using those two APIs, so it would be the best case to document the Win32 APIs, as those won't have to do any significant work to adopt an official solution rather than an undocumented one (and, truth be told, they are much simpler to use than their WinRT counterparts, especially if your language doesn't have a WinRT projection available)

Also, there exists other APIs in uxtheme.dll which might be of interest for people transitioning to WinUI and/or XAML islands:

• SetPreferredAppMode:
  • This allows apps to enable dark theme support for Win32 controls. This is notably used by Windows Explorer for its dark theme.
• AllowDarkModeForWindow:
  • Once the app mode is set to AllowDark using the API above, it is a per-window opt-in.
  • Once this method is called, the Win32 controls in the window uses dark theme if the system dark theme is enabled, and automatically switches to light theme when the user changes their settings.
  • Note that some controls might need to have their theme manually set to DarkMode_Explorer for this to be effective
  • Dark mode ribbon can be opt-in with the window property UI_PKEY_DarkModeRibbon

Those methods are useful because when transitioning, it allows developers to use a dark theme for old controls and new controls alike, to get a somewhat consistent UI. Darkening Win32 or winforms controls manually is extremely hard to get right, and leveraging the work done in Windows Explorer would prevent a lot of misdirected attempts at dark theming Win32 controls.

EVEN MORE, there's an undocumented window attribute allowing dark mode title bars (DWMWA_USE_IMMERSIVE_DARK_MODE). This one was even used by the command prompt itself and openly on GitHub, before it got removed from the OSS version because it was internal (see microsoft/terminal@bc7eb96#diff-e26a93b2aa9fea92ebf24336c4fe6412L19-L22). No true dark mode comes without a dark titlebar, and customizing the titlebar is a complex endeavour that would be greatly simplified by the publication of this attribute.

All of the APIs mentioned have been added since the introduction of dark mode Explorer, and have proven to be stable or only very slightly modified, so I'm sad they are being kept private because it would allow so many apps to get a dark mode (light mode makes me cry 😢)

[jonwis]

Thanks! Project Reunion APIs will be defined in metadata like WinRT objects are so they can be projected to all languages and all runtimes.

Can you mock up what an API for this would look like? Maybe something like:

enum WindowThemePreferenceColorMode {
    None = 0,
    Dark,
    Light
}
runtimeclass WindowThemePreference {
    static WindowThemePreferenceColorMode SystemColorMode { get; };
    static WindowThemePreferenceColorMode AppColorMode { get; };
    static event EventHandler<Object> PreferenceChanged;

    static void SetAppPreferredColorMode(WindowThemePreferenceColorMode mode);
    static void SetWindowPreferredColorMode(WindowId window, WindowThemePreferenceColorMode mode);
    static void SetWindowTitleBarPreferredColorMode(WindowId window, WindowThemePreferenceColorMode mode);
}

[mdtauk]

Ideally it would remain a RequestedTheme = Light/Dark value in the App.xaml or Window Xaml element. The Window Frame and TitleBar reflecting that setting, or if it is not set, the System setting.

[sylveon]

My suggestion is for non-XAML code, so RequestedTheme is not a thing. Currently, this code has no reliable way to detect the theme, and I would very much like to be able to follow user preferences for non-XAML parts of my app that is using XAML Islands (eg. tray icon and its context menu).

I can't adopt WinUI's UWP app model "clone" intended for desktop apps either without a significant rewrite. C++/WinRT is already causing compilation time and error headaches even when only a small part of my code is using it, so I would actually rather not adopt it at all (not to mention that IDL is a complete PITA).

If a WinRT API for this only supports WinUI desktop app scenarios, it would be useless to me, and I'll just use the undocumented functions I listed above.

I would suggest documenting the OS APIs that I listed (and already exist as well as being usable in uxtheme.dll today, they are just not documented and exported by ordinal only) in some Windows SDK update, because it would reach a wider audience (all Win32 devs) than exposing this through only a WinRT API would (only early adopters of Project Reunion, and people whose language of choice includes a WinRT projection)

For example, a Delphi-based Win32 app (you know those still exist) or a C++ app using an older version of the C++ compiler (like VS2013) could use ShouldAppsUseDarkMode trivially but it will be much harder to use a WinRT API for either of those apps.

This might not be in the scope of Project Reunion itself, but it's where I was told to file feedback about it.

[sylveon]

If this isn't the place to request raw Win32 APIs, feel free to redirect me to the right place (except if that place is the Feedback Hub, my confidence in it has been reduced to 0)

[jonwis]

Project Reunion is about making APIs available to all apps - no matter which language, UX framework, runtime, or packaging system you use. WinUI-specific APIs would go in the WinUI repo.

We're still planning out which language projections to add - issue #18 has a proposed projection of an IDL based type for "flat C." Can you add comments / bumps to it so we can get a sense of which projections are important? See also issues tagged with "projection" for others folks have asked for.

Some Project Reunion APIs will also be "flat C to start" (ie: direct exports from the DLL with an associated header & import library) and then also get a metadata wrapper for languages & runtimes whose FFI is cumbersome.

Can you also file an issue in the cppwinrt repo for compilation times? (@kennykerr)

[sylveon]

Of course, I'm not opposed to providing a WinRT projection as well, I just believe that stabilizing the Win32 APIs would be best, as there are already existing users of those in the wild, and providing a guarantee the API won't break or be removed from under their feet would be best. It's also much simpler for those who can't use existing projections to use those.

Documenting and then wrapping those APIs in a WinRT class would also take less time than reimplementing them in WinRT.

[sylveon]

As for the compilation times, it's more of an inherent issue with C++ compilers, should be somewhat fixed when modules support is enabled in C++/WinRT.

[jonwis]

Aha! Check out the UISettings type from your Win32 apps, like this (C++/WinRT) example:

winrt::Windows::UI::ViewManagement::UISettings settings;
auto fg = settings.GetColorValue(winrt::Windows::UI::ViewManagement::UIColorType::Foreground);
auto bg = settings.GetColorValue(winrt::Windows::UI::ViewManagement::UIColorType::Background);

Apps can listen to changes to this setting on the UISettings.ColorValuesChanged event. There's also the (missing a verb) UIElementColor method, which you can for specific colors of UX components.

While you can't ask "are you dark/light/custom mode", you can definitely get the set of colors used by Windows to theme its own UX elements, which would let your apps be consistent.

[sylveon]

That certainly can work if you do your own custom drawing, but it doesn't cover cases where your UI kit has a simple dark/light toggle, where you have to guesstimate if bg is dark or light, neither does it cover the case where your app uses common controls or context menus with no custom drawing.

For example, XAML islands supports dark/light theming according to user preferences, but it doesn't update the theme when the user changes it in settings, so when my app receives WM_SETTINGCHANGE, I manually call the undocumented ShouldAppsUseDarkMode function and update the RequestedTheme on the XAML content appropriately:

https://github.com/TranslucentTB/TranslucentTB/blob/d8fa18512b11405bdacf93d463fb4b500de69b62/TranslucentTB/uwp/xamlpagehost.hpp#L59-L70

Also, if your app has a tray icon, you may want to know if the system uses a light or dark theme (not the apps), to choose the appropriate tray icon color (a white tray icon for the dark theme, and a black tray icon for the light theme)