Theme Management

Preview and do not use the theme feature in development, yet. We're refining it and other controls.

This feature enables developers to control and monitor the visual theme of the control, allowing seamless switching between light, dark, system, and custom appearances to match operating system preferences.

---

Overview

The Theme Management feature provides the following front-facing functionalities:

• Theme Selection: Developers can set the control’s theme to Light, Dark, System, or Custom using the Theme property.

• System Theme Detection: The control automatically detects the current operating system theme via the CurrentSystemTheme property.

• Dynamic Theme Updates: When the operating system theme changes, the control notifies subscribers through the SystemThemeChanged event.

• Internal Theme Adjustment: The internal ThemeManager class handles system-specific theme detection and monitors for theme changes (Windows, macOS, and Linux).

---

Key Points

Aspect	Description
Theme Modes	The control supports four theme modes: Light, Dark, System, and Custom.
Dynamic System Updates	Changes in the system’s theme trigger the SystemThemeChanged event, allowing the control to update accordingly.
Automatic Color Adjustments	When in System mode, the control updates colors (e.g., UnSelectedEmojiColor, HoveredEmojiColor, BackColor) based on system theme.
Developer Integration	Developers can subscribe to theme events to synchronize application UI with the control’s appearance.

---

Best Practices

Practice	Recommendation
Set the Theme early	Configure the Theme property at form initialization to ensure a consistent appearance from the start.
Handle Theme Changes	Subscribe to the SystemThemeChanged event to update other UI elements in your application when the system theme changes.
Test on multiple platforms	Since the control supports Windows, macOS, and Linux, verify theme changes on all targeted platforms.
Use custom themes with caution	If using the Custom theme, ensure that the custom color settings do not conflict with other UI elements.

---

Common Pitfalls

Pitfall	Explanation	How to Avoid
Ignoring system theme updates	Failing to subscribe to the SystemThemeChanged event may lead to a static UI that does not match OS changes.	Always add an event handler to SystemThemeChanged if dynamic updates are required.
Overriding theme colors	Manually overriding colors when in System mode may conflict with automatic updates.	Use the provided theme properties and avoid hardcoding colors when in System theme mode.
Platform-specific discrepancies	Differences in system theme detection across platforms may result in inconsistent appearances.	Test the control thoroughly on Windows, macOS, and Linux, and adjust custom settings as needed.

---

Usage Scenarios

Scenario	Description
Consistent UI Appearance	Ensure that the control’s appearance aligns with the OS theme by setting Theme = ThemeMode.System.
Custom Branding	Use a Custom theme for branding purposes by manually setting color properties while still leveraging theme management features.
Reactive UI Updates	Subscribe to SystemThemeChanged to trigger additional UI adjustments across the application when the OS theme changes.

Code Sample: Setting System Theme

// Setting the control to use the system theme mode
SiticoneRatingEmoji ratingControl = new SiticoneRatingEmoji();
ratingControl.Theme = SiticoneRatingEmoji.ThemeMode.System;

// Subscribe to theme changes to update other parts of your UI if necessary
ratingControl.SystemThemeChanged += (sender, args) =>
{
    // Example: Change form background based on the new system theme
    if (args.NewTheme == SystemTheme.Dark)
    {
        this.BackColor = Color.FromArgb(32, 32, 32);
    }
    else
    {
        this.BackColor = Color.White;
    }
};

---

Real Life Usage Scenarios

Scenario	Description
Cross-Platform Applications	Applications that run on multiple platforms can automatically adjust their appearance based on the underlying OS theme.
Adaptive User Interfaces	Applications that support both light and dark modes can use this control to match the overall system preference, enhancing user experience.
Accessibility Enhancements	For users who rely on system-level high-contrast themes, integrating the control’s theme management ensures consistency and improved accessibility.

Code Sample: Custom Handling of Theme Changes

// In a multi-theme application, update the entire form's controls when the system theme changes
ratingControl.SystemThemeChanged += (sender, args) =>
{
    // Update form and control styles based on the new theme
    if (args.NewTheme == SystemTheme.Dark)
    {
        this.BackColor = Color.Black;
        ratingControl.UnSelectedEmojiColor = Color.LightGray;
    }
    else
    {
        this.BackColor = Color.White;
        ratingControl.UnSelectedEmojiColor = Color.DarkGray;
    }
    // Force a refresh to apply the new theme immediately
    this.Refresh();
};

---

Troubleshooting Tips

Tip	Recommendation
Event not firing	Verify that the operating system supports dynamic theme changes and that the event subscription is correctly set up.
Inconsistent color updates	Ensure that the control’s theme properties are not being overridden elsewhere in your code.
Platform detection issues	Test the control on different OS platforms; if issues arise, review the internal logic within the ThemeManager class.

---

Review

Aspect	Comments
Integration	The theme management is seamlessly integrated into the control via properties and events, making it straightforward for developers to use.
Flexibility	Offers both automatic and custom theme options, allowing for a wide range of application styles.
Responsiveness	The control automatically updates its appearance based on system theme changes, enhancing user experience.
Documentation	Clear separation of theme-related properties, events, and usage examples in the provided code.

---

Summary

Summary Point	Explanation
Theme Management Overview	Provides comprehensive tools to match the control’s appearance with the operating system's theme.
Dynamic and Custom Options	Supports automatic theme detection as well as manual customizations through the Theme property.
Developer-Friendly Integration	With clear event notifications and property settings, integrating theme management is straightforward.
Cross-Platform Compatibility	Designed to work across Windows, macOS, and Linux, ensuring a consistent user experience in diverse environments.

---

Additional Resources

Resource	Description
Code Example Repository	Refer to the sample code provided in this documentation for integration ideas.
API Reference	Use the code comments in the provided source as a guide for detailed behavior of each property and method.
Platform Testing Guidelines	Ensure thorough testing on all supported platforms (Windows, macOS, Linux) to handle any OS-specific nuances.

---

The Theme Management feature is designed to simplify the process of keeping the control's UI in sync with the operating system's theme settings. We're refining this feature to be perfect for production scenarios and usage.