Logging and Diagnostics

Monitor, track, and debug toggle switch interactions using built-in logging and diagnostics capabilities.

Overview

The SiticoneToggleSwitch provides built-in logging and diagnostic support to help developers track state changes, debug issues, and log user interactions efficiently. This guide covers logging mechanisms, best practices, and diagnostic tools available in the control.

---

1. Logging System

1.1 IToggleSwitchLogger Interface

The control supports custom logging implementations via the IToggleSwitchLogger interface.

Interface	Description
IToggleSwitchLogger	Defines a custom logger to track switch state changes.

Method Signature

public interface IToggleSwitchLogger
{
    void Log(string message);
}

---

1.2 File-Based Logging

The FileToggleSwitchLogger is a prebuilt logger that logs toggle events to a text file.

Class	Description
FileToggleSwitchLogger	Logs messages to a specified file.

Usage Example

// Initialize the logger
var logger = new SiticoneToggleSwitch.FileToggleSwitchLogger("toggle_log.txt");

// Assign to the control
myToggleSwitch.Logger = logger;

// Log a custom message
logger.Log("Toggle Switch Initialized.");

---

2. State Change Tracking

2.1 Toggle Events

The control provides events for tracking toggle state changes.

Event	Description
Toggled	Fired when the switch changes state (ON/OFF).
StateChanging	Triggered before the state changes (can be canceled).
StateChanged	Fired after the state has changed.

Usage Example

myToggleSwitch.Toggled += (sender, e) =>
{
    Console.WriteLine($"Toggle state changed: {(e.IsOn ? "On" : "Off")}");
};

---

2.2 Preventing State Changes

The StateChangingEventArgs allows preventing unwanted state changes.

Property	Type	Description
CurrentState	bool	The existing state before change.
NewState	bool	The requested new state.
Cancel	bool	Set true to prevent the change.

Usage Example

myToggleSwitch.StateChanging += (sender, e) =>
{
    if (!UserHasPermission)
    {
        e.Cancel = true; // Prevent state change
        Console.WriteLine("Toggle action denied.");
    }
};

---

3. Theme Change Detection

The SiticoneToggleSwitch can track system-wide theme changes and log them.

Event	Description
SystemThemeChanged	Fired when the Windows theme changes.

Usage Example

myToggleSwitch.SystemThemeChanged += (sender, e) =>
{
    Console.WriteLine($"System theme changed to: {e.NewTheme}");
};

---

4. When to Use These Features? ✅

Feature	Use Case
Logger	Track user interactions for debugging.
Toggled Event	Execute actions on state change.
StateChanging	Restrict toggling based on conditions.
SystemThemeChanged	Monitor system theme changes for UI adaptation.

---

5. Common Pitfalls & Design Considerations 🛑

Pitfall	Cause	Solution
Logs not saving	Missing file path in FileToggleSwitchLogger.	Ensure valid path is set.
Event handlers not triggering	Not attached properly.	Use += to subscribe to events.
StateChanging doesn’t prevent toggling	Cancel flag not set.	Set e.Cancel = true; in the event handler.
Theme change detection fails	TrackDeviceTheme = false.	Enable TrackDeviceTheme.

---

6. Points Learned 🎯

✅ Use Logger for debugging toggle interactions. ✅ Attach Toggled and StateChanged for real-time updates. ✅ Use StateChanging to restrict state changes. ✅ Monitor SystemThemeChanged for adaptive UI.

---

7. Review Checklist ✔️

Item	Check
Are all toggle interactions logged?	✅
Is StateChanging used for validation?	✅
Is logging enabled for debugging?	✅
Are event handlers properly assigned?	✅
Is theme tracking active (if needed)?	✅

---

8. Summary 📌

8.1 Feature Summary

Feature	Type	Description
Logger	interface	Custom logging system.
FileToggleSwitchLogger	class	Logs to a file.
Toggled	event	Fires when toggle state changes.
StateChanging	event	Fires before state change (cancelable).
SystemThemeChanged	event	Detects system-wide theme updates.

---

8.2 Key Takeaways

Key Takeaway	Description
Logging enables better debugging & analytics.	Helps track toggle interactions and diagnose issues.
Events allow real-time tracking & state control.	Provides instant feedback on toggle state changes.
StateChanging can restrict toggling when needed.	Use it to prevent unintended state changes.
Use SystemThemeChanged for seamless UI adaptation.	Ensures the control matches system theme changes dynamically.