App​Bar​Button App​Bar​Button App​Bar​Button Class

Definition

Represents a templated button control to be displayed in an AppBar.

public class AppBarButton : Button, IAppBarButton, IAppBarButton3, ICommandBarElement, ICommandBarElement2public class AppBarButton : Button, IAppBarButton, IAppBarButton3, ICommandBarElement, ICommandBarElement2Public Class AppBarButton Inherits Button Implements IAppBarButton, IAppBarButton3, ICommandBarElement, ICommandBarElement2
<AppBarButton .../>
Inheritance
Attributes
Windows 10 requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

Inherited Members

Inherited properties

Inherited events

Inherited methods

Remarks

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.

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 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 glyph from the Segoe MDL2 Assets font as listed in the Symbol enumeration.

Control style and template

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 Styling controls. 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 available in the (Program Files)\Windows Kits\10\DesignTime\CommonConfiguration\Neutral\UAP&lt;SDK version>\Generic folder from a Windows Software Development Kit (SDK) installation. Styles and resources from different versions of the SDK might have different values.

Starting in Windows 10, version 1607 (Windows Software Development Kit (SDK) version 10.0.14393.0), generic.xaml includes resources that you can use to modify the colors of a control in different visual states without modifying the control template. In apps that target this software development kit (SDK) or later, modifying these resources is preferred to setting properties such as Background and Foreground. For more info, see the Light-weight styling section of the Styling controls article.

This table shows the resources used by the AppBarButton control.

Resource keyDescription
AppBarButtonBackgroundBackground color at rest
AppBarButtonBackgroundPointerOverBackground color on hover
AppBarButtonBackgroundPressedBackground color when pressed
AppBarButtonBackgroundDisabledBackground color when disabled
AppBarButtonForegroundForeground color at rest
AppBarButtonForegroundPointerOverForeground color on hover
AppBarButtonForegroundPressedForeground color when pressed
AppBarButtonForegroundDisabledForeground color when disabled
AppBarButtonBorderBrushBorder color at rest
AppBarButtonBorderBrushPointerOverBorder color on hover
AppBarButtonBorderBrushPressedBorder color when pressed
AppBarButtonBorderBrushDisabledBorder color when disabled

Examples

This example shows AppBarButton controls with each type of icon:

App bar button icon examples.

<!-- 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="&#x03A3;"/>
    </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>

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);
    }
}

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";
    }  
}

Constructors

AppBarButton() AppBarButton() AppBarButton()

Initializes a new instance of the AppBarButton class.

public AppBarButton()public AppBarButton()Public Sub New()
Attributes

Properties

DynamicOverflowOrder DynamicOverflowOrder DynamicOverflowOrder

Gets or sets the order in which this item is moved to the CommandBar overflow menu.

public int DynamicOverflowOrder { get; set; }public int DynamicOverflowOrder { get; set; }Public ReadWrite Property DynamicOverflowOrder As int
<AppBarButton DynamicOverflowOrder="int" .../>
Value
int int int

The order in which this item is moved to the overflow menu relative to other items.

Attributes
Additional features and requirements
Device family
Windows 10 Anniversary Edition (introduced v10.0.14393.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v3)

Remarks

For more info and guidelines, see the App bar and command bar article.

Starting in Windows 10, version 1607, CommandBar introduces a dynamic overflow feature. By default, PrimaryCommands automatically move in or out of the overflow area as the command bar width changes, for example, when users resize their app window. You can set the IsDynamicOverflowEnabled property to false to disable this behavior.

Dynamic overflow affects only the UI presentation of the commands, it doesn’t move commands from the PrimaryCommands collection to SecondaryCommands.

This property has an effect only when this element is in the CommandBar.PrimaryCommands collection and CommandBar.IsDynamicOverflowEnabled is true.

You can assign the same DynamicOverflowOrder value to more than one element. Elements with the same value move in and out of the overflow area at the same time.

Version compatibility

The DynamicOverflowOrder property is not available prior to Windows 10, version 1607. If your app’s 'minimum platform version' setting in Microsoft Visual Studio is less than the 'introduced version' shown in the Requirements block later in this page, you must design and test your app to account for this. For more info, see Version adaptive code.

Note

Dynamic overflow is available when your app is compiled for Windows 10, version 1607 and running on version 1607 (or later). Dynamic overflow is not available when your app is compiled for a previous version or is running on a previous version.

