System Theme Integration

System Theme Integration enables the control to automatically adjust its appearance to match the current system theme (light or dark) and react dynamically to theme changes.

Overview

This section documents the properties and behaviors that allow the control to track and respond to system theme changes. Developers can enable this feature to ensure that the control’s colors, gradients, and other visual aspects automatically update to align with the operating system's theme settings.

---

Key Points

Aspect	Description
Automatic Theme Detection	The control reads the system's theme settings from the registry and updates its appearance accordingly.
Dynamic Theme Updates	The control subscribes to system events (e.g., WM_THEMECHANGED and UserPreferenceChanged) to detect and apply theme changes in real time.
Customizable Theme Behavior	Developers can enable or disable theme tracking with a single property, allowing for manual theme management if preferred.

---

Best Practices

Practice Area	Recommendation
Enable Theme Tracking	Set the TrackSystemTheme property to true to automatically synchronize the control’s appearance with the system theme for a consistent user experience.
Define Fallback Styles	Provide default colors that work well in both light and dark themes, ensuring that the control remains usable even if system theme detection fails.
Test Across Themes	Test the control in both light and dark modes to verify that all visual elements (borders, fills, shadows, text colors) update correctly and remain legible.

---

Common Pitfalls

Pitfall	Description
Inconsistent Theme Updates	Failing to subscribe or unsubscribe properly from system theme events may result in delayed or inconsistent updates when the system theme changes.
Overriding User Preferences	Overriding the control’s appearance after a system theme change may cause conflicts with the automatic theme integration if not handled carefully.
Hard-Coded Colors	Relying on hard-coded colors without accounting for both light and dark themes can lead to poor contrast or readability when the system theme changes.

---

Real Life Usage Scenarios

Scenario	Description
Adaptive Application Interfaces	Integrate the control into applications that support both light and dark modes to provide a seamless and visually consistent user experience.
Dynamic Theme Switching	Use system theme integration to automatically update control styling when the user switches between light and dark themes in the operating system.
Themed Control Libraries	Develop control libraries that automatically adapt to the host application's theme settings, reducing the need for manual styling adjustments.

---

Troubleshooting Tips

Issue	Suggested Solution
Theme Not Updating Automatically	Verify that TrackSystemTheme is set to true and that the control is subscribed to system events (e.g., UserPreferenceChanged, WM_THEMECHANGED).
Inconsistent Appearance After Theme Change	Ensure that default colors and gradients are defined to accommodate both light and dark themes, and check for any hard-coded values that might conflict.
Performance Impact on Theme Detection	If theme detection impacts performance, consider throttling event handling or deferring theme updates during periods of rapid theme switching.

---

Property Reference

Below is a reference table of key properties and events for system theme integration:

Property/Method/Event	Type/Return	Description
TrackSystemTheme	bool	Enables or disables automatic tracking of the system theme.
CurrentSystemTheme	SystemTheme	Returns the current system theme (e.g., Light or Dark) as determined from the system registry.
SystemThemeChanged	event	Event raised when the system theme changes, allowing custom handling in response to theme updates.
WndProc (with WM_THEMECHANGED)	override method	Processes the WM_THEMECHANGED message to detect system theme changes and update the control accordingly.

---

Code Examples

Below are code examples that demonstrate how to integrate and use system theme integration in the control.

Example 1: Enabling Automatic Theme Tracking

This example demonstrates how to enable automatic theme tracking so that the control updates its appearance to match the system theme.

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

public class ThemeIntegrationForm : Form
{
    public ThemeIntegrationForm()
    {
        var customTextBox = new SiticoneTextBox
        {
            // Enable system theme tracking
            TrackSystemTheme = true,
            
            // Set initial appearance properties (these may be adjusted automatically based on theme)
            SolidBorderColor = Color.LightSlateGray,
            SolidFillColor = Color.White,
            
            // Location and size
            Location = new Point(20, 20),
            Size = new Size(300, 40)
        };

        // Optionally subscribe to the SystemThemeChanged event for additional custom actions
        customTextBox.SystemThemeChanged += (sender, e) =>
        {
            MessageBox.Show($"System theme changed to: {e.Theme}", "Theme Update", MessageBoxButtons.OK, MessageBoxIcon.Information);
        };

        Controls.Add(customTextBox);
        Text = "System Theme Integration Demo";
        Size = new Size(360, 120);
    }

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

---

Example 2: Manual Theme Handling

This example shows how to disable automatic theme tracking and apply custom logic to update the control’s appearance based on a simulated theme change.

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

public class ManualThemeForm : Form
{
    private SiticoneTextBox customTextBox;
    private Button toggleThemeButton;
    private bool isLightTheme = true;

