SettingsPane SettingsPane SettingsPane SettingsPane Class

Note

SettingsPane may be altered or unavailable for releases after Windows 10. Instead of using a SettingsPane, integrate settings options into the app experience. For more info, see Guidelines for app settings.

A static class that enables the app to control the Settings Charm pane. The app can add or remove commands, receive a notification when the user opens the pane, or open the pane programmatically.

Syntax

Declaration

public sealed class SettingsPanepublic sealed class SettingsPanePublic NotInheritable Class SettingsPanepublic sealed class SettingsPane

Remarks

Note

: This class is not agile, which means that you need to consider its threading model and marshaling behavior. For more info, see Threading and Marshaling (C++/CX) and Using Windows Runtime objects in a multithreaded environment (.NET).

Examples

The following code shows how to add app commands by using the SettingsPane and SettingsCommand classes. For the full example, see App settings sample.

using Windows.UI.ApplicationSettings;
using Windows.UI.Popups;
using Windows.UI.Xaml;
using Windows.UI.Xaml.Controls;
using Windows.UI.Xaml.Navigation;
using System;

// This is the click handler for the 'addSettingsScenarioAdd' button.  
// Replace this with your own handler if you have a button or buttons on this page.
void addSettingsScenarioAdd_Click(object sender, RoutedEventArgs e)
{
    Button b = sender as Button;
    if (b != null)
    {
        rootPage.NotifyUser(
            "You selected the " + b.Content + " button", 
            NotifyType.StatusMessage);

        if (!this.isEventRegistered)
        {
            SettingsPane.GetForCurrentView().CommandsRequested += onCommandsRequested;
            this.isEventRegistered = true;
        }
    }
}

void onSettingsCommand(IUICommand command)
{
    SettingsCommand settingsCommand = (SettingsCommand)command;
    rootPage.NotifyUser(
        "You selected the " + settingsCommand.Label + " settings command from the " + 
        SettingsPane.Edge.ToString(), NotifyType.StatusMessage);

}

void onCommandsRequested(
    SettingsPane settingsPane, 
    SettingsPaneCommandsRequestedEventArgs eventArgs)
{
    UICommandInvokedHandler handler = new UICommandInvokedHandler(onSettingsCommand);

    SettingsCommand generalCommand = new SettingsCommand(
        "generalSettings", "General", handler);
    eventArgs.Request.ApplicationCommands.Add(generalCommand);

    SettingsCommand helpCommand = new SettingsCommand("helpPage", "Help", handler);
    eventArgs.Request.ApplicationCommands.Add(helpCommand);
}
Imports Windows.UI.ApplicationSettings
Imports Windows.UI.Popups
Imports Windows.UI.Xaml
Imports Windows.UI.Xaml.Controls
Imports Windows.UI.Xaml.Navigation
Imports System

    '' This is the click handler for the 'addSettingsScenarioAdd' button.  
    '' Replace this with your own handler if you have a button or buttons on this page.
    Private Sub addSettingsScenarioAdd_Click(sender As Object, e As RoutedEventArgs)
        Dim b As Button = TryCast(sender, Button)
        If b IsNot Nothing Then
            rootPage.NotifyUser("You selected the " & b.Content & " button", _
                NotifyType.StatusMessage)
            If Not Me.isEventRegistered Then
                AddHandler SettingsPane.GetForCurrentView.CommandsRequested, _
                    AddressOf onCommandsRequested
                Me.isEventRegistered = True
            End If
        End If
    End Sub

    Private Sub onSettingsCommand(command As IUICommand)
        Dim settingsCommand As SettingsCommand = DirectCast(command, SettingsCommand)
        rootPage.NotifyUser( _
        "You selected the " & settingsCommand.Label & " command from the " & SettingsPane.Edge.ToString(), _
        NotifyType.StatusMessage)
    End Sub

    Private Sub onCommandsRequested(settingsPane As SettingsPane, _
        eventArgs As SettingsPaneCommandsRequestedEventArgs)
        Dim handler As New UICommandInvokedHandler(AddressOf onSettingsCommand)

        Dim generalCommand As New SettingsCommand("generalSettings", "General", handler)
        eventArgs.Request.ApplicationCommands.Add(generalCommand)

        Dim helpCommand As New SettingsCommand("helpPage", "Help", handler)
        eventArgs.Request.ApplicationCommands.Add(helpCommand)
    End Sub


    '' This is the click handler for the 'addSettingsScenarioShow' button.  
    '' Replace this with your own handler if you have a button or buttons on this page.
    Private Sub addSettingsScenarioShow_Click(sender As Object, e As RoutedEventArgs)
        Dim b As Button = TryCast(sender, Button)
        If b IsNot Nothing Then
            rootPage.NotifyUser("You selected the " & b.Content & " button", _
                NotifyType.StatusMessage)
            SettingsPane.Show()
        End If
    End Sub
#include "pch.h"
#include "AddSettingsScenario.xaml.h"

using namespace ApplicationSettings;

using namespace Windows::Foundation;
using namespace Windows::UI::Xaml;
using namespace Windows::UI::Xaml::Controls;
using namespace Windows::UI::Xaml::Navigation;
using namespace Windows::UI::ApplicationSettings;
using namespace Windows::UI::Popups;

void ApplicationSettings::AddSettingsScenario::addSettingsScenarioAdd_Click(
    Platform::Object^ sender, Windows::UI::Xaml::RoutedEventArgs^ e)
{
    Button^ b = safe_cast<Button^>(sender);
    if (b != nullptr)
    {
        rootPage->NotifyUser("You selected the " + b->Content + " button", 
            NotifyType::StatusMessage);
        if (!this->isEventRegistered)
        {
            this->commandsRequestedEventRegistrationToken = 
                SettingsPane::GetForCurrentView()->CommandsRequested += 
                    ref new TypedEventHandler<SettingsPane^, 
                    SettingsPaneCommandsRequestedEventArgs^>(this, 
                        &AddSettingsScenario::onCommandsRequested);
            this->isEventRegistered = true;
        }
    }
}

