tray

stable

Builds system-tray menu configurations as plain Zolo tables, including regular items, separators, checkboxes, and submenus — with JSON export for handoff to a native tray implementation.

use plugin tray::{create_tray_config, add_menu_item, add_separator, …}

11 functions Systems

/ filter jk navigate Esc clear

Functions (11)

create_tray_config Create a new tray config with title and tooltip
add_menu_item Append a regular menu item
add_separator Append a visual separator
set_icon_path Set the tray icon file path
set_tooltip Update the tray tooltip text
set_title Update the tray title text
add_checkbox_item Append a checkable menu item
add_submenu Append a submenu placeholder item
get_item_count Return the number of items in the menu
set_enabled Set the enabled/disabled flag on a config
to_json Serialize the tray config to a JSON string

Overview

tray is a pure configuration builder: it constructs a system-tray menu as an ordinary Zolo table — title, tooltip, icon path, and an ordered list of items — without touching any platform APIs itself. There is no opaque tray handle and no hidden state; create_tray_config returns a plain table and every other function takes that table, returns a new copy with the change applied, and leaves the original untouched. Once the menu is described, to_json serializes the whole thing so a native tray layer (or another process) can render and wire up the click handlers using each item's id.

Use it whenever you want to describe a tray menu declaratively in Zolo — building items, separators, checkboxes, and submenus by chaining calls — and hand the result off as JSON rather than driving the OS tray directly.

Common patterns

Build a menu by threading the config through a chain of builders, then export it:

use plugin tray::{create_tray_config, add_menu_item, add_separator, to_json}

let tray = create_tray_config("MyApp", "MyApp is running")
let tray = add_menu_item(tray, "Open", "open")
let tray = add_menu_item(tray, "Settings", "settings")
let tray = add_separator(tray)
let tray = add_menu_item(tray, "Quit", "quit")
print(to_json(tray))

Mix item kinds — a checkbox toggle, a submenu, and a separator — in one menu:

use plugin tray::{create_tray_config, set_icon_path, add_checkbox_item, add_submenu, add_separator, add_menu_item}

let tray = create_tray_config("MyApp", "Idle")
let tray = set_icon_path(tray, "assets/icon.png")
let tray = add_checkbox_item(tray, "Start at login", "start_at_login", false)
let tray = add_submenu(tray, "Themes", "submenu_themes")
let tray = add_separator(tray)
let tray = add_menu_item(tray, "Quit", "quit")

Inspect and gate a menu before exporting it:

use plugin tray::{create_tray_config, add_menu_item, get_item_count, set_enabled, to_json}

let tray = create_tray_config("MyApp", "")
let tray = add_menu_item(tray, "Open", "open")
let tray = set_enabled(tray, get_item_count(tray) > 0)
print(to_json(tray))

create_tray_config(title, tooltip) → table

Create a new tray config with title and tooltip

Creates a new tray configuration table with the given title and tooltip text. The config starts with an empty items list and no icon path set. All other functions accept and return this table.

use plugin tray::{create_tray_config}

let tray = create_tray_config("MyApp", "Click to open MyApp menu")

Because the config is a plain table, you can read its fields directly after creating it:

use plugin tray::{create_tray_config}

let tray = create_tray_config("MyApp", "Running")
print("title: {tray["title"]}")
print("tooltip: {tray["tooltip"]}")

add_menu_item(config, label, id) → table

Append a regular menu item

Appends a regular clickable menu item with the given display label and action id. Returns a new config table with the item added; the original is not modified.

use plugin tray::{create_tray_config, add_menu_item}

let tray = create_tray_config("MyApp", "MyApp is running")
let tray = add_menu_item(tray, "Open", "action_open")
let tray = add_menu_item(tray, "Quit", "action_quit")

add_separator(config) → table

Append a visual separator

Appends a visual separator line between menu items. Separators have no label or ID.

use plugin tray::{create_tray_config, add_menu_item, add_separator}

let tray = create_tray_config("MyApp", "")
let tray = add_menu_item(tray, "Open", "open")
let tray = add_separator(tray)
let tray = add_menu_item(tray, "Quit", "quit")

