Changes to your apps activation

Code examples below will be shown in C++/WinRT. For C#, the changes are the same but different syntax. Refer to the WidgetSampleCS sample project for exact code changes if necessary.

Unlike a foreground activation launch where your app's OnLaunched method will be called, Game Bar activation will occur via a OnActivated launch. The ActivationKind will be Protocol. The type of protocol launch will be ms-gamebarwidget:.

Update OnActivated

If your App class doesn't already have OnActivated, add one now.

In App.h add:

struct App : AppT<App>
{
    void OnActivated(Windows::ApplicationModel::Activation::IActivatedEventArgs const& args);
    // ...
}

Update your App class

In App.cpp add:

void App::OnActivated(IActivatedEventArgs const& e)
{
}

Add Game Bar namespace to top of App.cpp:

using namespace Microsoft::Gaming::XboxGameBar;

If using C++/WinRT, add the following header to your pch.h file:

#include <winrt/Microsoft.Gaming.XboxGameBar.h>

Handle OnActivated event

---

Game Bar Widget activations occur as a Protocol activation with the URI scheme set to ms-gamebarwidget. You'll first check the activation kind, then examine the URI, and if it matches Game Bar Widget you will cast the args to XboxGameBarWidgetActivatedEventArgs. In App.cpp add

void App::OnActivated(IActivatedEventArgs const& e)
{
    XboxGameBarWidgetActivatedEventArgs widgetArgs{ nullptr };
    if (e.Kind() == ActivationKind::Protocol)
    {
        auto protocolArgs = e.try_as<IProtocolActivatedEventArgs>();
        if (protocolArgs)
        {
            const wchar_t* scheme = protocolArgs.Uri().SchemeName().c_str();
            if (0 == wcscmp(scheme, L"ms-gamebarwidget"))
            {
                widgetArgs = e.try_as<XboxGameBarWidgetActivatedEventArgs>();
            }
        }
    }
    if (widgetArgs)
    {
        if (widgetArgs.IsLaunchActivation())
        {
            // Game Bar Widget activation work here
        }
        else
        {
            // Repeat activation for this widget. Ignore, or respond to URI payload
        }
    }
}

Creating your frame

Create your Frame and set the current Window's contents to it.

if (widgetArgs)
{
    auto rootFrame = Frame();
    rootFrame.NavigationFailed({ this, &App::OnNavigationFailed });
    Window::Current().Content(rootFrame);
}

In App.h App class, add the following member to hold the XboxGameBarWidget object

private:
    Microsoft::Gaming::XboxGameBar::XboxGameBarWidget m_widget{ nullptr };

Instantiate XboxGameBarWidget

Instantiate the XboxGameBarWidget object with your args object, core window, and frame. The XboxGameBarWidget object must be held for the lifetime of your App object (App class member works fine). More on XboxGameBarWidget below.

m_widget = XboxGameBarWidget(widgetArgs, Window::Current().CoreWindow(), rootFrame);

Navigate to your widget page and activate

    rootFrame.Navigate(xaml_typename<WidgetSample::Widget1>());
    Window::Current().Activate();

Listen to window closed event for cleanup

In App.h App class, add the following member to hold the event_token for the window closed event.

    event_token m_widget1WindowClosedHandlerToken{};

Add the declaration for the event handler method.

    void Widget1WindowClosedHandler(IInspectable const&, IInspectable const&);

In App.cpp after initializing your m_widget object, register for the window closed event

    m_widget1WindowClosedHandlerToken = Window::Current().Closed(
        { get_weak(), &App::Widget1WindowClosedHandler });

Implement the handler method

    void App::Widget1WindowClosedHandler(IInspectable const&, IInspectable const&)
    {
        // Release widget object
        m_widget1 = nullptr;
        // Unregister from window closed event
        Window::Current().Closed(m_widget1WindowClosedHandlerToken);
    }

NOTE: The window closed event will only fire when your widget is closed and it is not the last widget open for your app (assuming your app has multiple widgets). If you only have a single widget, this event will never be called. When the last widget is closed for your app, you will get the App::OnSuspending call. It is not necessary to cleanup the widget object during the App::OnSuspending since it will automatically be cleaned up in this case. However, you can leverage App::OnSuspending to cleanup other data or save state as you would with any other UWP app.

About XboxGameBarWidget

This object has multiple purposes:

1. On creation it creates a private communication channel between your widget and Game Bar to ensure the proper input/focus transitions occur. This happens automatically without any addition work from you.

2. Provides methods, properties, and events for your widget to communicate with Game Bar.

3. Provides required context for some Game Bar SDK APIs.

Repeated Activations

---

Your widget can be activated multiple times beyond the initial launch activation. This can occur primarily if your widget supports receiving commands from other widgets. For example, Widget A could send repeated activations to Widget B to control it. Each activation will come through the same activation path as described above, but there is an important difference: during the initial launch activation you MUST create the XboxGameBarWidget object, and on repeat activations you MUST NOT create it.

You can tell if you're getting your initial launch activation or not, by observing the corresponding property on the XboxGameBarWidgetActivatedEventArgs object: IsLaunchActivation(). The advanced sample demonstrates leveraging this property.

ms-gamebarwidget URI scheme

With all activations from Game Bar, your widget will receive a protocol activation with a scheme of ms-gamebarwidget. Here is the format of that URI:

ms-gamebarwidget:<appExtensionId>[?query][#fragment]

Parameter	Definition
?query	Defined by each widget
[#fragment]	Defined by each widget

Notice the query and fragment portions are defined by you as the widget developer. When you perform widget to widget commands (activations), you will be able to control the query and fragment portions of the URI. More on widget control APIs in the API reference section.