AppBarToggleButton AppBarToggleButton AppBarToggleButton Class

Represents a button control that can switch states and be displayed in an AppBar.

Syntax

Declaration

public class AppBarToggleButtonpublic class AppBarToggleButtonPublic Class AppBarToggleButton
<AppBarToggleButton .../>

Inheritance Hierarchy

Inherited Members

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

Remarks

An AppBarToggleButton is similar to an AppBarButton with an additional toggle state. When used inside a CommandBar. the visual appearance changes based on whether the control appears in the primary commands or the overflow menu. Here is an example of a toggled button as both a primary command and secondary command.

App bar button icon examples.

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 AppBarToggleButton control.

Resource keyDescription
AppBarToggleButtonBackgroundBackground color at rest
AppBarToggleButtonBackgroundDisabledBackground color when disabled
AppBarToggleButtonBackgroundCheckedBackground color at rest and checked
AppBarToggleButtonBackgroundCheckedPointerOverBackground color on hover and checked
AppBarToggleButtonBackgroundCheckedPressedBackground color when pressed and checked
AppBarToggleButtonBackgroundCheckedDisabledBackground color when disabled and checked
AppBarToggleButtonBackgroundHighLightOverlayOverlay background color at rest
AppBarToggleButtonBackgroundHighLightOverlayPointerOverOverlay background color on hover
AppBarToggleButtonBackgroundHighLightOverlayPressedOverlay background color when pressed
AppBarToggleButtonBackgroundHighLightOverlayCheckedPointerOverOverlay background color on hover and checked
AppBarToggleButtonBackgroundHighLightOverlayCheckedPressedOverlay background color when pressed and checked
AppBarToggleButtonForegroundLabel text color at rest
AppBarToggleButtonForegroundPointerOverLabel text color on hover
AppBarToggleButtonForegroundPressedLabel text color when pressed
AppBarToggleButtonForegroundDisabledLabel text color when disabled
AppBarToggleButtonForegroundCheckedLabel text color at rest and checked
AppBarToggleButtonForegroundCheckedPointerOverLabel text color on hover and checked
AppBarToggleButtonForegroundCheckedPressedLabel text color when pressed and checked
AppBarToggleButtonForegroundCheckedDisabledLabel text color when disabled and checked
AppBarToggleButtonBorderBrushBorder color at rest
AppBarToggleButtonBorderBrushPointerOverBorder color on hover
AppBarToggleButtonBorderBrushPressedBorder color when pressed
AppBarToggleButtonBorderBrushDisabledBorder color when disabled
AppBarToggleButtonBorderBrushCheckedBorder color at rest and checked
AppBarToggleButtonBorderBrushCheckedPointerOverBorder color on hover and checked
AppBarToggleButtonBorderBrushCheckedPressedBorder color when pressed and checked
AppBarToggleButtonBorderBrushCheckedDisabledBorder color when disabled and checked
AppBarToggleButtonCheckGlyphForegroundCheck mark color at rest (in overflow)
AppBarToggleButtonCheckGlyphForegroundPointerOverCheck mark color on hover (in overflow)
AppBarToggleButtonCheckGlyphForegroundPressedCheck mark color when pressed (in overflow)
AppBarToggleButtonCheckGlyphForegroundDisabledCheck mark color when disabled (in overflow)
AppBarToggleButtonCheckGlyphForegroundCheckedCheck mark color at rest and checked (in overflow)
AppBarToggleButtonCheckGlyphForegroundCheckedPointerOverCheck mark color on hover and checked (in overflow)
AppBarToggleButtonCheckGlyphForegroundCheckedPressedCheck mark color when pressed and checked (in overflow)
AppBarToggleButtonCheckGlyphForegroundCheckedDisabledCheck mark color when disabled and checked (in overflow)
AppBarToggleButtonOverflowLabelForegroundPointerOverLabel text color on hover (in overflow)
AppBarToggleButtonOverflowLabelForegroundPressedLabel text color when pressed (in overflow)
AppBarToggleButtonOverflowLabelForegroundDisabledLabel text color when disabled (in overflow)
AppBarToggleButtonOverflowLabelForegroundCheckedPointerOverLabel text color on hover and checked (in overflow)
AppBarToggleButtonOverflowLabelForegroundCheckedPressedLabel text color when pressed and checked (in overflow)
AppBarToggleButtonOverflowLabelForegroundCheckedDisabledLabel text color when disabled and checked (in overflow)

Constructors summary

Initializes a new instance of the AppBarToggleButton 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 toggle 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 toggle 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

  • AppBarToggleButton()
    AppBarToggleButton()
    AppBarToggleButton()
    AppBarToggleButton()

    Initializes a new instance of the AppBarToggleButton class.

    public AppBarToggleButton()public AppBarToggleButton()Public Function AppBarToggleButton() 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
    <AppBarToggleButton 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">
        <AppBarToggleButton x:Name="appBarButtonShuffle" Icon="Shuffle" Label="Shuffle"/>
        <AppBarToggleButton x:Name="appBarButtonRepeat" Icon="RepeatAll" Label="Repeat"/>
    </CommandBar>
    
    private void CommandBar_Loaded(object sender, RoutedEventArgs e)
    {
        if (ApiInformation.IsPropertyPresent("Windows.UI.Xaml.Controls.AppBarToggleButton", "DynamicOverflowOrder"))
        {
            commandBar1.IsDynamicOverflowEnabled = true;
            appBarButtonShuffle.DynamicOverflowOrder = 1;
            appBarButtonRepeat.DynamicOverflowOrder = 2;
        }
    }
    
  • 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 toggle button.

    public IconElement Icon { get; set; }public IconElement Icon { get; set; }Public ReadWrite Property Icon As IconElement
    <AppBarToggleButton 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
    <AppBarToggleButton IsCompact="bool" .../>
    

    Property Value

    • bool
      bool
      bool

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

  • 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.AppBarToggleButton", "IsInOverflow"))
    {
        bool overflow = appBarToggleButton1.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 toggle button.

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

    Property Value

    • string
      string
      string

      The text description displayed on the app bar toggle 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
    <AppBarToggleButton 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">
        <AppBarToggleButton x:Name="appBarButtonShuffle" Icon="Shuffle" Label="Shuffle"/>
    </CommandBar>
    
    private void CommandBar_Loaded(object sender, RoutedEventArgs e)
    {
        if (ApiInformation.IsPropertyPresent("Windows.UI.Xaml.Controls.AppBarToggleButton", "LabelPosition"))
        {
            appBarButtonShuffle.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.ContractVersionAttribute
Windows.Foundation.Metadata.StaticAttribute
Windows.Foundation.Metadata.MarshalingBehaviorAttribute
Windows.Foundation.Metadata.StaticAttribute
Windows.Foundation.Metadata.WebHostHiddenAttribute

Details

Assembly

Windows.UI.Xaml.Controls.dll