# System Theme (Preview) ## 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. ```csharp // 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. ```csharp 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. | --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs-siticoneframework.gitbook.io/home/net-framework-or-net-core-ui/input-controls/siticone-phonenumberbox/system-theme-preview.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.