AppBarButton AppBarButton AppBarButton Class

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

Syntax

Declaration

public class AppBarButtonpublic class AppBarButtonPublic Class AppBarButton
<AppBarButton .../>

Inheritance Hierarchy

Inherited Members

, , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , ,
Tag
Tag
Tag
, , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , ,

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 summary

Initializes a new instance of the AppBarButton class.

Properties summary

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

Identifies the DynamicOverflowOrder dependency property.

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

Identifies the Icon dependency property.

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

Identifies the IsCompact dependency property.

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

Identifies the IsInOverflow dependency property.

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

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

Identifies the LabelPosition dependency property.

Identifies the Label dependency property.

Constructors

  • AppBarButton()
    AppBarButton()
    AppBarButton()
    AppBarButton()

    Initializes a new instance of the AppBarButton class.

    public AppBarButton()public AppBarButton()Public Function AppBarButton() As

Properties

  • DynamicOverflowOrder
    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" .../>
    

    Property Value

    • int
      int
      int

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

    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 PrimaryCommands collection and 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
    DynamicOverflowOrderProperty

    Identifies the DynamicOverflowOrder dependency property.

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

    Property Value

  • Icon
    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" .../>
    

    Property Value

  • IconProperty
    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

    Property Value

  • IsCompact
    IsCompact
    IsCompact
    IsCompact

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

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

    Property Value

    • bool
      bool
      bool

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

    Remarks

  • IsCompactProperty
    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

    Property Value

  • IsInOverflow
    IsInOverflow
    IsInOverflow
    IsInOverflow

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

    public bool IsInOverflow { get; }public bool IsInOverflow { get; }Public ReadOnly Property IsInOverflow As bool

    Property Value

    • bool
      bool
      bool

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

    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;
    }
    
  • IsInOverflowProperty
    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

    Property Value

  • Label
    Label
    Label
    Label

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

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

    Property Value

    • string
      string
      string

      The text description displayed on the app bar button.

  • LabelPosition
    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" />
    

    Property Value

    Remarks

    By default, the app bar button's label is displayed in the position specified by the 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
    LabelPositionProperty

    Identifies the LabelPosition dependency property.

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

    Property Value

  • LabelProperty
    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

    Property Value

Device family

Windows 10 (introduced v10.0.10240.0)

API contract

Windows.Foundation.UniversalApiContract (introduced v1)

Attributes

Windows.Foundation.Metadata.ComposableAttribute
Windows.Foundation.Metadata.ThreadingAttribute
Windows.Foundation.Metadata.MarshalingBehaviorAttribute
Windows.Foundation.Metadata.StaticAttribute
Windows.Foundation.Metadata.WebHostHiddenAttribute
Windows.Foundation.Metadata.StaticAttribute
Windows.Foundation.Metadata.ContractVersionAttribute

Details

Assembly

Windows.UI.Xaml.Controls.dll