SettingsFlyout SettingsFlyout SettingsFlyout Class

Represents a control that provides in-context access to settings that affect the current app. (Not recommended for Universal Windows Platform (UWP) app. See @Windows.UI.Xaml.Controls.Flyout.)

Syntax

Declaration

public class SettingsFlyoutpublic class SettingsFlyoutPublic Class SettingsFlyout
<SettingsFlyout ...>
  singleRootElement
</SettingsFlyout>

Inheritance Hierarchy

Inherited Members

Inherited properties

, , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , ,
Tag
Tag
Tag
, , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , ,

Inherited events

, , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , ,

Inherited methods

, , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , ,

Remarks

Note

SettingsFlyout is not supported for use in Universal Windows Platform (UWP) app for Windows 10.

Note

SettingsFlyout is supported only for use with the SettingsPane in Windows 8. While the SettingsFlyout type is visible in Windows Phone projects, SettingsPane is not present on Windows Phone, so use of SettingsFlyout is not supported.

A SettingsFlyout control isn't intended to be a composite part of a page or general app UI. Instead, a SettingsFlyout control is typically defined as a separate XAML file, where the class you're defining is a SettingsFlyout subclass that's unique to your project, using a SettingsFlyout object element as a XAML file root. In Microsoft Visual Studio, you can use the Add New Item menu options for a project to add the files to your project using a basic starting template. This starting template sets styles for items contained by the SettingsFlyout control that reference existing pre-defined styles. For example, there's a style for a section header that references the TitleTextBlockStyle style that's defined by the Windows Runtime as a XAML resource. The generated XAML also provides some initial attribute values that are intended to be replaced. For example it sets the initial Title value to use the class name. You'll also want to add controls or other UI to the content section to replace the templated UI it starts with.

Showing and dismissing a Settings flyout

Users can access your SettingsFlyout control through the Settings charm. You can programmatically show a SettingsFlyout control by calling the Show() or ShowIndependent() methods, and dismiss it by calling Hide(). A SettingsFlyout always includes a back button in its header area that uses the typical arrow glyph (this button isn't part of the adjustable XAML template, it's always there and is added by default control logic). By default, the back button dismisses the flyout.

If a SettingsFlyout control is shown by calling Show(), clicking the back button dismisses the flyout and reopens the settings pane. If a SettingsFlyout is shown by calling ShowIndependent(), clicking the back button dismisses the flyout and returns the user to the app. For example, if you open a SettingsFlyout control from a "Settings" button in your app, you will typically call ShowIndependent() so users are returned directly to your app when they dismiss the flyout.

Only one SettingsFlyout control can be shown at a time. Calling Show() on any SettingsFlyout instance hides any other SettingsFlyout instance currently shown.

You can override the default back button behavior by handling the BackClick event. This event is raised whenever the user clicks the back button. To override the default behavior, wire an event handler for the event and set the Handled property to true. This is useful when you have a SettingsFlyout that opens a second SettingsFlyout. By default, when the user taps the Back button on the second flyout, it will open the SettingsPane. You should handle the BackClick event and open the first flyout instead.

Connecting to the SettingsPane

You must manually associate the SettingsFlyout control with the app’s SettingsPane object. Do this by handling the CommandsRequested event and adding a SettingsCommand to the ApplicationCommands collection. The SettingsCommand has a label for your SettingsFlyout control that’s shown in the Settings charm, and specifies a method that's executed when a user selects the command in the Settings charm. In this method, you create an instance of the SettingsFlyout control and show it.

We recommend that you add the CommandsRequested event handler in the overridden OnWindowCreated(WindowCreatedEventArgs) method, and remove it in the@Windows.UI.Xaml.Application.Suspending event handler method. See the examples section for more info.

Defining a Settings flyout

To add a SettingsFlyout control to an app project in Microsoft Visual Studio:

  1. Right-click your project in Solution Explorer. Select Project > Add New Item.
  2. In the Add New Item dialog, select Settings Flyout from the middle pane.
  3. Type a name for the SettingsFlyout control subclass in the Name field and click Add.
Note

When you add a SettingsFlyout control, you're creating a new class with a name you choose. When you look at the generated code-behind file, you'll see that the class you define is subclassing from SettingsFlyout.

To instantiate your SettingsFlyout control, use the class name you specified and the default constructor for it. For example, if you named your SettingsFlyout class as UpdateSettingsFlyout, you'd call new UpdateSettingsFlyout().

