# System Theme Integration

{% hint style="info" %}
This feature is under development. The component comes with some of the Automatic Theme features disabled intentionally so that we integrate this innovation with other controls and components then support various Operating Systems including Virtual Machine instances.

Feel free to try the feature as trial only. This does not affect the rest of the features as they come fully tested and packed with innovation, ready for deployment in a real-world commercial software.
{% endhint %}

## Overview

The System Theme Integration feature allows the taskbar badge component to monitor and respond to changes in the Windows system theme by reading registry values and firing events when the theme changes. This ensures that the badge appearance remains consistent with the user's system settings. The read-only property CurrentSystemTheme indicates the active theme, while EnableSystemThemeTracker enables or disables this automatic monitoring. As always, it is critical that the ParentForm property is set exclusively in the parent's OnShown method for the system to work correctly.

***

### Key Points

<table><thead><tr><th width="266">Key Point</th><th>Description</th></tr></thead><tbody><tr><td>Automatic Theme Detection</td><td>The component automatically monitors the Windows registry to detect changes in the system theme.</td></tr><tr><td>Current Theme Indicator</td><td>The read-only property CurrentSystemTheme reflects the active system theme (e.g., Light or Dark).</td></tr><tr><td>Theme Change Event</td><td>The SystemThemeChanged event fires when a change in the system theme is detected.</td></tr><tr><td>Tracker Enablement</td><td>The EnableSystemThemeTracker property allows developers to enable or disable the system theme tracking feature.</td></tr><tr><td>ParentForm Dependency</td><td>The ParentForm property must be set in the parent's OnShown method for the theme tracker to initialize properly.</td></tr></tbody></table>

***

### Best Practices

<table><thead><tr><th width="299">Best Practice</th><th>Description</th></tr></thead><tbody><tr><td>Set ParentForm in OnShown</td><td>Always set the ParentForm property in the parent's OnShown override to ensure proper initialization of the system theme tracker.</td></tr><tr><td>Enable Tracking Judiciously</td><td>Use the EnableSystemThemeTracker property to turn theme monitoring on only when your application needs to adjust its appearance dynamically.</td></tr><tr><td>Respond to Theme Changes</td><td>Subscribe to the SystemThemeChanged event to update UI elements when the system theme changes.</td></tr><tr><td>Maintain Consistent Appearance</td><td>Use the CurrentSystemTheme property to adjust badge colors and styles so that they match the overall system theme.</td></tr></tbody></table>

***

### Common Pitfalls

<table><thead><tr><th width="359">Pitfall</th><th>How to Avoid It</th></tr></thead><tbody><tr><td>Incorrect ParentForm Setup</td><td>Ensure that the ParentForm property is set only in the OnShown method; setting it elsewhere can prevent the theme tracker from initializing properly.</td></tr><tr><td>Disabling Theme Tracking Unintentionally</td><td>Verify that EnableSystemThemeTracker is set to true if you require automatic theme updates; otherwise, manual UI adjustments may be needed.</td></tr><tr><td>Ignoring Theme Change Events</td><td>Always handle the SystemThemeChanged event to update your UI; ignoring it might lead to inconsistent application appearance.</td></tr><tr><td>Overcomplicating UI Updates</td><td>Avoid overly complex adjustments in response to theme changes; a simple color and style update usually suffices.</td></tr></tbody></table>

***

### Usage Scenarios

<table><thead><tr><th width="264">Scenario</th><th>Description</th></tr></thead><tbody><tr><td>Dynamic Theme Adaptation</td><td>Automatically adjust badge colors and other UI elements to match the system theme (Light or Dark) in real time.</td></tr><tr><td>User-Driven Customization</td><td>Allow users to choose whether they want the badge appearance to update with system theme changes by toggling EnableSystemThemeTracker.</td></tr><tr><td>Consistent Visual Experience</td><td>Ensure that your application maintains a consistent look and feel by responding to system-wide theme changes automatically.</td></tr></tbody></table>

***

### Real Life Usage Scenarios

