Toggle Functionality

Provides the ability to switch the control’s state between On and Off, along with associated events and command support.

Overview

This feature enables the SiticoneToggleButton to function as a traditional toggle switch. When a user clicks (or otherwise activates) the control, its state flips between On and Off. The control exposes helpful events, properties, and a command interface that allow developers to handle changes in the toggle state seamlessly.

---

Key API Members

Below is a table summarizing the key properties and events that relate to the Toggle Functionality:

Name	Type	Description	Example
IsToggled	bool	Indicates the current toggle state. Setting it to true turns the control On, while false sets it Off.	myToggle.IsToggled = true;
Click	event	Triggered every time the control is clicked. Internally, it toggles the state unless the control is in a read-only state.	myToggle.Click += (s, e) => {/* code */};
ToggledOn	event	Fires only when the toggle transitions from Off to On.	myToggle.ToggledOn += (s, e) => {/* code */};
ToggledOff	event	Fires only when the toggle transitions from On to Off.	myToggle.ToggledOff += (s, e) => {/* code */};
StateChanged	event	Fires whenever the control’s toggle state changes, regardless of whether it is turning On or Off.	myToggle.StateChanged += (s, e) => {/* code */};
ToggleCommand	ICommand	Executes an ICommand whenever the toggle state changes. Typically used in MVVM or command-based architectures.	```csharp

myToggle.ToggleCommand.Execute(null);

---

Key Points to Note

1. Toggling Mechanism

   • The toggle switch automatically flips its IsToggled property when the user clicks the control (unless IsReadonly is true).

   • Programmatic toggling is also possible by explicitly setting IsToggled to true or false.

2. Events Firing Sequence

   • Click → The control checks IsReadonly; if not read-only, IsToggled is flipped.

   • ToggledOn/ToggledOff → One of these fires based on the new state.

   • StateChanged → Raised for every toggle change.

   • ToggleCommand → Invoked from an internal method (OnToggle) if assigned and executable.

3. Read-Only Check

   • If IsReadonly is true, attempts to change the state by clicking will trigger a visual/audio feedback (if enabled) but will not change the toggle state.

4. ToggleCommand Usage

   • Ideal when following a command-based pattern. The command executes whenever IsToggled changes.

---

Usage Example

Toggling Programmatically

// Assume you have a SiticoneToggleButton named myToggle
myToggle.IsToggled = false;

// Attach event to know when it changes to On
myToggle.ToggledOn += (sender, e) =>
{
    MessageBox.Show("The toggle is now ON!");
};

// Attach event to know when it changes to Off
myToggle.ToggledOff += (sender, e) =>
{
    MessageBox.Show("The toggle is now OFF!");
};

// Attach event to handle any state change
myToggle.StateChanged += (sender, e) =>
{
    Console.WriteLine($"New Toggle State: {myToggle.IsToggled}");
};

Command-Based Toggle (Optional)

// If using ICommand with MVVM patterns:
myToggle.ToggleCommand = new RelayCommand(
    execute: _ => MessageBox.Show("Toggle command executed!"),
    canExecute: _ => true
);

Note: RelayCommand is not part of the .NET Framework. You can implement or use your own ICommand implementation.

---

Best Practices to Create Beautiful UI and Apps

Practice	Reason
Use a clear, contrasting On and Off BackColor scheme.	Makes it immediately apparent to users whether the button is ON or OFF.
Combine ToggledOn / ToggledOff events with subtle UI cues (e.g., text or icon).	Provides visual confirmation and improves usability.
Consider setting a ToggleCommand when working with MVVM-style patterns.	Keeps your UI logic and business logic separated, more maintainable, and testable.
Use StateChanged to update other dependent UI elements.	Simplifies synchronization across multiple controls or UI components.
Ensure IsReadonly is clearly indicated (e.g., disable or style differently).	Improves user experience by visually indicating that toggling is not permitted.

---

Common Pitfalls and Design Considerations

Pitfall	Mitigation / Recommendation
Forgetting to handle read-only state (IsReadonly).	Always check if your button can be toggled programmatically or by user input.
Creating infinite loops when toggling IsToggled in event handlers.	Avoid setting IsToggled again within the ToggledOn, ToggledOff, or StateChanged events unless absolutely necessary.
Relying only on Click instead of the dedicated toggle events.	Use ToggledOn/ToggledOff/StateChanged for clarity and to avoid confusion about the button’s actual state.
Not checking ToggleCommand.CanExecute(...).	If the command can’t execute, toggling still occurs, but the intended action may fail silently.
Overusing toggles without appropriate labeling.	Provide clear textual or iconographic cues to explain the significance of each toggle in the UI.

---

Review and Summary

• What You Learned: The Toggle Functionality in SiticoneToggleButton makes it simple to manage an On/Off state. Through IsToggled, developers can programmatically control or observe the state. Events (ToggledOn, ToggledOff, StateChanged) provide granular control for reacting to changes. Additionally, ToggleCommand allows integration with command-based architectures.

• Why It’s Important: Toggle controls are essential for any user interface that requires binary choices—such as enabling/disabling settings, turning features on/off, or selecting between two mutually exclusive states.

• How to Move Forward: With this understanding, you can seamlessly implement toggling into your application logic, hooking up additional UI changes, sound effects, or commands whenever the user flips the toggle.

By keeping these points in mind and taking advantage of the events, properties, and command features, you’ll create a smooth, intuitive toggle experience for your end-users.