Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 4 additions & 4 deletions .github/workflows/speech.yml
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,7 @@ jobs:
strategy:
fail-fast: false
matrix:
os: [macos-14, macos-15-intel, windows-2022, ubuntu-latest]
os: [macos-15, macos-15-intel, windows-2022, ubuntu-latest]
env:
MACOSX_DEPLOYMENT_TARGET: '11.0'
steps:
Expand All @@ -39,16 +39,16 @@ jobs:
if: runner.os == 'macOS'
run: bash crates/speech/swift/tests/run.sh
- name: Compile iOS backends
if: matrix.os == 'macos-14'
if: matrix.os == 'macos-15'
run: |
rustup target add aarch64-apple-ios aarch64-apple-ios-sim
cargo check -p robius-speech --target aarch64-apple-ios
cargo check -p robius-speech --target aarch64-apple-ios-sim
- uses: actions/setup-java@v4
if: matrix.os == 'macos-14'
if: matrix.os == 'macos-15'
with:
distribution: temurin
java-version: '17'
- name: Android speech lifecycle regressions
if: matrix.os == 'macos-14'
if: matrix.os == 'macos-15'
run: python3 crates/speech/tests/android_retry_test.py
51 changes: 51 additions & 0 deletions .github/workflows/theme.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,51 @@
name: System theme

