State Management

A feature that enables the button to maintain and persist its toggled state, providing a built-in mechanism for tracking user interactions.

Overview

The State Management feature in the SiticoneTileButton control provides properties that allow developers to monitor and control whether the button is in a toggled state. In addition, developers can enable state persistence so that the button retains its toggled status between sessions. This feature is particularly useful in scenarios where buttons function as switches or indicators that reflect a current setting.

The main properties provided are:

1. IsToggled: Indicates whether the button is currently in a toggled state. The control automatically toggles this value upon click events.

2. PersistState: Determines whether the button should retain its state across sessions, allowing the toggled state to be saved and restored.

---

Feature Properties Table

Property Name	Type	Default Value	Description
IsToggled	bool	false	Indicates whether the button is in a toggled state; toggles automatically on user interaction.
PersistState	bool	false	Enables the button to maintain its state across sessions if state persistence logic is implemented.

---

Key Points

Aspect	Details
Toggle Behavior	The button automatically changes its IsToggled value when clicked, simulating switch-like functionality.
State Persistence	When PersistState is enabled, the control is intended to save and restore its toggled state across application sessions (custom persistence logic may be required).
User Feedback	The toggled state can be used to provide visual feedback that clearly indicates the button's current mode.

---

Best Practices

Practice	Explanation
Implement persistence logic if needed	If using PersistState, ensure you add the necessary code to store and retrieve the state (e.g., via settings or configuration files).
Use toggled buttons for binary options	Ideal for features such as on/off switches or selection indicators where a binary state is required.
Update visual cues based on toggled state	Consider adjusting the button’s appearance (color, text, etc.) to reflect the toggled state clearly to the user.
Test state changes in various scenarios	Verify that toggling behaves consistently across different user interactions (click, keyboard, etc.).

---

Common Pitfalls

Pitfall	Recommendation
Neglecting persistence implementation	PersistState only flags the intention to save state; you must implement the actual persistence logic separately.
Inconsistent state feedback	Ensure that any visual cues (such as color changes or text updates) are synchronized with the IsToggled property.
Overcomplicating state logic	Keep state management straightforward to avoid bugs in toggling behavior; rely on the built-in toggling mechanism unless advanced logic is needed.

---

Usage Scenarios

Scenario	Description
Toggle Buttons for Settings	Use the IsToggled property to create buttons that turn features on or off (e.g., enabling/disabling notifications).
Persistent User Preferences	Enable PersistState to maintain user selections across sessions for a more personalized experience.
Mode Selection Controls	Implement toggle buttons for selecting modes or options in a user interface, such as switching between light and dark themes.

---

Code Examples

Example 1: Basic Toggle Button

This example demonstrates a simple SiticoneTileButton that toggles its state on click. The button’s toggled state is managed internally.

using System;
using System.Drawing;
using System.Windows.Forms;
using SiticoneNetFrameworkUI;

namespace StateManagementDemo
{
    public class MainForm : Form
    {
        public MainForm()
        {
            // Initialize the SiticoneTileButton with basic state management
            var toggleButton = new SiticoneTileButton
            {
                Text = "Toggle Me",
                Size = new Size(220, 150),
                Location = new Point(50, 50),
                
                // State Management settings
                IsToggled = false,
                PersistState = false  // Set to true if you implement persistence logic
            };

            // Optional: Update visual appearance based on toggle state
            toggleButton.Click += (s, e) =>
            {
                // Toggle is handled internally; add custom behavior here if needed.
                if (toggleButton.IsToggled)
                {
                    toggleButton.Text = "ON";
                    toggleButton.BaseColor = Color.Green;
                }
                else
                {
                    toggleButton.Text = "OFF";
                    toggleButton.BaseColor = Color.Red;
                }
            };

            Controls.Add(toggleButton);
        }

        [STAThread]
        static void Main()
        {
            Application.EnableVisualStyles();
            Application.Run(new MainForm());
        }
    }
}

Example 2: Persisting Toggle State

This example shows a conceptual approach for persisting the toggled state across sessions. (Note: Actual persistence implementation, such as using application settings, must be added.)

using System;
using System.Drawing;
using System.Windows.Forms;
using SiticoneNetFrameworkUI;

namespace PersistentStateManagementDemo
{
    public class MainForm : Form
    {
        // Simulated storage for demonstration purposes
        private bool persistedState = false;

        public MainForm()
        {
            // Retrieve persisted state (simulate loading from settings)
            bool initialState = persistedState;

            var persistentToggleButton = new SiticoneTileButton
            {
                Text = initialState ? "ON" : "OFF",
                Size = new Size(220, 150),
                Location = new Point(30, 30),
                
                // State Management settings
                IsToggled = initialState,
                PersistState = true  // Flag indicating state should be persisted
            };

            // Update visual state and simulate persistence on toggle
            persistentToggleButton.Click += (s, e) =>
            {
                if (persistentToggleButton.IsToggled)
                {
                    persistentToggleButton.Text = "ON";
                    persistentToggleButton.BaseColor = Color.Green;
                }
                else
                {
                    persistentToggleButton.Text = "OFF";
                    persistentToggleButton.BaseColor = Color.Red;
                }

                // Simulate saving state (in a real application, save to settings or a file)
                persistedState = persistentToggleButton.IsToggled;
            };

            Controls.Add(persistentToggleButton);
        }

        [STAThread]
        static void Main()
        {
            Application.EnableVisualStyles();
            Application.Run(new MainForm());
        }
    }
}

---

Review

Aspect	Review Comments
Toggle Functionality	The built-in toggling mechanism provides a simple way to create buttons that can switch states with a single click.
State Persistence	While the PersistState flag indicates intent, developers must implement the actual persistence logic as needed.
User Interaction	Visual feedback tied to the toggled state (e.g., text changes, color updates) greatly enhances usability and clarity.

---

Summary

The State Management feature of the SiticoneTileButton control offers an easy method to manage and persist a button’s toggled state. With properties like IsToggled and PersistState, developers can create interactive buttons that act as switches and optionally retain their state across sessions. Proper implementation of state persistence, along with clear visual feedback, ensures that the control effectively communicates its current status to users.

---

Additional Resources

Resource Category	Description
Integration Tips	Review the provided code examples to see how state management can be integrated and extended in your application.
Persistence Strategies	Consider exploring methods such as application settings or configuration files to implement effective state persistence.
UI/UX Best Practices	Ensure that visual cues (such as text or color changes) align with the state of the button for improved user experience.

---

By following these guidelines and examples, developers can seamlessly integrate and customize the State Management feature of the SiticoneTileButton control, thereby enhancing the interactivity and user feedback of their .NET WinForms applications.