To avoid exceptions when your app runs on previous versions of Windows 10, do not set this property in XAML or use it without performing a runtime check. This example shows how to use the ApiInformation class to check for the presence of this property before you set it.

<CommandBar x:Name="commandBar1" Loaded="CommandBar_Loaded">
    <AppBarButton x:Name="appBarButtonCut" Icon="Cut" Label="Cut"/>
    <AppBarButton x:Name="appBarButtonCopy" Icon="Copy" Label="Copy"/>
    <AppBarSeparator x:Name="appBarSeparator1"/>
    <AppBarButton x:Name="appBarButtonPaste" Icon="Paste" Label="Paste"/>
</CommandBar>
private void CommandBar_Loaded(object sender, RoutedEventArgs e)
{
    if (ApiInformation.IsPropertyPresent("Windows.UI.Xaml.Controls.AppBarButton", "DynamicOverflowOrder"))
    {
        commandBar1.IsDynamicOverflowEnabled = true;
        appBarButtonCut.DynamicOverflowOrder = 1;
        appBarButtonCopy.DynamicOverflowOrder = 2;
        appBarSeparator1.DynamicOverflowOrder = 2;
        appBarButtonPaste.DynamicOverflowOrder = 3;
    }
}

DynamicOverflowOrderProperty DynamicOverflowOrderProperty DynamicOverflowOrderProperty

Identifies the DynamicOverflowOrder dependency property.

public static DependencyProperty DynamicOverflowOrderProperty { get; }public static DependencyProperty DynamicOverflowOrderProperty { get; }Public Static ReadOnly Property DynamicOverflowOrderProperty As DependencyProperty
Value
DependencyProperty DependencyProperty DependencyProperty

The identifier for the DynamicOverflowOrder dependency property.

Attributes
Additional features and requirements
Device family
Windows 10 Anniversary Edition (introduced v10.0.14393.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v3)

Icon Icon Icon

Gets or sets the graphic content of the app bar button.

public IconElement Icon { get; set; }public IconElement Icon { get; set; }Public ReadWrite Property Icon As IconElement
<AppBarButton Icon="symbolName" .../>
Value
IconElement IconElement IconElement

The graphic content of the app bar button.

Attributes

IconProperty IconProperty IconProperty

Identifies the Icon dependency property.

public static DependencyProperty IconProperty { get; }public static DependencyProperty IconProperty { get; }Public Static ReadOnly Property IconProperty As DependencyProperty
Value
DependencyProperty DependencyProperty DependencyProperty

The identifier for the Icon dependency property.

Attributes

IsCompact IsCompact IsCompact

Gets or sets a value that indicates whether the button is shown with no label and reduced padding.

public PlatForm::Boolean IsCompact { get; set; }public bool IsCompact { get; set; }Public ReadWrite Property IsCompact As bool
<AppBarButton IsCompact="bool" .../>
Value
bool bool bool

true if the button is shown in its compact state; otherwise, false. The default is false.

Attributes

Remarks

IsCompactProperty IsCompactProperty IsCompactProperty

Identifies the IsCompact dependency property.

public static DependencyProperty IsCompactProperty { get; }public static DependencyProperty IsCompactProperty { get; }Public Static ReadOnly Property IsCompactProperty As DependencyProperty
Value
DependencyProperty DependencyProperty DependencyProperty

The identifier for the IsCompact dependency property.

Attributes

IsInOverflow IsInOverflow IsInOverflow

Gets a value that indicates whether this item is in the overflow menu.

public PlatForm::Boolean IsInOverflow { get; }public bool IsInOverflow { get; }Public ReadOnly Property IsInOverflow As bool
Value
bool bool bool

true if this item is in the overflow menu; otherwise, false.

Attributes
Additional features and requirements
Device family
Windows 10 Anniversary Edition (introduced v10.0.14393.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v3)

Remarks

For more info and guidelines, see the App bar and command bar article.

Starting in Windows 10, version 1607, CommandBar introduces a dynamic overflow feature. By default, PrimaryCommands automatically move in or out of the overflow area as the command bar width changes, for example, when users resize their app window. You can set the IsDynamicOverflowEnabled property to false to disable this behavior.

Dynamic overflow affects only the UI presentation of the commands, it doesn’t move commands from the PrimaryCommands collection to SecondaryCommands.

Version compatibility

