Quickstart: Add app help (Windows Store apps using C++, C#, or Visual Basic)

[アーティクル]
02/04/2016

[ This article is for Windows 8.x and Windows Phone 8.x developers writing Windows Runtime apps. If you’re developing for Windows 10, see the latest documentation ]

Add help to your app using the XAMLSettingsFlyout control.

The following steps walk you through the process of adding a Help flyout to your Windows Store app using the SettingsFlyout control. Using this XAML control makes it easy to add a Help command to your app's Settings pane and supports consistent flyout design.

In this quickstart, you'll add a new SettingsFlyout to an existing Microsoft Visual Studio 2013 project, learn how you can modify and style the default content, and create two ways for users to access your Help flyout: from a Help button on a bottom app bar and from your app's Settings pane.

Writing apps with Javascript and HTML? See Quickstart: add app help (Windows Store apps using Javascript and HTML).

Prerequisites

To download Visual Studio 2013 and Windows 8.1, see Get the tools.

This quickstart assumes you want to add help 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:

Add a SettingsFlyout to your app

Follow these steps to create a SettingsFlyout for your existing Windows Store app. The default SettingsFlyout control has a header section with a title, back button, and logo icon, as well as a 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 HelpSettingsFlyout. Visual Studio 2013 creates a HelpSettingsFlyout.xaml file and a corresponding HelpSettingsFlyout.xaml.cs file. These HelpSettingsFlyout files now appear with the rest of your project files in Solution Explorer.

Replace the default SettingsFlyout content with help that is specific to your app, 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. The default width for a SettingsFlyout is narrow (346px).
Display a different logo icon or remove the logo icon by resetting or removing the IconSource property.
Change the color scheme or fonts using 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 content sections as needed. If your app has a support resource online, consider linking there from your Help flyout.

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

The code below is nearly identical to a default SettingsFlyout except that it has a different title, contains an additional text block, and includes a hyperlink button. You can add this code to your HelpSettingsFlyout.xaml file.

Important: This SettingsFlyout was created in a project called AppHelpExample. In order for this code to work in your project, replace x:Class="AppHelpExample.HelpSettingsFlyout" with x:Class="<name of your project>.HelpSettingsFlyout" and xmlns:local="using:AppHelpExample" to xmlns:local="using:<name of your project>".

<SettingsFlyout
    x:Class="AppHelpExample.HelpSettingsFlyout"
    xmlns="https://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="https://schemas.microsoft.com/winfx/2006/xaml"
    xmlns:local="using:AppHelpExample"
    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="Help"
    d:DesignWidth="346">

    <!-- The width of a SettingsFlyout is adjustable (default width is 346px) -->
    <!-- The SettingsFlyout control automatically adjusts to match screen height -->
   
    <!-- This StackPanel organizes the flyout's content sections vertically -->
    <StackPanel VerticalAlignment="Stretch" HorizontalAlignment="Stretch" >

        <!-- The StackPanel(s) below define individual content sections -->

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

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

            <!-- Section 1 body -->
            <TextBlock Style="{StaticResource BodyTextBlockStyle}" Margin="0,0,0,25" TextWrapping="Wrap">
                <TextBlock.Text>
                   <!-- Replace with your own Help content -->
                    Help content is a single page that can include text, links, and images. To provide the most current content, consider linking to a support page.
                </TextBlock.Text>
            </TextBlock>

            <!--New TextBlock-->
            <TextBlock Style="{StaticResource BodyTextBlockStyle}">
                <TextBlock.Text>
                    Not sure what to include in your Help flyout? See:
                </TextBlock.Text>
            </TextBlock>

            <HyperlinkButton NavigateUri="https://go.microsoft.com/fwlink/p/?LinkID=275435" HorizontalAlignment="Center" Content="Guidelines for app help"/>
        </StackPanel>

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

    </StackPanel>
</SettingsFlyout>

Add a bottom app bar with a Help button

In the previous step, you created a fully functional Help flyout. Now, let users open your new Help flyout with the click of an app bar button. The code snippet below creates a bottom app bar with a Help button. This app bar appears when a user right-clicks anywhere on the page or swipes from the bottom of the screen. If a user clicks the Help button, the HelpButton_Click event is invoked.

To create a bottom app bar on the first page of your app, open your project's MainPage.xaml file and add the following XAML code:

    
<Page.BottomAppBar>
     <CommandBar x:Name="bottomAppBar" Background="#00b2f0">
         <AppBarButton Icon="Help" Label="Help" Click="HelpButton_Click"/>
     </CommandBar>
</Page.BottomAppBar>

The next bit of code handles the HelpButton_Click event you just added. The ShowIndependent method opens the Help flyout and returns to the app page when a user dismisses the flyout. The last line of this code snippet hides the bottom app bar from the screen when the Help flyout opens.

Add the following C# code to MainPage.xaml.cs:

private void HelpButton_Click(object sender, RoutedEventArgs e)
        {
            AppHelpExample.HelpSettingsFlyout helpSF = new AppHelpExample.HelpSettingsFlyout();
            // When the settings flyout is opened from the app bar instead of from
            // the setting charm, use the ShowIndependent() method.
            helpSF.ShowIndependent();
            bottomAppBar.IsOpen = false;
        }

After you add these two code snippets, build and run your app. Right-click or swipe from the bottom of the app's landing page and an app bar with a Help button should appear from the bottom of the screen. Click the button and the Help flyout will extend from the right side of the screen, as shown in the screen shot below.

Add Help to your app's Settings pane

When you use the SettingsFlyout control to create a Help flyout, you can easily add Help to your app's Settings pane. An app's Settings pane appears when a user swipes from the right edge of the screen and selects the Settings charm or presses Windows+I. For more info on app settings, skim our Guidelines for app settings. If you're curious about charms, see this Charms overview.

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 "Help" command to the Settings pane. SettingsCommand sets the custom setting's Label, Id, and Invoked properties. Set the Label property to the command 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 a command from the Settings pane. This example adds an event handler named ShowHelpSettingsFlyout. The event handler creates and opens the flyout when the user clicks “Help” in the Settings pane.

To add Help to your app's Settings pane, add following C# code to App.xaml.cs:

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

        private void OnCommandsRequested(SettingsPane sender, SettingsPaneCommandsRequestedEventArgs args)
        {

            args.Request.ApplicationCommands.Add(new SettingsCommand(
                "Help", "Help", (handler) => ShowHelpSettingsFlyout()));
        }

        public void ShowHelpSettingsFlyout()
        {
            HelpSettingsFlyout helpSF = new HelpSettingsFlyout();
            helpSF.Show();
        }

The process for adding other customized settings to your app's Settings pane is very similar to the steps described in this section. See Quickstart: Add app settings (Windows Store apps using C#/VB/C++) if you want to create additional settings and display them on your app's Settings pane.

Complete code examples

Here are complete copies of the four pages modified in this quickstart.

HelpSettingsFlyout.xaml: In order for this code to work in your project, replace x:Class="AppHelpExample.HelpSettingsFlyout" with x:Class="<name of your project>.HelpSettingsFlyout" and xmlns:local="using:AppHelpExample" to xmlns:local="using:<name of your project>".

<SettingsFlyout
    x:Class="AppHelpExample.HelpSettingsFlyout"
    xmlns="https://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="https://schemas.microsoft.com/winfx/2006/xaml"
    xmlns:local="using:AppHelpExample"
    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="Help"
    d:DesignWidth="346">

    <!-- The width of a SettingsFlyout is adjustable (default width is 346px) -->
    <!-- The SettingsFlyout control automatically adjusts to match screen height -->

    <!-- This StackPanel organizes the flyout's content sections vertically -->
    <StackPanel VerticalAlignment="Stretch" HorizontalAlignment="Stretch" >

        <!-- The StackPanel(s) below define individual content sections -->

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

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

            <!-- Section 1 body -->
            <TextBlock Style="{StaticResource BodyTextBlockStyle}" Margin="0,0,0,25" TextWrapping="Wrap">
                <TextBlock.Text>
                   <!-- Replace with your own Help content -->
                    Help content is a single page that can include text, links, and images. To provide the most current content, consider linking to a support page.
                </TextBlock.Text>
            </TextBlock>

            <!--New TextBlock-->
            <TextBlock Style="{StaticResource BodyTextBlockStyle}">
                <TextBlock.Text>
                    Not sure what to include in your Help flyout? See:
                </TextBlock.Text>
            </TextBlock>

            <HyperlinkButton NavigateUri="https://go.microsoft.com/fwlink/p/?LinkID=275435" HorizontalAlignment="Center" Content="Guidelines for app help"/>
        </StackPanel>

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

    </StackPanel>
</SettingsFlyout>

MainPage.xaml

<Page
    x:Class="AppHelpExample.MainPage"
    xmlns="https://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="https://schemas.microsoft.com/winfx/2006/xaml"
    xmlns:local="using:AppHelpExample"
    xmlns:d="https://schemas.microsoft.com/expression/blend/2008"
    xmlns:mc="https://schemas.openxmlformats.org/markup-compatibility/2006"
    mc:Ignorable="d">

    <Page.BottomAppBar>
        <CommandBar x:Name="bottomAppBar" Background="#00b2f0">
            <AppBarButton Icon="Help" Label="Help" Click="HelpButton_Click"/>
        </CommandBar>
    </Page.BottomAppBar>

    <Grid Background="{ThemeResource ApplicationPageBackgroundThemeBrush}">
    </Grid>
</Page>

MainPage.xaml.cs

using System.Linq;
using System.Runtime.InteropServices.WindowsRuntime;
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;

// The Blank Page item template is documented at https://go.microsoft.com/fwlink/p/?LinkID=234238

namespace AppHelpExample
{
    /// <summary>
    /// An empty page that can be used on its own or navigated to within a Frame.
    /// </summary>
    public sealed partial class MainPage : Page
    {
        public MainPage()
        {
            this.InitializeComponent();
        }

        private void HelpButton_Click(object sender, RoutedEventArgs e)
        {
            AppHelpExample.HelpSettingsFlyout helpSF = new AppHelpExample.HelpSettingsFlyout();
            // When the settings flyout is opened from the app bar instead of from
            // the setting charm, use the ShowIndependent() method.
            helpSF.ShowIndependent();
            bottomAppBar.IsOpen = false;
        }
    }
}

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 AppHelpExample
{
    /// <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(
                "Help", "Help", (handler) => ShowHelpSettingsFlyout()));
        }

        public void ShowHelpSettingsFlyout()
        {
            HelpSettingsFlyout helpSF = new HelpSettingsFlyout();
            helpSF.Show();
        }
    }
}

Summary

You've now added a Help flyout to your app using the SettingsFlyout control and enabled users to access Help from both a bottom app bar and the Settings pane.

Reference

SettingsFlyout class

SettingsFlyout.ShowIndependent method

SettingsFlyout.Show method

SettingsFlyout.IconSource property

Application.OnWindowCreated method

SettingsPane.CommandsRequested event

SettingsPane.Show method

AppBar class

Samples

App settings sample

Guidelines