Behavior and State

This feature governs the interactive behavior and current state of the control, enabling mode transitions and event-driven updates during user interactions.

Overview

The Behavior and State feature is primarily controlled via the CurrentMode property and the ThemeModeChanged event. Changing the CurrentMode not only updates the visual representation of the control (switching between Light, Dark, and Auto modes) but also triggers smooth animations and raises the ThemeModeChanged event for developers to handle additional application logic. This integrated approach ensures that the control remains responsive and provides immediate feedback to user interactions in .NET WinForms applications.

---

Key Points

Aspect	Detail
Properties	CurrentMode
Data Types	CurrentMode: Enum (ThemeMode with values Light, Dark, Auto)
Default Value	Light (as defined by the private field _currentMode)
Events	ThemeModeChanged (raises an event with a ThemeModeChangedEventArgs parameter when CurrentMode changes)
Category	Behavior
Effects	Updates the active theme mode, triggers visual animations, and notifies subscribers of the mode change
Mechanism	Setting a new value for CurrentMode initiates an animation (via timers) and calls Invalidate() to redraw the control, ensuring a smooth visual transition and state update

---

Best Practices

Practice	Description
Validate Mode Transitions	Ensure that the transition between modes (Light, Dark, Auto) is logical and fits within the overall application workflow.
Leverage ThemeModeChanged Event	Subscribe to the ThemeModeChanged event to update other parts of your application that may depend on the current theme mode, ensuring consistency across your UI.
Synchronize with Application State	Align the control’s mode with the broader application state to avoid conflicts between the control’s appearance and the overall theme of your application.

---

Common Pitfalls

Pitfall	Description
Ignoring the Event Subscription	Failing to subscribe to the ThemeModeChanged event might lead to missed opportunities for synchronizing the theme state across the application.
Abrupt Mode Changes	Rapid or uncoordinated changes to CurrentMode without considering the animation duration (AnimationDuration) may result in jarring transitions that confuse users.
Overlooking Animation Effects	Not accounting for the visual transition effects when changing modes may lead to a disjointed user experience, especially if the animations are not perceived as smooth or intuitive.

---

Usage Scenarios

Scenario	Description
Theme Switching	Use the CurrentMode property to switch between Light, Dark, and Auto modes based on user interaction, ensuring that the control's visual state is updated appropriately.
Synchronized UI Updates	Subscribe to the ThemeModeChanged event to trigger other UI updates (e.g., adjusting form backgrounds or updating related controls) when the theme changes.
Responsive User Interactions	Utilize the integrated animation triggered by CurrentMode changes to provide users with immediate and engaging feedback, enhancing overall interactivity.

---

Real Life Usage Scenarios

Scenario	Description
Adaptive Application Themes	In applications where users can toggle between different themes, the CurrentMode property allows for real-time adjustments, and the ThemeModeChanged event helps propagate the change throughout the UI.
Multi-Component Dashboards	In a dashboard with several interconnected widgets, the ThemeModeChanged event can be used to update the appearance of all components consistently when the theme is switched.
Accessibility-Driven Designs	For applications emphasizing accessibility, mode changes (e.g., high contrast dark mode) can be managed effectively by coordinating state changes across multiple controls.

---

Troubleshooting Tips

Tip	Description
Confirm Mode Value Changes	Ensure that the CurrentMode property is updated correctly by debugging its value and verifying that the corresponding animations trigger as expected.
Monitor Event Handlers	Check that subscribers to the ThemeModeChanged event are registered and that their handlers execute correctly upon a mode change.
Inspect Animation Timers	If transitions appear laggy or abrupt, examine the timers (_animationTimer, _hoverTimer, _pressTimer, _rippleTimer) and adjust AnimationDuration if necessary to smooth the animations.

---

Code Examples

Basic Integration

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

public class MainForm : Form
{
    public MainForm()
    {
        // Initialize the theme switcher control with default behavior settings
        var themeSwitcher = new SiticoneThemeSwitcher
        {
            Size = new Size(120, 120),
            Location = new Point(50, 50)
        };
        
        // Subscribe to the ThemeModeChanged event
        themeSwitcher.ThemeModeChanged += ThemeSwitcher_ThemeModeChanged;
        
        Controls.Add(themeSwitcher);
    }
    
