# native-theme-gtk
Resolve the user's effective GTK 4 theme into a versioned JSON snapshot.
This crate asks GTK to resolve the theme, including its normal lookup rules and
user CSS overrides. It does not attempt to implement a second GTK CSS parser.
On GTK 4.20 and newer, the desktop's explicit interface color scheme is applied
before sampling so dark and light variants produce their effective colors.
An explicit `GTK_THEME` environment override remains authoritative.
```console
$ native-theme-gtk > gtk-theme.json
```
The snapshot currently contains:
- GTK theme, display backend, font, icon, and cursor settings
- animation, scrolling, input, color-scheme, contrast, reduced-motion, and
dark-variant preferences (when supported by the GTK runtime)
- GTK and libadwaita symbolic colors recognized by the active theme
- a toolkit-neutral semantic palette derived from those symbolic colors
- preferred sizes and foreground colors for representative widgets across
normal, hovered, pressed, focused, checked, selected, disabled, and inactive
states
## Process model
`probe()` initializes GTK and must be called from the main thread. A GPUI, iced,
or other non-GTK application should normally execute the CLI in a subprocess and
deserialize its output. This keeps the two GUI event loops and global toolkit
state isolated.
## GPUI integration
Enable the optional bridge to the existing `native-theme-gpui` crate:
```toml
native-theme-gtk = { version = "0.1", features = ["gpui"] }
```
Keep the probe in a subprocess, deserialize its snapshot, and build a complete
`gpui-component` theme:
```rust
let snapshot: native_theme_gtk::ThemeSnapshot =
serde_json::from_slice(&probe_output.stdout)?;
let theme: gpui_component::theme::Theme = snapshot.to_gpui_theme()?;
// During GPUI application setup, after gpui_component::init(cx):
cx.set_global(theme);
```
`resolve_native_theme()` exposes the intermediate `native_theme::ResolvedTheme`
when an application needs it. The GTK values are merged over native-theme's
Adwaita preset, which supplies fields GTK does not expose through its public
theme API. Call `snapshot.validate()` after deserializing snapshots received
from any source other than this crate's probe.
GTK 3 and deeper GTK 4 render-node extraction are intentionally left for later
backends. The schema is versioned so those additions can remain compatible.
## Development
```console
nix develop
cargo test
cargo run
```
Display-independent tests run with `cargo test`. To include the GTK integration
matrix against the current display:
```console
NATIVE_THEME_RUN_LIVE_TESTS=1 cargo test --test cli
```
`./scripts/check` is the same format, test, strict Clippy, and rustdoc gate used
by CI. CI runs the live matrix under a virtual X11 display.