Skip to main content

hyprforge_tray/
item.rs

1//! What a tray icon *is*, with no D-Bus in sight.
2//!
3//! Kept separate from [`crate::sni`] so the interesting question — which
4//! icon does this state deserve, and what should the tooltip say — is a
5//! pure function that can be asserted on without a bus, a bar, or a
6//! radio. That is the same split `hyprforge-network` makes between its
7//! model and its NetworkManager client, and for the same reason.
8
9/// `org.kde.StatusNotifierItem.Category`.
10///
11/// Both of this suite's items are [`Category::Hardware`]: they report the
12/// state of a radio, not of an application. Hosts use this to group and
13/// order icons, so getting it wrong puts Wi-Fi among the chat apps.
14#[derive(Debug, Clone, Copy, PartialEq, Eq)]
15pub enum Category {
16    ApplicationStatus,
17    Communications,
18    SystemServices,
19    Hardware,
20}
21
22impl Category {
23    /// The exact strings the spec defines. A host that does not
24    /// recognise the value falls back to `ApplicationStatus` silently, so
25    /// a typo here is invisible rather than an error.
26    pub fn as_str(self) -> &'static str {
27        match self {
28            Category::ApplicationStatus => "ApplicationStatus",
29            Category::Communications => "Communications",
30            Category::SystemServices => "SystemServices",
31            Category::Hardware => "Hardware",
32        }
33    }
34}
35
36/// `org.kde.StatusNotifierItem.Status`.
37///
38/// [`Status::Passive`] asks the host to hide the icon. That is the right
39/// answer for a radio that is switched off — a Bluetooth icon on a
40/// machine with Bluetooth disabled is a permanent piece of noise — but it
41/// is *not* the right answer for a radio that is on and unconnected,
42/// which is exactly when someone goes looking for it.
43#[derive(Debug, Clone, Copy, PartialEq, Eq)]
44pub enum Status {
45    Passive,
46    Active,
47    NeedsAttention,
48}
49
50impl Status {
51    pub fn as_str(self) -> &'static str {
52        match self {
53            Status::Passive => "Passive",
54            Status::Active => "Active",
55            Status::NeedsAttention => "NeedsAttention",
56        }
57    }
58}
59
60/// One tray icon's entire visible state.
61///
62/// Icons are named, never drawn. The name is resolved by the host against
63/// the user's own icon theme, which `hyprforge-appearance` already sets
64/// through gsettings — so the tray matches the desktop without this crate
65/// owning a single pixel, and without a second place to configure what
66/// the desktop already decides.
67#[derive(Debug, Clone, PartialEq)]
68pub struct TrayItem {
69    /// Stable across the life of the process; hosts key their own state
70    /// on it.
71    pub id: String,
72    pub category: Category,
73    pub status: Status,
74    pub title: String,
75    pub icon_name: String,
76    /// First line of the tooltip — typically what is connected.
77    pub tooltip_title: String,
78    /// Second line, for the detail that does not fit in the first.
79    pub tooltip_body: String,
80}
81
82impl TrayItem {
83    /// What a left-click should run.
84    ///
85    /// Every item in this suite opens the Settings page it is about,
86    /// which is why `--screen` exists. Returning the argument rather than
87    /// spawning keeps this testable: asserting that the Bluetooth icon
88    /// opens the Bluetooth page needs no process.
89    pub fn activate_screen(&self) -> Option<&'static str> {
90        match self.id.as_str() {
91            "hyprforge-network" => Some("network"),
92            "hyprforge-bluetooth" => Some("bluetooth"),
93            // Night light has a Settings page of its own. It used to be a
94            // tab of the Desktop screen, and naming the screen rather than
95            // the tab once landed a click on Wallpaper instead.
96            "hyprforge-night-light" => Some("night-light"),
97            // Keep awake has its own Power screen now (see
98            // `hyprforge-trayd`'s module doc) — this used to point at
99            // `"idle"`, the Desktop screen's tab it lived on before the
100            // move, and would have silently kept sending clicks there
101            // forever if nothing had updated it alongside the move.
102            "hyprforge-keep-awake" => Some("power"),
103            // The battery and profile icon opens the same Power screen,
104            // which shows both.
105            "hyprforge-power" => Some("power"),
106            "hyprforge-displays" => Some("displays"),
107            // An id nothing claims falls through to `None`.
108            _ => None,
109        }
110    }
111}
112
113#[cfg(test)]
114mod tests {
115    use super::*;
116
117    /// The spec's strings, spelled exactly. A host that does not
118    /// recognise a category does not complain — it silently treats the
119    /// item as an application, and the icon turns up in the wrong group
120    /// with nothing logged anywhere.
121    #[test]
122    fn the_category_and_status_strings_are_the_ones_the_spec_defines() {
123        assert_eq!(Category::Hardware.as_str(), "Hardware");
124        assert_eq!(Category::SystemServices.as_str(), "SystemServices");
125        assert_eq!(Status::Passive.as_str(), "Passive");
126        assert_eq!(Status::NeedsAttention.as_str(), "NeedsAttention");
127    }
128
129    #[test]
130    fn each_item_opens_the_settings_page_it_is_about() {
131        let item = |id: &str| TrayItem {
132            id: id.to_string(),
133            category: Category::Hardware,
134            status: Status::Active,
135            title: String::new(),
136            icon_name: String::new(),
137            tooltip_title: String::new(),
138            tooltip_body: String::new(),
139        };
140        assert_eq!(item("hyprforge-network").activate_screen(), Some("network"));
141        assert_eq!(item("hyprforge-bluetooth").activate_screen(), Some("bluetooth"));
142        assert_eq!(item("something-else").activate_screen(), None);
143    }
144
145    /// Each icon opens the page its own setting is on.
146    ///
147    /// Night light names its own page — when it was a tab of the Desktop
148    /// screen, naming the screen instead once landed it on Wallpaper.
149    /// Keep awake names the Power screen it now lives on, having moved
150    /// off that same Desktop screen's `Idle` tab.
151    #[test]
152    fn every_icon_opens_the_page_its_own_setting_is_on() {
153        let item = |id: &str| TrayItem {
154            id: id.to_string(),
155            category: Category::SystemServices,
156            status: Status::Active,
157            title: String::new(),
158            icon_name: String::new(),
159            tooltip_title: String::new(),
160            tooltip_body: String::new(),
161        };
162        assert_eq!(
163            item("hyprforge-night-light").activate_screen(),
164            Some("night-light")
165        );
166        assert_eq!(item("hyprforge-keep-awake").activate_screen(), Some("power"));
167        assert_eq!(item("hyprforge-power").activate_screen(), Some("power"));
168        assert_eq!(item("hyprforge-displays").activate_screen(), Some("displays"));
169        // An id nothing claims still resolves to nothing, rather than to
170        // whichever arm happens to be last.
171        assert_eq!(item("hyprforge-nonsense").activate_screen(), None);
172    }
173}