---
description: >-
  This feature enables the control to detect and adapt to changes in the
  operating system's theme, ensuring that its appearance remains consistent with
  the user's system-wide visual preferences.
---

# System Theme Tracking

## Overview

The System Theme Tracking feature monitors the system's theme settings and automatically updates the control's internal state via the read-only `CurrentSystemTheme` property. An event, `SystemThemeChanged`, is raised whenever the detected theme changes, allowing developers to synchronize the control's appearance with system-wide visual updates (e.g., switching between Light and Dark modes). This capability ensures that the progress bar integrates seamlessly into modern, theme-aware applications.

***

### Properties and Their Details

The table below summarizes the main property and event related to system theme tracking:

| Member             | Type/Value                   | Description                                                                                                                          |
| ------------------ | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| CurrentSystemTheme | Read-only (SystemTheme enum) | Indicates the current system theme (e.g., Light or Dark), allowing the control to adapt its styling accordingly.                     |
| SystemThemeChanged | Event (EventHandler)         | Raised when the system theme changes, providing a mechanism for developers to update the UI dynamically in response to theme shifts. |

_Note:_ The system theme is determined primarily by querying registry settings for the `AppsUseLightTheme` value, and additional logic may be incorporated to handle various Windows versions.

***

### Key Points

| Aspect               | Details                                                                                                                                         |
| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| Dynamic Appearance   | By tracking the system theme, the control can automatically adjust its color scheme and other visual elements to match the user's preferences.  |
| Event-Driven Updates | The `SystemThemeChanged` event allows developers to hook into theme changes and perform additional UI updates or customizations as needed.      |
| Seamless Integration | This feature ensures that the control remains consistent with other applications on the system, enhancing overall user experience and cohesion. |

***

### Best Practices

| Practice                              | Explanation                                                                                                                                     |
| ------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| Subscribe to Theme Changes Early      | Register for the `SystemThemeChanged` event during control initialization to ensure that the application can respond promptly to theme changes. |
| Adjust Custom Styling Accordingly     | When the system theme changes, update any custom color settings or styles on the control to maintain consistency with the new theme.            |
| Test Under Different Theme Conditions | Simulate both Light and Dark modes during development to verify that the control adapts correctly and maintains legibility and visual appeal.   |

***

### Common Pitfalls

| Pitfall                                | Explanation                                                                                                                                            | Avoidance Strategy                                                                                                          |
| -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------- |
| Ignoring the Event                     | Failing to subscribe to the `SystemThemeChanged` event may cause the control to appear out-of-sync with system theme changes.                          | Ensure that your application subscribes to the event and triggers appropriate UI updates.                                   |
| Overriding Default Behavior            | Overriding the default theme adaptation logic without proper testing can lead to inconsistent UI appearances between the control and the system theme. | Customize theme-dependent styling carefully, and test thoroughly in both Light and Dark modes.                              |
| Dependency on Specific Registry Values | Relying solely on registry-based theme detection may not cover all edge cases, especially on newer or non-standard Windows configurations.             | Consider implementing additional checks or fallback mechanisms if theme detection appears inconsistent across environments. |

***

### Usage Scenarios

| Scenario                              | Description                                                                                                                                                                    | Sample Code Integration                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Automatic Theme Synchronization       | In applications that support both Light and Dark modes, use the control’s system theme tracking to automatically adjust its appearance when the user changes the system theme. | `csharp<br>// Subscribe to system theme changes<br>SiticoneHProgressBar progressBar = new SiticoneHProgressBar();<br>progressBar.SystemThemeChanged += (sender, newTheme) => {<br> // Update custom styling based on the new theme<br> if(newTheme == SystemTheme.Dark)<br> {<br> progressBar.BackgroundBarColor = Color.Black;<br> progressBar.BorderColor = Color.Gray;<br> }<br> else<br> {<br> progressBar.BackgroundBarColor = Color.White;<br> progressBar.BorderColor = Color.Black;<br> }<br> progressBar.Invalidate();<br>};<br>this.Controls.Add(progressBar);<br>` |
| Customized UI Updates on Theme Change | React to the `SystemThemeChanged` event by adjusting other UI elements in your application (not just the progress bar) to provide a cohesive theme experience.                 | `csharp<br>// Global theme change handling<br>SiticoneHProgressBar progressBar = new SiticoneHProgressBar();<br>progressBar.SystemThemeChanged += (sender, newTheme) => {<br> // For example, update the form's background color<br> this.BackColor = newTheme == SystemTheme.Dark ? Color.FromArgb(30,30,30) : Color.White;<br> // Optionally update the progress bar styling as well<br> progressBar.Invalidate();<br>};<br>this.Controls.Add(progressBar);<br>`                                                                                                            |

