Quickstart: Add app settings (XAML)

Article
08/31/2015

Add customized settings to your app's Settings pane using the XAMLSettingsFlyout control.

All Windows Store apps automatically participate in the Settings contract. Even if you never modify your app's settings, a user will be able to click on the Settings charm from within your app and see a default Settings pane. This default, system-provided Settings pane contains a Permissions link as well as six system settings, including volume, network information, and power. However, you can customize this pane by creating your own app settings with the SettingsFlyout control and linking to these new custom settings from the Settings pane.

This quickstart shows you how to make a new SettingsFlyout, add app-specific content and controls, and incorporate the new setting into the Settings pane using a new SettingsCommand and the SettingsPane.CommandsRequested event. By the end of this quickstart, a user will be able to click on a custom setting from within your app's Settings pane and see a customized setting flyout. If you copy the code provided in the following steps, your customized flyout will look like this:

See this feature in action as part of our App features, start to finish series: Windows Store app UI, start to finish

Writing apps with Javascript and HTML? See Quickstart: Adding app settings using Javascript.

Prerequisites

You'll need Microsoft Visual Studio 2013 and Windows 8.1 to complete this quickstart. For downloads, see Get the tools.
This quickstart also assumes you want to add custom settings to an existing Windows Store app project using C#, Visual Basic, or C++. If you haven't already created an app, choose your preferred language and check out our step-by-step guidance:
- Create your first Windows Store app using C# or Visual Basic
- Create your first Windows Store app using C++
Read the Guidelines for app settings for a brief overview of the Settings charm and pane, as well as recommendations for how to best use these features in your app.

Step 1: Create a new SettingsFlyout for your app

Follow these steps to add a SettingsFlyout to your existing Windows Store app. The default SettingsFlyout control has a header section with a title, back button, and logo icon, as well as section for content.

Open the Windows Store app project you created in Visual Studio 2013.
Select the Project menu, and click Add New Item. An Add New Item dialog box appears. (You can also use the shortcut, Ctrl+Shift+A, to open this dialog box.)
In the Visual C# pane, select Windows Store.
From the center pane, scroll down and select Settings Flyout.
In the Name text box, enter a name for your SettingsFlyout. This example uses the name CustomSetting. Visual Studio 2013 creates a CustomSetting.xaml file and a corresponding CustomSetting.xaml.cs file. These CustomSetting files now appear with the rest of your project files in Solution Explorer.

Step 2: Add content and controls to your custom SettingsFlyout

After adding the SettingsFlyout in the previous step, open the CustomSetting.xaml file. Replace the default content with information that is specific to your app, and then style the flyout to match your design scheme. You can modify a SettingsFlyout in the following ways:

Change the display title of your flyout using the Title property. By default, the title shown at the top of your flyout will match the name you chose for the SettingsFlyout when you added it to your project.
Consider adjusting the width of the flyout. Note that the default width for a SettingsFlyout is narrow (346px), which matches the width of the SettingsPane.
Change or remove the logo icon by resetting or removing the IconSource property.
Modify the color scheme or fonts. Use the Properties pane. If you don't see this pane next to the Solution Explorer tab on the right side of your screen, open the View menu and click Properties, or press Ctrl+W+P to open it.
Add controls, if desired. Depending on your setting's purpose, you may want to take advantage of the standard XAML controls available for Windows Store apps. For more information on standard XAML controls, see the Controls list or Quickstart: Adding controls and content.
Add content sections as needed.

Keep in mind that you can't remove the back button on a SettingsFlyout. Also, a SettingsFlyout always adjusts to match the height of the screen.

If you'd like to see how to implement some frequently used controls, copy the following XAML into your CustomSetting.xaml file. This code replaces the default SettingsFlyout content with examples of a ToggleSwitch, Button, ComboBox, HyperlinkButton, TextBox, and RadioButton.

Important: When a new SettingsFlyout is added to a project, the automatically generated class and namespace declarations include the project's name. Because the code snippet below was created in a project called AppSettingsExample, this code will not build unless you replace "AppSettingsExample" with the name of your project in the following lines:

