AppBarToggleButton

The AppBarToggleButton is a control that provides a button with a toggle state, commonly used in application bars to represent actions that can be switched on or off.

Overview

AppBarToggleButton inherits from ButtonBase and extends its functionality with a visual state that indicates whether it is "checked" or "unchecked". This makes it ideal for scenarios like toggling features, showing/hiding UI elements, or controlling application states.

When to Use

To provide an on/off switch for a feature within an application bar.
To visually represent a state that can be changed by the user.
When you need a button that has a distinct visual representation for its selected/active state.

Example Usage

Here's a simple example of how to implement an AppBarToggleButton in XAML and how it might be styled:

XAML

<AppBarToggleButton x:Name="toggleThemeButton"
                                  Label="Dark Mode"
                                  Icon="DarkTheme"
                                  IsChecked="False"
                                  Checked="ToggleThemeButton_Checked"
                                  Unchecked="ToggleThemeButton_Unchecked" />

And here's a conceptual representation of the button in HTML/CSS/JS for demonstration:

Key Properties

Property	Description	Type	Default Value
`Label`	The text displayed with the button.	`string`	Empty
`Icon`	The icon displayed with the button.	`string` or `Symbol`	None
`IsChecked`	Gets or sets a value that indicates whether the toggle button is in the checked state.	`bool`	`False`
`Checked`	Occurs when the toggle button is checked.	`RoutedEventHandler`	None
`Unchecked`	Occurs when the toggle button is unchecked.	`RoutedEventHandler`	None

Events

Checked: Fired when IsChecked changes from False to True.
Unchecked: Fired when IsChecked changes from True to False.

Styling and Templating

The appearance of the AppBarToggleButton can be customized extensively using styles and control templates. You can modify the visual states for Normal, PointerOver, Pressed, and Checked to achieve the desired look and feel.

Best Practices

Use descriptive labels for your toggle buttons.
Ensure the icon clearly represents the action or state.
Provide visual feedback for both the checked and unchecked states.
Consider the placement within your application bar for optimal user experience.

JavaScript Interaction Example

document.addEventListener('DOMContentLoaded', () => {
    const demoButton = document.getElementById('demoAppBarToggleButton');
    const demoButtonActive = document.getElementById('demoAppBarToggleButtonActive');

    // Simulate click for the first button
    demoButton.addEventListener('click', () => {
        demoButton.classList.toggle('is-active');
        const icon = demoButton.querySelector('.icon');
        const text = demoButton.querySelector('.text');
        if (demoButton.classList.contains('is-active')) {
            icon.textContent = '☀️';
            text.textContent = 'Light Mode';
            console.log('Dark Mode Enabled');
        } else {
            icon.textContent = '🌙';
            text.textContent = 'Dark Mode';
            console.log('Dark Mode Disabled');
        }
    });

    // Simulate click for the second button (already active)
    demoButtonActive.addEventListener('click', () => {
        demoButtonActive.classList.toggle('is-active');
        const icon = demoButtonActive.querySelector('.icon');
        const text = demoButtonActive.querySelector('.text');
        if (demoButtonActive.classList.contains('is-active')) {
            icon.textContent = '☀️';
            text.textContent = 'Light Mode';
            console.log('Dark Mode Enabled');
        } else {
            icon.textContent = '🌙';
            text.textContent = 'Dark Mode';
            console.log('Dark Mode Disabled');
        }
    });
});