Proposal: SettingsCard, SettingsExpander, SettingsButton, SettingsGroup

[0x5bfa]

Proposal: SettingsCard, SettingsExpander, SettingsButton, SettingsGroup

The new Windows 11 Settings app experience has gained a lot of approval and is used as the standard for many apps.

However, the implementation of each app is very different and the lack of these standard controls has frustrated developers having to create them again and again.

Toolkit Lab has already created some of those controls as a sample but it is not full control and so I decided to bring this conversation into here WinUI.

---

Summary

Name	Description
SettingsControls	General term of following controls
SettingsCard	Static settings control
SettingsExpander	Expandable settings control
SettingsGroup	Grouping settings control
SettingsButton	Clickable settings control

Naming validation

SettingsControls is valid naming because these controls are only used in settings pages or apps. FormControls #82 was valid for Windows 10 Settings control styles.

Rationale

• There should be standard controls as I described in the top section
• It's already built in the community lab, but it's available in C# devs, not in C++ devs.

• SettingsCard: for obvious reasons
• SettingsExpander: for obvious reasons
• SettingsGroup: If you create these controls in code, They should be created all at once with group title
• SettingsButton: This control can be created by SettingsCard with the property IsClickable, but Card and Button will be used in different scenarios and so Card and Button should be separated.

Scope

Capability	Priority
There should be standard of them	Must
Developers/users can use/see consistent UI control	Must
Creat SettingsCard/SettingsExpander	Must
Create SettingsGroup	Must
Create SettingsButton	Should

Important Notes

SettingsCard

Default

<muxc:SettingsCard
    Icon="{StaticResource SampleIcon}"
    Header="Edit your color"
    Description="You can able to customize your color by picking color">

    <Button Content="Change" />

</muxc:SettingsCard>

Property	Type	Description
Header	String
Description	String
Icon	IconElement
Content	Object

SettingsExpander

Expanded

Collapsed

Expanded, multiple SettingsExpanderItemCard, Footer

Expanded, multiple SettingsExpanderItemButton

<muxc:SettingsExpander
    Icon="{StaticResource SampleIcon}"
    Title="App theme"
    Description="Select which app theme to display">

    <TextBlock Text="Dark" />

    <muxc:SettingsExpander.Items>
        <muxc:SettingsExpanderItemCard>
           <CheckBox IsTrue="True" />
        </muxc:SettingsExpanderItemCard>
        <muxc:SettingsExpanderItemButton Title="">
           <CheckBox IsTrue="True" />
        </muxc:SettingsExpanderItemButton>
    </muxc:SettingsExpander.Items>
</muxc:SettingsExpander>

Property	Type	Description
Header	String
Description	String
Icon	IconElement
Content	Object
Items	Object (list of SettingsCard)
Footer	Object

SettingsButtons

Default

Property	Type	Description
Header	String
Description	String
Icon	IconElement
Content	Object
Click event	event

SettingsGroup

Default

Property	Type	Description
Header	String
Content	Object

Open Questions

• Create SettingsCard with 'IsClickable' property and Remove SettingsButton
• Name validation: Settings* or Form*

References

• Official controls created for general use case by Microsoft
  • MUXC.Expander
  • CommunityToolkitLabs.SettingsControl
• Third party control libraries
  • Richasy/ExpanderEx
  • PowerToys.Setting.UI
  • ghost1372/SettingsUI

[niels9001]

@onein528 To give you a bit of perspective on why we didn't include the SettingsGroup in the current Toolkit Labs SettingsControls: we want to make sure these controls can be as flexible and usable across as many scenarios as possible. A layout is maybe more of a design pattern vs. a control?

In our samples we have created a Settingspage experience that is inline with the design specifications in case developers want to replicate this experience: https://github.com/CommunityToolkit/Labs-Windows/blob/main/labs/SettingsControls/samples/SettingsControls.Samples/SettingsPageExample.xaml

As you can see, you can use the SettingsCardSpacing to get the correct spacing between cards and use SettingsSectionHeaderTextBlockStyle on group headers to get the same effect!

#82 might be a great way to create these layouts!

[0x5bfa]

I wonder why those controls aren’t here.

[sylveon]

I support this idea. Currently, C++ devs cannot use the settings control from the WCT.

It should also be added to WinUI 2, because otherwise it leaves C++ UWP devs in a state where they will never get this important control for modern Windows 11 app design (while C# UWP devs have it from the WCT)

[mdtauk]

Which of the various implementations are you basing yours on?

Windows Terminal has something called the SettingsContainer

https://github.com/microsoft/terminal/blob/68cce101bc7b8056b7b1f040956b000ccbef1621/src/cascadia/TerminalSettingsEditor/SettingContainer.h

[niels9001]

@onein528 Maybe good to check with the maintenaing team first to see if they would be open for such PR :)?

Which of the various implementations are you basing yours on?

Windows Terminal has something called the SettingsContainer

https://github.com/microsoft/terminal/blob/68cce101bc7b8056b7b1f040956b000ccbef1621/src/cascadia/TerminalSettingsEditor/SettingContainer.h

@mdtauk The implementation that we've done in the Toolkit was together with the design team and is inline with the W11 Settings implementation (inc. a11y and resizing behavior). So I'd follow that as much as possible!

[0x5bfa]

Which of the various implementations are you basing yours on?

@mdtauk Toolkit lab. They created with the design team(so I don't know if I can create the PR of this proposal😅)