Creating a settings widget
Game Bar provides a consistent user experience for opening a settings widget for a parent widget.
A widget is able to add a settings button to its title bar using an entry in its app manifest. That entry will point to another widget you create in your application called a settings widget. When a user presses the settings button, your main widget is notified the button was pressed. From there you should activate your settings widget as you would any other widget.
Configure your existing widget to use settings
Existing widgets require two changes to provide support for a settings button and widget. First let's make the necessary changes to the app manifest.
Open your Package.appxmanifest in an XML or text editor, and modify your existing widget entry to include a <SettingsSupported /> element. This entry defines the additional widget you will create to represent your settings widget
<Application ...>
...
<Extensions>
<uap3:Extension Category="windows.appExtension">
<uap3:AppExtension Name="microsoft.gameBarUIExtension"
Id="YourUniqueIdHere"
DisplayName="Display name for your widget"
Description="Description for your widget"
PublicFolder="GameBar\Ext1">
<uap3:Properties>
<GameBarWidget Type="Standard">
...
<!-- insert a SettingsSupport element into your GameBarWidget, the AppExtensionId should match that of the additional widget you will create and use as a settings widget>-->
<SettingsSupported AppExtensionId="YourSettingsExtensionId" />
...
</GameBarWidget>
</uap3:Properties>
</uap3:AppExtension>
Depending on your applications needs you can create one or more settings widget for all the widget. You may choose to create one settings widget for all the widgets in your application, or for each widget; any combination is possible.
Create a settings widget
Creating a settings widget is no different from creating a regular widget, except that the widget should be marked as <GameBarWidget Type="Settings">. This tells Game Bar to treat the widget differently.
<Application ...>
...
<Extensions>
<uap3:Extension Category="windows.appExtension">
<uap3:AppExtension Name="microsoft.gameBarUIExtension"
Id="YourPrimaryWidgetId"
DisplayName="Display name for your widget"
Description="Description for your widget"
PublicFolder="GameBar\YourWidget">
<uap3:Properties>
...
</uap3:Properties>
</uap3:AppExtension>
</uap3:Extension>
<uap3:Extension Category="windows.appExtension">
<uap3:AppExtension Name="microsoft.gameBarUIExtension"
Id="YourSettingsWidgetId"
DisplayName="Display name for your settings widget"
Description="Description for your settings widget"
PublicFolder="GameBar\YourWidget">
<uap3:Properties>
<!--When creating your settings widget, be sure to set its type to "Settings" -->
<GameBarWidget Type="Settings">
...
</GameBarWidget>
</uap3:Properties>
</uap3:AppExtension>
</uap3:Extension>
</Extensions>
</Application>
Open your settings widget
A small amount of work is required for a parent widget to open its settings. Game Bar is responsible for listening to the button clicked event in the title bar and notifying the corresponding parent widget, which must then respond to the event and activate its settings. This scheme allows you to perform any setup work prior to activating the settings widget, but if no extra work is required, you can simply activate the settings widget immediately upon receiving the event.
Subscribe to the SettingsClicked event
Your widget must subscribe to the XboxGameBarWidget.SettingsClicked event. To do so, you must provide a way for the widget to access the XboxGameBarWidget object. In our samples, we pass the object as a parameter to the OnNavigatedTo event. You may wish to implement this differently, but ultimately the parent widget will need access to this object to subscribe.
protected override void OnNavigatedTo(NavigationEventArgs e)
{
// In our example we pass the XboxGameBarWidget through the Navigate event when creating and showing the parent widget for the first time, your implementation may differ.
// Here we store the parameter in a member variable "widget":
widget = e.Parameter as XboxGameBarWidget;
// Hook up the settings clicked event
widget.SettingsClicked += Widget_SettingsClicked;
// ...
}
Once the event is setup, you widget will receive a notification when the user interacts with the settings button in the title bar, prompting the settings widget activation.
private async void Widget_SettingsClicked(XboxGameBarWidget sender, object args)
{
// if necessary pre-configure any required data needed by the settings widget prior to activation
// ...
await sender.ActivateSettingsAsync();
}
Passing XboxGameBarWidget to OnNavigatedTo
For reference, here is an example of a widget activation where the XboxGameBarWidget is passed when navigating:
protected override void OnActivated(IActivatedEventArgs args)
{
// ...
if (widgetArgs.AppExtensionId == "YourPrimaryWidgetId")
{
widget1 = new XboxGameBarWidget(/*...*/)
// after creation of the XboxGameBarWidget it is passed a parameter to the widget when navigating to that page
rootFrame.Navigate(typeof(YourPrimaryWidget), widget1);
}
}
Activating your settings widget
After responding to the SettingsClicked event and calling XboxGameBarWidget.ActivateSettingsAsync to activate the settings widget, your app will need to be updated to handle the OnActivated event, which will immediately be called with the AppExtensionId. In simple scenarios your application may only assume the activation of one widget (adjust accordingly for more than one widget).
protected override void OnActivated(IActivatedEventArgs args)
{
XboxGameBarWidgetActivatedEventArgs widgetArgs = null;
if (args.Kind == ActivationKind.Protocol)
{
var protocolArgs = args as IProtocolActivatedEventArgs;
string scheme = protocolArgs.Uri.Scheme;
if (scheme.Equals("ms-gamebarwidget"))
{
widgetArgs = args as XboxGameBarWidgetActivatedEventArgs;
}
}
if (widgetArgs != null)
{
if (widgetArgs.IsLaunchActivation)
{
var rootFrame = new Frame();
Window.Current.Content = rootFrame;
// Navigate to correct view, the AppExtensionId should match the widget you wish to create and activate.
// The activation of a settings widget is no different from other widgets.
if (widgetArgs.AppExtensionId == "YourPrimaryWidgetId")
{
// This is the parent widget activation.
widget1 = new XboxGameBarWidget(
widgetArgs,
Window.Current.CoreWindow,
rootFrame);
rootFrame.Navigate(typeof(YourPrimaryWidget), widget1);
Window.Current.Closed += Widget1Window_Closed;
}
else if (widgetArgs.AppExtensionId == "YourSettingsWidgetId")
{
// This is the settings widget, the AppExtensionId should match your widget parameters as defined in the application manifest.
widget1Settings = new XboxGameBarWidget(
widgetArgs,
Window.Current.CoreWindow,
rootFrame);
rootFrame.Navigate(typeof(YourSettingsWidget));
Window.Current.Closed += Widget1SettingsWindow_Closed;
}
else
{
// Unknown - Game Bar should never send you an unknown App Extension Id
return;
}
Window.Current.Activate();
}
}
}
What makes a settings widget different
A widget which is marked as Type="Settings" behaves similarly to other widgets as you control the behavior of the loaded page. However, the following behavioral changes will take affect:
If a widget finds that it is of type settings, it will maximize, restore, and/or close along with its assigned parent(s). The settings widget behaves as a child to the parent widget.
A settings widget will not show up in the home menu, as mentioned, it is assumed that the settings widget is a child to the parent widget which has its own entry.
Settings widgets can't have settings - no widget inception here.
The following manifest entries are ignored and will always default as follows:
HomeMenuVisible- Always false, settings widgets never show in the home menu.PinningSupported- Always false, settings widgets cannot be pinned.ActivateAfterInstall- Always false, settings widgets will never automatically be activated.FavoriteAfterInstall- Always false, settings widgets will never automatically be marked as favorite.
More details about these settings can be found in the optional properties
SDK Samples
Samples for showing a settings button and opening the corresponding settings widget can be found on the XboxGameBarSamples GitHub page. In particular the WidgetSettingsSample, WidgetAdvSample, and WidgetAdvSampleCS all provide examples implementations as described above.