Skip to content
alpha 0.1.0-alpha.7 is on crates.io. Install the CLI Start here

0021 - Tray

Status: Implemented (2026-11-18; icon selection, menu and click callbacks)

Phase 2 needs apps to be able to show a system tray icon with a small menu and react to clicks. This spec fixes the tray service contract. The backend is pluggable so tests can inspect visibility, tooltip and menu changes and fire events instead of creating a real tray icon. The auro::services re-export requires the facade's services feature, and Tray additionally requires the tray feature. On Linux the backend speaks StatusNotifierItem over D-Bus; it needs no GTK initialization and no GTK event loop, which an app built on GPUI cannot provide.

Scope

  • auro-services::Tray: show or hide a tray icon, set its tooltip and supply RGBA pixels.
  • TrayIcon: validated RGBA pixels and dimensions.
  • TrayMenuItem and Tray::set_menu: replace the context menu.
  • Tray::on_menu_event: receive the activated item's id.
  • TrayClick, TrayButton, TrayButtonState and Tray::on_click: receive icon clicks.
  • TrayBackend: a pluggable backend trait; the default is tray-icon.
  • auro::services::Tray re-export.

Out of scope

  • App bundle icon discovery or packaging; apps provide RGBA pixels.
  • Tray persistence across app restarts.
  • PNG/theme file decoding.
  • Submenus, check items, icons-in-menu and accelerators.
  • Other platform services.

Decisions

D1 - tray-icon is the default backend

Auro delegates the per-OS mechanics to tray-icon, which uses the Windows shell, macOS NSStatusItem and, on Linux, the StatusNotifierItem D-Bus protocol through its ksni backend. The ksni backend runs its own D-Bus thread, so Tray::new() works before any GTK or GPUI loop exists and does not need the application to pump a GTK loop.

Rejected: implementing the three mechanisms inside Auro. tray-icon is MIT licensed and already handles the quirks. Rejected: tray-icon's AppIndicator backend, which requires gtk::init on a thread that must also run the GTK main loop; a GPUI app owns its main thread and cannot provide that loop without a second event loop.

D2 - The backend is pluggable for tests

Tray::with_backend accepts any TrayBackend. Tests can inject a recorder and verify show/hide, tooltip and menu changes, then invoke the stored callbacks without creating a real tray icon. Production code uses Tray::new().

TrayBackend is not Send + Sync, because tray-icon's internal handle is not Send. The service stores the backend in an Arc, but the trait object is main-thread-only like a GPUI view. Callbacks are Send + Sync; they run off the app thread.

Rejected: a mock flag on the production type. It keeps the boundary explicit and makes the test double a test-only type.

D3 - Menus, click callbacks and icons

TrayMenuItem is a flat id/label/enabled item. Tray::set_menu rebuilds and installs a platform menu; Tray::on_menu_event receives the activated id. Tray::on_click receives a TrayClick with the button and up/down state; enter/move/leave/double-click events are ignored. TrayIcon carries validated RGBA pixels; Tray::set_icon replaces or clears the icon.

The callback runs off the app thread. Apps use EventSender (or another channel) to move the work onto the main thread; the service does not depend on GPUI or auro-core.

The platform event handlers are process-global and can only be installed once per process. The service documents this; a second on_menu_event or on_click call is intentionally not supported. On Linux, StatusNotifierItem delivers the primary activation as a left-button Up click and the secondary activation as a middle-button Up click; right-click is owned by the status-notifier host, which opens the menu. Menus and icons can be replaced after creation.

Rejected: a per-tray event dispatcher thread. tray-icon already owns the platform event source; an extra thread would only copy events and complicate shutdown.

Interfaces

#![allow(unused)]
fn main() {
pub enum TrayError { /* tray_icon, menu or icon error */ }

pub struct TrayIcon { /* rgba, width, height */ }

impl TrayIcon {
    pub fn from_rgba(rgba: Vec<u8>, width: u32, height: u32) -> Result<Self, TrayError>;
    pub fn width(&self) -> u32;
    pub fn height(&self) -> u32;
    pub fn rgba(&self) -> &[u8];
}

pub struct TrayMenuItem {
    pub id: String,
    pub label: String,
    pub enabled: bool,
}

pub enum TrayButton { Left, Right, Middle }
pub enum TrayButtonState { Up, Down }

pub struct TrayClick {
    pub button: TrayButton,
    pub state: TrayButtonState,
}

pub trait TrayBackend {
    fn set_visible(&self, visible: bool) -> Result<(), TrayError>;
    fn set_tooltip(&self, tooltip: Option<String>) -> Result<(), TrayError>;
    fn is_visible(&self) -> bool;
    fn set_icon(&self, icon: Option<TrayIcon>) -> Result<(), TrayError>;
    fn set_menu(&self, items: Vec<TrayMenuItem>) -> Result<(), TrayError>;
    fn set_menu_event_handler(&self, handler: Arc<dyn Fn(&str) + Send + Sync>);
    fn set_click_event_handler(&self, handler: Arc<dyn Fn(TrayClick) + Send + Sync>);
}

pub struct Tray { /* backend */ }

impl Tray {
    pub fn new() -> Result<Self, TrayError>;
    pub fn with_backend(backend: impl TrayBackend + 'static) -> Self;
    pub fn set_visible(&self, visible: bool) -> Result<(), TrayError>;
    pub fn set_tooltip(&self, tooltip: Option<String>) -> Result<(), TrayError>;
    pub fn is_visible(&self) -> bool;
    pub fn set_icon(&self, icon: Option<TrayIcon>) -> Result<(), TrayError>;
    pub fn set_menu(&self, items: &[TrayMenuItem]) -> Result<(), TrayError>;
    pub fn on_menu_event<F>(&self, handler: F)
    where
        F: Fn(&str) + Send + Sync + 'static;
    pub fn on_click<F>(&self, handler: F)
    where
        F: Fn(TrayClick) + Send + Sync + 'static;
}
}

Usage:

let tray = auro::services::Tray::new()?;
tray.set_menu(&[
    auro::services::TrayMenuItem::new("show", "Show"),
    auro::services::TrayMenuItem::new("quit", "Quit"),
])?;
tray.on_menu_event(|id| {
    // Send `id` to the app thread.
});
tray.set_visible(true)?;

Acceptance

  1. set_visible toggles the backend and is reflected by is_visible (shows_and_hides_the_icon).
  2. set_tooltip passes the tooltip to the backend and can clear it (updates_the_tooltip).
  3. A valid RGBA icon can be set and cleared; invalid pixels are rejected (sets_and_clears_the_icon).
  4. set_menu passes the items to the backend and menu events reach the callback (sets_a_menu_and_dispatches_its_events).
  5. Click events reach the callback (dispatches_clicks).
  6. A backend error surfaces as TrayError (backend_errors_surface).
  7. auro::services re-exports the API surface (crates/auro/src/lib.rs).
  8. cargo fmt --all --check, cargo clippy --workspace --all-targets --locked -- -D warnings, cargo test --workspace --locked, cargo test -p auro-services --features tray --locked, cargo check -p auro --features services,tray --locked, and mdbook build docs pass.

Open questions

QuestionWhere it settles
PNG/theme icon decodingTray UX spec
Tray persistence across restartsTray UX spec
Submenus, check items and acceleratorsTray UX spec
Other platform servicesPlatform services specs