Theme & DPI Integration

This feature enables the SiticoneFlowPanel to respond to system theme changes and DPI adjustments, ensuring a consistent appearance and optimal scaling in modern WinForms applications.

Overview

The Theme & DPI Integration feature provides the SiticoneFlowPanel control with the ability to track and react to system-wide theme changes and DPI variations. Through properties such as IsTrackingTheme and CurrentTheme, as well as events like SystemThemeChanged and DpiChanged, developers can ensure that the control remains visually consistent with system settings. The control intercepts native Windows messages (e.g., WM_THEMECHANGED and WM_DPICHANGED) to automatically adjust its appearance and scaling, creating a seamless integration with the operating system's visual configuration.

---

Detailed Documentation

1. Properties, Methods, and Events

The table below summarizes the key elements associated with Theme & DPI Integration:

Property/Method/Event	Type	Description
IsTrackingTheme	Property	Enables the control to track system theme changes; when set to true, the control will update its CurrentTheme automatically.
CurrentTheme	Property (Read-Only)	Retrieves the current system theme (Light, Dark, or Custom), as determined by the system settings and registry values.
SystemThemeChanged	Event	Fired when a system theme change is detected, allowing developers to apply custom adjustments or visual updates in response.
DpiChanged	Event	Raised when the system DPI changes; provides updated DPI information through DpiChangedEventArgs for custom scaling logic.
ScrollToControl(Control, bool) (related)	Method	When used in conjunction with DPI scaling, ensures that scrolling behavior remains consistent across different DPI settings.

---

2. Key Points

Key Point	Details
Automatic Theme Detection	The control leverages registry values and system messages to detect whether the system is using a light, dark, or custom (high contrast) theme.
Real-Time Theme Updates	With IsTrackingTheme enabled, any changes to the system theme will update the CurrentTheme property and trigger the SystemThemeChanged event.
DPI Change Handling	The control intercepts WM_DPICHANGED messages to recalculate scaling factors, ensuring that the UI elements are correctly sized and positioned.
Event-Driven Adjustments	Developers can subscribe to SystemThemeChanged and DpiChanged events to perform additional customizations in response to system changes.

---

3. Code Examples

Example 1: Enabling Theme Tracking

The following sample demonstrates how to enable system theme tracking and subscribe to the theme change event:

using System;
using System.Windows.Forms;
using SiticoneNetFrameworkUI;

namespace ThemeDpiDemo
{
    public partial class MainForm : Form
    {
        private SiticoneFlowPanel flowPanel;

        public MainForm()
        {
            InitializeComponent();
            InitializeFlowPanel();
        }

        private void InitializeFlowPanel()
        {
            flowPanel = new SiticoneFlowPanel
            {
                Dock = DockStyle.Fill,
                // Enable tracking of system theme changes
                IsTrackingTheme = true
            };

            // Subscribe to the system theme changed event
            flowPanel.SystemThemeChanged += FlowPanel_SystemThemeChanged;

            // Add sample controls
            for (int i = 0; i < 3; i++)
            {
                Label label = new Label
                {
                    Text = $"Sample Label {i + 1}",
                    Width = 120,
                    Height = 30,
                    TextAlign = System.Drawing.ContentAlignment.MiddleCenter,
                    BorderStyle = BorderStyle.FixedSingle
                };
                flowPanel.Controls.Add(label);
            }

            Controls.Add(flowPanel);
        }

        private void FlowPanel_SystemThemeChanged(object sender, SiticoneFlowPanel.SystemThemeChangedEventArgs e)
        {
            // Example: Log the new theme and update UI elements accordingly
            MessageBox.Show($"System theme changed to: {e.NewTheme}");
            // Additional custom theme-related logic can be implemented here.
        }
    }
}

Example 2: Handling DPI Changes

This example demonstrates how to subscribe to the DpiChanged event to adjust custom UI elements when the DPI changes:

using System;
using System.Windows.Forms;
using SiticoneNetFrameworkUI;

namespace ThemeDpiDemo
{
    public partial class MainForm : Form
    {
        private SiticoneFlowPanel flowPanel;

        public MainForm()
        {
            InitializeComponent();
            InitializeFlowPanel();
        }

        private void InitializeFlowPanel()
        {
            flowPanel = new SiticoneFlowPanel
            {
                Dock = DockStyle.Fill,
                // Enable automatic scaling based on DPI changes
                EnableAutoScale = true
            };

            // Subscribe to the DPI changed event
            flowPanel.DpiChanged += FlowPanel_DpiChanged;

            // Add sample controls to the panel
            for (int i = 0; i < 4; i++)
            {
                Button btn = new Button
                {
                    Text = $"Button {i + 1}",
                    Width = 90,
                    Height = 35
                };
                flowPanel.Controls.Add(btn);
            }

            Controls.Add(flowPanel);
        }

        private void FlowPanel_DpiChanged(object sender, SiticoneFlowPanel.DpiChangedEventArgs e)
        {
            // Example: Adjust custom UI elements based on the new DPI value.
            MessageBox.Show($"DPI changed to: {e.NewDpi}");
            // Additional custom scaling logic can be implemented here.
        }
    }
}

