System Theme (Preview)

This feature is in preview. It tracks the system’s theme (light or dark), and will soon ensure consistent integration with the operating system’s look and feel, across various systems, etc.

Overview

The System Theme Integration feature is managed through a set of public properties and events that allow the control to track the system theme. When enabled, the control reads theme settings from the system registry and listens to system events, updating its internal theme state and raising events when a change is detected.

Property / Event	Type	Default	Description
TrackSystemTheme	bool	false	When set to true, the control automatically tracks system theme changes and updates its appearance accordingly.
CurrentSystemTheme	SystemTheme (enum)	Light	A read-only property that reflects the current system theme, either Light or Dark.
SystemThemeChanged Event	EventHandler	N/A	An event that is raised when the system theme changes, allowing developers to perform additional actions in response to theme updates.

Internally, the control monitors system theme changes by reading values from the registry and subscribing to system events such as UserPreferenceChanged. When a theme change is detected, the control updates its internal state and triggers the SystemThemeChanged event.

---

Key Points

Aspect	Detail
Automatic Updates	When TrackSystemTheme is enabled, the control automatically adjusts its visual properties to match the current system theme.
Read-Only Theme Status	CurrentSystemTheme provides a real-time, read-only value representing the active system theme, allowing for conditional styling in code.
Event-Driven Integration	The SystemThemeChanged event notifies subscribers whenever the system theme changes, facilitating dynamic UI updates.

---

Best Practices

Practice	Explanation
Enable Theme Tracking Only When Needed	Set TrackSystemTheme to true in applications where visual consistency with the system theme is critical, avoiding unnecessary overhead otherwise.
Subscribe to SystemThemeChanged Event	Use the event to trigger additional UI updates or reapply custom styles that depend on the system theme.
Test on Multiple Windows Versions	Since registry keys and system events might vary, test the integration on different versions of Windows to ensure consistent behavior.

---

Common Pitfalls

Pitfall	How to Avoid
Not Unsubscribing from System Events	Ensure that event subscriptions (e.g., UserPreferenceChanged) are removed when the control is disposed to avoid memory leaks or unexpected behavior.
Assuming Immediate Theme Change Response	Be aware that there might be a short delay between a system theme change and the control’s update; use the SystemThemeChanged event to synchronize other UI elements if needed.
Overriding Visuals Post-Integration	Avoid hardcoding visual styles that conflict with the dynamic theme adjustments; let the control update its appearance based on CurrentSystemTheme.

---

Usage Scenarios

Scenario	Example Use Case
Adaptive UI Design	In applications that support both light and dark themes, enable theme tracking so that the control automatically adapts to system changes.
Dynamic Visual Feedback	Use the SystemThemeChanged event to update other parts of your UI (e.g., dialogs or menus) when the system theme changes.
Consistent Integration with OS Themes	Enable TrackSystemTheme to ensure that the control’s colors and styles are consistent with the operating system’s current appearance.

---

Code Examples

Example 1: Enabling System Theme Tracking This sample demonstrates how to enable system theme tracking and subscribe to the SystemThemeChanged event.

// Instantiate the control
SiticonePhoneNumberBox phoneNumberBox = new SiticonePhoneNumberBox();

// Enable system theme tracking
phoneNumberBox.TrackSystemTheme = true;

// Subscribe to the SystemThemeChanged event to update UI elements if necessary
phoneNumberBox.SystemThemeChanged += (sender, e) =>
{
    // Retrieve the current system theme
    SystemTheme currentTheme = phoneNumberBox.CurrentSystemTheme;

    // For example, update a label to reflect the theme
    themeStatusLabel.Text = $"Current Theme: {currentTheme}";
    
    // Additional logic can be added to reapply custom styles or perform other UI updates
};

// Set location and size
phoneNumberBox.Location = new Point(20, 20);
phoneNumberBox.Size = new Size(250, 40);

// Add the control to the form
this.Controls.Add(phoneNumberBox);

Example 2: Reacting to Theme Changes in Your Application This sample shows how to perform additional UI updates when the system theme changes.

private void InitializePhoneNumberBox()
{
    SiticonePhoneNumberBox phoneNumberBox = new SiticonePhoneNumberBox();
    phoneNumberBox.TrackSystemTheme = true;
    
    phoneNumberBox.SystemThemeChanged += OnSystemThemeChanged;

    phoneNumberBox.Location = new Point(20, 80);
    phoneNumberBox.Size = new Size(250, 40);
    this.Controls.Add(phoneNumberBox);
}

private void OnSystemThemeChanged(object sender, EventArgs e)
{
    var phoneNumberBox = sender as SiticonePhoneNumberBox;
    if (phoneNumberBox != null)
    {
        // Update a form background or other UI elements based on the current theme
        if (phoneNumberBox.CurrentSystemTheme == SystemTheme.Dark)
        {
            this.BackColor = Color.FromArgb(30, 30, 30);
        }
        else
        {
            this.BackColor = Color.White;
        }
    }
}

---

Review

Aspect	Review Comment
Integration Simplicity	With just a few property settings and event subscriptions, the control seamlessly integrates system theme changes into the UI.
Dynamic Visual Adaptation	The CurrentSystemTheme property and SystemThemeChanged event provide immediate feedback, ensuring the control’s appearance remains consistent with the OS.
Resource Management	Proper handling of system events (unsubscribing during disposal) is essential to avoid memory leaks; the control’s internal design manages this appropriately.

---

Summary

The System Theme Integration feature of the SiticonePhoneNumberBox control allows the control to automatically adjust its appearance based on the operating system’s current theme. By enabling TrackSystemTheme, the control monitors registry values and system events to update its CurrentSystemTheme property and raise the SystemThemeChanged event. This dynamic behavior supports a cohesive UI that adapts to light and dark modes without additional manual configuration.

---

Additional Notes

Note Type	Detail
Extensibility	The theme integration mechanism can be extended or customized by handling the SystemThemeChanged event to modify additional UI elements.
Integration Tips	When using theme tracking, ensure that any static visual customizations (such as hard-coded colors) are updated or overridden as necessary.
Debugging	Use logging or UI indicators (e.g., a label displaying CurrentSystemTheme) during development to verify that theme changes are detected and processed correctly.