Skip to content

Latest commit

 

History

History
70 lines (45 loc) · 4.09 KB

bitmapicon.md

File metadata and controls

70 lines (45 loc) · 4.09 KB
-api-id -api-type
T:Windows.UI.Xaml.Controls.BitmapIcon
winrt class

Windows.UI.Xaml.Controls.BitmapIcon

-description

Represents an icon that uses a bitmap as its content.

-xaml-syntax

<BitmapIcon .../>

-remarks

Note

BitmapIcon is typically used to provide the icon for an AppBarButton, and the remarks in this section assume this usage. However, it can be used anywhere a UIElement can be used. The remarks apply to all usages.

To use a BitmapIcon as the Icon for an AppBarButton, you specify the URI of an image file.

The file that you use should be a solid image on a transparent background. The bitmap image as retrieved from the UriSource location is expected to be a true bitmap that has transparent pixels and non-transparent pixels. The recommended format is PNG. Other file-format image sources will load apparently without error but result in a solid block of the foreground color inside the AppBarButton. This behavior can be ignored by setting the ShowAsMonochrome property to false.

All color info is stripped from the bitmap when the BitmapIcon is rendered. The remaining non-transparent colors are combined to produce an image that's entirely the foreground color as set by the Foreground property (this typically comes from styles or templates, such as the default template resolving to a theme resource). You can override this behavior by setting the ShowAsMonochrome property.

The value of the Foreground property must be a SolidColorBrush. After the Foreground's Color property is read, changes to it are ignored. To change the color you must change the value of the Foreground property itself to a new SolidColorBrush.

Note

You can set the Foreground property on the AppBarButton or on the BitmapIcon. If you set the Foreground on the AppBarButton, it's applied only to the default visual state. It's not applied to the other visual states defined in the AppBarButton template, like MouseOver. If you set the Foreground on the BitmapIcon, the color is applied to all visual states.

The default font size for an AppBarButton Icon is 20px.

You typically specify a UriSource value that references a bitmap that you've included as part of the app, as a resource or otherwise within the app package. For more info on the ms-appx: scheme and other URI schemes that you can use to reference resources in your app, see Uri schemes.

Version history

Windows version SDK version Value added
1703 15063 ShowAsMonochrome

-examples

Tip

For more info, design guidance, and code examples, see Command bar.

[!div class="nextstepaction"] Open the WinUI 2 Gallery app and see the BitmapIcon in action

The WinUI 2 Gallery app includes interactive examples of most WinUI 2 controls, features, and functionality. Get the app from the Microsoft Store or get the source code on GitHub.

This example shows an AppBarButton with a BitmapIcon. The UriSource specifies an image that's included in the app package.

<AppBarButton Label="BitmapIcon" Click="AppBarButton_Click">
    <AppBarButton.Icon>
        <BitmapIcon UriSource="ms-appx:///Assets/globe.png"/>
    </AppBarButton.Icon>
</AppBarButton>

-see-also

IconElement, AppBarButton, Icons for UWP apps