For more information and detailed steps, see Quickstart: Add app settings and Quickstart: Add app help.

Examples

This example shows the result of adding a templated item for Settings Flyout and naming the class UpdateSettingsFlyout. Then, the SettingsFlyoutSectionStyle resource is redefined, and appropriate strings and controls are added to the XAML composition of the SettingsFlyout XAML so that the user can adjust the settings.

<SettingsFlyout
    x:Class="SettingsFlyoutExample.UpdateSettingsFlyout"
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
    xmlns:local="using:SettingsFlyoutExample"
    xmlns:d="http://schemas.microsoft.com/expression/blend/2008"
    xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006"
    mc:Ignorable="d"
    IconSource="Assets/SmallLogo.png"
    Title="App Updates"
    d:DesignWidth="346"
    Width="346" 
    HeaderBackground="#FF2B4A80">
    <SettingsFlyout.Resources>
        <Style x:Key="SettingsFlyoutSectionStyle" TargetType="StackPanel">
            <Setter Property="Margin" Value="0,0,0,39"/>
        </Style>
    </SettingsFlyout.Resources>

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

        <!-- The stack panels below define individual content sections. -->

        <!-- Content Section 1-->
        <StackPanel Style="{StaticResource SettingsFlyoutSectionStyle}">

            <!-- Section 1 header -->
            <TextBlock Style="{StaticResource TitleTextBlockStyle}"
                                 Text="Automatic updates"/>

            <!-- Section 1 body -->
            <TextBlock Style="{StaticResource BodyTextBlockStyle}" Margin="0,0,0,25" TextWrapping="Wrap">
                <TextBlock.Text>
                    Turn automatic updating on or off.
                </TextBlock.Text>
            </TextBlock>
            <ToggleSwitch Header="Download updates automatically"/>
            <ToggleSwitch Header="Install updates automatically"/>

        </StackPanel>

        <!-- Define more Content Sections below as necessary. -->

    </StackPanel>
</SettingsFlyout>

Here's how this SettingsFlyout control can be associated with the app's SettingsPane and ApplicationCommands. These methods are in App.xaml.cs.


// Add the CommandsRequested handler when the window is created.
protected override void OnWindowCreated(WindowCreatedEventArgs args)
{
    SettingsPane.GetForCurrentView().CommandsRequested += OnCommandsRequested;
}

// Commands are requested when the Settings charm is used to open the SettingsPane.
private void OnCommandsRequested(SettingsPane sender, SettingsPaneCommandsRequestedEventArgs args)
{
    args.Request.ApplicationCommands.Add(new SettingsCommand(
    "AppUpdateSettings", "App updates", (handler) => ShowAppUpdatesSettingFlyout()));
}

// This code is executed when the user taps the "App updates" command in the SettingsPane.
public void ShowAppUpdatesSettingFlyout()
{
    UpdateSettingsFlyout updatesFlyout = new UpdateSettingsFlyout();
    updatesFlyout.Show();
}

// Remove the CommandsRequested handler when the app is suspending.
private async void OnSuspending(object sender, SuspendingEventArgs e)
{
    SettingsPane.GetForCurrentView().CommandsRequested -= App_CommandsRequested;

    var deferral = e.SuspendingOperation.GetDeferral();
    await SuspensionManager.SaveAsync();
    deferral.Complete();
}

Alternatively, the@Windows.UI.Xaml.Controls.SettingsFlyout can be shown independently:

<Button Content="App update settings" Click="UpdateSettingsButton_Click"/>
private void UpdateSettingsButton_Click(object sender, RoutedEventArgs e)
{
    UpdateSettingsFlyout updatesFlyout = new UpdateSettingsFlyout();
    updatesFlyout.ShowIndependent();
}

For more code in context, see the App settings sample.

Constructors summary

Initializes a new instance of the SettingsFlyout class.

Properties summary

Gets or sets the Brush that fills the background of the SettingsFlyout header.

Identifies the HeaderBackground dependency property.

Gets or sets the Brush that fills the foreground of the SettingsFlyout header.

Identifies the HeaderForeground dependency property.

Gets or sets the icon image displayed in the SettingsFlyout header.

Identifies the IconSource dependency property.

Gets an object that provides calculated values that can be referenced as TemplateBinding sources when defining templates for a SettingsFlyout control.