void ApplicationSettings::AddSettingsScenario::onSettingsCommand(
    Windows::UI::Popups::IUICommand^ command)
{
    SettingsCommand^ settingsCommand = safe_cast<SettingsCommand^>(command);
    rootPage->NotifyUser(
        "You selected the " + settingsCommand->Label + " settings command from the " + 
        SettingsPane::Edge.ToString(), NotifyType::StatusMessage);
}

void ApplicationSettings::AddSettingsScenario::onCommandsRequested(
    Windows::UI::ApplicationSettings::SettingsPane^ settingsPane,
    Windows::UI::ApplicationSettings::SettingsPaneCommandsRequestedEventArgs^ eventArgs)
{
    UICommandInvokedHandler^ handler = ref new UICommandInvokedHandler(
        this, &AddSettingsScenario::onSettingsCommand);

    SettingsCommand^ generalCommand = ref new SettingsCommand(
        "generalSettings", "General", handler);
    eventArgs->Request->ApplicationCommands->Append(generalCommand);

    SettingsCommand^ helpCommand = ref new SettingsCommand("helpPage", "Help", handler);
    eventArgs->Request->ApplicationCommands->Append(helpCommand);
}

Properties summary

Note

SettingsPane may be altered or unavailable for releases after Windows 10. Instead of using a SettingsPane, integrate settings options into the app experience. For more info, see Guidelines for app settings.

Gets a value indicating whether the Settings charm appears on the left or right edge of the screen.

Methods summary

Note

SettingsPane may be altered or unavailable for releases after Windows 10. Instead of using a SettingsPane, integrate settings options into the app experience. For more info, see Guidelines for app settings.

Gets a SettingsPane object that is associated with the current app view (that is, with CoreWindow ).

Note

SettingsPane may be altered or unavailable for releases after Windows 10. Instead of using a SettingsPane, integrate settings options into the app experience. For more info, see Guidelines for app settings.

Displays the Settings Charm pane to the user.

Events summary

Note

SettingsPane may be altered or unavailable for releases after Windows 10. Instead of using a SettingsPane, integrate settings options into the app experience. For more info, see Guidelines for app settings.

Occurs when the user opens the settings pane. Listening for this event lets the app initialize the setting commands and pause its UI until the user closes the pane.

During this event, append your SettingsCommand objects to the available ApplicationCommands vector to make them available to the SettingsPane UI.

Properties

  • Edge
    Edge
    Edge
    Edge
    Note

    SettingsPane may be altered or unavailable for releases after Windows 10. Instead of using a SettingsPane, integrate settings options into the app experience. For more info, see Guidelines for app settings.

    Gets a value indicating whether the Settings charm appears on the left or right edge of the screen.

    public static SettingsEdgeLocation Edge { get; }public static SettingsEdgeLocation Edge { get; }Public Static ReadOnly Property Edge As SettingsEdgeLocationpublic static SettingsEdgeLocation Edge { get; }

    Property Value

Methods

  • GetForCurrentView()
    GetForCurrentView()
    GetForCurrentView()
    GetForCurrentView()
    Note

    SettingsPane may be altered or unavailable for releases after Windows 10. Instead of using a SettingsPane, integrate settings options into the app experience. For more info, see Guidelines for app settings.

    Gets a SettingsPane object that is associated with the current app view (that is, with CoreWindow ).

    public static SettingsPane GetForCurrentView()public static SettingsPane GetForCurrentView()Public Static Function GetForCurrentView() As SettingsPanepublic static SettingsPane GetForCurrentView()

    Returns

    Remarks

    If you're creating an app with XAML, you should override OnWindowCreated in App.xaml.cs/vb/cpp to register the CommandsRequested event there.

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

    SettingsPane may be altered or unavailable for releases after Windows 10. Instead of using a SettingsPane, integrate settings options into the app experience. For more info, see Guidelines for app settings.

    Displays the Settings Charm pane to the user.

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

    Remarks

    The Show() method raises an exception if one of the following is true:

    • It is called from a snapped app.
    • It is called when the current app does not have focus.
    • It is called when the pane is already displayed.

Events

  • CommandsRequested
    CommandsRequested
    CommandsRequested
    CommandsRequested
    Note

    SettingsPane may be altered or unavailable for releases after Windows 10. Instead of using a SettingsPane, integrate settings options into the app experience. For more info, see Guidelines for app settings.

    Occurs when the user opens the settings pane. Listening for this event lets the app initialize the setting commands and pause its UI until the user closes the pane.

    During this event, append your SettingsCommand objects to the available ApplicationCommands vector to make them available to the SettingsPane UI.

    public event TypedEventHandler CommandsRequestedpublic event TypedEventHandler CommandsRequestedPublic Event CommandsRequestedpublic event TypedEventHandler CommandsRequested

Device family

Windows Desktop Extension SDK (introduced v10.0.10240.0)
Xbox One Extensions for the UWP (introduced v10.0.10586.0)

API contract

Windows.UI.ApplicationSettings.ApplicationsSettingsContract (introduced v1)

Attributes

Windows.Foundation.Metadata.ContractVersionAttribute
Windows.Foundation.Metadata.DeprecatedAttribute
Windows.Foundation.Metadata.MarshalingBehaviorAttribute
Windows.Foundation.Metadata.MuseAttribute
Windows.Foundation.Metadata.StaticAttribute

Details

Assembly

Windows.UI.ApplicationSettings.dll