***

### Code Example and Demo

Below is an extensive example demonstrating how to integrate and respond to the System Theme Tracking feature in a simple WinForms application:

```csharp
using System;
using System.Drawing;
using System.Windows.Forms;
using SiticoneNetFrameworkUI;
using SiticoneNetFrameworkUI.Helpers.Enum;  // Assumes SystemTheme enum is defined here

namespace SystemThemeTrackingDemo
{
    public class MainForm : Form
    {
        private SiticoneHProgressBar progressBar;
        private Label themeLabel;

        public MainForm()
        {
            // Initialize the form
            Text = "System Theme Tracking Demo";
            Size = new Size(600, 400);
            this.StartPosition = FormStartPosition.CenterScreen;

            // Initialize the progress bar
            progressBar = new SiticoneHProgressBar()
            {
                Location = new Point(50, 50),
                Size = new Size(500, 30),
                Value = 50
            };

            // Initialize a label to display the current system theme
            themeLabel = new Label()
            {
                Location = new Point(50, 100),
                AutoSize = true,
                Font = new Font("Segoe UI", 12, FontStyle.Bold),
                Text = $"Current Theme: {progressBar.CurrentSystemTheme}"
            };

            // Subscribe to system theme changes
            progressBar.SystemThemeChanged += ProgressBar_SystemThemeChanged;

            // Add controls to the form
            Controls.Add(progressBar);
            Controls.Add(themeLabel);
        }

        private void ProgressBar_SystemThemeChanged(object sender, SystemTheme newTheme)
        {
            // Update the label text to reflect the new system theme
            themeLabel.Text = $"Current Theme: {newTheme}";

            // Optionally, update additional styling based on the theme
            if (newTheme == SystemTheme.Dark)
            {
                this.BackColor = Color.FromArgb(30, 30, 30);
                progressBar.BackgroundBarColor = Color.Black;
                progressBar.BorderColor = Color.Gray;
            }
            else
            {
                this.BackColor = Color.White;
                progressBar.BackgroundBarColor = Color.White;
                progressBar.BorderColor = Color.Black;
            }
            progressBar.Invalidate();
        }

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

***

### Review

| Aspect                    | Evaluation                                                                                                                                                                   |
| ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Dynamic Adaptation        | The control’s ability to track the system theme and raise events allows for dynamic, seamless updates to its styling, ensuring consistency with user preferences.            |
| Event-Driven Architecture | The `SystemThemeChanged` event provides a clean mechanism to integrate theme-based updates across the application, promoting a unified user interface.                       |
| Integration Simplicity    | Accessing the read-only `CurrentSystemTheme` property and subscribing to the event is straightforward, making theme tracking easy to implement within existing applications. |

***

### Summary

The System Theme Tracking feature enables the progress bar to dynamically adapt to the operating system's theme by exposing a read-only property (`CurrentSystemTheme`) and raising a `SystemThemeChanged` event when the theme updates. This allows developers to automatically synchronize the control’s appearance with the system-wide theme, ensuring a consistent and modern user interface that responds to Light and Dark mode changes.

***

### Additional Sections

#### Troubleshooting Tips

| Tip                                    | Description                                                                                                                              |
| -------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| Verify Event Subscription              | Ensure that the `SystemThemeChanged` event is properly subscribed to, so that your application receives theme change notifications.      |
| Test Across Different Windows Versions | Check the control's behavior on various versions of Windows, as registry settings for theme detection may differ and affect the outcome. |
| Confirm Consistent Styling             | After a theme change, verify that all related UI elements update correctly to maintain a harmonious look throughout the application.     |

#### Integration Checklist

| Checklist Item                                               | Status    |
| ------------------------------------------------------------ | --------- |
| Subscribe to the SystemThemeChanged event                    | \[ ] Done |
| Use the CurrentSystemTheme property to set initial styling   | \[ ] Done |
| Update custom UI elements when the theme changes             | \[ ] Done |
| Test in both Light and Dark modes                            | \[ ] Done |
| Validate performance and responsiveness during theme changes | \[ ] Done |

***

This comprehensive documentation should assist developers in understanding, integrating, and leveraging the System Theme Tracking feature of the provided control effectively.