Replace x:Class="AppSettingsExample.CustomSetting" with x:Class="<name of your project>.CustomSetting"
Replace xmlns:local="using:AppSettingsExample" to xmlns:local="using:<name of your project>"

<SettingsFlyout
    x:Class="AppSettingsExample.CustomSetting"
    xmlns="https://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="https://schemas.microsoft.com/winfx/2006/xaml"
    xmlns:local="using:AppSettingsExample"
    xmlns:d="https://schemas.microsoft.com/expression/blend/2008"
    xmlns:mc="https://schemas.openxmlformats.org/markup-compatibility/2006"
    mc:Ignorable="d"
    IconSource="Assets/SmallLogo.png"
    Title="CustomSetting"
    d:DesignWidth="346">

    <!-- This StackPanel acts as a root panel for vertical layout of the content sections -->
    <StackPanel VerticalAlignment="Stretch" HorizontalAlignment="Stretch" >

        <!-- Toggle switch -->
        <StackPanel Style="{StaticResource SettingsFlyoutSectionStyle}">
            <TextBlock Text="Toggle Switch" Style="{StaticResource TitleTextBlockStyle}"/>
            <TextBlock Margin="0,0,0,25" Text="Use toggle switches to let users set Boolean values." Style="{StaticResource BodyTextBlockStyle}"/>
            <ToggleSwitch Margin="-6,0,0,0" Header = "Download updates automatically" HorizontalAlignment="Left" HorizontalContentAlignment="Left"/>
            <ToggleSwitch Margin="-6,0,0,0" Header = "Install updates automatically" HorizontalAlignment="Stretch"/>
        </StackPanel>
        
        <!-- Button -->
        <StackPanel Style="{StaticResource SettingsFlyoutSectionStyle}">
            <TextBlock Text="Push button" Style="{StaticResource TitleTextBlockStyle}"/>
            <TextBlock Margin="0,0,0,25" Text="With a push button, users initiate an immediate action." Style="{StaticResource BodyTextBlockStyle}"/>
            <TextBlock Text="Button label" Style="{StaticResource BodyTextBlockStyle}"/>
            <Button Margin="-3,0,0,0" Content="Clear"/>
        </StackPanel>

        <!-- ComboBox -->
        <StackPanel Style="{StaticResource SettingsFlyoutSectionStyle}">
            <TextBlock Text="ComboBox" Style="{StaticResource TitleTextBlockStyle}"/>
            <TextBlock Margin="0,0,0,25" Text="Use the ComboBox to allow users to select one item from a set of text-only items." Style="{StaticResource BodyTextBlockStyle}"/>
            <ComboBox Header="State:" Margin="0,7,0,0" SelectedIndex="0" HorizontalAlignment="Left">
                <ComboBoxItem Content="Washington"/>
                <ComboBoxItem Content="Oregon"/>
                <ComboBoxItem Content="California"/>
            </ComboBox>
        </StackPanel>
        
        <!-- HyperlinkButton -->
        <StackPanel Style="{StaticResource SettingsFlyoutSectionStyle}">
            <TextBlock Text="Hyperlink" Style="{StaticResource TitleTextBlockStyle}"/>
            <TextBlock Margin="0,0,0,25" Text="Use a hyperlink when the associated action will take the user out of this flyout." Style="{StaticResource BodyTextBlockStyle}"/>
            <HyperlinkButton Padding="-5,0,0,0" Content="View privacy statement" Tag="https://privacy.microsoft.com" HorizontalAlignment="Left"/>
        </StackPanel>

        <!-- TextBox -->
        <StackPanel Style="{StaticResource SettingsFlyoutSectionStyle}">
            <TextBlock Text="TextBox" Style="{StaticResource TitleTextBlockStyle}"/>
            <TextBlock Margin="0,0,0,25" Text="Use a TextBox to allow users to enter text." Style="{StaticResource BodyTextBlockStyle}"/>
            <StackPanel Margin="0,7,0,0" Orientation="Horizontal">
                <TextBox HorizontalAlignment="Left" Width="150"/>
                <Button Margin="20,0,0,0" Content="Add"/>
            </StackPanel>
        </StackPanel>

        <!-- RadioButton -->
        <StackPanel Style="{StaticResource SettingsFlyoutSectionStyle}">
            <TextBlock Text="Radio button group" Style="{StaticResource TitleTextBlockStyle}"/>
            <TextBlock Margin="0,0,0,25" Text="Lets users choose one item from a small set of mutually exclusive, related options." Style="{StaticResource BodyTextBlockStyle}"/>
            <TextBlock Text="Video quality" Style="{StaticResource BodyTextBlockStyle}"/>
            <RadioButton Margin="0,7,0,0" Content="High"/>
            <RadioButton Margin="0,17,0,0" Content="Medium"/>
            <RadioButton Margin="0,17,0,0" Content="Low"/>
        </StackPanel>
    </StackPanel>