    public ManualThemeForm()
    {
        customTextBox = new SiticoneTextBox
        {
            TrackSystemTheme = false, // Disable automatic tracking
            SolidBorderColor = Color.LightSlateGray,
            SolidFillColor = Color.White,
            Location = new Point(20, 20),
            Size = new Size(300, 40)
        };

        toggleThemeButton = new Button
        {
            Text = "Toggle Theme",
            Location = new Point(20, 80),
            Size = new Size(300, 30)
        };
        toggleThemeButton.Click += ToggleThemeButton_Click;

        Controls.Add(customTextBox);
        Controls.Add(toggleThemeButton);
        Text = "Manual Theme Integration Demo";
        Size = new Size(360, 160);
    }

    private void ToggleThemeButton_Click(object sender, EventArgs e)
    {
        isLightTheme = !isLightTheme;

        // Update control appearance based on simulated theme
        if (isLightTheme)
        {
            customTextBox.SolidBorderColor = Color.LightSlateGray;
            customTextBox.SolidFillColor = Color.White;
        }
        else
        {
            customTextBox.SolidBorderColor = Color.DarkSlateGray;
            customTextBox.SolidFillColor = Color.Black;
        }
    }

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

---

Frequently Asked Questions

Question	Answer
How does the control detect system theme changes?	The control monitors system messages (such as WM_THEMECHANGED and UserPreferenceChanged) and reads registry values to determine the current system theme.
How do I enable automatic theme updates?	Set the TrackSystemTheme property to true; the control will then automatically update its appearance and raise the SystemThemeChanged event when needed.
Can I override the default behavior after a theme change?	Yes, subscribe to the SystemThemeChanged event to apply additional customizations when the theme changes.
What happens if the system theme detection fails?	The control defaults to a light theme if it cannot retrieve the theme settings from the registry.
Is it necessary to manually update the control’s appearance if system theme tracking is enabled?	No, once TrackSystemTheme is enabled, the control handles appearance updates automatically; manual changes may override these defaults if applied afterward.

---

Integration Checklist

Step	Verification
Enable Theme Tracking	Confirm that TrackSystemTheme is set to true in the control properties if automatic theme updates are desired.
System Message Handling	Verify that the control correctly processes WM_THEMECHANGED and UserPreferenceChanged events to detect theme changes.
Appearance Consistency	Test the control in both light and dark modes to ensure that colors, gradients, and other appearance properties update as expected.
Custom Event Handling	If subscribing to SystemThemeChanged, ensure that the event handler performs the intended customizations without interfering with default behavior.
Fallback Behavior	Verify that the control defaults to a light theme when theme detection fails or is not available.
Cross-Platform Consistency	Confirm that theme integration behaves consistently across different Windows versions and environments with varying theme settings.

---

Review

Review Aspect	Details
Theme Responsiveness	The control effectively detects and responds to system theme changes, ensuring a consistent look with the operating system's settings.
Ease of Integration	With a single property (TrackSystemTheme), developers can enable or disable theme tracking, simplifying integration into theme-aware applications.
Customization Flexibility	The provision of the SystemThemeChanged event allows developers to further tailor the control’s appearance beyond the automatic updates.
Robustness	By relying on system messages and registry settings, the control maintains accurate theme integration across various Windows environments.

---

Summary

System Theme Integration provides a mechanism for the control to automatically detect and adapt to system-wide theme changes.

With properties like TrackSystemTheme and events such as SystemThemeChanged, developers can ensure that the control remains visually consistent with the user's system preferences, reducing manual styling effort and enhancing the overall user experience.