SettingsFlyout SettingsFlyout SettingsFlyout SettingsFlyout Class

Definition

Note

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

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.

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

public : class SettingsFlyout : ContentControl, ISettingsFlyoutpublic class SettingsFlyout : ContentControl, ISettingsFlyoutPublic Class SettingsFlyout Inherits ContentControl Implements ISettingsFlyout// This API is not available in Javascript.
<SettingsFlyout ...>
  singleRootElement
</SettingsFlyout>
Inheritance
Attributes
Windows 10 requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

Inherited Members

Inherited properties

Inherited events

Inherited methods

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?text=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.

Remarks

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 BackClickEventArgs.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 SettingsPane.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 method, and remove it in the@Windows.UI.Xaml.Application.Suspending?text= 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.

Constructors

SettingsFlyout() SettingsFlyout() SettingsFlyout() SettingsFlyout()

Initializes a new instance of the SettingsFlyout class.

public : SettingsFlyout()public SettingsFlyout()Public Sub New()// This API is not available in Javascript.

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 Brush// This API is not available in Javascript.
<SettingsFlyout HeaderBackground="{StaticResource resourceName}"/>

Value
Brush Brush Brush Brush

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.

See Also

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 DependencyProperty// This API is not available in Javascript.

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 Brush// This API is not available in Javascript.
<SettingsFlyout HeaderForeground="{StaticResource resourceName}"/>

Value
Brush Brush Brush Brush

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.

See Also

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 DependencyProperty// This API is not available in Javascript.

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 ImageSource// This API is not available in Javascript.
<SettingsFlyout IconSource="uri"/>
Value
ImageSource ImageSource ImageSource ImageSource

The icon image displayed in the SettingsFlyout header area, typically to the right of the Title. The default is null, which results in no displayed image.

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 BitmapImage(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 DependencyProperty// This API is not available in Javascript.
Value
DependencyProperty DependencyProperty DependencyProperty DependencyProperty

The identifier for the IconSource dependency property.

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 SettingsFlyoutTemplateSettings// This API is not available in Javascript.

Title Title Title Title

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

public : PlatForm::String Title { get; set; }public string Title { get; set; }Public ReadWrite Property Title As string// This API is not available in Javascript.
<SettingsFlyout Title="string"/>
Value
PlatForm::String 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 DependencyProperty// This API is not available in Javascript.
Value
DependencyProperty DependencyProperty DependencyProperty DependencyProperty

The identifier for the Title dependency property.

Methods

Hide() Hide() Hide() Hide()

Closes the Settings flyout.

public : void Hide()public void Hide()Public Function Hide() As void// This API is not available in Javascript.

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 void// This API is not available in Javascript.

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.

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.

See Also

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 void// This API is not available in Javascript.

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.

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.

See Also

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 BackClick// This API is not available in Javascript.
<SettingsFlyout BackClick="eventhandler"/>

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.

Remarks

By default, clicking the back button on a SettingsFlyout control hides the control. Handle the BackClick event and set BackClickEventArgs.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.

See Also