</SettingsFlyout>

Step 3: Add a SettingsFlyout to your app's Settings pane

The SettingsFlyout control allows you to easily add your customized flyout to the app's Settings pane. After you add the two following pieces of C# code to your app, the Settings pane will include a "Custom Setting" command that links to your new flyout.

First, add the ApplicationSettings namespace to your app's App.xaml.cs page:

    using Windows.UI.ApplicationSettings;

In the code below, the OnWindowCreated method prepares the app's Settings pane when your app launches. OnCommandsRequested adds a "Custom Setting" command to the Settings pane. SettingsCommand sets the custom setting's Label, Id, and Invoked properties. Set the Label property to the name you'd like users to see in the Settings pane. The Invoked property sets the handler for the event raised when a user selects the command from the Settings pane. This example adds an event handler named ShowCustomSettingFlyout. The event handler creates and opens the flyout when the user clicks “Custom Setting” in the Settings pane.

Add following C# code to App.xaml.cs to add your custom flyout to your app's Settings pane:

        protected override void OnWindowCreated(WindowCreatedEventArgs args)
        {
            SettingsPane.GetForCurrentView().CommandsRequested += OnCommandsRequested;
        }

        private void OnCommandsRequested(SettingsPane sender, SettingsPaneCommandsRequestedEventArgs args)
        {

            args.Request.ApplicationCommands.Add(new SettingsCommand(
                "Custom Setting", "Custom Setting", (handler) => ShowCustomSettingFlyout()));
        }

        public void ShowCustomSettingFlyout()
        {
            CustomSetting CustomSettingFlyout = new CustomSetting();
            CustomSettingFlyout.Show();
        }

Now, when users expose the Settings pane (either by swiping from the right edge of the screen and selecting the Settings charm or by pressing Windows+I), the Settings pane will appear with links to your customized flyout as well as the system-generated Permissions flyout.

Complete code examples

Here are complete copies of the two pages modified in this quickstart:

CustomSetting.xaml: This code will not build unless you replace x:Class="AppSettingsExample.CustomSetting" with x:Class="<name of your project>.CustomSetting" and xmlns:local="using:AppSettingsExample" to xmlns:local="using:<name of your project>".

