> For the complete documentation index, see [llms.txt](https://docs-siticoneframework.gitbook.io/home/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs-siticoneframework.gitbook.io/home/net-framework-or-net-core-ui/input-controls/siticone-togglebutton/events-and-callback.md).

# Events and Callback

## **Overview**

The **Events & Callback** feature provides ways to execute custom logic when the toggle button is clicked, toggled, or when animations complete. Developers can hook into these events to trigger additional UI updates, save settings, or control other components dynamically based on the toggle’s state.

***

### **Key API Members**

Below is a table summarizing the available events and their purpose:

<table data-header-hidden><thead><tr><th width="211"></th><th width="173"></th><th></th><th></th></tr></thead><tbody><tr><td><strong>Event Name</strong></td><td><strong>Type</strong></td><td><strong>Triggered When...</strong></td><td><strong>Example Usage</strong></td></tr><tr><td><strong>Click</strong></td><td><code>EventHandler</code></td><td>The toggle button is <strong>clicked</strong> (but does not necessarily change state).</td><td><code>myToggle.Click += (s, e) => { Console.WriteLine("Clicked"); };</code></td></tr><tr><td><strong>StateChanged</strong></td><td><code>EventHandler</code></td><td>The <code>IsToggled</code> state <strong>changes</strong> (from On to Off or vice versa).</td><td><code>myToggle.StateChanged += (s, e) => { /* Handle state change */ };</code></td></tr><tr><td><strong>ToggledOn</strong></td><td><code>EventHandler</code></td><td>The toggle <strong>switches to the On state</strong> (<code>IsToggled = true</code>).</td><td><code>myToggle.ToggledOn += (s, e) => { Console.WriteLine("Enabled!"); };</code></td></tr><tr><td><strong>ToggledOff</strong></td><td><code>EventHandler</code></td><td>The toggle <strong>switches to the Off state</strong> (<code>IsToggled = false</code>).</td><td><code>myToggle.ToggledOff += (s, e) => { Console.WriteLine("Disabled!"); };</code></td></tr><tr><td><strong>AnimationCompleted</strong></td><td><code>EventHandler</code></td><td>The <strong>toggle animation completes</strong>, meaning the transition effect has finished.</td><td><code>myToggle.AnimationCompleted += (s, e) => { Console.WriteLine("Done!"); };</code></td></tr><tr><td><strong>StateLoaded</strong></td><td><code>EventHandler</code></td><td>The toggle state is <strong>loaded from a saved file</strong> and applied.</td><td><code>myToggle.StateLoaded += (s, e) => { Console.WriteLine("Loaded state"); };</code></td></tr><tr><td><strong>StateSaved</strong></td><td><code>EventHandler</code></td><td>The toggle state is <strong>successfully saved to file</strong>.</td><td><code>myToggle.StateSaved += (s, e) => { Console.WriteLine("State saved!"); };</code></td></tr></tbody></table>

***

### **Key Points to Note**

1. **Click vs. StateChanged**
   * The `Click` event fires **whenever** the button is clicked, **even if** the state doesn’t change.
   * `StateChanged` fires **only if** `IsToggled` actually changes from On to Off or vice versa.
2. **ToggledOn vs. ToggledOff**
   * These are more **specific** than `StateChanged`—use them if you only care about one state (e.g., triggering an action **only when toggled on**).
3. **AnimationCompleted Considerations**
   * Some UI updates should happen **after** animations finish rather than immediately on `StateChanged`.
   * Example: Updating labels **after** the toggle visually completes the transition.
4. **StateLoaded and StateSaved**
   * These ensure you can track and confirm persistence actions (e.g., for debugging or notifying users of saved settings).

***

### **Usage Example**

#### **Basic Event Hooking**

```csharp
// Assume you have a SiticoneToggleButton named myToggle

// Detect clicks
myToggle.Click += (sender, e) =>
{
    Console.WriteLine("Button clicked!");
};

// Detect when the toggle state changes
myToggle.StateChanged += (sender, e) =>
{
    Console.WriteLine($"New State: {(myToggle.IsToggled ? "ON" : "OFF")}");
};

// Handle toggled ON event
myToggle.ToggledOn += (sender, e) =>
{
    Console.WriteLine("Feature enabled!");
};

// Handle toggled OFF event
myToggle.ToggledOff += (sender, e) =>
{
    Console.WriteLine("Feature disabled!");
};

// Respond to animation completion
myToggle.AnimationCompleted += (sender, e) =>
{
    Console.WriteLine("Animation finished!");
};

// Handle state persistence events
myToggle.StateSaved += (sender, e) =>
{
    Console.WriteLine("State successfully saved.");
};

myToggle.StateLoaded += (sender, e) =>
{
    Console.WriteLine("State loaded from file.");
};
```

> **Tip:** Use `ToggledOn` and `ToggledOff` when you only need to perform an action **on a specific state**, rather than checking `IsToggled` inside `StateChanged`.

***

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

| **Practice**                                                 | **Reason**                                                                                   |
| ------------------------------------------------------------ | -------------------------------------------------------------------------------------------- |
| Use `StateChanged` for general toggle detection.             | Ensures you handle **all** toggle changes in one event rather than multiple event handlers.  |
| Use `AnimationCompleted` for UI elements that should wait.   | Prevents visual inconsistencies where text or UI updates too early before animations finish. |
| Log or notify users when **StateSaved** and **StateLoaded**. | Confirms that persistence actions succeeded, improving user confidence in saved settings.    |
| Keep `Click` and `StateChanged` event logic **lightweight**. | Running heavy operations inside UI events can **block the UI thread** and cause lag.         |

***

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

| **Pitfall**                                                            | **Mitigation / Recommendation**                                                                 |
| ---------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
| Using `Click` instead of `StateChanged` when toggling logic is needed. | Clicking fires every time; use `StateChanged` for logic that depends on the toggle state.       |
| Overusing `AnimationCompleted` for logic that can run immediately.     | Avoid unnecessary delays unless waiting for UI transitions is truly needed.                     |
| Forgetting to unsubscribe from events when disposing.                  | Ensure event handlers are removed when the control is no longer needed to prevent memory leaks. |

***

### **Review and Summary**

* **What You Learned**:\
  How to use the `SiticoneToggleButton`’s events to detect state changes, clicks, animations, and persistence actions.
* **Why It’s Important**:\
  Events allow dynamic behavior in applications, enabling toggles to trigger UI updates, save settings, and notify users.
* **How to Move Forward**:\
  Use these events to create **responsive, user-friendly interactions**, ensuring your application reacts appropriately to user actions.

By leveraging **Events & Callback**, you make your toggle **more interactive**, allowing real-time updates and persistent settings for an improved user experience.