SettingsExpander

The SettingsCard, SettingsExpander, and SettingsGroup controls are used together to organize and present configurable settings.

SettingsCard and SettingsExpander displayed within a SettingsGroup

A SettingsExpander has functionality similar to a SettingsCard but can also be expanded to show additional child settings.

SettingsExpander with header, description, header icon, and ToggleSwitch content in the expanded state with two SettingsCard children

Primary Content Areas

The SettingsExpander control is defined by multiple content areas:

• Header - The primary label for the setting.
• Description - An additional description for the setting.
• HeaderIcon - The primary icon for the setting.
• Content (Editor) - The control used to edit the setting (e.g., ToggleSwitch, ComboBox).

Each content area, including the icon, can optionally be set to any value supported by ContentPresenter and the layout will adjust to only show the areas where content is defined.

Header and Description

The Header and Description are typically string values describing the setting, and both are optional. The following demonstrates how to create a SettingsExpander with a header and description:

xmlns:views="http://schemas.actiprosoftware.com/winfx/xaml/views"
...
<views:SettingsExpander Header="Setting name" Description="Use the description for additional context" ... />

Since both properties can be set to any content supported by ContentPresenter, either property can be configured with more complex content. The following example demonstrates how a hyperlink could be used as the Description :

xmlns:views="http://schemas.actiprosoftware.com/winfx/xaml/views"
xmlns:themes="http://schemas.actiprosoftware.com/winfx/xaml/themes"
...
<views:SettingsExpander Header="Setting name">

	<views:SettingsExpander.Description>
		<TextBlock>
			<Hyperlink
				FontSize="{DynamicResource {x:Static themes:AssetResourceKeys.SmallFontSizeDoubleKey}}"
				FontWeight="DemiBold"
				Command="{Binding SomeCommand}"
				TextDecorations="None">
				Click here for more
			</Hyperlink>
		</TextBlock>
	</views:SettingsExpander.Description>

	...

</views:SettingsExpander>

Header Icon

The SettingsExpander supports a HeaderIcon. This icon is displayed on the left side of the card with a default size of 24x24. This icon is typically related to the value(s) defined by the setting. For example, a speaker icon might be used for a setting related to output sound volume.

The following sample demonstrates using a Geometry for defining the icon, but any content supported by ContentPresenter can be used to define the icon (like Image or DynamicImage controls):

xmlns:views="http://schemas.actiprosoftware.com/winfx/xaml/views"
...
<views:SettingsExpander Header="Setting name" HeaderIcon="M19,13H5V11H19V13Z">
	...
</views:SettingsExpander>

Content (Editor)

In additional to organizing child settings, a SettingsExpander may also use the Content property to present a control for an individual setting. Any content supported by ContentPresenter can be used, but a setting is typically defined by common controls like CheckBox, ComboBox, Slider, and ToggleSwitch.

The following demonstrates defining a SettingsExpander that uses a ToggleSwitch control as the Content:

xmlns:shared="http://schemas.actiprosoftware.com/winfx/xaml/shared"
xmlns:views="http://schemas.actiprosoftware.com/winfx/xaml/views"
...
<views:SettingsExpanderHeader="Setting name" ... >

	<views:SettingsExpander.Content>
		<shared:ToggleSwitch IsChecked="{Binding SomeProperty}" />
	</views:SettingsExpander.Content>

	<!-- Define child settings here -->

</views:SettingsExpander>

See the SettingsCard topic for more examples on using different controls for settings.

Items (Child Settings)

The SettingsExpander is an ItemsControl that supports defining one or more SettingsCard instances as child settings that are only displayed when the control is expanded.

The following sample demonstrates defining a SettingsExpander with multiple child settings and sets the IsExpanded property to true so the child settings are visible by default:

xmlns:shared="http://schemas.actiprosoftware.com/winfx/xaml/shared"
xmlns:views="http://schemas.actiprosoftware.com/winfx/xaml/views"
...
<views:SettingsExpanderHeader="Setting name" IsExpanded="True" ... >

	<views:SettingsCard Header="Child setting">
		<ComboBox> ... </ComboBox>
	</views:SettingsCard>

	<views:SettingsCard Header="Child setting">
		<shared:ToggleSwitch />
	</views:SettingsCard>

</views:SettingsExpander>

See the SettingsCard topic for more details.

Indentation

By default, child settings of a SettingsExpander are indented by setting both IsHeaderIconVisible and IsActionIconVisible to true. This reserves space in the layout for the HeaderIcon and ActionIcon even if those icons are not defined.

To change this behavior, modify the ItemContainerStyle property as desired, like demonstrated in the following sample:

xmlns:shared="http://schemas.actiprosoftware.com/winfx/xaml/shared"
xmlns:themes="http://schemas.actiprosoftware.com/winfx/xaml/themes"
xmlns:views="http://schemas.actiprosoftware.com/winfx/xaml/views"
...
<views:SettingsExpanderHeader="Setting name" ... >

	<views:SettingsExpander.ItemContainerStyle>
		<Style TargetType="views:SettingsCard" BasedOn="{StaticResource {x:Static themes:ViewsResourceKeys.SettingsCardSettingsExpanderItemStyleKey}}">
			<Setter Property="IsHeaderIconVisible" Value="{x:Null}" />
			<Setter Property="IsActionIconVisible" Value="{x:Null}" />
		</Style>
	</views:SettingsExpander.ItemContainerStyle>

	<!-- Define child settings here -->

</views:SettingsExpander>

Items Header and Footer

SettingsExpander showing ItemsHeader and ItemsFooter

SettingsExpander allows for additional content to be displayed above and below the child settings. Any content supported by ContentPresenter can be defined in the ItemsHeader or ItemsFooter.

The following sample demonstrates adding an informational message in the ItemsHeader:

xmlns:views="http://schemas.actiprosoftware.com/winfx/xaml/views"
...
<views:SettingsExpanderHeader="Setting name" ... >

	<views:SettingsExpander.ItemsHeader>
		<TextBlock Padding="12">Any content can be displayed above the child settings</TextBlock>
	</views:SettingsExpander.ItemsHeader>

	<!-- Define child settings here -->

</views:SettingsExpander>

Wrapping

SettingsExpander displayed in the unwrapped and wrapped states

If enough space is available, the Content (Editor) of the setting is displayed to the right of the Header and/or Description with default right alignment. When the width of the expander is less than or equal to the WrapThreshold, the Content will be wrapped to the bottom of the expander with default left alignment.

Use the IsWrapped property to manually control wrap behavior. When set to null (the default), wrapping is based on the WrapThreshold. Set the property to true to force wrapping at any width, and false to prevent wrapping at any width.

Animation

Fluent animation in the control is enabled by default but can be disabled by setting the IsAnimationEnabled property to false.

Theme Assets

See the Theme Reusable Assets topic for more details on using and customizing theme assets. The following reusable assets are used by SettingsExpander: