Skip to main content

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}