The IsInOverflow property is not available prior to Windows 10, version 1607. If your app’s 'minimum platform version' setting in Microsoft Visual Studio is less than the 'introduced version' shown in the Requirements block later in this page, you must design and test your app to account for this. For more info, see Version adaptive code.

Note

Dynamic overflow is available when your app is compiled for Windows 10, version 1607 and running on version 1607 (or later). Dynamic overflow is not available when your app is compiled for a previous version or is running on a previous version.

To avoid exceptions when your app runs on previous versions of Windows 10, do not use this property without first performing a runtime check. This example shows how to use the ApiInformation class to check for the presence of this property before you use it.

if (ApiInformation.IsPropertyPresent("Windows.UI.Xaml.Controls.AppBarButton", "IsInOverflow"))
{
    bool overflow = appBarButton1.IsInOverflow;
}
See Also

IsInOverflowProperty IsInOverflowProperty IsInOverflowProperty

Identifies the IsInOverflow dependency property.

public static DependencyProperty IsInOverflowProperty { get; }public static DependencyProperty IsInOverflowProperty { get; }Public Static ReadOnly Property IsInOverflowProperty As DependencyProperty
Value
DependencyProperty DependencyProperty DependencyProperty

The identifier for the IsInOverflow dependency property.

Attributes
Additional features and requirements
Device family
Windows 10 Anniversary Edition (introduced v10.0.14393.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v3)

Label Label Label

Gets or sets the text description displayed on the app bar button.

public PlatForm::String Label { get; set; }public string Label { get; set; }Public ReadWrite Property Label As string
<AppBarButton Label="stringContent" .../>
Value
string string string

The text description displayed on the app bar button.

Attributes

LabelPosition LabelPosition LabelPosition

Gets or sets a value that indicates the placement and visibility of the button's label.

public CommandBarLabelPosition LabelPosition { get; set; }public CommandBarLabelPosition LabelPosition { get; set; }Public ReadWrite Property LabelPosition As CommandBarLabelPosition
<AppBarButton LabelPosition="commandBarLabelPositionMemberName" />
Value
CommandBarLabelPosition CommandBarLabelPosition CommandBarLabelPosition

An enumeration value that specifies the placement and visibility of the button's label. The default is Default.

Attributes
Additional features and requirements
Device family
Windows 10 Anniversary Edition (introduced v10.0.14393.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v3)

Remarks

By default, the app bar button's label is displayed in the position specified by the CommandBar.DefaultLabelPosition property. You can set the LabelPosition property to override this value and make the label always collapsed for a specific app bar button.

Version compatibility

The LabelPosition property is not available prior to Windows 10, version 1607. If your app’s 'minimum platform version' setting in Microsoft Visual Studio is less than the 'introduced version' shown in the Requirements block later in this page, you must design and test your app to account for this. For more info, see Version adaptive code.

To avoid exceptions when your app runs on previous versions of Windows 10, do not set this property in XAML or use it without performing a runtime check. This example shows how to use the ApiInformation class to check for the presence of this property before you set it.

<CommandBar x:Name="commandBar1" Loaded="CommandBar_Loaded">
    <AppBarButton x:Name="appBarButtonCut" Icon="Cut" Label="Cut"/>
</CommandBar>
private void CommandBar_Loaded(object sender, RoutedEventArgs e)
{
    if (ApiInformation.IsPropertyPresent("Windows.UI.Xaml.Controls.AppBarButton", "LabelPosition"))
    {
        appBarButtonCut.LabelPosition = CommandBarLabelPosition.Collapsed;
    }
}

LabelPositionProperty LabelPositionProperty LabelPositionProperty

Identifies the LabelPosition dependency property.

public static DependencyProperty LabelPositionProperty { get; }public static DependencyProperty LabelPositionProperty { get; }Public Static ReadOnly Property LabelPositionProperty As DependencyProperty
Value
DependencyProperty DependencyProperty DependencyProperty

The identifier for the LabelPosition dependency property.

Attributes
Additional features and requirements
Device family
Windows 10 Anniversary Edition (introduced v10.0.14393.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v3)

LabelProperty LabelProperty LabelProperty

Identifies the Label dependency property.

public static DependencyProperty LabelProperty { get; }public static DependencyProperty LabelProperty { get; }Public Static ReadOnly Property LabelProperty As DependencyProperty
Value
DependencyProperty DependencyProperty DependencyProperty

The identifier for the Label dependency property.

Attributes

See Also