Events and Callback

Provides built-in events that allow developers to respond to user interactions and state changes in Siticone ToggleButton.

Overview

The Events & Callback feature provides ways to execute custom logic when the toggle button is clicked, toggled, or when animations complete. Developers can hook into these events to trigger additional UI updates, save settings, or control other components dynamically based on the toggle’s state.

---

Key API Members

Below is a table summarizing the available events and their purpose:

Event Name	Type	Triggered When...	Example Usage
Click	EventHandler	The toggle button is clicked (but does not necessarily change state).	myToggle.Click += (s, e) => { Console.WriteLine("Clicked"); };
StateChanged	EventHandler	The IsToggled state changes (from On to Off or vice versa).	myToggle.StateChanged += (s, e) => { /* Handle state change */ };
ToggledOn	EventHandler	The toggle switches to the On state (IsToggled = true).	myToggle.ToggledOn += (s, e) => { Console.WriteLine("Enabled!"); };
ToggledOff	EventHandler	The toggle switches to the Off state (IsToggled = false).	myToggle.ToggledOff += (s, e) => { Console.WriteLine("Disabled!"); };
AnimationCompleted	EventHandler	The toggle animation completes, meaning the transition effect has finished.	myToggle.AnimationCompleted += (s, e) => { Console.WriteLine("Done!"); };
StateLoaded	EventHandler	The toggle state is loaded from a saved file and applied.	myToggle.StateLoaded += (s, e) => { Console.WriteLine("Loaded state"); };
StateSaved	EventHandler	The toggle state is successfully saved to file.	myToggle.StateSaved += (s, e) => { Console.WriteLine("State saved!"); };

---

Key Points to Note

1. Click vs. StateChanged

   • The Click event fires whenever the button is clicked, even if the state doesn’t change.

   • StateChanged fires only if IsToggled actually changes from On to Off or vice versa.

2. ToggledOn vs. ToggledOff

   • These are more specific than StateChanged—use them if you only care about one state (e.g., triggering an action only when toggled on).

3. AnimationCompleted Considerations

   • Some UI updates should happen after animations finish rather than immediately on StateChanged.

   • Example: Updating labels after the toggle visually completes the transition.

4. StateLoaded and StateSaved

   • These ensure you can track and confirm persistence actions (e.g., for debugging or notifying users of saved settings).

---

Usage Example

Basic Event Hooking

// Assume you have a SiticoneToggleButton named myToggle

// Detect clicks
myToggle.Click += (sender, e) =>
{
    Console.WriteLine("Button clicked!");
};

// Detect when the toggle state changes
myToggle.StateChanged += (sender, e) =>
{
    Console.WriteLine($"New State: {(myToggle.IsToggled ? "ON" : "OFF")}");
};

// Handle toggled ON event
myToggle.ToggledOn += (sender, e) =>
{
    Console.WriteLine("Feature enabled!");
};

// Handle toggled OFF event
myToggle.ToggledOff += (sender, e) =>
{
    Console.WriteLine("Feature disabled!");
};

// Respond to animation completion
myToggle.AnimationCompleted += (sender, e) =>
{
    Console.WriteLine("Animation finished!");
};

// Handle state persistence events
myToggle.StateSaved += (sender, e) =>
{
    Console.WriteLine("State successfully saved.");
};

myToggle.StateLoaded += (sender, e) =>
{
    Console.WriteLine("State loaded from file.");
};

Tip: Use ToggledOn and ToggledOff when you only need to perform an action on a specific state, rather than checking IsToggled inside StateChanged.

---

Best Practices to Create Beautiful UI and Apps

Practice	Reason
Use StateChanged for general toggle detection.	Ensures you handle all toggle changes in one event rather than multiple event handlers.
Use AnimationCompleted for UI elements that should wait.	Prevents visual inconsistencies where text or UI updates too early before animations finish.
Log or notify users when StateSaved and StateLoaded.	Confirms that persistence actions succeeded, improving user confidence in saved settings.
Keep Click and StateChanged event logic lightweight.	Running heavy operations inside UI events can block the UI thread and cause lag.

---

Common Pitfalls and Design Considerations

Pitfall	Mitigation / Recommendation
Using Click instead of StateChanged when toggling logic is needed.	Clicking fires every time; use StateChanged for logic that depends on the toggle state.
Overusing AnimationCompleted for logic that can run immediately.	Avoid unnecessary delays unless waiting for UI transitions is truly needed.
Forgetting to unsubscribe from events when disposing.	Ensure event handlers are removed when the control is no longer needed to prevent memory leaks.

---

Review and Summary

• What You Learned: How to use the SiticoneToggleButton’s events to detect state changes, clicks, animations, and persistence actions.

• Why It’s Important: Events allow dynamic behavior in applications, enabling toggles to trigger UI updates, save settings, and notify users.

• How to Move Forward: Use these events to create responsive, user-friendly interactions, ensuring your application reacts appropriately to user actions.

By leveraging Events & Callback, you make your toggle more interactive, allowing real-time updates and persistent settings for an improved user experience.