<table><thead><tr><th width="245">Scenario</th><th>Description</th></tr></thead><tbody><tr><td>Productivity Applications</td><td>In applications like calendars or task managers, automatically adapt badge notifications to be visible in both light and dark modes.</td></tr><tr><td>Messaging Applications</td><td>Adjust the badge display to ensure that notifications remain legible regardless of the current system theme, enhancing user experience.</td></tr><tr><td>Customizable UI Themes</td><td>In applications that support custom themes, integrate system theme tracking to provide a seamless transition between user-selected and system settings.</td></tr></tbody></table>

***

### Troubleshooting Tips

<table><thead><tr><th width="325">Tip</th><th>Description</th></tr></thead><tbody><tr><td>Verify ParentForm Initialization</td><td>Ensure that the ParentForm property is set only in the parent's OnShown method to enable proper initialization of the theme tracker.</td></tr><tr><td>Monitor the Registry Changes</td><td>Use debugging tools to check if registry changes for the system theme are detected, particularly the AppsUseLightTheme value.</td></tr><tr><td>Check Event Subscriptions</td><td>Confirm that the SystemThemeChanged event is subscribed to correctly so that your UI updates when the theme changes.</td></tr><tr><td>Validate EnableSystemThemeTracker</td><td>If the system theme is not updating as expected, ensure that EnableSystemThemeTracker is set to true and not inadvertently disabled.</td></tr></tbody></table>

***

### Code Examples and Demos

#### Integration in Parent Form

Override the parent's OnShown method to set the ParentForm property for the taskbar badge component. This is the only acceptable location to set ParentForm.

```csharp
public partial class MainForm : Form
{
    private SiticoneTaskbarBadgeSystem taskbarBadge;

    public MainForm()
    {
        InitializeComponent();
        taskbarBadge = new SiticoneTaskbarBadgeSystem();
        // Enable system theme tracking
        taskbarBadge.EnableSystemThemeTracker = true;
    }

    protected override void OnShown(EventArgs e)
    {
        base.OnShown(e);
        // Set the ParentForm property here; do not set it anywhere else.
        taskbarBadge.ParentForm = this;
    }
}
```

#### Handling Theme Changes

Subscribe to the SystemThemeChanged event to update your application's UI when the system theme changes.

```csharp
public MainForm()
{
    InitializeComponent();
    taskbarBadge = new SiticoneTaskbarBadgeSystem();
    taskbarBadge.EnableSystemThemeTracker = true;

    // Subscribe to the theme changed event
    taskbarBadge.SystemThemeChanged += TaskbarBadge_SystemThemeChanged;
}

private void TaskbarBadge_SystemThemeChanged(object sender, SystemThemeChangedEventArgs e)
{
    // Update the badge or other UI elements based on the new theme
    if (e.NewTheme == SystemTheme.Dark)
    {
        // Example: Change badge colors for dark theme
        taskbarBadge.BadgeColor = Color.DarkGray;
        taskbarBadge.TextColor = Color.White;
    }
    else
    {
        // Example: Change badge colors for light theme
        taskbarBadge.BadgeColor = Color.Red;
        taskbarBadge.TextColor = Color.White;
    }
}
```

#### Complete Demo Application Flow

Below is a comprehensive demo that shows how to integrate system theme tracking with the taskbar badge component.

```csharp
public partial class MainForm : Form
{
    private SiticoneTaskbarBadgeSystem taskbarBadge;

    public MainForm()
    {
        InitializeComponent();
        taskbarBadge = new SiticoneTaskbarBadgeSystem();
        // Enable system theme tracking
        taskbarBadge.EnableSystemThemeTracker = true;
        // Optionally, subscribe to the theme change event
        taskbarBadge.SystemThemeChanged += TaskbarBadge_SystemThemeChanged;
    }

    protected override void OnShown(EventArgs e)
    {
        base.OnShown(e);
        // Set the ParentForm property here; this is the only place it should be set.
        taskbarBadge.ParentForm = this;
    }

    private void TaskbarBadge_SystemThemeChanged(object sender, SystemThemeChangedEventArgs e)
    {
        // Example of handling the theme change event to update the UI
        if (e.NewTheme == SystemTheme.Dark)
        {
            taskbarBadge.BadgeColor = Color.DarkGray;
            taskbarBadge.TextColor = Color.White;
        }
        else
        {
            taskbarBadge.BadgeColor = Color.Red;
            taskbarBadge.TextColor = Color.White;
        }
    }
}
```

