State Persistence

Provides functionality to save and load the toggle’s current state, ensuring your SiticoneToggleButton retains its On/Off setting across application sessions.

Overview

The State Persistence feature uses JSON serialization to store or retrieve the toggle’s IsToggled value from a file. This is useful for preserving user preferences between application launches, or when switching between different user profiles. The mechanism is straightforward: you specify a key (used as a filename), and the control saves or loads the state from a .json file in your application’s directory.

---

Key API Members

Below is a table summarizing the core methods and events for state persistence:

Member	Type	Description	Example
SaveState(key)	void	Serializes the toggle’s current IsToggled value and saves it to a JSON file named <key>.json.	myToggle.SaveState("UserToggleState");
LoadState(key)	void	Reads <key>.json (if it exists), deserializes the stored toggle state, and applies it to IsToggled.	myToggle.LoadState("UserToggleState");
StateSaved	event	Fires after the toggle state has been successfully saved to file.	myToggle.StateSaved += (s, e) => { /* handle save complete */ };
StateLoaded	event	Fires after the toggle state has been successfully loaded from file and applied to the control.	myToggle.StateLoaded += (s, e) => { /* handle load complete */ };

---

Key Points to Note

1. Simple JSON File Storage

   • By default, the control saves its state in <AppDomain.BaseDirectory>/<key>.json.

   • Ensure your application has write/read permissions in this directory.

2. Selective Persistence

   • You can call SaveState(key) or LoadState(key) at any time, based on your app’s logic. For instance, call SaveState on form close, and LoadState on form load.

3. Event Notifications

   • StateSaved triggers once the file writing is done, letting you log or provide user feedback.

   • StateLoaded triggers once the file reading and state application are complete, useful for any post-load logic.

4. Error Handling

   • If exceptions occur during save or load (e.g., invalid file path, permission issues), they are handled with a simple Console.WriteLine in the code. Adapt for your own error handling as necessary.

5. IsReadonly Override**

   • If IsReadonly is true, loading a saved state still updates IsToggled, but user clicks remain blocked. Make sure you set IsReadonly = false if you want the user to toggle after loading.

---

Usage Example

// Assume you have a SiticoneToggleButton named myToggle

// Optional: Subscribe to events for debugging or user feedback
myToggle.StateSaved += (sender, e) =>
{
    Console.WriteLine("Toggle state saved successfully!");
};

myToggle.StateLoaded += (sender, e) =>
{
    Console.WriteLine("Toggle state loaded successfully!");
};

// Saving the toggle’s state to a file "MyToggleState.json"
myToggle.SaveState("MyToggleState");

// Later, or upon application restart, load the state back
myToggle.LoadState("MyToggleState");

// The control’s IsToggled property will reflect whatever was stored.

Tip: You can personalize the file path or name by passing different keys or modifying the code to use subdirectories, but ensure the path is valid and the directory exists.

---

Best Practices to Create Beautiful UI and Apps

Practice	Reason
Use unique keys if you have multiple toggles.	Prevents overlaps or overwriting states inadvertently for different controls.
Handle IO exceptions gracefully.	The provided code logs to Console.WriteLine; consider prompting the user or logging in your application’s environment.
Combine LoadState with UI initialization.	Ensure the toggle’s stored state is applied as early as possible (e.g., in Form_Load).
Use StateSaved / StateLoaded for logging or additional logic.	Great for auditing user settings or providing on-screen notifications.

---

Common Pitfalls and Design Considerations

Pitfall	Mitigation / Recommendation
Not verifying file existence prior to loading.	The provided code handles if a file doesn’t exist, but you can also check manually or prompt the user.
Overwriting states unintentionally with the same key.	Use meaningful key names (e.g., UserThemeToggle) to avoid mixing up states of different toggles.
Storing sensitive data in plain JSON.	For more sensitive contexts, consider encryption or alternate secure storage methods.
Forgetting to re-save after toggling changes.	Each time the user toggles, call SaveState at some logical point (e.g., on form close or a “Save Settings” button).

---

Review and Summary

• What You Learned: How the toggle’s state can be stored in JSON and reloaded to preserve On/Off preferences. You also learned about the StateSaved and StateLoaded events, which notify you after operations complete.

• Why It’s Important: Persistent settings enhance user experience, allowing consistent behavior and removing the frustration of reconfiguring controls on every startup.

• How to Move Forward: Integrate State Persistence into a broader settings strategy in your application. Combine it with your other UI persistence routines, ensuring the toggle reflects user preferences across sessions.

By implementing State Persistence, you seamlessly maintain your SiticoneToggleButton's toggle state, offering a fluid, user-centric experience every time the application runs.