<SettingsFlyout
    x:Class="AppSettingsExample.CustomSetting"
    xmlns="https://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="https://schemas.microsoft.com/winfx/2006/xaml"
    xmlns:local="using:AppSettingsExample"
    xmlns:d="https://schemas.microsoft.com/expression/blend/2008"
    xmlns:mc="https://schemas.openxmlformats.org/markup-compatibility/2006"
    mc:Ignorable="d"
    IconSource="Assets/SmallLogo.png"
    Title="CustomSetting"
    d:DesignWidth="346">

    <!-- This StackPanel acts as a root panel for vertical layout of the content sections -->
    <StackPanel VerticalAlignment="Stretch" HorizontalAlignment="Stretch" >

        <!-- Toggle switch -->
        <StackPanel Style="{StaticResource SettingsFlyoutSectionStyle}">
            <TextBlock Text="Toggle Switch" Style="{StaticResource TitleTextBlockStyle}"/>
            <TextBlock Margin="0,0,0,25" Text="Use toggle switches to let users set Boolean values." Style="{StaticResource BodyTextBlockStyle}"/>
            <ToggleSwitch Margin="-6,0,0,0" Header = "Download updates automatically" HorizontalAlignment="Left" HorizontalContentAlignment="Left"/>
            <ToggleSwitch Margin="-6,0,0,0" Header = "Install updates automatically" HorizontalAlignment="Stretch"/>
        </StackPanel>

        <!-- Button -->
        <StackPanel Style="{StaticResource SettingsFlyoutSectionStyle}">
            <TextBlock Text="Push button" Style="{StaticResource TitleTextBlockStyle}"/>
            <TextBlock Margin="0,0,0,25" Text="With a push button, users initiate an immediate action." Style="{StaticResource BodyTextBlockStyle}"/>
            <TextBlock Text="Button label" Style="{StaticResource BodyTextBlockStyle}"/>
            <Button Margin="-3,0,0,0" Content="Clear"/>
        </StackPanel>

        <!-- ComboBox -->
        <StackPanel Style="{StaticResource SettingsFlyoutSectionStyle}">
            <TextBlock Text="ComboBox" Style="{StaticResource TitleTextBlockStyle}"/>
            <TextBlock Margin="0,0,0,25" Text="Use the ComboBox to allow users to select one item from a set of text-only items." Style="{StaticResource BodyTextBlockStyle}"/>
            <ComboBox Header="State:" Margin="0,7,0,0" SelectedIndex="0" HorizontalAlignment="Left">
                <ComboBoxItem Content="Washington"/>
                <ComboBoxItem Content="Oregon"/>
                <ComboBoxItem Content="California"/>
            </ComboBox>
        </StackPanel>

        <!-- HyperlinkButton -->
        <StackPanel Style="{StaticResource SettingsFlyoutSectionStyle}">
            <TextBlock Text="Hyperlink" Style="{StaticResource TitleTextBlockStyle}"/>
            <TextBlock Margin="0,0,0,25" Text="Use a hyperlink when the associated action will take the user out of this flyout." Style="{StaticResource BodyTextBlockStyle}"/>
            <HyperlinkButton Padding="-5,0,0,0" Content="View privacy statement" Tag="https://privacy.microsoft.com" HorizontalAlignment="Left"/>
        </StackPanel>

        <!-- TextBox -->
        <StackPanel Style="{StaticResource SettingsFlyoutSectionStyle}">
            <TextBlock Text="TextBox" Style="{StaticResource TitleTextBlockStyle}"/>
            <TextBlock Margin="0,0,0,25" Text="Use a TextBox to allow users to enter text." Style="{StaticResource BodyTextBlockStyle}"/>
            <StackPanel Margin="0,7,0,0" Orientation="Horizontal">
                <TextBox HorizontalAlignment="Left" Width="150"/>
                <Button Margin="20,0,0,0" Content="Add"/>
            </StackPanel>
        </StackPanel>

        <!-- RadioButton -->
        <StackPanel Style="{StaticResource SettingsFlyoutSectionStyle}">
            <TextBlock Text="Radio button group" Style="{StaticResource TitleTextBlockStyle}"/>
            <TextBlock Margin="0,0,0,25" Text="Lets users choose one item from a small set of mutually exclusive, related options." Style="{StaticResource BodyTextBlockStyle}"/>
            <TextBlock Text="Video quality" Style="{StaticResource BodyTextBlockStyle}"/>
            <RadioButton Margin="0,7,0,0" Content="High"/>
            <RadioButton Margin="0,17,0,0" Content="Medium"/>
            <RadioButton Margin="0,17,0,0" Content="Low"/>
        </StackPanel>
    </StackPanel>
</SettingsFlyout>

App.xaml.cs

using System;
using System.Collections.Generic;
using System.IO;
using System.Linq;
using System.Runtime.InteropServices.WindowsRuntime;
using Windows.ApplicationModel;
using Windows.ApplicationModel.Activation;
using Windows.Foundation;
using Windows.Foundation.Collections;
using Windows.UI.Xaml;
using Windows.UI.Xaml.Controls;
using Windows.UI.Xaml.Controls.Primitives;
using Windows.UI.Xaml.Data;
using Windows.UI.Xaml.Input;
using Windows.UI.Xaml.Media;
using Windows.UI.Xaml.Navigation;
using Windows.UI.ApplicationSettings;

// The Blank Application template is documented at https://go.microsoft.com/fwlink/p/?LinkID=234227