Example 3: Integrating Theme and DPI Changes Together

In this example, both theme tracking and DPI scaling are enabled for a seamless UI adaptation:

using System;
using System.Windows.Forms;
using SiticoneNetFrameworkUI;

namespace ThemeDpiDemo
{
    public partial class MainForm : Form
    {
        private SiticoneFlowPanel flowPanel;

        public MainForm()
        {
            InitializeComponent();
            InitializeFlowPanel();
        }

        private void InitializeFlowPanel()
        {
            flowPanel = new SiticoneFlowPanel
            {
                Dock = DockStyle.Fill,
                IsTrackingTheme = true,    // Enable system theme tracking
                EnableAutoScale = true     // Enable DPI based scaling
            };

            // Subscribe to theme and DPI events
            flowPanel.SystemThemeChanged += (s, e) =>
            {
                // Log or adjust UI on theme change
                Console.WriteLine($"Theme updated to: {e.NewTheme}");
            };

            flowPanel.DpiChanged += (s, e) =>
            {
                // Log or adjust UI on DPI change
                Console.WriteLine($"New DPI: {e.NewDpi}");
            };

            // Add some controls to the panel
            for (int i = 0; i < 6; i++)
            {
                TextBox textBox = new TextBox
                {
                    Text = $"TextBox {i + 1}",
                    Width = 150,
                    Height = 25,
                    Margin = new Padding(5)
                };
                flowPanel.Controls.Add(textBox);
            }

            Controls.Add(flowPanel);
        }
    }
}

---

4. Usage Scenarios

Scenario	Explanation
Adaptive UI Design	Applications that need to adjust their appearance dynamically to reflect the user's system theme or high-contrast settings benefit from these features.
High DPI Displays	With the prevalence of high-resolution displays, enabling DPI change handling ensures that the UI scales correctly and remains crisp and legible.
Consistent Look Across Systems	Ensuring that the control automatically adapts to system theme changes provides a consistent and modern look regardless of user settings.
Accessibility Focused Applications	Applications aiming for accessibility can leverage high contrast (custom theme) detection to adjust UI elements for better readability and usability.

---

5. Best Practices

Best Practice	Recommendation
Enable Theme Tracking When Needed	Set IsTrackingTheme to true only when your application needs to dynamically adjust to theme changes, to avoid unnecessary processing.
Respond Appropriately to DPI Changes	Use the DpiChanged event to adjust custom elements or fonts; ensure that your scaling logic does not distort the layout of critical UI components.
Consolidate Theme Adjustments	When a theme change occurs, centralize UI updates (e.g., colors, fonts) within the event handler to maintain consistency across the application.
Test on Multiple Systems	Validate behavior on systems with different themes and DPI settings to ensure the control renders correctly across various configurations.

---

6. Common Pitfalls

Pitfall	Explanation	How to Avoid
Ignoring Theme Change Events	Not subscribing to or properly handling SystemThemeChanged can lead to outdated or inconsistent UI appearances.	Always implement an event handler to update UI elements when a theme change is detected.
Overcomplicating DPI Scaling	Overly complex scaling logic in response to DPI changes can lead to layout issues or performance overhead.	Keep DPI scaling adjustments straightforward, and test under different DPI settings to confirm consistency.
Conflicting Customizations	Custom UI updates made independently of the theme or DPI events might conflict with the automatic adjustments provided by the control.	Centralize UI adjustments within the event handlers to ensure consistency.

---

7. Review

Aspect	Summary
Theme Tracking	Uses IsTrackingTheme and CurrentTheme to automatically monitor and react to system theme changes, ensuring visual consistency.
DPI Responsiveness	Captures DPI change events to enable dynamic scaling, making the control adaptable to high-resolution displays.
Event-Driven Customization	Provides events (SystemThemeChanged, DpiChanged) that allow developers to extend functionality with custom UI adjustments.
Seamless Integration	Integrates with Windows system messages (WM_THEMECHANGED and WM_DPICHANGED) to provide real-time updates without manual intervention.

---

8. Summary

The Theme & DPI Integration feature is essential for modern applications that require their UI to be adaptive and responsive to system-wide changes. By leveraging system messages and registry settings, the SiticoneFlowPanel control can automatically adjust its appearance and scaling based on the current theme and DPI settings. This ensures that the control maintains a consistent, professional look across various system configurations, ultimately enhancing the user experience.

---

9. Additional Resources

Resource	Description
Code Samples	Utilize the provided code examples to integrate theme tracking and DPI handling into your applications.
Windows API Documentation	Review documentation on WM_THEMECHANGED and WM_DPICHANGED messages for deeper insight into system integration.
UI/UX Best Practices	Consult modern UI/UX design guidelines to optimize the use of theme and DPI integrations for a cohesive user experience.

This comprehensive documentation serves as a guide for developers aiming to integrate and fully utilize the Theme & DPI Integration feature of the SiticoneFlowPanel control in .NET WinForms applications.