Add an app bar to a DirectX game

[This documentation is preliminary and is subject to change.]

In this topic, you will learn about adding an app bar to a DirectX 11.1 game for the Windows Store using C++. We'll explore the charms, the Settings charm, related store requirements, and how to add an app bar by using C++ and XAML.

Note  If your game does not use XAML, see Creating an app bar or Setting (DirectX and C++) for information about detecting when the app bar is invoked by the user.

The example code in this topic is already included in the Direct3DGame_XAML template. See the Use DirectX with a XAML overlay topic for more information.

What is an app bar

In a game, the main interaction the player has with the app is through the game controls. The app bar provides an interface in addition to your game controls. Use the app bar to present menu navigation, commands, and tools to users. The app bar is hidden by default and appears when users swipe a finger from the top or bottom edge of the screen. It covers the content of the app and can be dismissed by the user with an edge swipe, or by interacting with the game.

Here is an image of the app bar.

You determine the commands to be displayed on the app bar. The example in this topic uses XAML and C++ to display the app bar.

Why use an app bar in a game

An app bar allows you to give players additional commands on demand and in context to the current state of the game. The app bar is a standard Windows Store control across all apps, so users do not have to learn a new UI on top of your game controls.

You might want to use these commands in your game app bar:

• Restart the level.
• Save the game.
• Load a game.
• Return to the main menu.
• View high scores.
• In-game purchases.

You might want different commands depending on your game category. For example, a roleplaying game might have app bar commands to open the inventory or display the map. Or, a strategy game might have an app bar command to create a unit.

Adding an app bar using XAML and C++

Adding an app bar involves a code in a .xaml file and its associated .h and .cpp files. In the Direct3DGame_XAML template template, these files are named Direct3DPage.xaml, Direct3DPage.xaml.h, and Direct3DPage.xaml.cpp.

Design the app bar in XAML

The code here shows how to add a bottom app bar to the XAML file.

    <Page.BottomAppBar>
        <AppBar x:Name="bottomAppBar" Padding="10,0,10,0" 
                Opened="AppBar_Opened" Closed="AppBar_Closed">
            <Grid>
                <StackPanel Orientation="Horizontal" HorizontalAlignment="Left">
                    <Button Style="{StaticResource EditAppBarButtonStyle}" Click="EditButton_Click"/>
                </StackPanel>
            </Grid>
        </AppBar>
    </Page.BottomAppBar>

You add an app bar to your game by assigning an AppBar control to the TopAppBar or BottomAppBar property of a Page.

Your game might need to pause when the app bar opens and resume when it closes. The Opened and Closed attributes of the AppBar specify the methods that handle the app bar state changes.

Note  The app bar button style that is used in the preceding example is located in the StandardStyles.xaml file. In the Direct3DGame_XAML template these are available to use. However in Microsoft Visual Studio 2012 project templates, the app bar button styles are commented out in StandardStyles.xaml. For more info, see Quickstart: Styling app bar buttons.

Handle the app bar events

The code here declares the handlers that were specified for the app bar control in the previous XAML code.

        void EditButton_Click( Platform::Object^ sender, Windows::UI::Xaml::RoutedEventArgs^ e );
        void AppBar_Opened( Platform::Object^ sender, Platform::Object^ e );
        void AppBar_Closed( Platform::Object^ sender, Platform::Object^ e );

In the Direct3DGame_XAML template, the preceding code is in the Direct3DPage.xaml.h file.

The code here defines the event handlers for the app bar open, close, and button events.

// Handles the edit button event.
void Direct3DPage::EditButton_Click
    (Platform::Object^ sender, Windows::UI::Xaml::RoutedEventArgs^ e)
{
    // Use the app bar if it is appropriate for your app. Design the app bar, 
    // then fill in event handlers (like this one).
}

// Handles the AppBar open event.
void Direct3DPage::AppBar_Opened(Platform::Object^ sender, Platform::Object^ e)
{
    // If you need something to happen when the app bar opens, do it here.
       m_paused = true;
}

// Handles the AppBar close event.
void Direct3DPage::AppBar_Closed(Platform::Object^ sender, Platform::Object^ e)
{
    // If you need something to happen when the app bar closes, do it here.
       m_paused = false;
}

The AppBar_Opened and AppBar_Closed methods here pause and resume the game when triggered. You should also put any other game code that you want to run when the app bar opens or closes.

Further resources

For additional information on adding an app bar with XAML, see Adding app bars (Windows Store apps using C#/VB/C++ and XAML).

Build date: 3/22/2013