跳到主要内容

系统托盘

用途：在任务栏右下角放一个托盘图标，支持悬停提示、右键菜单；用户点菜单项或点图标时，宿主用 jade_on 收到 tray-menu-command 或 tray-event（见 事件类型）。

整个进程里只允许一个托盘；重复 tray_create 只会拿到同一个 tray_id。

TrayMenuItemDesc​

用途：描述一行菜单（普通项、子菜单、分隔线等）。很多行拼成一棵树，交给 tray_set_menu_items 一次性设好右键菜单。

typedef struct TrayMenuItemDesc {
  int32_t item_type;
  const char *key;
  const char *label;
  const char *parent_key;
  int32_t disabled;
  int32_t dangerous;
} TrayMenuItemDesc;
字段含义
item_type0 普通项、1 子菜单、2 分隔线、3 分组。
key业务主键，整表唯一，代码里靠它分辨点了哪一项（分隔线也要给个唯一 key）。
label用户看到的文字。
parent_key挂在哪个子菜单下面：空表示顶层；填某一行的 key，那一行必须是子菜单/分组。
disabled非 0 为灰色不可点。
dangerous非 0 时事件 JSON 里会带危险标记（如标红样式由系统/库决定）。

最多 512 行，嵌套不超过 32 层。

tray_create​

用途：创建托盘图标（若已有则直接返回已有 id）。

uint32_t tray_create(void);

返回值大于 0 即为 tray_id，后面所有托盘 API 都要带这个 id。

tray_destroy​

用途：去掉托盘图标并清掉菜单状态。

int32_t tray_destroy(uint32_t tray_id);

tray_id 必须对应当前托盘，否则返回 0。

tray_set_visible​

用途：显示或隐藏托盘上的小图标（不销毁，只是看不见）。

int32_t tray_set_visible(uint32_t tray_id, int32_t visible);

非 0 显示，0 隐藏。

tray_set_tooltip​

用途：鼠标悬停在托盘图标上时显示的一句话提示。

int32_t tray_set_tooltip(uint32_t tray_id, const char* tooltip_utf8);

指针不能为 NULL。

tray_set_icon_from_file​

用途：从 .ico 等图片文件加载托盘图标。

int32_t tray_set_icon_from_file(uint32_t tray_id, const char* icon_path_utf8);

tray_set_menu_items​

用途：整表替换右键菜单内容。传 0 行表示清空菜单。

int32_t tray_set_menu_items(
  uint32_t tray_id,
  const TrayMenuItemDesc* items,
  uint32_t item_count
);

库会复制所有字符串，校验不通过返回 0。

和主窗口的关系​

关掉主窗口不会自动删托盘；要不要随最后一窗退出进程，由你在 window-closing / window-all-closed 里自己决定。