Theme resources support

[maxkatz6]

UPD: done with #8166

Description

This proposal is about introducing a new API to handle application/system color schemes and defining resources specific to them. It's firstly focused on developers of custom themes.

Theme resources documentation from UWP, to be in context:
https://docs.microsoft.com/en-us/windows/apps/design/style/xaml-theme-resources

Goals:

• Provide ability to handle color-schemes in easier way. Currently we have to use separated StyleInclude per each color-scheme.
• New markup extension which won't listen for whole visual tree resource changes, and trigger updates only when actual color scheme was changed. So, work faster than DynamicResource.
• Make ApplicationTheme first-class citizen in Avalonia Application class, so developers can rely on it, instead of guessing on which fluent/default/any-other theme mode is used.
• Integrate with system color scheme. Not in 11.0, but in 11.x.

Would be nice:

• Have ability to define new application color-scheme on application or third-party controls library level
• Changing of color-scheme per control, like it is possible in UWP. Not a goal, unless we will find a way to implement it without too much of overhead.

Planned APIs:

public class ApplicationTheme
{
        public ApplicationTheme(object key);
        public object Key { get; }

        public static ApplicationTheme Light { get; } = new(nameof(Light));
        public static ApplicationTheme Dark { get; } = new(nameof(Dark));
}

public class Application
{
        public static readonly DirectProperty<Application, ApplicationTheme> RequestedThemeProperty;
        public ApplicationTheme RequestedTheme { get; set; }

        public event Action<ApplicationTheme>? ThemeChanged;
}

public class ResourceDictionary
{
        public IDictionary<ApplicationTheme, IResourceProvider> ThemeDictionaries { get; }

        public bool TryGetThemeResource(ApplicationTheme theme, object key, out object? value);
}

public class ThemeResourceExtension : IBinding
{
        public object? ResourceKey { get; set; }

        public IBinding ProvideValue(IServiceProvider serviceProvider);
}

This API is currently available in themeresource branch (only Default theme is updated to use new markup extension).

Example of usage

Define resources:

<Application>
  <Application.Resources>
    <ResourceDictionary>
      <ResourceDictionary.ThemeDictionaries>
        <ResourceDictionary x:Key="Light">

          <Color x:Key="MyBaseLowColor">#33000000</Color>

        </ResourceDictionary>
        <ResourceDictionary x:Key="Dark">

          <Color x:Key="MyBaseLowColor">#33FFFFFF</Color>

        </ResourceDictionary>
      </ResourceDictionary.ThemeDictionaries>
    </ResourceDictionary>
  </Application.Resources>
</Application>

<Border Background="{ThemeResource MyBaseLowColor}" />

Here border background will be updated only when Application.RequestedTheme is changed, but not when ResourceDictionary content is modified (here is the difference from DynamicResource extension).

Questions

1. Naming is confusing. In UWP they use "theme" term for dark, light and high contrast modes. Same naming was used in this API so far. But in Avalonia we historically used "theme" term for groups of styles - Fluent and Default themes. And "Mode" term for dark or light sets of resources. Color palette? Color scheme? Color theme? Should we avoid UWP naming here then or accept it anyway?
2. As an alternative we can implement only ThemeDictionaries, which will solve bigger problem of defining resources depended on color-scheme. But let developers to use DynamicResource to access them. Possibly, it will help us avoid confusion between similar markup extension. But won't improve existing performance of color-scheme, which is acceptable now, but still slow on slower devices like mobile and wasm.
3. If we support system color themes, there can be a conflict with custom ApplicationTheme defined by user. Application can ignore unsupported system color scheme, but can ignore it in opposite way? When user selects "Pink" color scheme in app, we would like to notify system about this, so system dialogs and frame can be also updated. But how to map "Pink" or any other random key to the system one? Should there be an enum of supported system schemes, which to map ApplicationTheme to? Flag enum to be more flexible?

[amwx]

What's the reason for using ApplicationTheme class over just making ThemeDictionaries be IDictionary<object, object> or even IDictionary<string, object>. UWP makes this an enum which lacks extensibility, but making this a dedicated class and all the lookup methods requiring ApplicationTheme makes it less ideal for third party libraries as they'd have to subclass ApplicationTheme just to add their own.

 
Is it necessary to make RequestedTheme an AvaloniaProperty? I would think just having the event would be fine.

 
 

Have ability to define new application color-scheme on application or third-party controls library level

Isn't this already possible with this proposal, just with extra work as I said above? Or am I misunderstanding what you mean here?

 
 

