rustsni
A poll-friendly StatusNotifierItem host library for Linux system trays, built on rustbus.
rustsni implements the host side of the SNI protocol — it acts as a StatusNotifierWatcher + StatusNotifierHost on the D-Bus session bus, discovers tray items, and provides their properties, icons, and menus — all without spawning threads.
Features
- Poll-friendly — single
fd()for poll/epoll, no threads, no callbacks - Item discovery — catches items that register before and after the host starts
- Async probing — one D-Bus unique name probed per
poll()call (non-blocking, 500 ms timeout, 3 retries) - Full property access — category, title, status, icons (name + pixmap), tooltip, menu path, window id, and more
- Menu support —
com.canonical.dbusmenulayout fetching, property queries, and click events - Item interaction —
Activate,ContextMenu,SecondaryActivate,Scroll,ProvideXdgActivationToken
Platform
- Linux only
- Requires a running D-Bus session bus
Minimum supported Rust version
Rust 1.85 (edition 2024).
Usage
Add this to your Cargo.toml:
[]
= "0.1"
Basic example — discover tray items and print them using an fd-based event loop:
use ;
let mut host = new?;
// Flush initial discovery events (items that were already running).
for event in host.poll?
// Register host.fd() with your poll/epoll loop. When it fires:
for event in host.poll?
// Interact with items by their ItemId:
let app_id = ItemId;
let _ = host.activate; // left-click
let _ = host.context_menu; // right-click
See the docs for the full API reference.
Architecture
┌──────────────────────────────────────────────────────────┐
│ Your application (system tray / bar) │
│ │
│ poll() → TrayEvent[] ─── handle UI updates │
│ activate(), get_menu(), menu_click() ─── interact │
└──────────────────┬───────────────────────────────────────┘
│ poll-friendly, no threads
┌──────────────────▼───────────────────────────────────────┐
│ rustsni::TrayHost │
│ │
│ ┌──────────┐ ┌──────────────┐ ┌──────────────────┐ │
│ │ Watcher │ │ Host │ │ Item cache │ │
│ │ (reg. & │ │ (announce │ │ (HashMap │ │
│ │ signal) │ │ presence) │ │ ItemId→TrayItem)│ │
│ └────┬─────┘ └──────┬───────┘ └────────┬─────────┘ │
│ └───────────────┼───────────────────┘ │
└───────────────────────┼──────────────────────────────────┘
│ D-Bus session bus
┌───────────────┼─────────────────────┐
▼ ▼ ▼
┌────────┐ ┌──────────┐ ┌──────────┐
│ App A │ │ App B │ ... │ App N │
│ SNI │ │ SNI │ │ SNI │
└────────┘ └──────────┘ └──────────┘
(tray items on the session bus)
License
MIT — see LICENSE-MIT.