Working with the Settings Charm for Windows 8.1 Store Applications

Windows 8 features a Settings charm to display both application (the top part) and system (the bottom part) settings (you get it from swiping from the side of the screen). The system provides two entry points, Permissions and Rate and Review, the later only for applications installed through the store.

You can customize the settings charm by adding new entry points. For instance, you may want to add an About pane. If your application uses network capabilities then you have to add a privacy policy, otherwise your application will not pass the Windows Store Certification.

In this post I will show how you can add new entries to the settings charm for Windows 8.1 applications (this won’t work for Windows 8 applications). We have to use two classes:

• SettingsPane: 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.
• SettingsFlyout: represents a control that provides in-context access to settings that affect the current app. This class is new to Windows 8.1

The following code adds a new entry to the settings pane called Privacy policy and provides a handler for the command. In the handler we create a new instance of a SettingsFlayout and show it.

internal static class PrivacyPolicy
{
  public static void Initialise()
  {
     SettingsPane settingsPane = SettingsPane.GetForCurrentView();

     settingsPane.CommandsRequested += (s, e) =>
     {
        SettingsCommand settingsCommand = new SettingsCommand(
          "PRIVACY_ID",
          "Privacy policy",    
          async command =>
          {
             var flyout = new SettingsFlyout();
             flyout.Title = "Privacy policy";

             var file = await StorageFile.GetFileFromApplicationUriAsync(
                new Uri("ms-appx:///Settings/PrivacyPolicy.txt"));
             var properties = await file.GetBasicPropertiesAsync();
             var stream = await file.OpenAsync(FileAccessMode.Read);
             var reader = new DataReader(stream.GetInputStreamAt(0));
             await reader.LoadAsync((uint)properties.Size);
             string text = reader.ReadString(reader.UnconsumedBufferLength);

             flyout.Content = new TextBlock()
             {
                Text = text,
                TextAlignment = Windows.UI.Xaml.TextAlignment.Left,
                TextWrapping = Windows.UI.Xaml.TextWrapping.Wrap,
                FontSize = 14
             };

             flyout.Show();
          }
        );
        e.Request.ApplicationCommands.Add(settingsCommand);
     };
  }
}

The text of the privacy policy is kept in a text file under the Settings folder. We asynchronously open and read the content of the file and when the text is available we create a new TextBlock control and use it as the content of the flyout content control.

Then we have to initialize the settings pane when the application starts.

protected override void OnLaunched(LaunchActivatedEventArgs e)
{
    // ...
    
    // Ensure the current window is active
    Window.Current.Activate();

    PrivacyPolicy.Initialise();
}

When you start the application and swipe the right edge of the screen the charms bar shows up. Opening the Settings charm will now show two entries for the application: Privacy Policy and Permissions.

The next sample shows how to add an About page. It’s very similar actually.

internal static class AboutPage
{
  public static void Initialise()
  {
     SettingsPane settingsPane = SettingsPane.GetForCurrentView();

     settingsPane.CommandsRequested += (s, e) =>
     {
        SettingsCommand settingsCommand = new SettingsCommand(
          "ABOUT_ID",
          "About",    
          command =>
          {
             var flyout = new SettingsFlyout();
             flyout.Title = "About";

             var version = Package.Current.Id.Version;
             var versionstring = string.Format("{0}.{1}.{2}.{3}",
                version.Major, version.Minor, version.Build, version.Revision);

             flyout.Content = new TextBlock()
             {
                Text = "Created by Marius Bancila\r\nVersion "+
                       versionstring+
                       "\r\n\r\nThis is a demo app that shows how to work with Windows Settings Charm.",
                TextAlignment = Windows.UI.Xaml.TextAlignment.Left,
                TextWrapping = Windows.UI.Xaml.TextWrapping.Wrap,
                FontSize = 14
             };

             flyout.Show();
          }
        );
        e.Request.ApplicationCommands.Add(settingsCommand);
     };
  }
}

protected override void OnLaunched(LaunchActivatedEventArgs e)
{
    // ...
    
    // Ensure the current window is active
    Window.Current.Activate();

    AboutPage.Initialise();
    PrivacyPolicy.Initialise();
}

Notice that the entries in the settings charm appear in the order they where added.

The content of the flyout can be any visual object (the simple TextBlock is used only for demo purposes). It is also possible to customize the flyout header, icon, background, etc. Here is the same About page with additional flyout settings.

var flyout = new SettingsFlyout();
flyout.Title = "About";
flyout.HeaderBackground = new SolidColorBrush(Colors.DeepSkyBlue);
flyout.HeaderForeground = new SolidColorBrush(Colors.Black);
flyout.IconSource = new BitmapImage(new Uri("ms-appx:///Images/about.png"));
flyout.Background = new SolidColorBrush(Colors.Wheat);

Here is some additional reading: Guidelines for app settings (Windows Store apps).