# Events and Callbacks

## **Overview**

The `SiticoneToggleSwitch` provides **various events and callbacks** to respond to **user interactions, state changes, and system updates**. Developers can use these events to trigger **custom logic**, perform **validations**, or **synchronize UI components** dynamically.

***

### **1. Available Events and Callbacks** 📅

| **Event**            | **Type**                                    | **Description**                                                |
| -------------------- | ------------------------------------------- | -------------------------------------------------------------- |
| `Toggled`            | `EventHandler<ToggledEventArgs>`            | Fires when the toggle **changes state** (ON/OFF).              |
| `StateChanging`      | `EventHandler<StateChangingEventArgs>`      | Fires **before the state changes**, allowing **cancellation**. |
| `StateChanged`       | `EventHandler<StateChangedEventArgs>`       | Fires **after the state has changed** successfully.            |
| `SystemThemeChanged` | `EventHandler<SystemThemeChangedEventArgs>` | Fires when the **system’s theme changes**.                     |

***

### **2. Handling `Toggled` Event** 🔘

| **Use Case**                                           | **Trigger Condition**                          |
| ------------------------------------------------------ | ---------------------------------------------- |
| Execute **custom actions** when the switch is toggled. | Fires **every time** the switch changes state. |

**Example**

```csharp
myToggleSwitch.Toggled += (s, e) => 
{
    MessageBox.Show($"Toggle state: {(e.IsOn ? "ON" : "OFF")}");
};
```

✅ This event ensures **UI updates and state-dependent logic execution**.

***

### **3. State Changing** 🚧

| **Use Case**                                   | **Trigger Condition**                      |
| ---------------------------------------------- | ------------------------------------------ |
| Prevent toggling under **certain conditions**. | Fires **before the toggle state changes**. |

**Example**

```csharp
myToggleSwitch.StateChanging += (s, e) =>
{
    if (e.NewState == false) // Prevent turning OFF
    {
        e.Cancel = true;
        MessageBox.Show("This switch cannot be turned OFF!");
    }
};
```

✅ This event allows **validation before state changes**.

***

### **4. State Changed** 🔄

| **Use Case**                                                 | **Trigger Condition**                               |
| ------------------------------------------------------------ | --------------------------------------------------- |
| Execute logic **after the toggle switch state has changed**. | Fires **only after the state update is completed**. |

**Example**

```csharp
myToggleSwitch.StateChanged += (s, e) =>
{
    Console.WriteLine($"Switch is now {(e.NewState ? "ON" : "OFF")}");
};
```

✅ Helps in **tracking final state changes** and performing **post-change actions**.

***

### **5. System Theme** 🎨

| **Use Case**                                                      | **Trigger Condition**                              |
| ----------------------------------------------------------------- | -------------------------------------------------- |
| Adapt the toggle switch appearance to match **OS theme changes**. | Fires when **Windows theme (Light/Dark) updates**. |

**Example**

```csharp
myToggleSwitch.SystemThemeChanged += (s, e) =>
{
    MessageBox.Show($"System theme changed to: {e.NewTheme}");
};
```

✅ Ensures the **toggle switch remains visually consistent** with system themes.

***

### **6. Using These Events** ✅

| **Event**            | **Use Case**                                                           |
| -------------------- | ---------------------------------------------------------------------- |
| `Toggled`            | When executing **custom actions** after a toggle state change.         |
| `StateChanging`      | When **validating and preventing** state changes dynamically.          |
| `StateChanged`       | When performing **follow-up actions** after a successful state change. |
| `SystemThemeChanged` | When adapting UI **to match system-wide themes**.                      |

***

### **7. Common Pitfalls & Design Considerations** 🛑

| **Pitfall**                                  | **Cause**                     | **Solution**                                        |
| -------------------------------------------- | ----------------------------- | --------------------------------------------------- |
| **Event not firing**                         | Handler not attached          | Ensure the event is properly **subscribed**.        |
| **`StateChanging` doesn’t prevent toggling** | `e.Cancel = true;` not set    | Explicitly **set the `Cancel` property** to `true`. |
| **Laggy UI updates**                         | Heavy logic in event handlers | Move **complex operations to background tasks**.    |

***

### **8. Points Learned** 🎯

| **Point**                                                       | **Description**                                                     |
| --------------------------------------------------------------- | ------------------------------------------------------------------- |
| **Events provide better control over state changes.**           | Enables **dynamic UI behaviors and custom logic execution**.        |
| **Preventing unwanted toggles avoids unexpected user actions.** | `StateChanging` ensures **proper validation** before state updates. |
| **Post-change actions can be automated.**                       | `StateChanged` helps **synchronize UI and backend states**.         |

***

### **9. Review Checklist** ✔️

| **Item**                                                 | **Check** |
| -------------------------------------------------------- | --------- |
| Is the **Toggled event firing** as expected?             | ✅         |
| Does **StateChanging properly prevent invalid toggles**? | ✅         |
| Are UI updates **synchronized with SystemThemeChanged**? | ✅         |

***

### **10. Key Takeaways**

| **Key Takeaway**                                          | **Description**                                                 |
| --------------------------------------------------------- | --------------------------------------------------------------- |
| **Events allow real-time response to user interactions.** | Enables **immediate reactions** to toggle changes.              |
| **State validation prevents incorrect behavior.**         | Avoids **invalid or undesired state transitions**.              |
| **Proper event usage improves UI adaptability.**          | Ensures **consistent user experience** across different themes. |

***

### **11. Summary** 📌

#### **11.1 Feature Summary**

| **Event**            | **Trigger Condition**                        | **Usage**                                         |
| -------------------- | -------------------------------------------- | ------------------------------------------------- |
| `Toggled`            | Fires when the toggle state changes.         | Execute **actions when ON/OFF**.                  |
| `StateChanging`      | Fires **before** a state change occurs.      | **Validate and prevent changes** when needed.     |
| `StateChanged`       | Fires **after** a state change is completed. | **Perform follow-up tasks** after toggle updates. |
| `SystemThemeChanged` | Fires when the OS theme changes.             | Adapt **toggle appearance dynamically**.          |

#### **11.2 Key Benefits**

| **Benefit**                                                | **Description**                                             |
| ---------------------------------------------------------- | ----------------------------------------------------------- |
| **Allows developers to handle toggle events dynamically.** | Supports **real-time state tracking**.                      |
| **Prevents unwanted state changes when necessary.**        | `StateChanging` provides **full control over transitions**. |
| **Ensures UI consistency with OS themes.**                 | Matches **system-wide dark/light mode** dynamically.        |


---

# 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-toggleswitch/events-and-callbacks.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.