# tray-icon

## 项目概述

跨平台系统托盘图标库，基于 muda 库实现，支持 Windows、macOS 和 Linux。

**GitHub**: https://github.com/tauri-apps/tray-icon.git
**本地路径**: `vendors/tray-icon`

## 目录结构

```
tray-icon/
├── src/
│   ├── lib.rs              # 公共 API
│   ├── icon.rs             # 图标处理
│   ├── menu.rs             # 菜单构建
│   └── platform_impl/      # 平台特定实现
│       ├── mod.rs
│       ├── windows.rs
│       ├── macos.rs
│       └── linux.rs
├── Cargo.toml
└── README.md
```

## 核心依赖

```toml
[dependencies]
muda = "1.0"              # 跨平台菜单库
crossbeam-channel = "0.5"
once_cell = "1.18"
thiserror = "1.0"

# 平台依赖
objc2 = { version = "0.5", optional = true }
gtk = { version = "0.18", optional = true, features = ["v3_22"] }
libappindicator = { version = "0.8", optional = true }
windows = { version = "0.48", optional = true }
```

## 核心 API

### TrayIconBuilder

```rust
// lib.rs

pub struct TrayIconBuilder {
    id: TrayIconId,
    attrs: TrayIconAttributes,
}

impl TrayIconBuilder {
    pub fn new() -> Self;

    /// 设置托盘图标
    pub fn with_icon(mut self, icon: Icon) -> Self;

    /// 设置提示文本
    pub fn with_tooltip<S: AsRef<str>>(self, s: S) -> Self;

    /// 设置标题（macOS）
    pub fn with_title<S: AsRef<str>>(self, title: S) -> Self;

    /// 设置上下文菜单
    pub fn with_menu(mut self, menu: Box<dyn menu::ContextMenu>) -> Self;

    /// 左键点击显示菜单（默认右键）
    pub fn with_menu_on_left_click(self, enable: bool) -> Self;

    /// 设置临时目录路径
    pub fn with_temp_dir_path<P: AsRef<Path>>(self, s: P) -> Self;

    /// 构建托盘图标
    pub fn build(self) -> Result<TrayIcon>;
}
```

### TrayIcon

```rust
pub struct TrayIcon {
    id: TrayIconId,
    tray: Rc<RefCell<platform_impl::TrayIcon>>,
}

impl TrayIcon {
    /// 设置图标
    pub fn set_icon(&self, icon: Option<Icon>) -> Result<()>;

    /// 设置菜单
    pub fn set_menu(&self, menu: Option<Box<dyn menu::ContextMenu>>);

    /// 设置提示文本
    pub fn set_tooltip<S: AsRef<str>>(&self, tooltip: Option<S>) -> Result<()>;

    /// 设置可见性
    pub fn set_visible(&self, visible: bool) -> Result<()>;

    /// 获取托盘区域矩形
    pub fn rect(&self) -> Option<Rect>;
}
```

### TrayIconEvent

```rust
pub enum TrayIconEvent {
    Click {
        id: TrayIconId,
        position: Position,
        rect: Rect,
        button: MouseButton,
        button_state: ButtonState,
    },
    DoubleClick {
        id: TrayIconId,
        position: Position,
        rect: Rect,
        button: MouseButton,
    },
    Enter {
        id: TrayIconId,
        position: Position,
        rect: Rect,
    },
    Move {
        id: TrayIconId,
        position: Position,
        rect: Rect,
    },
    Leave {
        id: TrayIconId,
        position: Position,
        rect: Rect,
    },
}

impl TrayIconEvent {
    /// 获取事件接收器
    pub fn receiver() -> &'a TrayIconEventReceiver;

    /// 设置事件处理函数
    pub fn set_event_handler<F>(f: Option<F>)
    where
        F: Fn(TrayIconEvent, &dyn TrayIconHandle) + Send + 'static;
}
```

## 使用示例

```rust
use tray_icon::{TrayIconBuilder, icon::Icon, menu::MenuBuilder};

fn main() -> Result<()> {
    // 加载图标
    let icon = Icon::from_resource(1, None);

    // 创建菜单
    let menu = MenuBuilder::new()
        .item("Show Window", "show_window", true, None)?
        .separator()
        .item("Settings", "settings", true, None)?
        .separator()
        .quit("Quit")
        .build()?;

    // 创建托盘图标
    let _tray_icon = TrayIconBuilder::new()
        .with_icon(icon)
        .with_tooltip("My App")
        .with_menu(Box::new(menu))
        .with_on_tray_event(|event, tray| {
            match event {
                TrayIconEvent::Click { button, .. } => {
                    if button == MouseButton::Left {
                        show_window();
                    }
                }
                TrayIconEvent::MenuItemClick { id, .. } => {
                    match id.as_ref() {
                        "quit" => std::process::exit(0),
                        "settings" => open_settings(),
                        "show_window" => show_window(),
                        _ => {}
                    }
                }
                _ => {}
            }
        })
        .build()?;

    Ok(())
}
```

