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:actipro="http://schemas.actiprosoftware.com/avaloniaui"
...
<actipro: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 (using the HyperlinkTextBlock control) :

xmlns:actipro="http://schemas.actiprosoftware.com/avaloniaui"
...
<actipro:SettingsExpander Header="Setting name">

	<actipro:SettingsExpander.Description>
		<actipro:HyperlinkTextBlock Text="Click here for more"
			Command="{Binding SomeCommand}"
			FontSize="{actipro:ThemeResource DefaultFontSizeSmall}"
			FontWeight="DemiBold" />
	</actipro:SettingsExpander.Description>

	...

</actipro: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 PathIcon for defining the icon, but any content supported by Icon Presenter can be used to define the icon (like IImage data or DynamicImage control):

xmlns:actipro="http://schemas.actiprosoftware.com/avaloniaui"
...
<actipro:SettingsExpander Header="Setting name">

	<!-- Use a PathIcon as the primary icon -->
	<actipro:SettingsExpander.HeaderIcon>
		<PathIcon Data="M19,13H5V11H19V13Z" />
	</actipro:SettingsExpander.HeaderIcon>

	...

</actipro: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:actipro="http://schemas.actiprosoftware.com/avaloniaui"
...
<actipro:SettingsExpander Header="Setting name" ... >

	<actipro:SettingsExpander.Content>
		<ToggleSwitch actipro:ThemeProperties.ToggleSwitchHasFarAffinity="True" IsChecked="{Binding SomeProperty}" />
	</actipro:SettingsExpander.Content>

	<!-- Define child settings here -->

</actipro: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:actipro="http://schemas.actiprosoftware.com/avaloniaui"
...
<actipro:SettingsExpander Header="Setting name" IsExpanded="True" ... >

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

	<actipro:SettingsCard Header="Child setting">
		<ToggleSwitch actipro:ThemeProperties.ToggleSwitchHasFarAffinity="True" />
	</actipro:SettingsCard>

</actipro: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 ItemContainerTheme property as desired, like demonstrated in the following sample:

xmlns:actipro="http://schemas.actiprosoftware.com/avaloniaui"
...
<actipro:SettingsExpander Header="Setting name" ... >

	<actipro:SettingsExpander.ItemContainerTheme>
		<ControlTheme TargetType="actipro:SettingsCard" BasedOn="{actipro:ControlTheme SettingsCardSettingsExpanderItem}">
			<Setter Property="IsHeaderIconVisible" Value="{x:Null}" />
			<Setter Property="IsActionIconVisible" Value="{x:Null}" />
		</ControlTheme>
	</actipro:SettingsExpander.ItemContainerTheme>

	<!-- Define child settings here -->

</actipro:SettingsExpander>

Working with MVVM

All children of SettingsExpander must be instances of SettingsCard. When binding ItemsSource to a collection of view models, each view model will automatically be wrapped in a SettingsCard container with the DataContext set to the view model.

Properties on the view model can be bound to properties on the SettingsCard by assigning an ItemContainerTheme like shown in the following example:

xmlns:actipro="http://schemas.actiprosoftware.com/avaloniaui"
...
<actipro:SettingsExpander Header="Setting name" ... >

	<actipro:SettingsExpander.ItemContainerTheme>
		<ControlTheme
			TargetType="actipro:SettingsCard"
			BasedOn="{actipro:ControlTheme SettingsCardSettingsExpanderItem}"
			x:DataType="custom:MyViewModelType">

			<!-- Bind to view model properties -->
			<Setter Property="Header" Value="{Binding Header}" />
			<Setter Property="Description" Value="{Binding Description}" />

		</ControlTheme>
	</actipro:SettingsExpander.ItemContainerTheme>

</actipro: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:actipro="http://schemas.actiprosoftware.com/avaloniaui"
...
<actipro:SettingsExpander Header="Setting name" ... >

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

	<!-- Define child settings here -->

</actipro: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.

Pseudo-classes

The following pseudo-classes are available and can be used when styling the control:

Theme Resources

The following theme resources are available for customizing the appearance of the control:

See the Theme Assets topic for more details on working with theme resources.