1. Naming is confusing. In UWP they use "theme" term for dark, light and high contrast modes. Same naming was used in this API so far. But in Avalonia we historically used "theme" term for groups of styles - Fluent and Default themes. And "Mode" term for dark or light sets of resources. Color palette? Color scheme? Color theme? Should we avoid UWP naming here then or accept it anyway?

I'm conflicted here. I personally like RequestedTheme over something like Mode or RequestedMode, but on the other hand, we do call it 'Dark Mode' or 'Light Mode'. "Color Palette" and "Color Scheme" feel too technical, "Color Theme" would be ok but having the word "theme" in there kind of circles back around to the same issue.

2. As an alternative we can implement only ThemeDictionaries, which will solve bigger problem of defining resources depended on color-scheme. But let developers to use DynamicResource to access them. Possibly, it will help us avoid confusion between similar markup extension. But won't improve existing performance of color-scheme, which is acceptable now, but still slow on slower devices like mobile and wasm.

This ones also tricky, overall the loss of DynamicResource probably isn't too bad and the perf benefit probably does outweigh the downsides. However...
1- I imagine there are many people who have settings pages in their apps that allow real time changes of things that would disagree, as they'd need to force app restart or pop the dictionary and reapply it with a change.
2- There's also the issue of system resources changing - like the user accent color - as that would need to update the related 'SystemAccentColor' and variant resource colors and their linked brushes without forcing a full refresh. Even if getting system resources isn't part of the immediate plan (IMO it should be for this reason), this is something that needs to be considered now rather than later to prevent bigger issues. If we could find a way to bridge the gap between ThemeResource and DynamicResource that would be ideal.

[maxkatz6]

less ideal for third party libraries as they'd have to subclass ApplicationTheme just to add their own

Is it? Third party library can define their static instance as

public static ApplicationTheme Pink => new ApplicationTheme("Pink");

and used as x:Key="Pink" (so it will be parsed using TypeConverter) or {x:Static CustomThemes.Pink} directly.
See full definition of ApplicationTheme class. Light/Dark modes are not special here, only have predefined values build-in.

making ThemeDictionaries be IDictionary<object, object> or even IDictionary<string, object>

Yes, it can be done this way. I just preferred more typed approach with TypeConverter magic on top of it. Since it's still possible to use custom keys with it.

Is it necessary to make RequestedTheme an AvaloniaProperty? I would think just having the event would be fine.

How to change it in runtime then without a property? Developers want to have ability to change theme on the flight.
Actually, event is less necessary here, since it's a AvaloniaProperty with notifications build in.

Isn't this already possible with this proposal, just with extra work as I said above? Or am I misunderstanding what you mean here?

It's possible, if you will create multiple style files per each color-scheme. Like we had BaseDark.xaml and BaseLight.xaml for our build-in themes. User will need to detach old file and attach new file to switch them. We solved it by adding "Mode" property on the theme, which made it easier. But still hard to get current application theme (like, really, it's not the best API). And if you want to support multiple color schemes in your library of controls, you still need to have multiple style files to be included or do the same trick with Mode property.

[amwx]

1- Ahh ok, I misread the API. Still needing to create the static reference seems unnecessary. But I understand why a typed approach is probably better. This was more a question rather than an objection

How to change it in runtime then without a property? Developers want to have ability to change theme on the flight.
Actually, event is less necessary here, since it's a AvaloniaProperty with notifications build in.

Sorry, I meant just a CLR property and a corresponding event for change notifications. The only advantage I see of keeping it as a DirectProperty is someone could bind straight to the property, but I would think binding straight into Application isn't the best xaml practice - but I'm also not one that should be criticising best practices...

It's possible, if you will create multiple style files per each color-scheme. Like we had BaseDark.xaml and BaseLight.xaml for our build-in themes. User will need to detach old file and attach new file to switch them. We solved it by adding "Mode" property on the theme, which made it easier. But still hard to get current application theme (like, really, it's not the best API). And if you want to support multiple color schemes in your library of controls, you still need to have multiple style files to be included or do the same trick with Mode property.

I'm still confused here. Based on the API presented here, third parties can just do a ResourceInclude into the App level resource theme dictionaries which should resolve the custom theme and the current way of swapping files isn't needed anymore. Unless you mean "theme" in terms of Fluent vs. Default vs. third party instead of just light/dark/etc.? If so, I don't think this is easily solvable since every theme can have different resource names, which can't be standardized. At which point, now were getting into Control themes, which is a separate issue.

[maxkatz6]

Added yet another question, CC @amwx

3. If we support system color themes, there can be a conflict with custom ApplicationTheme defined by user. Application can ignore unsupported system color scheme, but can ignore it in opposite way? When user selects "Pink" color scheme in app, we would like to notify system about this, so system dialogs and frame can be also updated. But how to map "Pink" or any other random key to the system one? Should there be an enum of supported system schemes, which to map ApplicationTheme to? Flag enum to be more flexible?