set_icon_path(config, path) → table

Set the tray icon file path

Sets the file path for the tray icon image. The path is stored in the config and passed through to the native tray implementation via to_json.

use plugin tray::{create_tray_config, set_icon_path}

let tray = create_tray_config("MyApp", "")
let tray = set_icon_path(tray, "assets/icon.png")

set_tooltip(config, tooltip) → table

Update the tray tooltip text

Replaces the tooltip text shown when the user hovers over the tray icon. Returns a new config table with the updated tooltip.

use plugin tray::{create_tray_config, set_tooltip}

let tray = create_tray_config("MyApp", "Running")
let tray = set_tooltip(tray, "MyApp - 3 notifications")

set_title(config, title) → table

Update the tray title text

Replaces the tray title text. On macOS this appears next to the icon in the menu bar; behavior varies by platform.

use plugin tray::{create_tray_config, set_title}

let tray = create_tray_config("MyApp", "")
let tray = set_title(tray, "MyApp v2")

add_checkbox_item(config, label, id, checked) → table

Append a checkable menu item

Appends a checkable menu item. The checked boolean sets the initial checked state. The item type is "checkbox" in the exported config.

use plugin tray::{create_tray_config, add_checkbox_item}

let tray = create_tray_config("MyApp", "")
let tray = add_checkbox_item(tray, "Start at login", "start_at_login", false)
let tray = add_checkbox_item(tray, "Show notifications", "notifications", true)

Combine checkboxes with separators to group toggles in their own section:

use plugin tray::{create_tray_config, add_checkbox_item, add_separator, add_menu_item}

let tray = create_tray_config("MyApp", "")
let tray = add_checkbox_item(tray, "Dark mode", "dark_mode", true)
let tray = add_checkbox_item(tray, "Compact view", "compact", false)
let tray = add_separator(tray)
let tray = add_menu_item(tray, "Quit", "quit")

add_submenu(config, label, id) → table

Append a submenu placeholder item

Appends a submenu placeholder item with an empty children list. The item type is "submenu". Populate the children by building a separate tray config and embedding it, or populate them in your native tray handler using the id.

use plugin tray::{create_tray_config, add_submenu, add_menu_item}

let tray = create_tray_config("MyApp", "")
let tray = add_submenu(tray, "Themes", "submenu_themes")
let tray = add_menu_item(tray, "Quit", "quit")

get_item_count(config) → int

Return the number of items in the menu

Returns the number of items currently in the menu, including separators, checkboxes, and submenus.

use plugin tray::{create_tray_config, add_menu_item, add_separator, get_item_count}

let tray = create_tray_config("MyApp", "")
let tray = add_menu_item(tray, "Open", "open")
let tray = add_separator(tray)
let tray = add_menu_item(tray, "Quit", "quit")
print(get_item_count(tray))

Use the count to drive logic, such as only exporting a non-empty menu:

use plugin tray::{create_tray_config, add_menu_item, get_item_count, to_json}

let tray = create_tray_config("MyApp", "")
let tray = add_menu_item(tray, "Open", "open")
if get_item_count(tray) > 0 {
  print(to_json(tray))
}

set_enabled(config, enabled) → table

Set the enabled/disabled flag on a config

Adds or updates an enabled boolean field on the config table. Pass false to mark the entire tray menu as disabled; your native tray layer is responsible for enforcing this.

use plugin tray::{create_tray_config, set_enabled}

let tray = create_tray_config("MyApp", "")
let tray = set_enabled(tray, false)

to_json(config) → string

Serialize the tray config to a JSON string

Serializes the full tray configuration table to a pretty-printed JSON string. Use this to hand the config off to a native tray implementation or store it for later use.

use plugin tray::{create_tray_config, add_menu_item, add_separator, set_icon_path, to_json}

let tray = create_tray_config("MyApp", "MyApp is running")
let tray = set_icon_path(tray, "assets/icon.png")
let tray = add_menu_item(tray, "Open", "open")
let tray = add_separator(tray)
let tray = add_menu_item(tray, "Quit", "quit")
let json = to_json(tray)
print(json)

View source code