***

### Review

<table><thead><tr><th width="258">Aspect</th><th>Description</th></tr></thead><tbody><tr><td>ParentForm Requirement</td><td>The ParentForm property must be set only in the parent's OnShown method to correctly initialize system theme tracking.</td></tr><tr><td>Automatic Theme Detection</td><td>The component monitors registry changes to update the UI based on the current system theme, reflected by CurrentSystemTheme.</td></tr><tr><td>Event-Driven Updates</td><td>The SystemThemeChanged event provides a hook to update UI elements when the system theme changes, ensuring a consistent look.</td></tr><tr><td>Tracker Enablement</td><td>The EnableSystemThemeTracker property allows developers to control whether system theme monitoring is active.</td></tr></tbody></table>

***

### Summary

<table><thead><tr><th width="242">Summary Aspect</th><th>Description</th></tr></thead><tbody><tr><td>Feature Purpose</td><td>Enables the badge component to automatically detect and adapt to changes in the system theme, ensuring visual consistency.</td></tr><tr><td>Implementation Focus</td><td>Ensure ParentForm is set in the OnShown method and subscribe to the SystemThemeChanged event for dynamic UI updates.</td></tr><tr><td>Developer Considerations</td><td>Use EnableSystemThemeTracker to manage automatic theme tracking and adjust UI elements in response to system theme changes.</td></tr><tr><td>Benefit</td><td>Enhances the application's visual coherence by ensuring that the badge and related UI elements match the current system theme.</td></tr></tbody></table>

***

### Additional Useful Sections

#### Integration Checklist

<table><thead><tr><th width="325">Step</th><th>Details</th></tr></thead><tbody><tr><td>1. Create Badge Component Instance</td><td>Instantiate the SiticoneTaskbarBadgeSystem in your main form.</td></tr><tr><td>2. Override OnShown</td><td>Override the parent's OnShown method to set the ParentForm property, which is essential for system theme tracking to function.</td></tr><tr><td>3. Enable Theme Tracking</td><td>Set EnableSystemThemeTracker to true if automatic theme updates are desired.</td></tr><tr><td>4. Subscribe to Theme Change Event</td><td>Handle the SystemThemeChanged event to update UI elements dynamically when the system theme changes.</td></tr><tr><td>5. Test the Integration</td><td>Run your application and switch system themes to verify that the badge updates its appearance accordingly.</td></tr></tbody></table>

#### Demo Application Flow

```csharp
public partial class MainForm : Form
{
    private SiticoneTaskbarBadgeSystem taskbarBadge;

    public MainForm()
    {
        InitializeComponent();
        taskbarBadge = new SiticoneTaskbarBadgeSystem();
        taskbarBadge.EnableSystemThemeTracker = true;
        taskbarBadge.SystemThemeChanged += TaskbarBadge_SystemThemeChanged;
    }

    protected override void OnShown(EventArgs e)
    {
        base.OnShown(e);
        // Ensure the ParentForm property is set here only.
        taskbarBadge.ParentForm = this;
    }

    private void TaskbarBadge_SystemThemeChanged(object sender, SystemThemeChangedEventArgs e)
    {
        // Adjust badge colors based on the new system theme.
        if (e.NewTheme == SystemTheme.Dark)
        {
            taskbarBadge.BadgeColor = Color.DarkGray;
            taskbarBadge.TextColor = Color.White;
        }
        else
        {
            taskbarBadge.BadgeColor = Color.Red;
            taskbarBadge.TextColor = Color.White;
        }
    }
}
```

***

This comprehensive documentation for the System Theme Integration feature details how to integrate automatic system theme tracking into your .NET WinForms applications using the SiticoneTaskbarBadgeSystem component. By following these guidelines and examples, developers can ensure that their badge display dynamically adapts to system theme changes, providing a consistent and polished user experience.