SettingsControls: SettingsCard + SettingsExpander

[michael-hawker]

Settings Expander

Problem Statement

The new settings experience in Windows 11 was met with a lot of approval and has quickly been picked up as a common practice in many applications. However, there is no standard control or design template to achieve its behavior, this makes different app's implementations and behaviors inconsistent which is bad for users. It also is more work for developers to redo this effort.

It'd be great to provide a common control that can be used for these scenarios.

Inspiration

Many community developers have worked on their own implementations of this control/pattern.

Proposed Solution

It'd be great to have a wrapper around the built-in Expander control as a base, and provide a succinct syntax to providing this custom experience, something like (looking at Clock app as example patterns):

Simple Toggle Button

<controls:SettingsExpander Icon="{StaticResource ToDoIcon}" Title="To Do" Description="Show tile in the focus session experience">
    <ToggleSwitch IsOn="{x:Bind ViewModel.HasToDo, Mode=TwoWay}"/>
</controls:SettingsExpander>

Single Radio Buttons

Collapsed:

Expanded:

<controls:SettingsExpander Icon="{StaticResource PaletteIcon}" Title="App theme" Description="Select which app theme to display">
    <TextBlock Text="{x:Bind SelectedAppThemeText}"/> <!-- Or could be the ToggleSwitch, etc... -->
    <!-- Optional set of items to provide the drop-down without it, it won't expand -->
    <controls:SettingsExpander.Items>
        <controls:SettingsExpanderItem> <!-- Would also support Header in which case content is encapsulated and right-aligned, see next example -->
           <muxc:RadioButtons>
               <x:String>Light</x:String>
               <x:String>Dark</x:String>
               <x:String>Use system setting</x:String>
           </muxc:RadioButtons>
        </controls:SettingsExpanderItem>
    </controls:SettingsExpander.Items>
</controls:SettingsExpander>

Multiple Dropdown Options

Collapsed:

Expanded:

<controls:SettingsExpander Icon="{StaticResource FocusIcon}" Title="Focus periods" Description="Adjust the length of your focus time, or breaks to fit your needs.">
    <controls:SettingsExpander.Items> <!-- spacing of multiple items with style and corners automatic -->
        <controls:SettingsExpanderItem Header="Focus period">
             <ComboBox .../>
        </controls:SettingsExpanderItem>
        <controls:SettingsExpanderItem Header="Break period">
             <ComboBox .../>
        </controls:SettingsExpanderItem>
    </controls:SettingsExpander.Items>
</controls:SettingsExpander>

Adaptive layout

There should be logic to support smaller screen sizes:

Open Questions

API Reference Docs

• Expander

References

• https://github.com/Richasy/ExpanderEx
• https://github.com/microsoft/PowerToys/tree/main/src/settings-ui/Settings.UI/Controls/Setting
• https://github.com/ghost1372/SettingsUI

[niels9001]

Nice @michael-hawker!

Here are some thoughts on what things it should support:

Main card properties

Property name	Type	Comments
Header	string
Description	object	This would allow us to also support things like HyperLinkButtons (which is common across Settings)
Icon	IconElement	By default it should use ThemeSymbolFontFamily, but this would allow developers to also set images as icons
Content	object	This can be anything, empty by default. Allows users to also add multiple controls (with e.g. a horizontal StackPanel)
Items	SettingsExpanderItem

SettingsExpanderItem
This should be fully customizable - it could host a list of CheckBoxes, but also entirely custom UIs / panels. And a mix of those things :)

Visual style
Currently, there are many different implementations of this control across various inbox apps with all slightly different styles (e.g. margins, sizes, colors). I'd suggest that the implementation in the W11 Settings app is our northstar - I can check in with the Design team to get the correct brushes and margins.

Accesibility

Narrator should annouce this as Header + Content control. For example: "Windows display language - English (United States".
Additionally, the Description can be set as a HelpText (or by default?) and the Expanded state should be called out.

================

SettingsButton
W11 Settings also provides buttons to e.g. navigate to a subpage. I'm guessing this should be a separate control right? (If any.. since it's basically a Button with a specific layout - but would be nice to have). Would love to know your thoughts on that.

[michael-hawker]

Thanks @niels9001!

For the SettingsButton scenario, I could see it just using this control as well still, with an Alignment property to help:

