4.3. Standard dialogs and tray icon

The stddlg module binds the operating system’s standard dialogs and the system tray (menu bar on macOS, StatusNotifierItem on Linux desktops): message boxes, open and save file pickers, and a single tray icon with a tooltip, a context menu, click events and notifications.

The tray is pumped, not threaded: the host calls tray_poll from its own loop and receives every event through the block it passes. Icons are RGBA8 pixels plus a size, so one image serves all platforms:

require stddlg
require daslib/fio

[export]
def main() {
    if (!tray_create("my tool")) {
        return
    }
    tray_menu_add(1, "Open status page", true, false)
    tray_menu_add_separator()
    tray_menu_add(2, "Quit", true, false)
    tray_menu_commit()
    var quit = false
    while (!quit) {
        tray_poll() $(ev : TrayEvent) {
            if (ev.kind == TrayEventKind.menu && ev.id == 2) {
                quit = true
            }
        }
        sleep(50u)
    }
    tray_destroy()
}

tray_available reports whether this process can show an icon at all: a Linux box without a session bus, a macOS process off the main thread or without a window server session, and a Windows service session all report false, and tray_create then returns false.

There is one tray per process, owned by the thread that called tray_create; every other tray_* call, including tray_poll, belongs to that thread. On macOS tray_create gives an unbundled process an accessory activation policy and tray_poll pumps the application’s whole event queue.

4.3.1. Enumerations

TrayEventKind

What a tray event reports: how the icon or its menu was used.

Values:

  • click = 0 - Left click (or keyboard select) on the icon; the second press of a double click on Windows and macOS follows as double_click.

  • double_click = 1 - The second press of a double click, after its click; Windows and macOS only, Linux hosts report two clicks.

  • right_click = 2 - Right click (or control-click) on the icon; the context menu opens after the event is queued.

  • menu = 3 - A menu entry was chosen; the event’s id is the entry’s id from tray_menu_add.

  • notification = 4 - The notification balloon was clicked; Windows only.

4.3.2. Handled structures

TrayEvent

One tray event as handed to the tray_poll block.

Fields:

  • kind : TrayEventKind - Which kind of event this is.

  • id : int - For a menu event, the id of the chosen entry; zero otherwise.

  • x : int - Pointer x in the host’s screen units (pixels on Windows, points on macOS, the panel’s numbers on Linux), top-left origin, when the host reports it; zero otherwise.

  • y : int - Pointer y in the same units and origin as x; zero otherwise.

4.3.3. Standard dialogs

dlg_init()

Initializes the dialog backend (GTK on Linux); call once before the first dialog. A no-op on Windows and macOS.

get_dlg_ok_cancel_from_user(arg0: string; arg1: string ): bool

Shows a message box with OK and Cancel (Yes and No on GTK); returns true for OK.

Arguments:

  • arg0 : string implicit

  • arg1 : string implicit

get_dlg_ok_from_user(arg0: string; arg1: string ): bool

Shows a message box with the given caption and body and a single OK button; returns true once dismissed, false where no dialog backend exists.

Arguments:

  • arg0 : string implicit

  • arg1 : string implicit

get_dlg_open_file(arg0: string; arg1: string ): string

Shows the system open-file picker starting at the given folder; the filter is a | separated list of extensions. Returns the chosen path, or an empty string when cancelled.

Arguments:

  • arg0 : string implicit

  • arg1 : string implicit

get_dlg_save_file(arg0: string; arg1: string; arg2: string ): string

Shows the system save-file picker starting at the given file name and folder; the filter is a | separated list of extensions. Returns the chosen path, or an empty string when cancelled.

Arguments:

  • arg0 : string implicit

  • arg1 : string implicit

  • arg2 : string implicit

4.3.4. Tray icon

tray_available(): bool

True when this process can reach a tray host: a session bus (DBUS_SESSION_BUS_ADDRESS) plus a loadable libdbus-1 on Linux, the main thread of a window-server session on macOS, an interactive desktop with a taskbar on Windows. On Linux this says the item can be exported, not that a panel is showing icons right now.

tray_create(tooltip: string ): bool

Creates the process’s single tray icon with the given tooltip and returns true; a second call while the icon exists only replaces the tooltip. False where tray_available is false or the host refused the icon. An icon, tooltip or menu set before this call is applied to the new icon. On Linux the icon is exported to the session bus and shows once a StatusNotifier host (a panel) runs, now or later.

Arguments:

  • tooltip : string implicit

tray_destroy()

Removes the tray icon and releases the backend; a later tray_create starts over.

tray_menu_add(id: int; label: string; enabled: bool; checked: bool )

Appends a menu entry: its id (positive, unique within the menu; the call panics otherwise) is reported back in a menu event, then its label, whether it can be chosen, and whether it shows a check mark.

Arguments:

  • id : int

  • label : string implicit

  • enabled : bool

  • checked : bool

tray_menu_add_separator()

Appends a separator line to the menu being built.

tray_menu_clear()

Starts a new context menu; nothing changes on screen until tray_menu_commit.

tray_menu_commit()

Publishes the menu built since tray_menu_clear as the icon’s context menu.

tray_notify(title: string; body: string ): bool

Posts a desktop notification with the given title and body: a balloon on Windows (true once the shell accepted it), org.freedesktop.Notifications on Linux (true once the daemon answered), osascript on macOS (true once the script ran). False where the host refused the request or no tray exists.

Arguments:

  • title : string implicit

  • body : string implicit

tray_poll(blk: block<(TrayEvent):void> )

Pumps the tray’s platform events on the calling thread - the thread that called tray_create - and invokes the block once per event, in order. Call it from the host’s own loop. A right click may run the menu modally inside this call on Windows and macOS, and on macOS this pumps the whole application event queue.

Arguments:
tray_set_icon(rgba8: array<uint8>; width: int; height: int )

Replaces the icon with RGBA8 pixels, row-major, width by height; each side is 1 to 1024 and the array holds exactly width * height * 4 bytes, or the call panics. Before tray_create it is kept and applied to the icon once created.

Arguments:

  • rgba8 : array<uint8> implicit

  • width : int

  • height : int

tray_set_tooltip(text: string )

Replaces the tooltip (also the title a Linux host shows).

Arguments:

  • text : string implicit