Gets or sets the title of the SettingsFlyout control when displayed.

Identifies the Title dependency property.

Methods summary

Closes the Settings flyout.

Opens the Settings flyout, and returns the user to the Settings pane after the flyout is dismissed.

Opens the Settings flyout, and returns the user to the app after the flyout is dismissed.

Events summary

Occurs when the user clicks the back button on a SettingsFlyout control.

Constructors

  • SettingsFlyout()
    SettingsFlyout()
    SettingsFlyout()
    SettingsFlyout()

    Initializes a new instance of the SettingsFlyout class.

    public SettingsFlyout()public New()Public Sub New()public SettingsFlyout()

Properties

  • HeaderBackground
    HeaderBackground
    HeaderBackground
    HeaderBackground

    Gets or sets the Brush that fills the background of the SettingsFlyout header.

    public Brush HeaderBackground { get; set; }public Brush HeaderBackground { get; set; }Public ReadWrite Property HeaderBackground As Brushpublic Brush HeaderBackground { get; set; }
    <SettingsFlyout HeaderBackground="{StaticResource resourceName}"/>
    
    

    Property Value

    • The brush that provides the background of the SettingsFlyout header. The default is a null brush from a pure code perspective, but the default control template for SettingsFlyout applies a theme resource brush (SettingsFlyoutHeaderBackgroundThemeBrush) for this in a runtime instance of a SettingsFlyout control.

  • HeaderBackgroundProperty
    HeaderBackgroundProperty
    HeaderBackgroundProperty
    HeaderBackgroundProperty

    Identifies the HeaderBackground dependency property.

    public static DependencyProperty HeaderBackgroundProperty { get; }public static DependencyProperty HeaderBackgroundProperty { get; }Public Static ReadOnly Property HeaderBackgroundProperty As DependencyPropertypublic static DependencyProperty HeaderBackgroundProperty { get; }

    Property Value

  • HeaderForeground
    HeaderForeground
    HeaderForeground
    HeaderForeground

    Gets or sets the Brush that fills the foreground of the SettingsFlyout header.

    public Brush HeaderForeground { get; set; }public Brush HeaderForeground { get; set; }Public ReadWrite Property HeaderForeground As Brushpublic Brush HeaderForeground { get; set; }
    <SettingsFlyout HeaderForeground="{StaticResource resourceName}"/>
    
    

    Property Value

    • The brush that provides the foreground of the SettingsFlyout header. The default is a null brush from a pure code perspective, but the default control template for SettingsFlyout applies a theme resource brush (SettingsFlyoutHeaderForegroundThemeBrush) for this in a runtime instance of a SettingsFlyout control.

  • HeaderForegroundProperty
    HeaderForegroundProperty
    HeaderForegroundProperty
    HeaderForegroundProperty

    Identifies the HeaderForeground dependency property.

    public static DependencyProperty HeaderForegroundProperty { get; }public static DependencyProperty HeaderForegroundProperty { get; }Public Static ReadOnly Property HeaderForegroundProperty As DependencyPropertypublic static DependencyProperty HeaderForegroundProperty { get; }

    Property Value

  • IconSource
    IconSource
    IconSource
    IconSource

    Gets or sets the icon image displayed in the SettingsFlyout header.

    public ImageSource IconSource { get; set; }public ImageSource IconSource { get; set; }Public ReadWrite Property IconSource As ImageSourcepublic ImageSource IconSource { get; set; }
    <SettingsFlyout IconSource="uri"/>
    

    Property Value

    Remarks

    Note

    Even though the default property value is null, the Microsoft Visual Studio Settings Flyout item template sets the IconSource to your app’s small logo (IconSource="Assets/SmallLogo.png").

    The IconSource property is typically set in XAML to take advantage of the built-in conversion from string.

    If you do set the IconSource property in code, you can use a BitmapImage object, constructed with the Uniform Resource Identifier (URI) that describes the path to a valid image source file. You can also initialize a BitmapSource with a stream, perhaps a stream from a storage file, but that's not typical for a SettingsFlyout UI scenario.

    Setting IconSource in XAML

    If you set the IconSource property as an attribute in XAML, you are setting the IconSource property using a Uniform Resource Identifier (URI). This behavior relies on underlying type conversion that processes the string as a Uniform Resource Identifier (URI), and calls the equivalent of the @Windows.UI.Xaml.Media.Imaging.BitmapImage.#ctor(Windows.Foundation.Uri) constructor. The XAML parser interprets any strings that represent a relative Uniform Resource Identifier (URI), using the base Uniform Resource Identifier (URI) of the XAML page that is being parsed. For example, if you specify a value "Images/myimage.png" in XAML, that string is interpreted as a relative path suffix that is appended to the base Uniform Resource Identifier (URI) location within the app package where the XAML page itself exists.

    <SettingsFlyout Width="346" IconSource="Images/myimage.png" />
    

    A property element syntax in XAML is also possible, specifying a BitmapImage object element with valid source as the property value.

  • IconSourceProperty
    IconSourceProperty
    IconSourceProperty
    IconSourceProperty

    Identifies the IconSource dependency property.

    public static DependencyProperty IconSourceProperty { get; }public static DependencyProperty IconSourceProperty { get; }Public Static ReadOnly Property IconSourceProperty As DependencyPropertypublic static DependencyProperty IconSourceProperty { get; }

    Property Value

  • TemplateSettings
    TemplateSettings
    TemplateSettings
    TemplateSettings

    Gets an object that provides calculated values that can be referenced as TemplateBinding sources when defining templates for a SettingsFlyout control.

    public SettingsFlyoutTemplateSettings TemplateSettings { get; }public SettingsFlyoutTemplateSettings TemplateSettings { get; }Public ReadOnly Property TemplateSettings As SettingsFlyoutTemplateSettingspublic SettingsFlyoutTemplateSettings TemplateSettings { get; }

    Property Value

  • Title
    Title
    Title
    Title

    Gets or sets the title of the SettingsFlyout control when displayed.

    public string Title { get; set; }public string Title { get; set; }Public ReadWrite Property Title As stringpublic string Title { get; set; }
    <SettingsFlyout Title="string"/>
    

    Property Value

    • string
      string
      string

      The title of the SettingsFlyout control. This typically appears in the SettingsFlyout control header area. The default is an empty string.

    Remarks

    Note

    Even though the default property value is an empty string, the Microsoft Visual Studio Settings Flyout item template sets the Title to the name of your settings flyout class (for example, Title="AccountSettingsFlyout").

  • TitleProperty
    TitleProperty
    TitleProperty
    TitleProperty

    Identifies the Title dependency property.

    public static DependencyProperty TitleProperty { get; }public static DependencyProperty TitleProperty { get; }Public Static ReadOnly Property TitleProperty As DependencyPropertypublic static DependencyProperty TitleProperty { get; }

    Property Value