## 与 agent-client 集成场景

### 场景1：完整的托盘管理器

```rust
// agent-client 托盘管理器

use tray_icon::{TrayIconBuilder, icon::Icon, menu::{Menu, MenuItem, MenuBuilder}};
use std::sync::atomic::{AtomicBool, Ordering};

pub struct TrayManager {
    // 托盘图标
    tray_icon: Option<TrayIcon>,
    // 是否显示主窗口
    window_visible: AtomicBool,
    // 连接状态
    connection_state: Arc<dyn ConnectionStatusProvider>,
    // 应用退出标志
    exit_flag: Arc<AtomicBool>,
}

impl TrayManager {
    pub fn new(
        connection_state: Arc<dyn ConnectionStatusProvider>,
        exit_flag: Arc<AtomicBool>,
    ) -> Result<Self> {
        let icon = Self::load_icon()?;

        let menu = MenuBuilder::new()
            .item("Show Window", "show_window", true, None)?
            .separator()
            .item("Agent Status", "status", true, None)?
            .item("Open Settings", "settings", true, None)?
            .separator()
            .item("Quit", "quit", true, None)?
            .build()?;

        let tray_icon = TrayIconBuilder::new()
            .with_icon(icon)
            .with_tooltip("qiming-agent")
            .with_menu(Box::new(menu))
            .with_menu_on_left_click(true)  // 左键也显示菜单
            .build()?;

        Ok(Self {
            tray_icon: Some(tray_icon),
            window_visible: AtomicBool::new(true),
            connection_state,
            exit_flag,
        })
    }

    fn load_icon() -> Result<Icon> {
        // 从资源文件加载图标
        let icon_data = include_bytes!("../../assets/tray_icon.png");
        let image = image::load_from_memory(icon_data)?
            .to_rgba8()
            .into_raw();

        Icon::from_rgba(icon_data.to_vec(), 32, 32)
    }

    /// 设置托盘事件处理
    pub fn setup_event_handler(&self) {
        TrayIconEvent::set_event_handler(Some(move |event, _tray| {
            match event {
                TrayIconEvent::Click { button, .. } => {
                    if button == MouseButton::Left {
                        // 左键点击切换窗口可见性
                        // 发送事件到主窗口
                    }
                }
                TrayIconEvent::MenuItemClick { id, .. } => {
                    match id.as_ref() {
                        "show_window" => {
                            // 显示主窗口
                        }
                        "settings" => {
                            // 打开设置窗口
                        }
                        "quit" => {
                            // 退出应用
                        }
                        _ => {}
                    }
                }
                _ => {}
            }
        }));
    }

    /// 更新托盘图标（根据连接状态）
    pub fn update_icon(&self, status: &ConnectionState) {
        let icon = match status {
            ConnectionState::Connected { .. } => self.load_connected_icon(),
            ConnectionState::Connecting => self.load_loading_icon(),
            ConnectionState::Disconnected { .. } => self.load_disconnected_icon(),
            ConnectionState::Error { .. } => self.load_error_icon(),
        };

        if let Some(tray) = &self.tray_icon {
            tray.set_icon(Some(icon)).ok();
        }
    }

    /// 更新托盘提示文本
    pub fn update_tooltip(&self, text: &str) {
        if let Some(tray) = &self.tray_icon {
            tray.set_tooltip(Some(text)).ok();
        }
    }

    /// 销毁托盘
    pub fn destroy(&mut self) {
        if let Some(tray) = self.tray_icon.take() {
            tray.set_visible(false).ok();
        }
    }
}
```

### 场景2：托盘菜单与主窗口通信

