通过

Using custom widget icons in Game Bar

  • 项目

The following describes how to add support to your Game Bar widget so that your own icons can be used within Game Bar. By default Game Bar will use the default application icon for your UWP to display your widget in both the Home Bar and Home Menu. In order to better differentiate your widgets from others we recommend providing icons that uniquely represent each of your widgets.

Modify your package appx manifest

Open your Package.appxmanifest: Right-click Package.appxmanifest

  • Select "Open With..."
  • Select XML Text Editor

Ensure you have an <AppExtension> element. If not see Changes to your project for more information.

If your <AppExtension> element doesn't have a "PublicFolder" attribute, add it now. You can provide any name you want. This is the location that Game Bar will be able to read files from.

In this sample the Widget1 widget uses the public folder Widget1Assets:

<uap3:AppExtension Name="microsoft.gameBarUIExtension"
                    Id="Widget1"
                    DisplayName="Widget 1"
                    Description="Widget 1 Description"
                    PublicFolder="Widget1Assets">

Create folders

From the root of your project's folder, add a folder with the same name that you specified in your AppX Manifest as the "PublicFolder".

Now, create a sub-folder within called "Icons". This is the actual location where you will place your icon asset files.

You should now have the following folder structure:

  • $ProjectDir
    • $PublicFolderName
      • Icons

Updating your project

Right-click on your widget project and choose Add -> New Filter and make the name the same as your "PublicFolder". Add another filter within and name it "Icons" to match the directory structure you just made. This is where your assets will be added to your project.

Formatting your image assets

The format of the assets should be .PNG. We recommend filling the entire space, except for a 1-pixel border around the edges. The background should be transparent.

It is recommended to provide the following sizes to handle various locations it will be displayed in the UI, as well as ensuring that your asset will still look good when the system is in high DPI mode.

16x16, 20x20, 24x24, 32x32, 44x44, 256x256

All of these sizes will be used for both dark and light theme. If you want to have different icons for light and dark theme, you can provide both sets using the following naming convention:

  • Dark theme assets: icon.targetsize-{size}.png
  • Light theme assets: icon.light.targetsize-{size}.png

{size} will be the first value from the list of sizes above, e.g. icon.targetsize-16.png

Verifying your custom image assets

When you re-deploy your widget you should see the new assets reflected in the Home Menu, the Home Bar, and the title bar of your overlay.

If you provided both light and dark theme assets, you can change the theme within Game Bar from the Game Bar settings to ensure they look how you want.

While we recommend providing specific assets for your widget following these steps, if none are provided we will instead fall back to using one of the images from your package. This will work, but generally will not look as polished.

Icon Samples

Our samples include a demonstration of incorporating proper assets into your widget. You can look at WidgetAdvSample for reference. This sample includes two widgets that both use different icons.

To see a sample of how Game Bar will use a fallback asset from your package, look at WidgetSampleCS or WidgetSampleCX.