use std::sync::atomic::{AtomicBool, Ordering};
use std::sync::{Arc, Mutex, OnceLock, Weak};
pub type Callback = Arc<dyn Fn() + Send + Sync + 'static>;
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct Icon {
pub width: u32,
pub height: u32,
pub rgba: Arc<[u8]>,
pub template: bool,
}
impl Icon {
pub fn rgba(width: u32, height: u32, pixels: impl Into<Arc<[u8]>>) -> Result<Self, Error> {
let icon = Self {
width,
height,
rgba: pixels.into(),
template: false,
};
icon.validate()?;
Ok(icon)
}
fn validate(&self) -> Result<(), Error> {
if self.width == 0
|| self.height == 0
|| self.width > 512
|| self.height > 512
|| self
.width
.checked_mul(self.height)
.and_then(|n| n.checked_mul(4))
.map(|n| n as usize)
!= Some(self.rgba.len())
{
return Err(Error::Invalid(
"tray icon must contain exact RGBA pixels, at most 512 × 512".into(),
));
}
Ok(())
}
}
#[derive(Clone)]
pub enum MenuItem {
Action {
label: String,
disabled: bool,
checked: Option<bool>,
default: bool,
on_select: Option<Callback>,
},
Separator,
Submenu {
label: String,
disabled: bool,
items: Vec<MenuItem>,
},
Quit {
label: Option<String>,
disabled: bool,
},
}
impl MenuItem {
pub fn action(label: impl Into<String>, on_select: impl Fn() + Send + Sync + 'static) -> Self {
Self::Action {
label: label.into(),
disabled: false,
checked: None,
default: false,
on_select: Some(Arc::new(on_select)),
}
}
pub fn submenu(label: impl Into<String>, items: Vec<MenuItem>) -> Self {
Self::Submenu {
label: label.into(),
disabled: false,
items,
}
}
pub fn quit() -> Self {
Self::Quit {
label: None,
disabled: false,
}
}
}
#[derive(Clone, Default)]
pub struct Options {
pub icon: Option<Icon>,
pub tooltip: String,
pub menu: Vec<MenuItem>,
pub on_click: Option<Callback>,
pub on_quit: Option<Callback>,
}
impl Options {
pub fn validate(&self) -> Result<(), Error> {
if self.tooltip.contains('\0') || self.tooltip.encode_utf16().count() > 127 {
return Err(Error::Invalid(
"tray tooltip must be NUL-free and at most 127 UTF-16 units".into(),
));
}
if let Some(icon) = &self.icon {
icon.validate()?;
}
let mut count = 0;
validate_menu(&self.menu, 0, &mut count, self.on_quit.is_some())
}
}
fn validate_menu(
items: &[MenuItem],
depth: usize,
count: &mut usize,
can_quit: bool,
) -> Result<(), Error> {
if depth > 8 {
return Err(Error::Invalid("tray menu nesting exceeds 8".into()));
}
for item in items {
*count += 1;
if *count > 512 {
return Err(Error::Invalid("tray menu exceeds 512 items".into()));
}
let label = match item {
MenuItem::Action { label, .. } | MenuItem::Submenu { label, .. } => {
Some(label.as_str())
}
MenuItem::Quit { label, .. } => {
if !can_quit {
return Err(Error::Invalid(
"a quit menu item requires Options::on_quit".into(),
));
}
label.as_deref()
}
MenuItem::Separator => None,
};
if label.is_some_and(|label| {
label.is_empty() || label.contains('\0') || label.encode_utf16().count() > 512
}) {
return Err(Error::Invalid(
"tray menu labels must be nonempty, NUL-free and at most 512 UTF-16 units".into(),
));
}
if let MenuItem::Submenu { items, .. } = item {
validate_menu(items, depth + 1, count, can_quit)?;
}
}
Ok(())
}
#[derive(Clone, Debug, PartialEq, Eq)]
pub enum Error {
Unsupported,
Closed,
Invalid(String),
Platform(String),
}
impl std::fmt::Display for Error {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
match self {
Self::Unsupported => f.write_str("native tray is not implemented on this platform"),
Self::Closed => f.write_str("native tray has stopped"),
Self::Invalid(message) | Self::Platform(message) => f.write_str(message),
}
}
}
impl std::error::Error for Error {}
#[cfg(windows)]
mod windows;
#[cfg(windows)]
use windows::Controller;
#[cfg(target_os = "macos")]
mod macos;
#[cfg(target_os = "macos")]
use macos::Controller;
#[cfg(any(target_os = "macos", test))]
mod mac_plan;
#[cfg(not(any(windows, target_os = "macos")))]
struct Controller;
#[cfg(not(any(windows, target_os = "macos")))]
impl Controller {
fn start() -> Result<Arc<Self>, Error> {
Err(Error::Unsupported)
}
fn set(&self, _: Option<Options>) -> Result<u64, Error> {
Err(Error::Unsupported)
}
fn revision(&self) -> u64 {
0
}
fn stop(&self) {}
}
struct Owner(Arc<Controller>);
impl Drop for Owner {
fn drop(&mut self) {
self.0.stop();
}
}
#[derive(Clone)]
pub struct Tray {
owner: Arc<Owner>,
}
static APP: OnceLock<Mutex<Weak<Owner>>> = OnceLock::new();
static APP_SHOWN: AtomicBool = AtomicBool::new(false);
impl Tray {
pub const fn is_available() -> bool {
cfg!(any(windows, target_os = "macos"))
}
pub fn new() -> Result<Self, Error> {
Ok(Self {
owner: Arc::new(Owner(Controller::start()?)),
})
}
pub fn app() -> Result<Self, Error> {
let mut slot = APP
.get_or_init(|| Mutex::new(Weak::new()))
.lock()
.map_err(|_| Error::Closed)?;
if let Some(owner) = slot.upgrade() {
return Ok(Self { owner });
}
let tray = Self::new()?;
*slot = Arc::downgrade(&tray.owner);
Ok(tray)
}
pub fn existing_app() -> Option<Self> {
let owner = APP.get()?.lock().ok()?.upgrade()?;
Some(Self { owner })
}
pub fn set(&self, options: Option<Options>) -> Result<u64, Error> {
if let Some(options) = &options {
options.validate()?;
}
let shown = options.is_some();
let revision = self.owner.0.set(options)?;
if self.is_app() {
APP_SHOWN.store(shown, Ordering::Release);
}
Ok(revision)
}
fn is_app(&self) -> bool {
APP.get()
.and_then(|slot| slot.lock().ok()?.upgrade())
.is_some_and(|owner| Arc::ptr_eq(&owner, &self.owner))
}
pub fn app_shown() -> bool {
APP_SHOWN.load(Ordering::Acquire) && Self::existing_app().is_some()
}
pub fn revision(&self) -> u64 {
self.owner.0.revision()
}
pub fn stop(&self) {
self.owner.0.stop();
}
pub fn downgrade(&self) -> WeakTray {
WeakTray(Arc::downgrade(&self.owner))
}
}
#[derive(Clone)]
pub struct WeakTray(Weak<Owner>);
impl WeakTray {
pub fn upgrade(&self) -> Option<Tray> {
self.0.upgrade().map(|owner| Tray { owner })
}
}
pub(super) fn invoke(callback: &Callback) {
if std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| callback())).is_err() {
crate::log_later("error", "native tray callback panicked".into());
}
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn menu_validation_bounds_state_without_opening_the_desktop() {
let mut options = Options {
menu: vec![
MenuItem::action("Open", || {}),
MenuItem::Separator,
MenuItem::submenu(
"Status",
vec![MenuItem::Action {
label: "Muted".into(),
disabled: true,
checked: Some(true),
default: false,
on_select: None,
}],
),
MenuItem::quit(),
],
on_quit: Some(Arc::new(|| {})),
..Default::default()
};
assert!(options.validate().is_ok());
options.on_quit = None;
assert!(options.validate().is_err());
options.menu.clear();
options.tooltip = "😀".repeat(64);
assert!(options.validate().is_err());
options.tooltip.clear();
options.menu = vec![MenuItem::Separator; 513];
assert!(options.validate().is_err());
options.menu = vec![MenuItem::action("", || {})];
assert!(options.validate().is_err());
}
#[test]
fn icon_validation_checks_exact_lengths_before_platform_calls() {
assert!(Icon::rgba(2, 2, vec![0; 16]).is_ok());
assert!(Icon::rgba(2, 2, vec![0; 15]).is_err());
assert!(Icon::rgba(0, 2, vec![]).is_err());
assert!(Icon::rgba(u32::MAX, u32::MAX, vec![]).is_err());
}
}