# Toggle Functionality

## **Overview**

This feature enables the `SiticoneToggleButton` to function as a traditional toggle switch. When a user clicks (or otherwise activates) the control, its state flips between **On** and **Off**. The control exposes helpful events, properties, and a command interface that allow developers to handle changes in the toggle state seamlessly.

***

### **Key API Members**

Below is a table summarizing the key properties and events that relate to the **Toggle Functionality**:

<table data-header-hidden><thead><tr><th width="180"></th><th width="122"></th><th></th><th></th></tr></thead><tbody><tr><td><strong>Name</strong></td><td><strong>Type</strong></td><td><strong>Description</strong></td><td><strong>Example</strong></td></tr><tr><td><strong>IsToggled</strong></td><td><code>bool</code></td><td>Indicates the current toggle state. Setting it to <code>true</code> turns the control <strong>On</strong>, while <code>false</code> sets it <strong>Off</strong>.</td><td><code>myToggle.IsToggled = true;</code></td></tr><tr><td><strong>Click</strong></td><td><code>event</code></td><td>Triggered every time the control is clicked. Internally, it toggles the state unless the control is in a read-only state.</td><td><code>myToggle.Click += (s, e) => {/* code */};</code></td></tr><tr><td><strong>ToggledOn</strong></td><td><code>event</code></td><td>Fires <strong>only</strong> when the toggle transitions from <strong>Off</strong> to <strong>On</strong>.</td><td><code>myToggle.ToggledOn += (s, e) => {/* code */};</code></td></tr><tr><td><strong>ToggledOff</strong></td><td><code>event</code></td><td>Fires <strong>only</strong> when the toggle transitions from <strong>On</strong> to <strong>Off</strong>.</td><td><code>myToggle.ToggledOff += (s, e) => {/* code */};</code></td></tr><tr><td><strong>StateChanged</strong></td><td><code>event</code></td><td>Fires whenever the control’s toggle state changes, regardless of whether it is turning <strong>On</strong> or <strong>Off</strong>.</td><td><code>myToggle.StateChanged += (s, e) => {/* code */};</code></td></tr><tr><td><strong>ToggleCommand</strong></td><td><code>ICommand</code></td><td>Executes an <code>ICommand</code> whenever the toggle state changes. Typically used in MVVM or command-based architectures.</td><td>```csharp</td></tr></tbody></table>

```
myToggle.ToggleCommand.Execute(null);
```

***

### **Key Points to Note**

1. **Toggling Mechanism**
   * The toggle switch automatically flips its `IsToggled` property when the user clicks the control (unless `IsReadonly` is `true`).
   * Programmatic toggling is also possible by explicitly setting `IsToggled` to `true` or `false`.
2. **Events Firing Sequence**
   * **Click** → The control checks `IsReadonly`; if not read-only, `IsToggled` is flipped.
   * **ToggledOn**/**ToggledOff** → One of these fires based on the new state.
   * **StateChanged** → Raised for every toggle change.
   * **ToggleCommand** → Invoked from an internal method (`OnToggle`) if assigned and executable.
3. **Read-Only Check**
   * If `IsReadonly` is `true`, attempts to change the state by clicking will trigger a visual/audio feedback (if enabled) but **will not** change the toggle state.
4. **ToggleCommand Usage**
   * Ideal when following a command-based pattern. The command executes whenever `IsToggled` changes.

***

### **Usage Example**

#### **Toggling Programmatically**

```csharp
// Assume you have a SiticoneToggleButton named myToggle
myToggle.IsToggled = false;

// Attach event to know when it changes to On
myToggle.ToggledOn += (sender, e) =>
{
    MessageBox.Show("The toggle is now ON!");
};

// Attach event to know when it changes to Off
myToggle.ToggledOff += (sender, e) =>
{
    MessageBox.Show("The toggle is now OFF!");
};

// Attach event to handle any state change
myToggle.StateChanged += (sender, e) =>
{
    Console.WriteLine($"New Toggle State: {myToggle.IsToggled}");
};
```

#### **Command-Based Toggle (Optional)**

```csharp
// If using ICommand with MVVM patterns:
myToggle.ToggleCommand = new RelayCommand(
    execute: _ => MessageBox.Show("Toggle command executed!"),
    canExecute: _ => true
);
```

> **Note:** `RelayCommand` is not part of the .NET Framework. You can implement or use your own ICommand implementation.

***

### **Best Practices to Create Beautiful UI and Apps**

| **Practice**                                                                                | **Reason**                                                                         |
| ------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
| Use a clear, contrasting **On** and **Off** **BackColor** scheme.                           | Makes it immediately apparent to users whether the button is ON or OFF.            |
| Combine **ToggledOn** / **ToggledOff** events with subtle **UI cues** (e.g., text or icon). | Provides visual confirmation and improves usability.                               |
| Consider setting a **ToggleCommand** when working with **MVVM**-style patterns.             | Keeps your UI logic and business logic separated, more maintainable, and testable. |
| Use **StateChanged** to update other dependent UI elements.                                 | Simplifies synchronization across multiple controls or UI components.              |
| Ensure **IsReadonly** is clearly indicated (e.g., disable or style differently).            | Improves user experience by visually indicating that toggling is not permitted.    |

***

### **Common Pitfalls and Design Considerations**

| **Pitfall**                                                            | **Mitigation / Recommendation**                                                                                                   |
| ---------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| Forgetting to handle **read-only state** (`IsReadonly`).               | Always check if your button can be toggled programmatically or by user input.                                                     |
| Creating infinite loops when toggling **IsToggled** in event handlers. | Avoid setting `IsToggled` again within the **ToggledOn**, **ToggledOff**, or **StateChanged** events unless absolutely necessary. |
| Relying **only** on `Click` instead of the dedicated toggle events.    | Use `ToggledOn`/`ToggledOff`/`StateChanged` for clarity and to avoid confusion about the button’s actual state.                   |
| Not checking `ToggleCommand.CanExecute(...)`.                          | If the command can’t execute, toggling still occurs, but the intended action may fail silently.                                   |
| Overusing toggles without appropriate labeling.                        | Provide clear textual or iconographic cues to explain the significance of each toggle in the UI.                                  |

***

### **Review and Summary**

* **What You Learned**:\
  The **Toggle Functionality** in `SiticoneToggleButton` makes it simple to manage an On/Off state. Through `IsToggled`, developers can programmatically control or observe the state. Events (`ToggledOn`, `ToggledOff`, `StateChanged`) provide granular control for reacting to changes. Additionally, `ToggleCommand` allows integration with command-based architectures.
* **Why It’s Important**:\
  Toggle controls are essential for any user interface that requires binary choices—such as enabling/disabling settings, turning features on/off, or selecting between two mutually exclusive states.
* **How to Move Forward**:\
  With this understanding, you can seamlessly implement toggling into your application logic, hooking up additional UI changes, sound effects, or commands whenever the user flips the toggle.

By keeping these points in mind and taking advantage of the events, properties, and command features, you’ll create a smooth, intuitive toggle experience for your end-users.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs-siticoneframework.gitbook.io/home/net-framework-or-net-core-ui/input-controls/siticone-togglebutton/toggle-functionality.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.