.. _stdlib_stddlg: ============================== Standard dialogs and tray icon ============================== .. das:module:: stddlg 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: .. code-block:: das 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. ++++++++++++ Enumerations ++++++++++++ .. _enum-stddlg-TrayEventKind: .. das:attribute:: 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. ++++++++++++++++++ Handled structures ++++++++++++++++++ .. _handle-stddlg-TrayEvent: .. das:attribute:: TrayEvent One tray event as handed to the tray_poll block. :Fields: * **kind** : :ref:`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. ++++++++++++++++ Standard dialogs ++++++++++++++++ * :ref:`dlg_init () ` * :ref:`get_dlg_ok_cancel_from_user (arg0: string; arg1: string) : bool ` * :ref:`get_dlg_ok_from_user (arg0: string; arg1: string) : bool ` * :ref:`get_dlg_open_file (arg0: string; arg1: string) : string ` * :ref:`get_dlg_save_file (arg0: string; arg1: string; arg2: string) : string ` .. _function-stddlg_dlg_init: .. das:function:: dlg_init() Initializes the dialog backend (GTK on Linux); call once before the first dialog. A no-op on Windows and macOS. .. _function-stddlg_get_dlg_ok_cancel_from_user_string_string: .. das:function:: 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 .. _function-stddlg_get_dlg_ok_from_user_string_string: .. das:function:: 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 .. _function-stddlg_get_dlg_open_file_string_string: .. das:function:: 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 .. _function-stddlg_get_dlg_save_file_string_string_string: .. das:function:: 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 +++++++++ Tray icon +++++++++ * :ref:`tray_available () : bool ` * :ref:`tray_create (tooltip: string) : bool ` * :ref:`tray_destroy () ` * :ref:`tray_menu_add (id: int; label: string; enabled: bool; checked: bool) ` * :ref:`tray_menu_add_separator () ` * :ref:`tray_menu_clear () ` * :ref:`tray_menu_commit () ` * :ref:`tray_notify (title: string; body: string) : bool ` * :ref:`tray_poll (blk: block\<(TrayEvent):void\>) ` * :ref:`tray_set_icon (rgba8: array\; width: int; height: int) ` * :ref:`tray_set_tooltip (text: string) ` .. _function-stddlg_tray_available: .. das:function:: 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. .. _function-stddlg_tray_create_string: .. das:function:: 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 .. _function-stddlg_tray_destroy: .. das:function:: tray_destroy() Removes the tray icon and releases the backend; a later tray_create starts over. .. _function-stddlg_tray_menu_add_int_string_bool_bool: .. das:function:: 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 .. _function-stddlg_tray_menu_add_separator: .. das:function:: tray_menu_add_separator() Appends a separator line to the menu being built. .. _function-stddlg_tray_menu_clear: .. das:function:: tray_menu_clear() Starts a new context menu; nothing changes on screen until tray_menu_commit. .. _function-stddlg_tray_menu_commit: .. das:function:: tray_menu_commit() Publishes the menu built since tray_menu_clear as the icon's context menu. .. _function-stddlg_tray_notify_string_string: .. das:function:: 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 .. _function-stddlg_tray_poll_block_ls_TrayEvent_c_void_gr_: .. das:function:: 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: * **blk** : block<( :ref:`TrayEvent `\ &):void> implicit .. _function-stddlg_tray_set_icon_array_ls_uint8_gr__int_int: .. das:function:: tray_set_icon(rgba8: array; 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 implicit * **width** : int * **height** : int .. _function-stddlg_tray_set_tooltip_string: .. das:function:: tray_set_tooltip(text: string) Replaces the tooltip (also the title a Linux host shows). :Arguments: * **text** : string implicit