Methods

  • Hide()
    Hide()
    Hide()
    Hide()

    Closes the Settings flyout.

    public void Hide()public void Hide()Public Function Hide() As voidpublic void Hide()

    Remarks

    By default, the settings flyout is dismissed when the user presses the back button, and is always light-dismissed when the user taps outside of it. In most cases, you will not need to call the Hide() method to dismiss the settings flyout.

    Calling the Hide() method has the same behavior as light dismiss. It always returns the user to your app and closes the settings pane, regardless of whether the settings flyout was opened by calling Show() or ShowIndependent().

  • Show()
    Show()
    Show()
    Show()

    Opens the Settings flyout, and returns the user to the Settings pane after the flyout is dismissed.

    public void Show()public void Show()Public Function Show() As voidpublic void Show()

    Remarks

    If a SettingsFlyout is shown by calling the Show() method, then clicking the Back button reopens the SettingsPane after the SettingsFlyout dismisses. If a SettingsFlyout is shown by calling ShowIndependent(), then clicking the Back button dismisses the SettingsFlyout and returns the user to the app; the SettingsPane is not reopened.

    Call the Show() method in your CommandsRequested event handler. This code is invoked when the user opens the SettingsFlyout from the SettingsPane, so you should return the user to the SettingsPane when they click the Back button.

    Only one SettingsFlyout is shown at a time. Calling Show() on a SettingsFlyout closes any other SettingsFlyout currently shown. The SettingsFlyout being closed completes its close animation before the new SettingsFlyout begins its show animation.

    Examples

    private void App_CommandsRequested(SettingsPane sender, SettingsPaneCommandsRequestedEventArgs args)
    {
        // Add update settings.
        Windows.UI.ApplicationSettings.SettingsCommand updateSetting =
            new Windows.UI.ApplicationSettings.SettingsCommand("AppUpdateSettings", "App updates", (handler) =>
            {
                UpdateSettingsFlyout updatesFlyout = new UpdateSettingsFlyout();
                updatesFlyout.Show();
            });
    
        args.Request.ApplicationCommands.Add(updateSetting);
    
        // Add account list.
        Windows.UI.ApplicationSettings.SettingsCommand accountListSetting =
            new Windows.UI.ApplicationSettings.SettingsCommand("AppAccountListSettings", "Accounts", (handler) =>
            {
                AccountListSettingsFlyout accountsListFlyout = new AccountListSettingsFlyout();
                accountsListFlyout.Show();
            });
    
        args.Request.ApplicationCommands.Add(accountListSetting);
    }
    

    For more code in context, see Scenario 3 of the App settings sample.

  • ShowIndependent()
    ShowIndependent()
    ShowIndependent()
    ShowIndependent()

    Opens the Settings flyout, and returns the user to the app after the flyout is dismissed.

    public void ShowIndependent()public void ShowIndependent()Public Function ShowIndependent() As voidpublic void ShowIndependent()

    Remarks

    If a SettingsFlyout is shown by calling the Show() method, then clicking the Back button reopens the SettingsPane after the SettingsFlyout dismisses. If a SettingsFlyout is shown by calling ShowIndependent(), then clicking the Back button dismisses the SettingsFlyout and returns the user to the app; the SettingsPane is not reopened.

    Call the ShowIndependent() method to open the SettingsFlyout from a button in your app. In this case, because the user did not open the SettingsFlyout from the SettingsPane, they should return to your app when they click the Back button.

    Only one SettingsFlyout is shown at a time. Calling ShowIndependent() on a SettingsFlyout closes any other SettingsFlyout currently shown. The SettingsFlyout being closed completes its close animation before the new SettingsFlyout begins its show animation.

    Examples

    This example shows how to use the ShowIndependent() method to open a SettingsFlyout from a button in your app.

    <Button Content="App update settings" Click="UpdateSettingsButton_Click"/>
    
    private void UpdateSettingsButton_Click(object sender, RoutedEventArgs e)
    {
        UpdateSettingsFlyout updatesFlyout = new UpdateSettingsFlyout();
        updatesFlyout.ShowIndependent();
    }
    

    For more code in context, see Scenario 4 of the App settings sample and Quickstart: Add app help.