on:
# Only on main: a branch pushed to this repo would otherwise also run every
# job a second time through its pull request.
push:
branches: [main]
paths:
- crates/theme/**
- Cargo.toml
- Cargo.lock
- .github/workflows/theme.yml
pull_request:
paths:
- crates/theme/**
- Cargo.toml
- Cargo.lock
- .github/workflows/theme.yml

jobs:
# The Android backend is checked by android.yml, along with every other crate.
native:
name: Theme (${{ matrix.os }})
runs-on: ${{ matrix.os }}
strategy:
fail-fast: false
matrix:
os: [macos-15, macos-15-intel, windows-2022, ubuntu-latest]
steps:
- uses: actions/checkout@v5
- uses: dtolnay/rust-toolchain@stable
with:
components: clippy
- uses: Swatinem/rust-cache@v2
- run: cargo clippy -p robius-theme --all-targets -- -D warnings
- run: cargo test -p robius-theme
# This flips the runner's own app theme and back, so it only runs when asked for.
- name: Follow a real theme change
if: runner.os == 'Windows'
run: cargo test -p robius-theme --test windows -- --ignored
- name: Compile the iOS backend
if: matrix.os == 'macos-15'
run: |
rustup target add aarch64-apple-ios aarch64-apple-ios-sim
cargo clippy -p robius-theme --target aarch64-apple-ios -- -D warnings
cargo clippy -p robius-theme --target aarch64-apple-ios-sim -- -D warnings
- name: Compile for a platform without a system theme
if: runner.os == 'Linux'
run: |
rustup target add wasm32-unknown-unknown
cargo clippy -p robius-theme --target wasm32-unknown-unknown -- -D warnings
13 changes: 13 additions & 0 deletions Cargo.lock

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

5 changes: 5 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -38,6 +38,9 @@ There's also a [status table](#crate--platform-status-table) that shows what eac
* [`robius-speech`](crates/speech/): streams native speech-to-text results and microphone levels on macOS, iOS, Android, and Windows.
* Provides recording sessions with partial/final transcripts, graceful stop, and cancellation, independently of the UI toolkit.
* Linux doesn't offer any OS-provided speech-to-text functionality, so this crate can't do anything on Linux.
* [`robius-theme`](crates/theme/): gets the system's light or dark theme, and allows you to subscribe and receive a callback whenever it changes.
* This reads the `AppleInterfaceStyle` preference on macOS, the main `UIScreen`'s traits on iOS, `Configuration.uiMode` on Android, the `AppsUseLightTheme` registry value on Windows, and the XDG Settings portal on Linux.
* The system reports each change, so nothing is checked on a timer. On macOS and Windows it has no dependencies at all.
* [`robius-web-auth-session`](crates/web_auth_session/): runs an OAuth/SSO login process in the OS's own in-app browser session, and then sends the result back to your app.
* Currently this is for iOS only, based on `ASWebAuthenticationSession`. There's no other safe/supported way to do web login on iOS, because otherwise iOS will suspend your app while showing the browser.

Expand All @@ -53,6 +56,7 @@ Symbol legend: ✅ fully supported · ⚠️ partial, or has issues · 🚧 unde
| [`robius-open`](crates/open/) | ✅ `NSWorkspace.openURL` | ✅ `UIApplication.openURL` | ✅ `Intent` (`ACTION_VIEW`) | ✅ `Launcher.LaunchUriAsync` (WinRT) | ✅ `xdg-open` |
| [`robius-share`](crates/share/) | ✅ `NSSharingServicePicker` | ✅ `UIActivityViewController` | ✅ `ACTION_SEND` / `ACTION_SEND_MULTIPLE` via `Intent.createChooser` | ✅ WinRT Share UI (`DataTransferManager`) | ✅ XDG portal "Open With" chooser (`OpenURI` / `OpenFile`), or its `SaveFiles` dialog for multi-item payloads; `xdg-open` fallback |
| [`robius-speech`](crates/speech/) | ✅ `SFSpeechRecognizer` + `AVAudioEngine` | ✅ `SFSpeechRecognizer` + `AVAudioEngine` | ✅ `SpeechRecognizer` (needs an installed recognition service) | ✅ SAPI dictation (needs an installed speech language) | ❌ no OS-native speech-to-text service exists |
| [`robius-theme`](crates/theme/) | ✅ `AppleInterfaceStyle` preference + `AppleInterfaceThemeChangedNotification` | ✅ `UIScreen` traits + `registerForTraitChanges` (`traitCollectionDidChange` before iOS 17) | ✅ `Configuration.uiMode` + `ComponentCallbacks` | ✅ `AppsUseLightTheme` registry value + `RegNotifyChangeKeyValue` | ✅ XDG Settings portal (`color-scheme`) |
| [`robius-web-auth-session`](crates/web_auth_session/) | ❌ not supported | ✅ `ASWebAuthenticationSession` | 🚧 planned (custom chrome tabs) | ❌ not supported | ❌ not supported |


Expand All @@ -70,6 +74,7 @@ On Android, most crates support API Level 26 and up (Android 8.0), but we're alw
| `robius-location` | 1.77 | 26 |
| `robius-open` | 1.72 | None |
| `robius-share` | 1.77 | 26) |
| `robius-theme` | 1.77 | 26 |
| `robius-web-auth-session` | 1.71 | Unsupported |


Expand Down
52 changes: 52 additions & 0 deletions crates/theme/Cargo.toml
Original file line number Diff line number Diff line change
@@ -0,0 +1,52 @@
[package]
name = "robius-theme"
version.workspace = true
edition.workspace = true
rust-version = "1.77.0"
authors.workspace = true
description = "Rust abstractions for getting the system's light or dark theme and subscribing to changes"
documentation = "https://docs.rs/robius-theme"
homepage.workspace = true
keywords = ["robius", "theme", "dark-mode", "appearance"]
categories.workspace = true
license.workspace = true
repository.workspace = true
readme = "README.md"

## macOS and Windows need no dependencies: they call a few system functions directly.

[target.'cfg(target_os = "android")'.dependencies]
jni.workspace = true
robius-android-env.workspace = true

[target.'cfg(target_os = "ios")'.dependencies]
dispatch2.workspace = true
objc2.workspace = true
objc2-foundation = { workspace = true, features = [
"NSArray",
"NSEnumerator",
"NSNotification",
"NSSet",
"NSString",
] }
objc2-ui-kit = { workspace = true, features = [
"UIApplication",
"UIInterface",
"UIResponder",
"UIScene",
"UIScreen",
"UITraitCollection",
"UIView",
"UIWindow",
"UIWindowScene",
] }

[target.'cfg(target_os = "linux")'.dependencies]
zbus = { workspace = true, features = ["async-io"] }

## The example needs an `NSApplication`, since macOS only reports changes to apps.
[target.'cfg(target_os = "macos")'.dev-dependencies]
objc2.workspace = true

[lints.rust]
unsafe_op_in_unsafe_fn = "forbid"
114 changes: 114 additions & 0 deletions crates/theme/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,114 @@
# robius-theme

Get the system's appearance setting (light/dark theme) and subscribe to appearance changes, all from Rust without depending on a UI toolkit.

```rust
use robius_theme::{query, subscribe, Subscription, Theme};

fn follow_the_system() -> robius_theme::Result<Subscription> {
let theme = query()?.unwrap_or(Theme::Light);
println!("System appearance: {theme:?}");

subscribe(|theme| {
// Runs on a system thread, so send the theme to your UI thread.
println!("System appearance: {theme:?}");
})
}
```

`Some(Theme::Light)` and `Some(Theme::Dark)` are concrete preferences.
`None` means no preference is available; your application should choose a fallback.
`Err` means that the system couldn't be asked, so your app should keep whichever theme it already has.

## Receiving updates

Keep the `Subscription` alive for as long as you want updates, and drop it to stop them.

The callback receives the current theme first, possibly before `subscribe()` returns, and then each change.
It never receives the same theme twice in a row.

The system reports each change, so this crate never checks the theme on a timer.
All of your subscriptions share one system subscription per process.

The callback runs on a thread that the system picks.
That is your main thread on macOS, iOS, and Android, and a background thread on Linux and Windows.
Keep it short and send the theme to your UI thread or event loop.
A call that is already running may still finish after you drop the subscription.

## Platforms

| Platform | Where the theme comes from | Requirements |
| --- | --- | --- |
| macOS | ✅ the `AppleInterfaceStyle` preference and `AppleInterfaceThemeChangedNotification` | macOS 11+; updates need an `NSApplication` |
| iOS | ✅ the main `UIScreen`'s `userInterfaceStyle` and UIKit's trait changes | iOS 13+ |
| Android | ✅ `Configuration.uiMode` and the application's `onConfigurationChanged` | API 26+; an Android SDK and JDK to build |
| Windows | ✅ the `AppsUseLightTheme` registry value, or the contrast theme's colors | Windows 10+ |
| Linux | ✅ the XDG Settings portal's `color-scheme` | a desktop that offers it through `xdg-desktop-portal` |
| others | ❌ | `Error::Unsupported` |

macOS and Windows need no dependencies at all. iOS uses `objc2`, Android uses `jni`, and Linux uses `zbus`.

### macOS

Apple documents neither the preference nor the change it posts, but AppKit itself and Apple's own apps rely on both.

* Your app's own `NSApp.appearance` has no effect on what this crate reports.
* The system only reports changes to processes that have an `NSApplication`. A command-line tool can `query()`, but its callback is only called once.
* On macOS 11 to 13 with the Auto appearance, the preference can be a day out of date after the Mac was shut down across sunrise or sunset. This is a macOS bug that later releases fixed.

### iOS

The main screen always has the system's theme, whatever your windows and views override.

* On iOS 17 and later, changes are reported even while a window has `overrideUserInterfaceStyle` set.
* On iOS 13 to 16, a change that happens while your key window overrides its style is reported when your app next becomes active, or as soon as you call `query()` on the main thread.
* If your `Info.plist` sets `UIUserInterfaceStyle`, the system hides its theme from your app, so this crate reports the value you set there.
* `query()` works on any thread, but before your app's UI has started, a background thread gets `None`.

### Android

Android 8 and 9 have a night mode, and the system-wide dark theme arrived in Android 10. This crate reports whichever one the device has.

* From Android 12, `UiModeManager.setApplicationNightMode(YES/NO)` replaces the system's theme in everything your app can see, so this crate reports the theme you forced. Call it with `MODE_NIGHT_AUTO` to follow the system again, and the callback then receives the system's theme.
* The app's Android context must be set up before you use this crate, which `robius-android-env` does. A Makepad app must depend on `robius-use-makepad` for that.
* Building for Android needs the Android SDK (a platform and build-tools) and a JDK, because a small Java class is compiled into the crate. Set `ANDROID_HOME` and `JAVA_HOME` if they aren't found, and `ANDROID_PLATFORM` or `ANDROID_BUILD_TOOLS_VERSION` to choose versions other than the newest installed ones.

### Windows

Windows keeps the app theme in the registry value that this crate reads, and it's the value that the `UISettings` API reads too.

* While a contrast theme is on, the theme is dark if that theme's window background is dark.
* An app that forces its own title bars or menus to light or dark has no effect on what this crate reports.

### Linux

The [Settings portal](https://flatpak.github.io/xdg-desktop-portal/docs/doc-org.freedesktop.portal.Settings.html) is the one source that every modern desktop shares, and the only one that works inside Flatpak and Snap.
GNOME 42+, KDE Plasma 5.24+, Cinnamon, Xfce 4.18+, MATE, COSMIC, and elementary OS all offer its `color-scheme`, and `darkman` adds it to any other desktop.

Older desktops only name a theme, so where the portal has no `color-scheme` (or one that the desktop doesn't keep current), this crate reads the desktop's own setting:

* GNOME before 42 (like Ubuntu 20.04) and KDE Plasma before 5.24: the GTK theme's name, or KDE's window color, through the same portal.
* Cinnamon, MATE and Xfce: their own GTK theme setting.
* Window managers without a desktop (i3, sway, Openbox, LXDE and others), and systems without the portal: GTK's `settings.ini`.

A theme whose name has "dark" in it (like `Yaru-dark`, but not `Arc-Darker`) counts as dark.
Changes to all of these are followed too, but only on desktops that need them: on a current desktop, none of this runs.

* GNOME 42+ reports its default light style as no preference (`None`).
* `query()` can wait up to a second while the desktop starts the portal. Once a subscription has received the theme, `query()` answers from memory.

## Following the system in an app with its own theme setting

Most apps let the user choose Light, Dark, or Auto. For Auto, your app should stop forcing a theme on the parts that the system draws for it:
that is required on Android 12+ (see above), and it lets title bars and keyboards change together with the system on macOS and iOS.
In Makepad, that is `NativeAppearance::System`.

When the user goes back to Auto, call `query()` again for the theme to show right away.

## Example

This prints the system theme and then each change:

```sh
cargo run -p robius-theme --example subscribe
```
Loading
Loading