[maxkatz6]

Note, it's not about "SystemAccentColor" colors as you mentioned. In my opinion these colors aren't really related to the application theme mechanism. Unless I miss something. Though with this naming of "color scheme" it's even more confusing.

It's specifically about notifying system, that we want darker or lighter window frame, or any other part of the system that should be updated with the rest of the app. Like system dialogs opened from the app (it is configurable at least on iOS).

[amwx]

For this case, I think this is where having ApplicationTheme class actually has value as we could have a property like SystemTheme or OSTheme or BasedOn that is mapped to light/dark/high contrast system theme. If this isn't specified, then defaulting to the default system theme I think would be fine.

On Windows, you can force light vs. dark mode after Win 10 1809 for a specific window and query the system (either via WinRT or undocumented apis) as I already do:
https://github.com/amwx/FluentAvalonia/blob/1cb8b27f669fa8e08a370023458fb7588aec0f7b/FluentAvalonia/Interop/Win32Interop.cs#L63

But this is all undocumented APIs, and I'm not sure how much help the WinRT interop stuff would be to alleviate that. They did add some new features to the Win 11/22000 SDK stuff for customizing window styles/colors via DwmSetWindowAttribute though, but would be Win 11 only.

Note, it's not about "SystemAccentColor" colors as you mentioned. In my opinion these colors aren't really related to the application theme mechanism. Unless I miss something. Though with this naming of "color scheme" it's even more confusing.

I just used SystemAccentColor as an example, but that's just referring to the user's system accent - which is just as important as whether the OS is in light/dark mode. My point here was, this is an example of a resource that needs to be able to change without changing theme, and thus the lack of "DynamicResource" would fail.
I don't think you can change the App Window's accent color (at least not without those new Win 11 APIs, and assuming showing accent color on borders/titlebars is enabled) so that's just a one-way respecting/handling if a change comes in from the system which can easily be ignored in custom themes if desired.

Yea, in having this discussion, the terminology is getting confusing, really fast 😂

[workgroupengineering]

Personally, I don't really feel the need to create specific classes for managing themes.

In the app test I used the Style Selector like this:

namespace AA2
{
    public class Theme
    {
        public readonly static AttachedProperty<string> NameProperty =
            AvaloniaProperty.RegisterAttached<Theme, AvaloniaObject, string>("Name", inherits: true);

        public static string GetName(AvaloniaObject avaloniaObject) =>
            avaloniaObject.GetValue(NameProperty);

        public static void SetName(AvaloniaObject avaloniaObject, string value) =>
            avaloniaObject.SetValue(NameProperty, value);
    }
}

namespace AA2.ViewModels
{
    public class MainWindowViewModel : ViewModelBase
    {
        private string selectedTheme = "Green";

        public string Greeting => "Welcome to Avalonia!";

        public string[] Themes => new[] { "Green", "Red" };

        public string SelectedTheme { get => selectedTheme; set => this.RaiseAndSetIfChanged(ref selectedTheme, value); }
    }
}

<Window xmlns="https://github.com/avaloniaui"
        xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
        xmlns:vm="using:AA2.ViewModels"
        xmlns:d="http://schemas.microsoft.com/expression/blend/2008"
        xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006"
        xmlns:l="using:AA2"
        mc:Ignorable="d" d:DesignWidth="800" d:DesignHeight="450"
        x:Class="AA2.Views.MainWindow"
        Icon="/Assets/avalonia-logo.ico"
        Title="AA2"
        l:Theme.Name="{Binding SelectedTheme}"
        >
  <Window.Styles>
    <Style Selector="Window[(l|Theme.Name)=Green]">
      <Setter Property="Background" Value="Green"/>
    </Style>
    <Style Selector="Window[(l|Theme.Name)=Red]">
      <Setter Property="Background" Value="Red"/>
    </Style>

    <Style Selector="Rectangle[(l|Theme.Name)=Green]">
      <Setter Property="Fill" Value="Red"/>
    </Style>
    <Style Selector="Rectangle[(l|Theme.Name)=Red]">
      <Setter Property="Fill" Value="Green"/>
    </Style>
    
  </Window.Styles>

  <StackPanel>
    <TextBlock Text="{Binding Greeting}"
               HorizontalAlignment="Center"
               VerticalAlignment="Center"/>
    <ComboBox Items="{Binding Themes}"
              SelectedItem="{Binding SelectedTheme}"/>
    <Rectangle Stroke="Black" Width="50" Height="50"/>
  </StackPanel>


</Window>

The only thing I miss compared to WPF and BasedOn.