Quickstart: Adding app bar buttons
[ This article is for Windows 8.x and Windows Phone 8.x developers writing Windows Runtime apps. If you’re developing for Windows 10, see the latest documentation ]
Commands in an app bar are typically shown using a special style with a round button, an icon, and a text label. You can use AppBarButton, AppBarToggleButton , and AppBarSeparator controls to more easily create app bars that reflect the proper design guidelines and behaviors.
App bar buttons differ from standard buttons in several ways:
- The default appearance is a circle instead of a rectangle.
- You use the Label and Icon properties to set the content instead of the Content property. The Content property is ignored when the Icon property is set.
- The button has the IsCompact property to control its size.
.png)
Prerequisites
- We assume that you can add controls to a basic Windows Store app using C++, C#, or Visual Basic. For instructions on adding a control, see Quickstart: Adding controls and handling events.
- Quickstart: Adding app bars
- Review Commanding design for Windows Store apps.
Set the icon and label (Windows 8.1)
Windows 8.1: This step applies only to Windows 8.1.
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 4 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 predefined list of glyphs from the Segoe UI Symbol font.
This example shows an AppBarButton with a SymbolIcon.
<AppBarButton Icon="Like" Label="SymbolIcon" Click="AppBarButton_Click"/>
This example shows an AppBarButton with a BitmapIcon.
<AppBarButton Label="BitmapIcon" Click="AppBarButton_Click">
<AppBarButton.Icon>
<BitmapIcon UriSource="ms-appx:///Assets/globe.png"/>
</AppBarButton.Icon>
</AppBarButton>
This example shows an AppBarToggleButton with a FontIcon.
<!-- App bar toggle button with font icon. -->
<AppBarToggleButton Label="FontIcon" Click="AppBarButton_Click">
<AppBarToggleButton.Icon>
<FontIcon FontFamily="Candara" Glyph="Σ"/>
</AppBarToggleButton.Icon>
</AppBarToggleButton>
This example shows an AppBarToggleButton with a PathIcon.
<AppBarToggleButton Label="PathIcon" Click="AppBarButton_Click">
<AppBarToggleButton.Icon>
<PathIcon Data="F1 M 20,20L 24,10L 24,24L 5,24"/>
</AppBarToggleButton.Icon>
</AppBarToggleButton>
This example creates these controls:
.jpg)
Make the button compact (Windows 8.1)
Windows 8.1: This step applies only to Windows 8.1.
The app bar button controls have two sizes; normal and compact. By default, they have a text label and full padding. When the IsCompact property is set to true, the text label is hidden and the padding around the buttons is reduced. The AppBarSeparator also has a compact state in which the padding is reduced.
Here are the same commands shown before, but in their compact state.
.png)
When used in the new CommandBar control, the CommandBar sets the IsCompact property automatically. If you use an app bar button outside of a CommandBar, like in an AppBar or the app canvas, you need to set the IsCompact property appropriately in your code.
App bar buttons can be used outside of an app bar. A common use is to use an app bar button as a Back button in a page header. When used outside of an app bar, Windows guidelines indicate that the button should always be in its compact state.
Use a standard app bar button style (Windows 8)
Windows 8: This step applies only to Windows 8. In Windows 8.1, AppBarButtonStyle is deprecated and replaced with AppBarButton controls.
All Microsoft Visual Studio 2012 project templates include the StandardStyles.xaml file in the Common folder. This file contains styles and resources that give your app the look and feel of a Windows Store app. It includes 192 styles for use with app bar buttons. These styles are based on the AppBarButtonStyle resource, which provides the template and visual states for the app bar button. The AppBarButtonStyle uses a glyph from the Segoe UI Symbol font as the icon shown in the button. To see the available button styles, see AppBar button style images.
By default, the app bar button styles are commented out in StandardStyles.xaml. To use a style, you must un-comment the Extensible Application Markup Language (XAML) for the Style resource in the file.
Tip The app bar button styles are commented out because parsing the XAML and loading the resources affects performance. Only un-comment styles that you use in your app. For more info, see Optimize loading XAML.
.gif)
To make an app bar button style available
In Solution Explorer, expand the Common folder and double-click StandardStyles.xaml to open it.
Find the Style for the app bar button you want to use.
Tip Press Ctrl+F to open the Find window and search for a style by key or by name.
For example, here's the XAML for the "PicturesAppBarButtonStyle" Style.
<Style x:Key="PicturesAppBarButtonStyle" TargetType="ButtonBase" BasedOn="{StaticResource AppBarButtonStyle}"> <Setter Property="AutomationProperties.AutomationId" Value="PicturesAppBarButton"/> <Setter Property="AutomationProperties.Name" Value="Pictures"/> <Setter Property="Content" Value=""/> </Style>Move the Style resource outside of the comment block (
<!-- comment -->) to make it available to use.Save and close StandardStyles.xaml.
To use an app bar button style in Visual Studio
In your XAML page, select the app bar Button element to apply the style to.
Clear the Content property of the Button.
The button content is set by the app bar button style.
Under Miscellaneous in the Properties panel, find the Style property.
Click the property marker next to the Style property to open the menu.
Note The property marker is the small box symbol to the right of each property value.
In the menu, select Local Resource and then select the app bar button style to use. For example, Local Resource > PicturesAppBarButtonStyle.
To use an app bar button style in Blend
In your XAML page, select the app bar Button element to apply the style to.
Clear the Content property of the Button.
The button content is set by the app bar button style.
Open the Resources tab, and expand the StandardStyles.xaml section.
Drag the style you want to use from the Resources panel and drop it on the app bar button.
Customize an app bar button (Windows 8)
Windows 8: This step applies only to Windows 8. In Windows 8.1, AppBarButtonStyle is deprecated and replaced with AppBarButton controls.
You can customize an app bar button in several ways. A typical Button has only one piece of content, which you can set to text, an image, or other UIElement. An app bar button has both an icon and a text label. In the AppBarButtonStyle resource, the icon is specified by setting the Content property of the button, and the text label is specified by setting the AutomationProperties.Name attached property. Using the AutomationProperties.Name property has the benefit of making the button text readable by screen reader software.
To change only the text label, you can override the AutomationProperties.Name property. For example, this is useful to localize the text label.
Here’s an app bar button with its AutomationProperties.Name property set to a StaticResource that overrides the default text label.
<Button Style="{StaticResource PicturesAppBarButtonStyle}"
AutomationProperties.Name="{StaticResource localizedPictureText"}/>
If the glyph you want to use isn't defined in a standard style, you can use the AppBarButtonStyle base style and specify the Content property and AutomationProperties.Name attached property as shown here. You specify the button icon by setting the Content property to a glyph in the Segoe UI Symbol font.
Tip You can use the Character Map utility in Windows to see the font glyphs and get their hex values.
This XAML shows how to use the Square Root glyph from the Segoe UI Symbol font in an app bar button.
<Button Style="{StaticResource AppBarButtonStyle}"
AutomationProperties.Name="Square Root"
Content="√"/>
To make the app bar button style reusable, you can specify the properties in a new Style resource based on the AppBarButtonStyle base style.
This XAML produces the same result as the previous example, but uses a reusable Style resource.
<App.Resources>
...
<Style x:Key="SquareRootAppBarButtonStyle"
BasedOn="{StaticResource AppBarButtonStyle}"
AutomationProperties.Name="Square Root"
Content="√"/>
...
<App.Resources>
...
<Button Style="{StaticResource SquareRootAppBarButtonStyle}"/>
To use a symbol from a font other than Segoe UI Symbol, you can override the FontFamily property that's set in the AppBarButtonStyle resource to specify a different font.
This XAML sets the app bar button content to a glyph from the Wingdings font.
<Button Style="{StaticResource AppBarButtonStyle}"
FontFamily="Wingdings"
AutomationProperties.Name="Glasses"
Content="$"/>
Use a custom Path as an app bar button icon (Windows 8)
Windows 8: This step applies only to Windows 8. In Windows 8.1, AppBarButtonStyle is deprecated and replaced with AppBarButton controls.
If you need to use an icon that isn’t available as a font glyph, you can use a XAML Path element to specify an icon. When you create an icon using a Path, by default it doesn’t respond to states like pointer over, pressed, and disabled the way a font glyph does. This is because the visual states in the AppBarButtonStyle resource change the Foreground property of the font glyph. A Path element doesn’t have a Foreground property, so you must change its Stroke and Fill properties instead. You can do this by binding its Stroke and Fill properties to the button's Foreground property. For more info about this binding, see RelativeSource markup extension.
Here, a Path element is used to create a custom Square Root icon. This simple Path doesn't have a Fill value, so only the Stroke property is bound to the button's Foreground property.
<Button Style="{StaticResource AppBarButtonStyle}"
AutomationProperties.Name="Square Root" >
<Button.ContentTemplate>
<DataTemplate>
<Path Data="F1 M 1,5L 5,5L 9,15L 15,1L 27,1"
Stroke="{Binding Foreground, RelativeSource={RelativeSource Mode=TemplatedParent}}"
Width="20" Height="20" StrokeThickness="2" Stretch="Uniform"/>
</DataTemplate>
</Button.ContentTemplate>
</Button>