<controls:SettingsExpander Icon="{StaticResource MonitorIcon}" Title="Display" Description="Monitors, brightness, night light, display profle">
    <Button HorizontalAlignment="Right" Command="{x:Bind OpenOtherPageCommand}" Content="&gt;"/>
</controls:SettingsExpander>

Since they should be able to take any content, it should be straight-forward. Though I guess in this case the hit box is just over the button. Where as in the Settings experience, the whole card itself is the button, eh? 🤔

It's frustrating that there's no way to cancel Expanding of an Expander... microsoft/microsoft-ui-xaml#4407 - as then we could intercept that and use it as a button in this case.

I suppose in either case, we'll probably need a StyleSelector to begin with, which could have three modes:

• If it has Items it's an Expander as a base
• If it has IsClickEnabled (or some other name) makes it a Button
• Otherwise it's just a static 'card', as there'll be some other content/control inside like a ToggleSwitch or ComboBox.

Then it'd just be:

<controls:SettingsExpander Icon="{StaticResource MonitorIcon}" Title="Display" Description="Monitors, brightness, night light, display profle"
                           IsClickEnabled="True" Click="SomeEventOrHookWithBehavior"/>

Though if we add Click not sure if we want to directly add Command as well or leverage behaviors for that. Not sure how common this scenario will be over just putting direct Items or other controls inside?

[niels9001]

For the SettingsButton scenario, I could see it just using this control as well still, with an Alignment property to help:

Since they should be able to take any content, it should be straight-forward. Though I guess in this case the hit box is just over the button. Where as in the Settings experience, the whole card itself is the button, eh? 🤔

Yep, and additional hover states when you mouse over etc.

I suppose in either case, we'll probably need a StyleSelector to begin with, which could have three modes:

• If it has Items it's an Expander as a base
• If it has IsClickEnabled (or some other name) makes it a Button
• Otherwise it's just a static 'card', as there'll be some other content/control inside like a ToggleSwitch or ComboBox.

Yeah, that would be nice. If it would make things overly complex, I could imagine 2 separate controls (SettingsExpander and SettingsCard) could work (with the latter having the IsClickEnabled property that will adopt the Button style).

[michael-hawker]

I've gotten a bit crafty with selectors these days (see TokenizingTextBox where we do wonky things too)...

I don't think it'd be as crazy here and we could investigate what it'd look like. If it's a single control it makes it nice as you could use an ItemsControl and a DataTemplate to bind properties to a the SettingsExpander and potentially make it a bit more data driven. Though that starts to fall apart a bit if you want more complex options and choices for that data...

[michael-hawker]

Talked to team, sounds like we may want a SettingsCard for the flat and button scenarios, and then the SettingsExpander for the more complex scenarios.

Some more examples which I think would fit in that framework are here as well:

[niels9001]

After our recent discussion, here are some updated specifications.

It seems to make most sense to create 2 separate controls: SettingsCard and SettingsExpander.

SettingsCard

A single card that has properties to set the icon, header, description and content (e.g. a ToggleSwitch), right aligned. It provides developers a way to display a single setting.

<controls:SettingsCard Icon="&#xE08F;" Title="This is the header" Description="And this is the description">
    <ToggleSwitch IsOn="{x:Bind ViewModel.HasToDo, Mode=TwoWay}"/>
</controls:SettingsCard>

Property name	Type	Comments
Icon	IconElement	By default it should use ThemeSymbolFontFamily, but this would allow developers to also set images as icons.
Header	string
Description	object	Should be a TextBlock by default, but can also be customized by non-string objects (e.g. to display a HyperLinkButton)
Content	object	This can be anything, empty by default. Allows users to also add multiple controls (with e.g. a horizontal StackPanel)
IsItemClickEnabled	bool	If true, this control turns into a Button

---

SettingsExpander

A control that enherites from WinUI.Expander thas properties to set the icon, header, description and content. It provides developers a way to group multiple options into a single UI control.

Automatic layouting of controls:

<controls:SettingsExpander Icon="{StaticResource FocusIcon}" Title="This is the header" Description="And this is the description">
    <controls:SettingsExpander.Items> <!-- spacing of multiple items with style and corners automatic -->
        <controls:SettingsExpanderItem Header="This is a first option">
             <ComboBox .../>
        </controls:SettingsExpanderItem>
        <controls:SettingsExpanderItem Header="And a second option">
             <ComboBox .../>
        </controls:SettingsExpanderItem>
    <controls:SettingsExpanderItem Header="And a third option">
             <Button.../>
        </controls:SettingsExpanderItem>
    </controls:SettingsExpander.Items>
