Core Toggle Functionality

The Siticone ToggleSwitch control provides a modern, customizable toggle switch for WinForms applications.

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

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

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

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

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

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

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

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.