Settings
A settings window with searchable pages, grouped items and a reset button, as uikit:Settings.
<Border BorderBrush="{DynamicResource UIKit.Border}" BorderThickness="1" CornerRadius="6" ClipToBounds="True"
Width="640" Height="440" HorizontalAlignment="Left">
<uikit:Settings GroupVariant="Outline" SidebarWidth="150" SidebarMinWidth="120">
<uikit:SettingPage Title="General" Icon="{StaticResource UIKit.Icon.Settings2}" IsOpen="True">
<uikit:SettingGroup Title="Appearance">
<uikit:SettingItem Title="Dark Mode" Description="Switch between light and dark themes." DefaultValue="False">
<ToggleSwitch />
</uikit:SettingItem>
<uikit:SettingItem Title="Auto Switch Theme" Description="Follow the system's light or dark setting." DefaultValue="False">
<CheckBox />
</uikit:SettingItem>
</uikit:SettingGroup>
<uikit:SettingGroup Title="Font" Footer="Font preferences apply to this window only.">
<uikit:SettingItem Title="Font Family" Description="Select the font family." DefaultValue="Inter">
<ComboBox SelectedIndex="0" Width="160">
<x:String>Inter</x:String>
<x:String>Helvetica</x:String>
<x:String>Times New Roman</x:String>
</ComboBox>
</uikit:SettingItem>
<uikit:SettingItem Title="Font Size" Description="Between 8 and 72." DefaultValue="14">
<NumericUpDown Value="14" Minimum="8" Maximum="72" />
</uikit:SettingItem>
</uikit:SettingGroup>
<uikit:SettingGroup Title="Other">
<uikit:SettingItem Title="CLI Path" Description="Path to the CLI executable." Keywords="shell, terminal"
Orientation="Vertical" DefaultValue="/usr/local/bin/bash">
<TextBox Text="/usr/local/bin/bash" />
</uikit:SettingItem>
</uikit:SettingGroup>
</uikit:SettingPage>
<uikit:SettingPage Title="Updates" Icon="{StaticResource UIKit.Icon.Cpu}">
<uikit:SettingGroup Title="Updates">
<uikit:SettingItem Title="Notifications" Description="Hear about updates and news." DefaultValue="True">
<ToggleSwitch IsChecked="True" />
</uikit:SettingItem>
<uikit:SettingItem Title="Auto Update" Description="Download and install new versions." DefaultValue="True">
<ToggleSwitch IsChecked="True" />
</uikit:SettingItem>
</uikit:SettingGroup>
</uikit:SettingPage>
<uikit:SettingPage Title="About" Icon="{StaticResource UIKit.Icon.Info}"
Description="The application and where to find out more.">
<uikit:SettingGroup>
<uikit:SettingItem>
<StackPanel Spacing="4">
<TextBlock Text="Avalonia UIKit" />
<TextBlock Text="Version 0.1.0" FontSize="14" Foreground="{DynamicResource UIKit.MutedForeground}" />
</StackPanel>
</uikit:SettingItem>
</uikit:SettingGroup>
<uikit:SettingGroup Title="Links">
<uikit:SettingItem Title="Repository" Description="The source on GitHub.">
<Button Classes="outline" Content="Open..." />
</uikit:SettingItem>
</uikit:SettingGroup>
</uikit:SettingPage>
</uikit:Settings>
</Border>Usage
uikit:Settings puts a sidebar beside the selected page, the boundary between them resizable (SidebarWidth, 250 by default, from SidebarMinWidth 160 to SidebarMaxWidth 360). The sidebar has a search box and a menu of the pages. Its items are uikit:SettingPages, which hold uikit:SettingGroups, which hold uikit:SettingItems:
<uikit:Settings GroupVariant="Outline">
<uikit:SettingPage Title="General" Icon="{StaticResource UIKit.Icon.Settings2}" IsOpen="True">
<uikit:SettingGroup Title="Appearance">
<uikit:SettingItem Title="Dark Mode" Description="Switch between light and dark themes." DefaultValue="False">
<ToggleSwitch IsChecked="{Binding DarkMode}" />
</uikit:SettingItem>
</uikit:SettingGroup>
</uikit:SettingPage>
</uikit:Settings>A page is a row in the menu with its Icon; when it has more than one group, its titled groups are rows under it, open while the page IsOpen. Clicking a page selects it (SelectedIndex); clicking a group selects it too (SelectedGroup) and scrolls the page to it. The page shows its Title, a TitleSuffix after it (a help button) and its Description above the groups, which scroll.
| Property | On | Effect |
|---|---|---|
SelectedIndex, SelectedGroup | Settings | The selected page, and the group chosen in the sidebar (null for the whole page) |
SearchText, SearchPlaceholderText | Settings | The search box's text and its placeholder ("Search..." by default) |
GroupVariant | Settings (inherited) | The groups' surface: Normal, Fill or Outline |
Title, Icon, Description, TitleSuffix | SettingPage | The page's header and its row in the sidebar |
IsOpen | SettingPage | Whether the page's groups show under it in the sidebar |
IsResettable | SettingPage | Whether the header shows the reset button (true by default) |
Title, Description, Footer | SettingGroup | The muted title and description above the surface, and small muted text under it |
Variant | SettingGroup | The group's own surface, instead of the settings' GroupVariant |
Title, Description | SettingItem | The text beside the field; without a title the content fills the row |
Keywords | SettingItem | Comma-separated words the search also matches, never shown |
Orientation | SettingItem | Horizontal puts the field at the end of the row, Vertical under the text |
DefaultValue, IsModified, Reset, ResetCommand | SettingItem | The field's default and what the reset button does (below) |
An item's content is its field: any control. Beside the text, a TextBox is 256px and a NumericUpDown 128px wide; under it, the field is the width of the row, except a ToggleSwitch or a CheckBox. A page narrower than 480px lays every item out vertically. The size classes on the settings (xsmall, small, large) go on every item's content. A disabled item (IsEnabled="False") is dimmed with its field.
The search keeps the items whose title, description or keywords contain the text, ignoring case, the groups with such items and the pages with such groups. An item without a title is found by its keywords only. The selected page stays while it has results, otherwise the first page with results is selected; with no results, no page shows.
Examples
The fields are the standard controls, in a group used on its own.
<uikit:SettingGroup Title="Editor" Description="The fields are the standard controls." Variant="Outline"
Width="560" HorizontalAlignment="Left">
<uikit:SettingItem Title="Line Numbers" Description="A ToggleSwitch.">
<ToggleSwitch IsChecked="True" />
</uikit:SettingItem>
<uikit:SettingItem Title="Word Wrap" Description="A CheckBox.">
<CheckBox />
</uikit:SettingItem>
<uikit:SettingItem Title="Theme" Description="A ComboBox, or any selection control.">
<ComboBox SelectedIndex="0" Width="160">
<ComboBoxItem Content="Default Light" />
<ComboBoxItem Content="Default Dark" />
</ComboBox>
</uikit:SettingItem>
<uikit:SettingItem Title="Tab Size" Description="A NumericUpDown, 128px wide beside the text.">
<NumericUpDown Value="4" Minimum="1" Maximum="8" />
</uikit:SettingItem>
<uikit:SettingItem Title="Formatter" Description="A vertical item: the field is under the text, the width of the row."
Orientation="Vertical">
<TextBox PlaceholderText="prettier --write" />
</uikit:SettingItem>
<uikit:SettingItem Title="Minimap" Description="A disabled item is dimmed." IsEnabled="False">
<ToggleSwitch />
</uikit:SettingItem>
</uikit:SettingGroup>Variant on a group, or GroupVariant on the settings for every group: the items on the page, on a filled surface, or in a bordered card.
<StackPanel Width="520" HorizontalAlignment="Left">
<uikit:SettingGroup Title="Normal">
<uikit:SettingItem Title="Auto Save" Description="The items sit on the page.">
<ToggleSwitch IsChecked="True" />
</uikit:SettingItem>
</uikit:SettingGroup>
<uikit:SettingGroup Title="Fill" Variant="Fill">
<uikit:SettingItem Title="Auto Save" Description="The items sit on a filled surface.">
<ToggleSwitch IsChecked="True" />
</uikit:SettingItem>
</uikit:SettingGroup>
<uikit:SettingGroup Title="Outline" Variant="Outline" Footer="A footer sits under the surface.">
<uikit:SettingItem Title="Auto Save" Description="The items sit in a bordered card.">
<ToggleSwitch IsChecked="True" />
</uikit:SettingItem>
</uikit:SettingGroup>
</StackPanel>With a DefaultValue, an item follows a ToggleSwitch or CheckBox (IsChecked), a TextBox (Text), a NumericUpDown or Slider (Value), a ComboBox or ListBox (SelectedValue) and a uikit:Select (SelectedItem); a default written in XAML is text converted to the field's type. While a field differs from its default, the page shows a reset button that sets every item the search keeps back to its default, through the field's bindings. Other content sets IsModified itself and puts its default back in Reset or ResetCommand.
<Border BorderBrush="{DynamicResource UIKit.Border}" BorderThickness="1" CornerRadius="6" ClipToBounds="True"
Width="560" HorizontalAlignment="Left">
<uikit:SettingPage Title="Editor" Description="Change a setting: the button at the end of the header resets them all.">
<uikit:SettingGroup Variant="Outline">
<uikit:SettingItem Title="Format On Save" Description="Follows its default: False." DefaultValue="False">
<ToggleSwitch />
</uikit:SettingItem>
<uikit:SettingItem Title="Tab Size" Description="Follows its default: 4." DefaultValue="4">
<NumericUpDown Value="4" Minimum="1" Maximum="8" />
</uikit:SettingItem>
<uikit:SettingItem Name="Density" Title="Density" Description="Custom content reports IsModified and handles Reset."
Reset="OnDensityReset">
<StackPanel Orientation="Horizontal" Spacing="4">
<Button Name="Comfortable" Classes="primary" Content="Comfortable" Click="OnDensityClick" />
<Button Name="Compact" Classes="outline" Content="Compact" Click="OnDensityClick" />
</StackPanel>
</uikit:SettingItem>
</uikit:SettingGroup>
</uikit:SettingPage>
</Border>