Creating an app bar or Setting (DirectX and C++)

[ 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 ]

The app bar and Settings are a fundamental part of any Windows Store app. In a Windows Store app using DirectX with C++ without XAML interop, however, you must provide an implementation of the app bar and Setting charms yourself. In this topic, we discuss general methods to create an app bar or Setting in DirectX.

You put your app-specific commands in the app bar and any system-specific commands in the Setting charms. If you are creating a Windows Store apps that implements the UI framework directly through the CoreWindow object in C++ and DirectX, and want a consistent app bar, you will need to explicitly render it in your app's code.

The app bar and Settings in DirectX apps

In Windows 8, the app bar can provide additional app UI in a consistent and natural way. It is invoked in any of 3 standard ways:

  • Make a vertical edge gesture; that is, swipe up with a finger or stylus from the bottom of the screen, or swipe down from the top.
  • Right-click with the right mouse button.
  • Press the Windows key and the Z key together (Win+Z) on the keyboard.

Settings (charms) are invoked in the following ways:

  • Make a horizontal edge gesture; that is, swipe left with a finger or stylus from the right of the screen.
  • Press the Windows key and the C key together (Win+C) on the keyboard.

For Windows Store apps that use HTML or XAML for the UI framework, an app bar control is provided as part of that framework.

Creating an app bar or Setting with the EdgeGesture class

The EdgeGesture class has events that fire when the user performs a swipe gesture. A swipe gesture occurs in two ways:

  • For touch input, the user presses the surface and makes a slide movement.
  • For mouse input, the user clicks the left mouse button and hold it while making a slide movement.

The following code example shows how to register for and handle an edge gesture:

// register handler for edge gesture completion events
Windows::Devices::Input::EdgeGesture::GetForCurrentView()->Completed +=
        ref new TypedEventHandler<EdgeGesture^, EdgeGestureEventArgs^>(this, &MyEdgeUIController::OnCompleted);
void MyEdgeUIController::OnCompleted(
    _In_ Windows::Devices::Input::EdgeGesture^ userEdgeGesture,
    _In_ Windows::Devices::Input::EdgeGestureEventArgs^ args
    // determine the gesture and draw the corresponding app bar or charm(s)

The EdgeGesture::Completed occurs as a result of either touch or keyboard input. In the case of keyboard input (Win+Z or Win+C), this is the only event that fires. In the case of touch input, it occurs when the user lifts his or her finger at the end of the swipe and is preceded by the EdgeGesture::Starting event.

Drawing an app bar or Setting

Once you have determined that the user intended to invoke the app bar or charm from your Windows Store app using DirectX, you must draw the app bar or Setting. You should create and draw a bitmap with Direct2D and DirectWrite that represents the app bar or Setting into the overlay for your app, and process any touch or mouse events that occur in that bitmap's region of the screen while it is drawn.

The following code demonstrates how you can add a Setting with the SettingsCommand type.

using namespace Windows::UI::ApplicationSettings;
    SettingsPane::GetForCurrentView()->CommandsRequested += ref new TypedEventHandler<SettingsPane^,SettingsPaneCommandsRequestedEventArgs^>(
    [=](SettingsPane^ sender, SettingsPaneCommandsRequestedEventArgs^ args)
        using namespace Windows::UI::Popups;
            ref new SettingsCommand(
                "Setting Name Here",
                ref new UICommandInvokedHandler(
                    [=](IUICommand^ command)
                        // show results of settings selection

Guidelines and checklist for app bars (Windows Store apps)