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}