native_theme/resolve/context.rs
1//! Resolution-time inputs (font DPI, button order, icon theme) captured
2//! once per theme-build and passed by reference through the pipeline.
3//!
4//! Per `docs/archive/v0.5.7_gaps.md` §G7:
5//! intentionally NO `impl Default` — runtime-detected types must signal
6//! intent at the call site. Use [`ResolutionContext::from_system`] for
7//! production, or [`ResolutionContext::for_tests`] for deterministic
8//! test values.
9
10use std::borrow::Cow;
11
12use crate::model::DialogButtonOrder;
13
14/// Resolution-time inputs captured once per theme-build.
15///
16/// Replaces the `font_dpi: Option<f32>` parameter on
17/// [`ThemeMode::into_resolved`](crate::theme::ThemeMode::into_resolved) and
18/// the corresponding internal `OverlaySource` field.
19///
20/// Accessibility preferences live on
21/// [`SystemTheme`](crate::SystemTheme), NOT here — accessibility is a
22/// render-time concern, not a resolve-time concern
23/// (`docs/archive/v0.5.7_gaps.md` §G7).
24///
25/// # Examples
26///
27/// ```
28/// use native_theme::resolve::ResolutionContext;
29///
30/// // Production: auto-detect from OS.
31/// let ctx = ResolutionContext::from_system();
32/// assert!(ctx.font_dpi > 0.0);
33///
34/// // Tests: deterministic values.
35/// let ctx = ResolutionContext::for_tests();
36/// assert_eq!(ctx.font_dpi, 96.0);
37/// assert!(ctx.icon_theme.is_none());
38/// ```
39#[derive(Clone, Debug)]
40pub struct ResolutionContext {
41 /// Font DPI for pt-to-px conversion. It must be finite and positive:
42 /// resolution rejects any other value as one
43 /// [`Error::ResolutionInvalid`](crate::Error::ResolutionInvalid) on the
44 /// path `context.font_dpi`, before any point size is converted.
45 ///
46 /// [`from_system`](Self::from_system) detects it: 72.0 on macOS, 96.0 on
47 /// Windows, 96.0 on a GNOME or Budgie desktop (with the `portal` feature;
48 /// GNOME's text-scaling factor is carried in
49 /// [`AccessibilityPreferences`](crate::AccessibilityPreferences), not in
50 /// the DPI; an unrecognised desktop counts as the one
51 /// [`SystemTheme::from_system`](crate::SystemTheme::from_system) reads,
52 /// its portal backend's once a system read has asked it), and on other
53 /// Linux desktops KDE's kcmfonts `forceFontDPI` on an X11
54 /// session (with the `kde` feature), then `Xft.dpi`, then xrandr's
55 /// physical DPI (with `kde` or `portal`), then 96.0; 96.0 elsewhere. The
56 /// detected DPI is cached until
57 /// [`invalidate_caches()`](crate::detect::invalidate_caches). When the
58 /// OS theme is read
59 /// ([`SystemTheme::from_system`](crate::SystemTheme::from_system)), the
60 /// reader's own DPI replaces it: KDE's this same cached chain; GNOME's
61 /// 96.0, macOS's 72.0 and Windows' 96.0.
62 pub font_dpi: f32,
63 /// Dialog button ordering (`PrimaryLeft` on KDE and Windows,
64 /// `PrimaryRight` elsewhere).
65 pub button_order: DialogButtonOrder,
66 /// Runtime-detected icon theme name, used when the preset and
67 /// per-variant `icon_theme` fields are both `None`. Three-tier
68 /// precedence in the pipeline: per-variant → `Theme`-level shared →
69 /// this runtime detection.
70 ///
71 /// [`from_system`](Self::from_system) puts the detected system icon
72 /// theme here, or `None` where detection failed;
73 /// [`system_icon_theme()`](crate::detect::system_icon_theme) gives the
74 /// reason.
75 pub icon_theme: Option<Cow<'static, str>>,
76}
77
78impl ResolutionContext {
79 /// Build the context by auto-detecting from the current OS.
80 ///
81 /// Calls:
82 /// - `crate::detect::system_font_dpi` for `font_dpi` (private)
83 /// - `crate::resolve::inheritance::platform_button_order` for
84 /// `button_order`
85 /// - [`crate::detect::system_icon_theme`] for `icon_theme`, which
86 /// is `None` where detection fails
87 #[must_use]
88 pub fn from_system() -> Self {
89 Self::with_detected_icon_theme(crate::detect::system_icon_theme())
90 }
91
92 /// [`from_system`](Self::from_system), with `detected` as the outcome
93 /// of the icon theme's detection.
94 pub(crate) fn with_detected_icon_theme(detected: crate::Result<String>) -> Self {
95 Self::with_font_dpi(crate::detect::system_font_dpi(), detected)
96 }
97
98 /// [`from_system`](Self::from_system) with a `font_dpi` already known,
99 /// such as the one a platform reader detected: no DPI detection runs.
100 /// `detected` is the outcome of the icon theme's detection.
101 pub(crate) fn with_font_dpi(font_dpi: f32, detected: crate::Result<String>) -> Self {
102 Self {
103 font_dpi,
104 button_order: crate::resolve::inheritance::platform_button_order(),
105 icon_theme: detected.ok().map(Cow::Owned),
106 }
107 }
108
109 /// Deterministic values for tests: 96 DPI, `PrimaryRight` button
110 /// order, no detected `icon_theme`.
111 ///
112 /// Tests that need a specific DPI (e.g. 72.0 for Apple point→pixel)
113 /// can construct the struct via a literal:
114 /// `ResolutionContext { font_dpi: 72.0, ..ResolutionContext::for_tests() }`.
115 #[must_use]
116 pub fn for_tests() -> Self {
117 Self {
118 font_dpi: 96.0,
119 button_order: DialogButtonOrder::PrimaryRight,
120 icon_theme: None,
121 }
122 }
123}
124
125// Intentionally NO `impl Default for ResolutionContext`.
126// See module-level doc comment for the signal-intent rationale.
127
128#[cfg(test)]
129mod tests {
130 use super::*;
131
132 #[test]
133 fn with_font_dpi_is_its_arguments() {
134 // The pipeline's constructor when the reader supplied a DPI: the
135 // context holds that DPI and the given icon-theme outcome, plus
136 // the platform's button order; no DPI detection replaces either.
137 let ctx = ResolutionContext::with_font_dpi(
138 123.3,
139 Err(crate::Error::PlatformUnsupported {
140 platform: "the test's failing detection",
141 }),
142 );
143 assert_eq!(ctx.font_dpi, 123.3);
144 assert!(ctx.icon_theme.is_none());
145 assert_eq!(
146 ctx.button_order,
147 crate::resolve::inheritance::platform_button_order()
148 );
149
150 let ctx = ResolutionContext::with_font_dpi(144.0, Ok("detected-theme".to_string()));
151 assert_eq!(ctx.font_dpi, 144.0);
152 assert_eq!(ctx.icon_theme.as_deref(), Some("detected-theme"));
153 }
154}