Merge pull request #1330 from unoplatform/dev/doti/systemthemehelper-…

…page docs: Add `SystemThemeHelper` page
unoplatform · Jan 30, 2025 · 57c1ba4 · 57c1ba4
2 parents 14b1b5e + ae6aeb5
commit 57c1ba4
Show file tree

Hide file tree

Showing 3 changed files with 60 additions and 1 deletion.
diff --git a/doc/controls-styles.md b/doc/controls-styles.md
@@ -20,12 +20,12 @@ The `Uno.Toolkit.UI` library adds the following controls:
 
 The `Uno.Toolkit.UI` library adds the following helper classes:
 
-- `SystemThemeHelper`: Provides a set of helper methods to check the current operating system theme, and manipulate the application dark/light theme.
 - [`AncestorBinding` and `ItemsControlBinding`](helpers/ancestor-itemscontrol-binding.md): These markup extensions provides relative binding based on ancestor type. If you are familiar with WPF, they are very similar to `{RelativeSource Mode=FindAncestor}`.
 - [`CommandExtensions`](helpers/command-extensions.md): Provides Command/CommandParameter attached properties for common scenarios.
 - [`InputExtensions`](helpers/input-extensions.md): Provides various attached properties for _input controls_, such as `TextBox` and `PasswordBox`.
 - [`ItemsRepeaterExtensions`](helpers/itemsrepeater-extensions.md): Provides selection support for ItemsRepeater.
 - [`StatusBar`](helpers/StatusBar-extensions.md): Provides two attached properties on `Page` to controls the visual of the status bar on mobile platforms.
+- [`SystemThemeHelper`](helpers/SystemThemeHelper.md): Provides a set of helper methods to check the current operating system theme, and manipulate the application dark/light theme.
 - [`TabBarItemExtensions`](helpers/TabBarItem-extensions.md): Provides additional features for `TabBarItem`.
 - [`VisualStateManagerExtensions`](helpers/VisualStateManager-extensions.md): Provides a way of manipulating the visual states of Control with attached property.
 

diff --git a/doc/helpers/SystemThemeHelper.md b/doc/helpers/SystemThemeHelper.md
@@ -0,0 +1,57 @@
+---
+uid: Toolkit.Helpers.SystemThemeHelper
+---
+
+# SystemThemeHelper
+
+Provides utilities for managing and retrieving the current theme of the operating system and the application.
+
+## Theme Retrieval
+
+### Methods
+
+| Method                       | Return Type             | Description                                                                                                   |
+|------------------------------|-------------------------|---------------------------------------------------------------------------------------------------------------|
+| `GetCurrentOsTheme()`        | `ApplicationTheme`      | Retrieves the current theme of the operating system.                          |
+| `GetApplicationTheme()`      | `ApplicationTheme`      | **[Obsolete]** Retrieves the current theme of the application. Will be removed in future versions.           |
+| `GetRootTheme(XamlRoot?)`    | `ApplicationTheme`      | Gets the `ApplicationTheme` of the provided `XamlRoot`, or falls back to the operating system theme.          |
+| `IsAppInDarkMode()`          | `bool`                 | **[Obsolete]** Returns `true` if the application is currently in dark mode, otherwise `false`.               |
+| `IsRootInDarkMode(XamlRoot)` | `bool`                 | Determines if the provided `XamlRoot` is in dark mode.                                                       |
+
+### Usage
+
+Example of retrieving the current OS theme:
+
+```csharp
+var osTheme = SystemThemeHelper.GetCurrentOsTheme();
+Console.WriteLine($"Current OS Theme: {osTheme}");
+```
+
+Retrieve the application theme:
+
+```csharp
+var xamlRoot = someElement.XamlRoot;
+var appTheme = SystemThemeHelper.GetRootTheme(xamlRoot);
+Console.WriteLine($"Current App Theme: {appTheme}");
+```
+
+## Theme Management
+
+### Methods
+
+| Method                              | Description                                                                                  |
+|-------------------------------------|----------------------------------------------------------------------------------------------|
+| `SetApplicationTheme(bool)`         | **[Obsolete]** Sets the application theme to dark mode if `darkMode` is `true`, otherwise light mode. Will be removed in future versions. |
+| `SetRootTheme(XamlRoot?, bool)`     | Sets the theme for the provided `XamlRoot` based on the `darkMode` parameter.              |
+| `SetApplicationTheme(XamlRoot?, ElementTheme)` | Sets the `ElementTheme` (`Light` or `Dark`) for the provided `XamlRoot`. |
+| `ToggleApplicationTheme()`          | **[Obsolete]** Toggles the application theme between light and dark modes. Will be removed in future versions. |
+
+### Usage
+
+Set the theme for a specific `XamlRoot`:
+
+```csharp
+var xamlRoot = someElement.XamlRoot;
+SystemThemeHelper.SetApplicationTheme(xamlRoot, ElementTheme.Light);
+Console.WriteLine("XamlRoot theme set to Light Mode.");
+```
diff --git a/doc/toc.yml b/doc/toc.yml
@@ -76,6 +76,8 @@
       href: helpers/Selector-extensions.md
     - name: StatusBar Extensions
       href: helpers/StatusBar-extensions.md
+    - name: SystemThemeHelper
+      href: helpers/SystemThemeHelper.md
     - name: TabBarItem Extensions
       href: helpers/TabBarItem-extensions.md
     - name: VisualStateManager Extensions