wayle_systray/lib.rs
1//! System tray management via the StatusNotifier (SNI) and DBusMenu protocols.
2//!
3//! # Overview
4//!
5//! The service discovers and monitors system tray items registered on D-Bus,
6//! providing reactive access to item properties, icons, and menus. It can operate
7//! as either a StatusNotifierWatcher (central registry) or a StatusNotifierHost
8//! (consumer of items from an existing watcher).
9//!
10//! # Reactive Pattern
11//!
12//! All tray item properties use [`Property<T>`](wayle_core::Property):
13//! - `.get()` returns the current value snapshot
14//! - `.watch()` returns a stream of value changes
15//!
16//! # Quick Start
17//!
18//! ```rust,no_run
19//! use wayle_systray::SystemTrayService;
20//!
21//! # async fn example() -> Result<(), wayle_systray::error::Error> {
22//! let service = SystemTrayService::new().await?;
23//!
24//! // Get current items
25//! for item in service.items.get().iter() {
26//! println!("{}: {}", item.id.get(), item.title.get());
27//! }
28//! # Ok(())
29//! # }
30//! ```
31//!
32//! # Watching for Changes
33//!
34//! ```rust,no_run
35//! use wayle_systray::SystemTrayService;
36//! use futures::StreamExt;
37//!
38//! # async fn example() -> Result<(), wayle_systray::error::Error> {
39//! # let service = SystemTrayService::new().await?;
40//! // React to tray item changes
41//! let mut stream = service.items.watch();
42//! while let Some(items) = stream.next().await {
43//! println!("Tray items changed: {} items", items.len());
44//! }
45//! # Ok(())
46//! # }
47//! ```
48//!
49//! # Configuration
50//!
51//! | Method | Effect |
52//! |--------|--------|
53//! | `with_daemon()` | Interact with tray items from scripts or other processes |
54//! | `mode(TrayMode)` | Set operating mode: `Watcher`, `Host`, or `Auto` (default) |
55//!
56//! ```rust,no_run
57//! use wayle_systray::{SystemTrayService, types::TrayMode};
58//!
59//! # async fn example() -> Result<(), wayle_systray::error::Error> {
60//! let tray = SystemTrayService::builder()
61//! .with_daemon()
62//! .mode(TrayMode::Auto)
63//! .build()
64//! .await?;
65//! # Ok(())
66//! # }
67//! ```
68//!
69//! # D-Bus Interface
70//!
71//! When `with_daemon()` is enabled, the service registers on the session bus.
72//!
73//! - **Service:** `com.wayle.SystemTray1`
74//! - **Path:** `/com/wayle/SystemTray`
75//! - **Interface:** `com.wayle.SystemTray1`
76//!
77//! See [`dbus.md`](https://github.com/wayle-rs/wayle/blob/master/crates/wayle-systray/dbus.md) for the full interface specification.
78//!
79//! # Service Fields
80//!
81//! | Field | Type | Description |
82//! |-------|------|-------------|
83//! | `is_watcher` | `bool` | Whether operating as the watcher registry |
84//! | `items` | `Property<Vec<Arc<TrayItem>>>` | Currently registered tray items |
85
86/// UI framework adapters (GTK4) for native systray menu rendering.
87pub mod adapters;
88mod builder;
89/// System tray item model.
90pub mod core;
91/// D-Bus interface for CLI control.
92pub mod dbus;
93mod discovery;
94/// Error types.
95pub mod error;
96mod events;
97mod monitoring;
98mod proxy;
99/// Main service implementation.
100pub mod service;
101/// SNI and DBusMenu protocol types.
102pub mod types;
103mod watcher;
104
105pub use builder::SystemTrayServiceBuilder;
106pub use dbus::SystemTrayWayleProxy;
107pub use service::SystemTrayService;
108
109#[doc = include_str!("../README.md")]
110#[cfg(doctest)]
111pub struct ReadmeDocTests;