    private void ThemeSwitcher_ThemeModeChanged(object sender, SiticoneThemeSwitcher.ThemeModeChangedEventArgs e)
    {
        // Respond to theme mode changes (for example, update the form's background)
        Console.WriteLine("Theme mode changed to: " + e.SetTheme);
    }
    
    [STAThread]
    public static void Main()
    {
        Application.EnableVisualStyles();
        Application.Run(new MainForm());
    }
}

Changing the Theme Mode Programmatically

// Assuming themeSwitcher is an existing instance of SiticoneThemeSwitcher

// Method to toggle the theme mode (cycles through Light, Dark, and Auto)
void ToggleThemeMode()
{
    // Cycle to the next theme mode
    themeSwitcher.CurrentMode = (SiticoneThemeSwitcher.ThemeMode)(((int)themeSwitcher.CurrentMode + 1) % 3);
    // The control will animate the transition and raise the ThemeModeChanged event
}

Reacting to Mode Changes Across the Application

// Example of subscribing to the ThemeModeChanged event to synchronize UI elements

public class DashboardForm : Form
{
    private SiticoneThemeSwitcher themeSwitcher;
    
    public DashboardForm()
    {
        themeSwitcher = new SiticoneThemeSwitcher
        {
            Size = new Size(100, 100),
            Location = new Point(20, 20)
        };
        themeSwitcher.ThemeModeChanged += OnThemeModeChanged;
        Controls.Add(themeSwitcher);
    }
    
    private void OnThemeModeChanged(object sender, SiticoneThemeSwitcher.ThemeModeChangedEventArgs e)
    {
        // Update the dashboard background color based on the selected theme
        switch (e.SetTheme)
        {
            case SiticoneThemeSwitcher.ThemeMode.Light:
                this.BackColor = Color.White;
                break;
            case SiticoneThemeSwitcher.ThemeMode.Dark:
                this.BackColor = Color.Black;
                break;
            case SiticoneThemeSwitcher.ThemeMode.Auto:
                // Implement auto mode logic, such as time-based adjustments
                this.BackColor = DateTime.Now.Hour < 18 ? Color.WhiteSmoke : Color.DimGray;
                break;
        }
    }
    
    [STAThread]
    public static void Main()
    {
        Application.EnableVisualStyles();
        Application.Run(new DashboardForm());
    }
}

---

Review

Aspect	Review
Interactive Responsiveness	The CurrentMode property and ThemeModeChanged event ensure that the control provides immediate and engaging feedback during theme transitions.
Event-Driven Integration	By leveraging the ThemeModeChanged event, developers can seamlessly integrate the control’s state changes with other parts of the application, enhancing overall consistency.
Smooth Visual Transitions	The integrated animations triggered by mode changes contribute to a modern, polished user experience that is both intuitive and visually appealing.

---

Summary

Summary Point	Description
Dynamic Mode Management	The Behavior and State feature provides developers with the ability to control and monitor the active theme mode, ensuring that the control responds fluidly to user interactions.
Event-Driven Architecture	Through the ThemeModeChanged event, the control enables centralized handling of theme changes, making it easier to keep the UI synchronized with the current state.
Enhanced User Experience	Smooth animations and immediate visual feedback during mode transitions significantly improve the usability and modern appeal of .NET WinForms applications.

---

Additional Sections

Performance Considerations

Consideration	Description
Animation Timer Impact	Changing CurrentMode triggers animations using timers; ensure that these timers are optimized and do not impact performance in scenarios with multiple animated controls.
Event Propagation	When multiple subscribers are attached to the ThemeModeChanged event, verify that event propagation does not lead to performance bottlenecks, especially during rapid state changes.

Customization Tips

Tip	Description
Centralize Theme Management	In larger applications, consider centralizing theme management to synchronize CurrentMode changes across multiple controls and forms, providing a unified user experience.
Utilize Debouncing Techniques	If rapid mode changes are expected, implement debouncing mechanisms to prevent excessive redraws and ensure smooth transitions.
Design for Flexibility	Keep in mind that behavior and state settings may need to evolve; design your event handlers and mode logic to be easily extendable for future enhancements.

---

This extensive documentation for the Behavior and State feature offers developers a detailed guide on managing the control’s interactive properties. The provided tables, code examples, and troubleshooting tips are designed to facilitate seamless integration and optimization of theme mode transitions and event-driven state changes in .NET WinForms applications.