Events

  • BackClick
    BackClick
    BackClick
    BackClick

    Occurs when the user clicks the back button on a SettingsFlyout control.

    public event BackClickEventHandler BackClickpublic event BackClickEventHandler BackClickPublic Event BackClickpublic event BackClickEventHandler BackClick
    <SettingsFlyout BackClick="eventhandler"/>
    
    

    Remarks

    By default, clicking the back button on a SettingsFlyout control hides the control. Handle the BackClick event and set Handled to true to override this behavior and introduce your own logic.

    This is useful when you have a SettingsFlyout that opens a second SettingsFlyout. By default, when the user taps the Back button on the second flyout, it will reopen the SettingsPane. You should handle the BackClick event and reopen the first flyout instead.

    Examples

    In this scenario, the Settings charm is used to open a SettingsFlyout that contains a list of accounts. When the user picks an account, a new SettingsFlyout is shown with options for the selected account.

    Here, you handle the BackClick event of the second flyout so that when the user clicks the Back button, you show the account list again instead of the SettingsPane.

    void AccountSettingsFlyout_BackClick(object sender, BackClickEventArgs e)
    {
        e.Handled = true;
        AccountListSettingsFlyout accountList = new AccountListSettingsFlyout();
        accountList.Show();  
    }
    

    For more code in context, see Scenario 5 of the App settings sample.

Device family

Windows 10 (introduced v10.0.10240.0)

API contract

Windows.Foundation.UniversalApiContract (introduced v1)

Attributes

Windows.Foundation.Metadata.ComposableAttribute
Windows.Foundation.Metadata.ContractVersionAttribute
Windows.Foundation.Metadata.MarshalingBehaviorAttribute
Windows.Foundation.Metadata.StaticAttribute
Windows.Foundation.Metadata.ThreadingAttribute
Windows.Foundation.Metadata.WebHostHiddenAttribute

Details

Assembly

Windows.UI.Xaml.Controls.dll