> For the complete documentation index, see [llms.txt](https://docs-siticoneframework.gitbook.io/home/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs-siticoneframework.gitbook.io/home/net-framework-or-net-core-ui/progress-and-loading/siticone-hprogressbar/system-theme-tracking.md).
# System Theme Tracking
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.
## 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
// Subscribe to system theme changes
SiticoneHProgressBar progressBar = new SiticoneHProgressBar();
progressBar.SystemThemeChanged += (sender, newTheme) => {
// Update custom styling based on the new theme
if(newTheme == SystemTheme.Dark)
{
progressBar.BackgroundBarColor = Color.Black;
progressBar.BorderColor = Color.Gray;
}
else
{
progressBar.BackgroundBarColor = Color.White;
progressBar.BorderColor = Color.Black;
}
progressBar.Invalidate();
};
this.Controls.Add(progressBar);
` |
| 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
// Global theme change handling
SiticoneHProgressBar progressBar = new SiticoneHProgressBar();
progressBar.SystemThemeChanged += (sender, newTheme) => {
// For example, update the form's background color
this.BackColor = newTheme == SystemTheme.Dark ? Color.FromArgb(30,30,30) : Color.White;
// Optionally update the progress bar styling as well
progressBar.Invalidate();
};
this.Controls.Add(progressBar);
` |
***
### 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.