| -api-id | -api-type |
|---|---|
T:Microsoft.UI.Xaml.Controls.AppBarButton |
winrt class |
Represents a templated button control to be displayed in an AppBar.
<AppBarButton .../>App bar buttons differ from standard buttons in several ways:
- The default appearance is a semi-transparent rectangle without a border.
- You use the Label and Icon properties to set the content instead of the Content property. The Content property is ignored if the Icon is set.
- The button has the IsCompact property to control its size.
AppBarButton has two sizes; normal and compact. By default, it's shown with a text label and full padding. When the IsCompact property is set to true, the text label is hidden and the height of the button is reduced.
Here are the same commands shown in their normal state, and then in their compact state.
When used in the CommandBar control as part of the PrimaryCommands collection, the CommandBar sets the IsCompact property automatically as the control opens and closes. If you use an app bar button elsewhere, like in the Content of a CommandBar, in an AppBar, or the app canvas, you need to set the IsCompact property appropriately in your code. When used outside of an app bar, Windows guidelines indicate that the button should always be in its compact state. You should also include a ToolTip to display the text label.
You use the Label and Icon properties to define the content of the app bar buttons. Set the Label property to a string to specify the text label. It's shown by default, and is hidden when the button is in its compact state, so you also need to define a meaningful icon. To define the app bar button icon, set the Icon property to an element derived from the IconElement class. There are four kinds of icon elements provided:
- FontIcon - the icon is based on a glyph from the specified font family.
- BitmapIcon - the icon is based on a bitmap image file with the specified Uri.
- PathIcon - the icon is based on Path data.
- SymbolIcon - the icon is based on a glyph from the Segoe MDL2 Assets font as listed in the Symbol enumeration.
- ImageIcon - the icon is based on an image file type supported by the Image class.
AppBarButton icons have a default font size of 20px.
You can modify the default Style and ControlTemplate to give the control a unique appearance. For information about modifying a control's style and template, see XAML styles. The default style, template, and resources that define the look of the control are included in the generic.xaml file. For design purposes, generic.xaml is installed with the Windows App SDK NuGet package. By default, this location is \Users\<username>\.nuget\packages\microsoft.windowsappsdk\<version>\lib\uap10.0\Microsoft.UI\Themes\generic.xaml. Styles and resources from different versions of the SDK might have different values.
XAML also includes resources that you can use to modify the colors of a control in different visual states without modifying the control template. Modifying these resources is preferred to setting properties such as Background and Foreground. For more info, see the Light-weight styling section of the XAML styles article.
Tip
For more info, design guidance, and code examples, see Command bar.
[!div class="nextstepaction"] Open the WinUI 3 Gallery app and see the AppBarButton in action
The WinUI 3 Gallery app includes interactive examples of most WinUI 3 controls, features, and functionality. Get the app from the Microsoft Store or get the source code on GitHub.
This example shows AppBarButton controls with each type of icon:
<!-- App bar button with symbol icon. -->
<AppBarButton Icon="Like" Label="SymbolIcon" Click="AppBarButton_Click"/>
<!-- App bar button with bitmap icon. -->
<AppBarButton Label="BitmapIcon" Click="AppBarButton_Click">
<AppBarButton.Icon>
<BitmapIcon UriSource="ms-appx:///Assets/Slices.png"/>
</AppBarButton.Icon>
</AppBarButton>
<!-- App bar button with font icon. -->
<AppBarButton Label="FontIcon" Click="AppBarButton_Click">
<AppBarButton.Icon>
<FontIcon FontFamily="Candara" Glyph="Σ"/>
</AppBarButton.Icon>
</AppBarButton>
<!-- App bar button with path icon. -->
<AppBarButton Label="PathIcon" Click="AppBarButton_Click">
<AppBarButton.Icon>
<PathIcon Data="F1 M 16,12 20,2L 20,16 1,16" HorizontalAlignment="Center"/>
</AppBarButton.Icon>
</AppBarButton>
<!-- App bar button with image icon. -->
<AppBarButton Label="ImageIcon" Click="AppBarButton_Click">
<AppBarButton.Icon>
<ImageIcon Source="ms-appx:///Assets/globe.png"/>
</AppBarButton.Icon>
</AppBarButton>Here's how to create the same AppBarButton controls in code.
void MainPage_Loaded(object sender, RoutedEventArgs e)
{
CommandBar bottomAppBar = this.BottomAppBar as CommandBar;
if (bottomAppBar != null)
{
// SymbolIcon
AppBarButton button1 = new AppBarButton();
button1.Icon = new SymbolIcon(Symbol.Like);
button1.Label = "SymbolIcon";
button1.Click += AppBarButton_Click;
bottomAppBar.PrimaryCommands.Add(button1);
// BitmapIcon
BitmapIcon bi = new BitmapIcon();
bi.UriSource = new Uri("ms-appx:///Assets/Slices.png");
AppBarButton button2 = new AppBarButton();
button2.Icon = bi;
button2.Label = "BitmapIcon";
button2.Click += AppBarButton_Click;
bottomAppBar.PrimaryCommands.Add(button2);
// FontIcon
FontIcon fi = new FontIcon();
fi.FontFamily = new Windows.UI.Xaml.Media.FontFamily("Candara");
fi.FontSize = 16;
fi.Glyph = "\u2211";
AppBarButton button3 = new AppBarButton();
button3.Icon = fi;
button3.Label = "FontIcon";
button3.Click += AppBarButton_Click;
bottomAppBar.PrimaryCommands.Add(button3);
// PathIcon
PathIcon pi = new PathIcon();
PathGeometry pg = new PathGeometry();
PathFigure pf = new PathFigure();
pf.IsFilled = true;
pf.IsClosed = true;
pf.StartPoint = new Windows.Foundation.Point(16.0, 12.0);
LineSegment s1 = new LineSegment();
s1.Point = new Windows.Foundation.Point(20.0, 2.0);
LineSegment s2 = new LineSegment();
s2.Point = new Windows.Foundation.Point(20.0, 16.0);
LineSegment s3 = new LineSegment();
s3.Point = new Windows.Foundation.Point(1.0, 16.0);
pf.Segments.Add(s1);
pf.Segments.Add(s2);
pf.Segments.Add(s3);
pg.Figures.Add(pf);
pi.Data = pg;
pi.HorizontalAlignment = HorizontalAlignment.Center;
AppBarButton button4 = new AppBarButton();
button4.Icon = pi;
button4.Label = "PathIcon";
button4.Click += AppBarButton_Click;
bottomAppBar.PrimaryCommands.Add(button4);
//ImageIcon
var source = new BitmapSource();
await source.SetSourceAsync(bitmapStream);
var ii = new ImageIcon() { Source = source };
AppBarButton button5 = new AppBarButton();
button5.Icon = ii;
button5.Label = "ImageIcon";
button5.Click += AppBarButton_Click;
bottomAppBar.PrimaryCommands.Add(button5);
}
}
void AppBarButton_Click(object sender, RoutedEventArgs e)
{
// Handle button click.
}This example shows how to change the Icon and Label of an AppBarButton that's initially defined in Extensible Application Markup Language (XAML). This code toggles a button between Play and Pause.
<Page.BottomAppBar>
<CommandBar>
<AppBarButton x:Name="PlayPauseButton" Tag="play" Icon="Play" Label="Play" Click="PlayPauseButton_Click"/>
<AppBarButton Icon="Stop" Label="Stop" Click="StopButton_Click"/>
</CommandBar>
</Page.BottomAppBar>private void PlayPauseButton_Click(object sender, RoutedEventArgs e)
{
// Using the Tag property value lets you localize the Label value
// without affecting the app code.
if ((string)PlayPauseButton.Tag == "play")
{
PlayPauseButton.Icon = new SymbolIcon(Symbol.Pause);
PlayPauseButton.Label = "Pause";
PlayPauseButton.Tag = "pause";
}
else
{
PlayPauseButton.Icon = new SymbolIcon(Symbol.Play);
PlayPauseButton.Label = "Play";
PlayPauseButton.Tag = "play";
}
}