# 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.        |