```rust
// 使用 channel 进行托盘事件通信

use tokio::sync::mpsc;

pub enum TrayEvent {
    ShowWindow,
    OpenSettings,
    Quit,
}

pub struct TrayEventChannel {
    sender: mpsc::UnboundedSender<TrayEvent>,
    receiver: Arc<Mutex<mpsc::UnboundedReceiver<TrayEvent>>>,
}

impl TrayEventChannel {
    pub fn new() -> Self {
        let (sender, receiver) = mpsc::unbounded_channel();
        Self {
            sender,
            receiver: Arc::new(Mutex::new(receiver)),
        }
    }

    pub fn sender(&self) -> mpsc::UnboundedSender<TrayEvent> {
        self.sender.clone()
    }

    pub fn receiver(&self) -> Arc<Mutex<mpsc::UnboundedReceiver<TrayEvent>>> {
        self.receiver.clone()
    }
}

/// 在托盘事件中发送消息
fn setup_tray_events(channel: &TrayEventChannel) {
    TrayIconEvent::set_event_handler(Some(move |event, _tray| {
        if let TrayIconEvent::MenuItemClick { id, .. } = event {
            let event = match id.as_ref() {
                "show_window" => TrayEvent::ShowWindow,
                "settings" => TrayEvent::OpenSettings,
                "quit" => TrayEvent::Quit,
                _ => return,
            };
            channel.sender().send(event).ok();
        }
    }));
}

/// 在主窗口中监听托盘事件
async fn handle_tray_events(channel: &TrayEventChannel, window: &WindowHandle) {
    let mut receiver = channel.receiver().lock().await;
    while let Some(event) = receiver.recv().await {
        match event {
            TrayEvent::ShowWindow => {
                window.activate().ok();
            }
            TrayEvent::OpenSettings => {
                // 打开设置窗口
            }
            TrayEvent::Quit => {
                // 退出应用
                std::process::exit(0);
            }
        }
    }
}
```

### 场景3：动态托盘菜单

```rust
// 根据状态动态更新菜单

pub struct DynamicTrayMenu {
    menu: Menu,
    status_item: MenuItem,
    settings_item: MenuItem,
}

impl DynamicTrayMenu {
    pub fn new() -> Result<Self> {
        let menu = MenuBuilder::new()
            .item("Show Window", "show_window", true, None)?
            .separator()
            .item("Status: Disconnected", "status", true, None)?
            .item("Open Settings", "settings", true, None)?
            .separator()
            .item("Quit", "quit", true, None)?
            .build()?;

        // 获取子菜单项的引用
        let status_item = menu.items().find(|item| item.id() == "status").unwrap();
        let settings_item = menu.items().find(|item| item.id() == "settings").unwrap();

        Ok(Self {
            menu,
            status_item,
            settings_item,
        })
    }

    /// 更新状态文本
    pub fn update_status(&mut self, status: &ConnectionState) {
        let text = match status {
            ConnectionState::Connected { mode, latency } => {
                match mode {
                    ConnectionMode::P2P => format!("Status: Connected (P2P) - {}ms", latency),
                    ConnectionMode::Relay => format!("Status: Connected (Relay) - {}ms", latency),
                }
            }
            ConnectionState::Connecting => "Status: Connecting...".into(),
            ConnectionState::Disconnected { .. } => "Status: Disconnected".into(),
            ConnectionState::Error { .. } => "Status: Error".into(),
        };

        // 更新菜单项文本（如果支持）
        // self.status_item.set_text(Some(&text));
    }

    /// 根据连接状态启用/禁用菜单项
    pub fn update_items(&mut self, connected: bool) {
        // 如果已连接，可能禁用某些选项
        // 如果未连接，可能启用重连选项
    }
}
```

### 场景4：托盘图标动画

```rust
// 连接状态动画图标

pub struct AnimatedTrayIcon {
    frames: Vec<Icon>,
    current_frame: usize,
    timer: Option<JoinHandle<()>>,
}

impl AnimatedTrayIcon {
    pub fn new_loading_animation() -> Result<Self> {
        // 创建加载动画帧
        let frames = (0..8).map(|i| {
            let degrees = i * 45;
            Self::create_rotated_icon(degrees)
        }).collect::<Result<Vec<_>>>()?;

        Ok(Self {
            frames,
            current_frame: 0,
            timer: None,
        })
    }

    /// 开始动画
    pub fn start_animation(&mut self, tray: &TrayIcon) {
        let tray = tray.clone();
        self.timer = Some(tokio::spawn(async move {
            let mut interval = tokio::time::interval(Duration::from_millis(100));
            loop {
                interval.tick().await;
                // 下一帧
            }
        }));
    }

    /// 停止动画
    pub fn stop_animation(&mut self) {
        if let Some(timer) = self.timer.take() {
            timer.abort();
        }
    }

    fn create_rotated_icon(degrees: u32) -> Result<Icon> {
        // 创建旋转后的图标
        // 使用图像处理库生成旋转帧
        Ok(Icon::from_rgba(vec![], 32, 32).unwrap())
    }
}
```

## 在本项目中的使用

用于实现 agent-client 的任务栏常驻和托盘菜单功能：

```
agent-client
    │
    ├── tray-icon (托盘图标)
    │       │
    │       ├── 托盘图标显示 (根据连接状态变化)
    │       ├── 右键菜单 (显示窗口、设置、退出)
    │       ├── 左键点击 (切换窗口可见性)
    │       └── 动态提示文本 (显示连接状态)
    │
    └── muda (菜单系统)
            │
            ├── Show Window
            ├── Agent Status (只读)
            ├── Open Settings
            └── Quit
```