> 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-toggleswitch/core-toggle-functionality.md).

# Core Toggle Functionality

## **Overview**

The `SiticoneToggleSwitch` is a **modern, customizable** toggle switch for WinForms, enabling smooth **ON/OFF transitions** with various **restrictions, event handling, and feedback mechanisms**.

This documentation covers the **core toggle features**, focusing on **state management, event handling, constraints, and best practices**.

***

### **1. Core Functionalities**

#### **1.1 IsOn (Property)**

Indicates whether the toggle switch is **on** or **off**.

| **Property** | **Type** | **Default** | **Description**                    |
| ------------ | -------- | ----------- | ---------------------------------- |
| `IsOn`       | `bool`   | `false`     | Gets or sets the **toggle state**. |

**Usage Example**

```csharp
if (myToggleSwitch.IsOn)
{
    Console.WriteLine("Switch is ON.");
}
```

***

#### **1.2 Toggled (Event)**

Fires **after** the switch toggles.

| **Event** | **Type**                         | **Description**                    |
| --------- | -------------------------------- | ---------------------------------- |
| `Toggled` | `EventHandler<ToggledEventArgs>` | Fires after **successful toggle**. |

**Usage Example**

```csharp
myToggleSwitch.Toggled += (sender, args) =>
{
    Console.WriteLine($"Switched to: {(args.IsOn ? "On" : "Off")}");
};
```

***

#### **1.3 StateChanging (Event)**

Fires **before** a state change occurs, allowing **cancellation**.

| **Event**       | **Type**                               | **Description**                        |
| --------------- | -------------------------------------- | -------------------------------------- |
| `StateChanging` | `EventHandler<StateChangingEventArgs>` | Allows validation **before** toggling. |

**Usage Example**

```csharp
myToggleSwitch.StateChanging += (sender, args) =>
{
    if (!UserCanToggle())
    {
        args.Cancel = true;  // Prevents toggling
    }
};
```

***

#### **1.4 DisallowToggling (Property)**

Prevents users from **changing the state**.

| **Property**       | **Type** | **Default** | **Description**           |
| ------------------ | -------- | ----------- | ------------------------- |
| `DisallowToggling` | `bool`   | `false`     | Prevents manual toggling. |

**Usage Example**

```csharp
myToggleSwitch.DisallowToggling = true;
```

***

#### **1.5 PreventToggleOff (Property)**

Ensures that **once ON, it cannot be turned OFF**.

| **Property**       | **Type** | **Default** | **Description**                              |
| ------------------ | -------- | ----------- | -------------------------------------------- |
| `PreventToggleOff` | `bool`   | `false`     | Ensures the switch cannot be turned **off**. |

**Usage Example**

```csharp
myToggleSwitch.PreventToggleOff = true;
```

***

#### **1.6 IsRequired (Property)**

Forces the switch to **always remain on**.

| **Property** | **Type** | **Default** | **Description**                   |
| ------------ | -------- | ----------- | --------------------------------- |
| `IsRequired` | `bool`   | `false`     | The switch **must always be ON**. |

**Usage Example**

```csharp
myToggleSwitch.IsRequired = true;
```

***

#### **1.7 PlayToggleSound (Method)**

Plays a sound **when toggling**.

| **Method**          | **Return Type** | **Description**             |
| ------------------- | --------------- | --------------------------- |
| `PlayToggleSound()` | `void`          | Plays a sound when toggled. |

**Usage Example**

```csharp
myToggleSwitch.PlayToggleSound();
```

***

### **2. When to Use These Features?** ✅

| **Feature**         | **Use Case**                                        |
| ------------------- | --------------------------------------------------- |
| `IsOn`              | When **reading or setting** the toggle state.       |
| `Toggled`           | When **reacting** to a state change.                |
| `StateChanging`     | When **validating state changes** before execution. |
| `DisallowToggling`  | When preventing **manual user toggling**.           |
| `PreventToggleOff`  | When requiring **permanent ON state**.              |
| `IsRequired`        | When ensuring **critical settings remain active**.  |
| `PlayToggleSound()` | When providing **audio feedback**.                  |

***

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

| **Pitfall**                  | **Cause**                                         | **Solution**                                              |
| ---------------------------- | ------------------------------------------------- | --------------------------------------------------------- |
| **Unexpected state changes** | External code modifies `IsOn` without validation. | Use `StateChanging` to **validate changes**.              |
| **Accidental toggles**       | User clicks too fast.                             | Enable `DisallowToggling` to **prevent** manual toggling. |
| **Cannot turn switch off**   | `PreventToggleOff` is `true`.                     | Ensure it's **intended behavior** before enabling.        |
| **Infinite loops in events** | `IsOn = !IsOn` inside event handlers.             | Always **validate** before changing state.                |

***

### **4. Points Learned** 🎯

✅ **Use `StateChanging` for validation before toggling**\
✅ **Leverage `PreventToggleOff` & `IsRequired` to enforce restrictions**\
✅ **Use `Toggled` & `StateChanged` for UI updates**\
✅ **Prevent unintended toggles with `DisallowToggling`**\
✅ **Use `PlayToggleSound()` for better user experience**

***

### **5. Review Checklist** ✔️

| **Item**                                                | **Check** |
| ------------------------------------------------------- | --------- |
| Does the toggle **change state correctly**?             | ✅         |
| Are `StateChanging` and `Toggled` **properly handled**? | ✅         |
| Does `DisallowToggling` prevent unwanted interactions?  | ✅         |
| Does `PreventToggleOff` enforce the ON state?           | ✅         |
| Are **common pitfalls** avoided?                        | ✅         |

***

### **6. Summary** 📌

#### **6.1 Feature Summary**

| **Feature**         | **Type** | **Description**                              |
| ------------------- | -------- | -------------------------------------------- |
| `IsOn`              | `bool`   | Gets or sets the **toggle state**.           |
| `Toggled`           | `Event`  | Fires **after** toggling.                    |
| `StateChanging`     | `Event`  | Fires **before** toggling (can be canceled). |
| `DisallowToggling`  | `bool`   | Prevents manual toggling.                    |
| `PreventToggleOff`  | `bool`   | Ensures the switch remains **on**.           |
| `IsRequired`        | `bool`   | Forces the switch to **always be ON**.       |
| `PlayToggleSound()` | `void`   | Plays a **toggle sound**.                    |

***

#### **6.2 Key Takeaways**

✔ **Control toggle state properly using `IsOn`**\
✔ **Use `StateChanging` to validate changes before they happen**\
✔ **Use `DisallowToggling` and `PreventToggleOff` to enforce rules**\
✔ **Improve user experience with `PlayToggleSound()`**\
✔ **Avoid common pitfalls by handling `Toggled` and `StateChanging` properly**

***

### **7. Final Thoughts & Best Practices** 💡

* **Use event handlers** to **control toggle behavior** effectively.
* **Leverage `DisallowToggling` and `PreventToggleOff`** to **enforce application rules**.
* **Use `StateChanging`** to **validate state changes before they happen**.
* **Use `PlayToggleSound()`** to **enhance user experience**.