Expand description
A poll-friendly StatusNotifierItem host library built on rustbus.
This crate implements the host side of the
StatusNotifierItem protocol (also known as the D-Bus
system tray protocol). It acts as a StatusNotifierWatcher +
StatusNotifierHost on the session bus, discovering tray items and
providing their properties, icons, and menus — all without blocking.
§Architecture
The main entry point is TrayHost. It:
- Connects to the D-Bus session bus.
- Registers itself as
org.kde.StatusNotifierWatcher(so tray items can register with it). - Registers itself as
org.freedesktop.StatusNotifierHost-{pid}(so items know a graphical shell is present). - Scans for already-running items via
ListNamesand probes each unique bus name for SNI support (one perpoll()call, non-blocking).
After construction, the caller hands the fd() to a
poll/epoll loop. When the fd becomes readable, call
poll() to process pending D-Bus messages and receive
TrayEvents.
§Event flow
┌─────────────┐ poll() ┌─────────────┐
│ TrayHost │ ──────────► │ TrayEvent │
│ (watcher) │ ◄────────── │ Vec │
└─────────────┘ events └─────────────┘
│
│ methods (activate, context_menu, get_menu, scroll, …)
▼
┌─────────────┐
│ TrayItem │
│ (on D-Bus) │
└─────────────┘§Non-blocking / poll-friendly design
This library never spawns threads. All I/O is driven by the caller’s event loop:
fd()returns the D-Bus socket fd for poll/epoll.poll()reads available messages without blocking and returns accumulatedTrayEvents.- Item discovery probes are sent asynchronously (one per
poll()call) with a 500 ms timeout and up to 3 retries.
§Interacting with tray items
Once an item is discovered (you receive TrayEvent::ItemAdded), you can:
- Read its properties from
TrayHost::items()(category, title, status, icons, tooltip, menu path, …). - Call
TrayHost::activate(),TrayHost::context_menu(),TrayHost::secondary_activate(), orTrayHost::scroll()to interact with it. - Get its menu layout via
TrayHost::get_menu()and fire click events viaTrayHost::menu_click().
§Platform
Linux only. Requires a running D-Bus session bus.
§Minimum supported Rust version
Rust 1.85 (edition 2024).
Structs§
- Icon
Pixmap - A decoded icon pixmap in native-endian ARGB32.
- ItemId
- A tray item’s unique identifier.
- Menu
Item Props - Properties for a single menu item as returned by
TrayHost::get_menu_group_properties. - Menu
Node - A node in the DBusMenu layout tree as returned by
TrayHost::get_menu. - ToolTip
- Tooltip data for a tray item.
- Tray
Host - A StatusNotifierWatcher + StatusNotifierHost on the D-Bus session bus.
- Tray
Item - Resolved properties of a StatusNotifierItem.
Enums§
- Error
- Errors returned by this library.
- Prop
Value - An owned property value from the DBusMenu protocol.
- Tray
Event - Events produced by
TrayHost::poll().
Functions§
- fire_
menu_ click - Fire a click event on a menu item using a standalone D-Bus connection.
- from_
tuples - Convert simple
(width, height, &[u8])tuples intoIconPixmaps.