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

Definition

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

public : class AppBarToggleButton : ToggleButton, IAppBarToggleButton, IAppBarToggleButton3, ICommandBarElement, ICommandBarElement2public class AppBarToggleButton : ToggleButton, IAppBarToggleButton, IAppBarToggleButton3, ICommandBarElement, ICommandBarElement2Public Class AppBarToggleButton Inherits ToggleButton Implements IAppBarToggleButton, IAppBarToggleButton3, ICommandBarElement, ICommandBarElement2
<AppBarToggleButton .../>
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

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

AppBarToggleButton() AppBarToggleButton() AppBarToggleButton()

Initializes a new instance of the AppBarToggleButton class.

public : AppBarToggleButton()public AppBarToggleButton()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
<AppBarToggleButton 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">
    <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

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 toggle button.

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

The graphic content of the app bar toggle button.

Attributes
See Also

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
<AppBarToggleButton IsCompact="bool" .../>
Value
PlatForm::Boolean bool bool

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

Attributes

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
PlatForm::Boolean 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.AppBarToggleButton", "IsInOverflow"))
{
    bool overflow = appBarToggleButton1.IsInOverflow;
}

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 toggle button.

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

The text description displayed on the app bar toggle 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
<AppBarToggleButton 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">
    <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

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