</controls:SettingsExpander>

Hosting a custom panel:

<controls:SettingsExpander Icon="{StaticResource FocusIcon}" Title="This is the header" Description="And this is the description">
    <controls:SettingsExpander.Items>
        <controls:SettingsExpanderItem Header="This is a first option">
             <StackPanel ...>
                  <TextBlock .../>
                   <Button .../>
                   <GridView .../>
              <StackPanel/>
        </controls:SettingsExpanderItem>
    </controls:SettingsExpander.Items>
</controls:SettingsExpander>

Property name	Type	Comments
Icon	IconElement	By default it should use ThemeSymbolFontFamily, but this would allow developers to also set images as icons.
Header	string
Description	object	Should be a TextBlock by default, but can also be customized by non-string objects (e.g. to display a HyperLinkButton)
Items	SettingsExpanderItem	This should be flexible as this could host custom layouts (e.g. a Grid) but also a single option (that would require automatic styling, based on the control type. A ComboBox would be right aligned, a CheckBox left etc..

Open questions

• SettingsExpanderItem - ?

[michael-hawker]

Awesome @niels9001. The the card, should the property be IsClickEnabled as it's not an "item" itself like a traditional ListView?

[michael-hawker]

Should Title be Header?

In either case Title/Description should be objects and use ContentPresenters to accept more than just strings (like Button content). That way someone could add a Hyperlink for the description to click on.

[Jay-o-Way]

Question: in the first example of the settings expander I see a few settings separated by a line. What element is used for the line?

[michael-hawker]

Can you clarify which image you're referring to? The line is automatic between SettingsExpanderItems.

[Jay-o-Way]

The one with "first, second, third". I suspect it should be a MenuFlyoutSeparator?

[niels9001]

@Jay-o-Way We set the Border of the root grid to 0,1,0,0 (SettingsExpanderItemBorderThickness) so it correctly renders for every SettingsExpanderMenuItem. The XAML is part of this PR: #253

[0x5bfa]

When adding these settings control in code-behind, it should be easy to create a title for the group as well. This can be seen in PowerToy's settings control

XAML code structure is here:

<uc:SettingsGroup Title="Input">
    <uc:SettingsGroup.Items>
        <uc:SettingsCard Icon="" Title="" Description="">
            <Button Background="transparent" BorderThickness="0">
                <FontIcon Glyph="" />
            <Button>
        </uc:SettingsCard>
        <uc:SettingsCard Icon="" Title="" Description="">
            <Button Background="transparent" BorderThickness="0">
                <FontIcon Glyph="" />
            <Button>
        </uc:SettingsCard>
    </uc:SettingsGroup.Items>
</uc:SettingsGroup>

Also, FYI, in Windows 11 Settings, SettingsExpander has footer border(background is not same as above items):

[michael-hawker]

@niels9001 we should probably just include these values in the control template? (Though I know WinUI makes it hard to use resources from controls due to resource lookup order.)

Labs-Windows/labs/SettingsControls/samples/SettingsControls.Samples/SettingsPageExample.xaml

Lines 10 to 24 in bfb745f

	<Page.Resources>
	<!-- These styles can be referenced to create a consistent SettingsPage layout -->
	<!-- Spacing between cards -->
	<x:Double x:Key="SettingsCardSpacing">3</x:Double>
	<!-- Style (inc. the correct spacing) of a section header -->
	<Style x:Key="SettingsSectionHeaderTextBlockStyle"
	BasedOn="{StaticResource BodyStrongTextBlockStyle}"
	TargetType="TextBlock">
	<Style.Setters>
	<Setter Property="Margin" Value="1,29,0,5" />
	</Style.Setters>
	</Style>
	</Page.Resources>

@onein528 we didn't want to have a control just to group settings as that's very rigid, we just provide the complete sample for design reference at the moment.

We plan to look at a more general form control experiment to help with this and other scenarios for grouping components on a page with headers in a specific layout. We just haven't gotten to that yet. Should probably open a new discussion/proposal here for tracking to copy over the relevant bits from that issue and the related possible panel PR here that sparked that discussion: CommunityToolkit/WindowsCommunityToolkit#3381

[michael-hawker]

This was shipped in the 8.0 Release, please update to use that version of the component. Any further issues/requests should start in the main repository.