std/desktop

Desktop applications: the application, its windows, and the screens they show on.

import "std/desktop"

AppOptions options = AppOptions("Notes", "dev.example.notes", single_instance: true)
app_run(options, func(App app) do
    Window main = app.window(WindowOptions(title: "Notes", remember: "main"))
    main.on(func(WindowEvent e) do
        if e.kind == WindowEventKind.CLOSE_REQUESTED and unsaved() then
            e.cancel()
        end
    end)
    app.on(func(AppEvent e) do
        if e.kind == AppEventKind.OPEN_FILES then
            open_documents(e.paths)
        end
    end)
end)?

app_run makes the system's window loop the event loop's wait, so the timers, processes, files, and sockets of std/loop keep working while windows are open, and while one is moved or resized. It returns when the application quits: when its last window closes, unless quit_on_last_window is false, or when App.quit is called.

Windows are Win32's on Windows, with per-monitor DPI awareness; Cocoa's on macOS; and GTK 3's on Linux and the BSDs, on X11 or Wayland, where GTK is loaded when the application starts, so a program builds without it and app_run gives an error of kind "unsupported" where it, or a display, is missing. What each system lacks:

Sizes are in pixels at a scale of 100%, so a window 800 wide is 1600 pixels wide on a screen at 200%, and it keeps its size as it moves between screens of different scales. Positions are the system's own screen coordinates, which on Windows are the screen's pixels.

The application

An AppEvent has a kind:

A Monitor has x, y, width, and height; work_x, work_y, work_width, and work_height for the area without the taskbar or Dock; scale in percent; and primary.

A second launch of a single instance finds the first by id, hands it its arguments and directory, and ends; a registered scheme or extension runs the program with the URL or the path as its argument, which reaches the first instance the same way.

Windows

WindowOptions say what a window is when it is made:

A WindowEvent has a kind and the window:

A handler cancels only while it runs for the event.

Menus and shortcuts

app.set_menu([
    submenu("&File", [
        menu_item("&Open…", "open", "mod+o"),
        menu_item("&Save", "save", "mod+s"),
        menu_separator(),
        role_item("quit"),
    ]),
    submenu("&Edit", [role_item("undo"), role_item("redo"), menu_separator(),
                      role_item("cut"), role_item("copy"), role_item("paste")]),
    submenu("&View", [menu_checkbox("&Word Wrap", "wrap", true),
                      menu_radio("&Small", "small", true), menu_radio("&Large", "large")]),
])
app.set_menu_enabled("save", false)

A MenuItem has a label, where & marks the letter that chooses it from the keyboard; an id, the program's name for it, which MENU events carry; a shortcut; a kind, NORMAL, CHECKBOX, RADIO, SEPARATOR, or SUBMENU with its items; checked, enabled, an icon file shown beside the label (.ico on Windows), and a role. menu_item, menu_checkbox, menu_radio, menu_separator, submenu, and role_item(role) make them. A checkbox turns over and a radio item checks itself alone in its group, the radio items next to each other, before the MENU event says so.

A shortcut is keys joined with +, as "mod+shift+s": the modifiers ctrl, alt, shift, super, and mod, which is Command on macOS and Ctrl elsewhere, then a letter, a digit, a punctuation key, f1 to f24, or a name such as enter, escape, tab, space, delete, up, or pagedown. A window's menu bar takes its items' shortcuts before the window's controls see the keys. shortcut_label(shortcut) is how the system shows it: Ctrl+Shift+S, or ⇧⌘S on macOS.

A role makes a standard item, labeled and given the shortcut each system gives it, which does what the system does, then gives a MENU event with the role as item unless the item has an id:

Dialogs

str[] paths = open_file_dialog(FileDialogOptions(filters: [FileFilter("Notes", ["*.note"])], window: main))
MessageAnswer answer = message_box(MessageOptions("Save changes to notes.txt?",
    buttons: ["Save", "Don't Save", "Cancel"], cancel_button: 2, icon: MessageIcon.QUESTION,
    window: main))
if answer.button == 0 then
    save()
end

Each dialog is the system's own and waits until it closes, while the event loop's timers and sources keep running; each has a form ending in _async that gives a Task instead and returns at once.

FileDialogOptions has title, the directory it starts in, the name it starts with, filters of FileFilter(name, patterns), multiple, folders to choose folders instead of files, show_hidden, an extension added to a name saved without one, confirm_overwrite, and the window it belongs to, which takes no input while it is open. MessageOptions has the message, a detail below it, a title (the application's name without one), buttons, default_button, cancel_button (-1 for a dialog that only a button closes), an icon (MessageIcon.NONE, INFO, WARNING, ERROR, or QUESTION), a checkbox label with checked, as for "Do not ask again", and window.

Tests answer dialogs with desktop_simulate("dialog", answer) from a timer: "cancel", "button 1", "check", or "accept name", which types a file name and presses the dialog's main button. It is false while no dialog shows yet. desktop_simulate also takes "press" with a window and a shortcut, "click" with a window and a menu item's label, "key", "end_menu", and "hotkey", so a test can stand in for a person at each part of an application.

The clipboard

set_clipboard_text("hello")
match clipboard_text() do
    when SOME(text) then
        print(text)
    when NONE then
end
set_clipboard(ClipboardContent(text: "bold", html: "<b>bold</b>"))

The clipboard works in programs without windows too. Inside app_run, each change to it, by any program, is a CLIPBOARD_CHANGED event.

The system

notify(Notification("Export finished", body: "notes.pdf is ready", id: "export", actions: ["Open"]))
app.on(func(AppEvent e) do
    if e.kind == AppEventKind.NOTIFICATION and e.action == "Open" then
        open_path(exported)
    end
end)
save_secret("notes-sync", "ana@example.com", token)

Notifications on Windows are toasts of the notification center, with the application registered under its id for the current user, as programs without a package need; choosing one while the program runs is a NOTIFICATION event. Starting at log-in is app.start_at_login. A screen reader reads a window's title and the native dialogs and menus; the contents a program draws get their accessibility from the web view of phase 8.