namespace AppSettingsExample
{
    /// <summary>
    /// Provides application-specific behavior to supplement the default Application class.
    /// </summary>
    sealed partial class App : Application
    {
        /// <summary>
        /// Initializes the singleton application object.  This is the first line of authored code
        /// executed, and as such is the logical equivalent of main() or WinMain().
        /// </summary>
        public App()
        {
            this.InitializeComponent();
            this.Suspending += OnSuspending;
        }

        /// <summary>
        /// Invoked when the application is launched normally by the end user.  Other entry points
        /// will be used such as when the application is launched to open a specific file.
        /// </summary>
        /// <param name="e">Details about the launch request and process.</param>
        protected override void OnLaunched(LaunchActivatedEventArgs e)
        {

#if DEBUG
            if (System.Diagnostics.Debugger.IsAttached)
            {
                this.DebugSettings.EnableFrameRateCounter = true;
            }
#endif

            Frame rootFrame = Window.Current.Content as Frame;

            // Do not repeat app initialization when the Window already has content,
            // just ensure that the window is active
            if (rootFrame == null)
            {
                // Create a Frame to act as the navigation context and navigate to the first page
                rootFrame = new Frame();
                // Set the default language
                rootFrame.Language = Windows.Globalization.ApplicationLanguages.Languages[0];

                rootFrame.NavigationFailed += OnNavigationFailed;

                if (e.PreviousExecutionState == ApplicationExecutionState.Terminated)
                {
                    //TODO: Load state from previously suspended application
                }

                // Place the frame in the current Window
                Window.Current.Content = rootFrame;
            }

            if (rootFrame.Content == null)
            {
                // When the navigation stack isn't restored navigate to the first page,
                // configuring the new page by passing required information as a navigation
                // parameter
                rootFrame.Navigate(typeof(MainPage), e.Arguments);
            }
            // Ensure the current window is active
            Window.Current.Activate();
        }

        /// <summary>
        /// Invoked when Navigation to a certain page fails
        /// </summary>
        /// <param name="sender">The Frame which failed navigation</param>
        /// <param name="e">Details about the navigation failure</param>
        void OnNavigationFailed(object sender, NavigationFailedEventArgs e)
        {
            throw new Exception("Failed to load Page " + e.SourcePageType.FullName);
        }

        /// <summary>
        /// Invoked when application execution is being suspended.  Application state is saved
        /// without knowing whether the application will be terminated or resumed with the contents
        /// of memory still intact.
        /// </summary>
        /// <param name="sender">The source of the suspend request.</param>
        /// <param name="e">Details about the suspend request.</param>
        private void OnSuspending(object sender, SuspendingEventArgs e)
        {
            var deferral = e.SuspendingOperation.GetDeferral();
            //TODO: Save application state and stop any background activity
            deferral.Complete();
        }

        protected override void OnWindowCreated(WindowCreatedEventArgs args)
        {
            SettingsPane.GetForCurrentView().CommandsRequested += OnCommandsRequested;
        }

        private void OnCommandsRequested(SettingsPane sender, SettingsPaneCommandsRequestedEventArgs args)
        {

            args.Request.ApplicationCommands.Add(new SettingsCommand(
                "Custom Setting", "Custom Setting", (handler) => ShowCustomSettingFlyout()));
        }

        public void ShowCustomSettingFlyout()
        {
            CustomSetting CustomSettingFlyout = new CustomSetting();
            CustomSettingFlyout.Show();
        }

    }
}

Summary

You created a custom SettingsFlyout and integrated it with your app's Settings pane. To add another SettingsFlyout, simply create another flyout using the SettingsFlyout control, add a new args.Request.ApplicationCommands.Add(new Settings Command()) line to OnCommandsRequested, and write an event handler to instantiate and show your new SettingsFlyout.

If you'd like to add help content to your app, see Quickstart: Add app help (Windows Store app using C++, C#, or VB).

Reference

SettingsFlyout class

SettingsFlyout.ShowIndependent method

SettingsFlyout.Show method

SettingsFlyout.IconSource property

ApplicationSettings namespace

Application.OnWindowCreated method

ApplicationSettings.SettingsCommand class

SettingsPane class

SettingsPane.CommandsRequested event

SettingsPane.Show method