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


---

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