@crossbind/extension-menu 0.0.0-bootstrap.0 → 2.0.0-beta.69

package/native/linux.cpp

@@ -0,0 +1,320 @@
+// The page's menus on Linux: a GTK menu bar above the webview.
+#include "menu.h"
+
+#include "crossbind/app.h"
+
+#include <gtk/gtk.h>
+#include <unistd.h>
+#include <webkit2/webkit2.h>
+
+#include <climits>
+#include <map>
+#include <memory>
+#include <stdexcept>
+
+namespace crossbind::menu {
+namespace {
+
+// Each window's bar, by the window's id, and the accelerators that come with it.
+struct Bar {
+    GtkWidget *bar = nullptr;
+    GtkAccelGroup *accelerators = nullptr;
+};
+std::map<uint64_t, Bar> bars;
+// The webviews' last button press, which a popup opens from, as Wayland asks of one, and when it came: a press too old
+// for a grab, as a contextmenu of the keyboard follows none, gives way to none.
+GdkEvent *lastPress = nullptr;
+gint64 lastPressTime = 0;
+constexpr gint64 FRESH_PRESS_US = 1000000;
+// Whether a popup of the page's shows, beside which the page opens none.
+bool isPopupOpen = false;
+
+// What a click of an item does: one of the page's tells its menu's owner its id, a standard one does what its role says,
+// to the window whose menus it is in.
+struct Action {
+    uint64_t window;
+    std::string id;
+    std::string role;
+    MenuClicked clicked;
+};
+
+// A standard item's label and accelerator, as GTK apps have them.
+struct Role {
+    const char *label;
+    guint key;
+    GdkModifierType modifiers;
+};
+
+constexpr auto CONTROL = GDK_CONTROL_MASK;
+const std::map<std::string, Role> ROLES{
+    {"undo", {"Undo", GDK_KEY_z, CONTROL}},
+    {"redo", {"Redo", GDK_KEY_z, static_cast<GdkModifierType>(CONTROL | GDK_SHIFT_MASK)}},
+    {"cut", {"Cut", GDK_KEY_x, CONTROL}},
+    {"copy", {"Copy", GDK_KEY_c, CONTROL}},
+    {"paste", {"Paste", GDK_KEY_v, CONTROL}},
+    {"selectAll", {"Select All", GDK_KEY_a, CONTROL}},
+    {"minimize", {"Minimize", 0, static_cast<GdkModifierType>(0)}},
+    {"close", {"Close", GDK_KEY_w, CONTROL}},
+    {"quit", {"Quit", GDK_KEY_q, CONTROL}},
+};
+
+const std::map<std::string, const char *> EDITING_COMMANDS{
+    {"undo", WEBKIT_EDITING_COMMAND_UNDO}, {"redo", WEBKIT_EDITING_COMMAND_REDO},
+    {"cut", WEBKIT_EDITING_COMMAND_CUT},   {"copy", WEBKIT_EDITING_COMMAND_COPY},
+    {"paste", WEBKIT_EDITING_COMMAND_PASTE}, {"selectAll", WEBKIT_EDITING_COMMAND_SELECT_ALL},
+};
+
+const std::map<std::string, guint> NAMED_KEYS{
+    {"Enter", GDK_KEY_Return}, {"Escape", GDK_KEY_Escape}, {"Tab", GDK_KEY_Tab},         {"Space", GDK_KEY_space},
+    {"Backspace", GDK_KEY_BackSpace}, {"Delete", GDK_KEY_Delete}, {"Up", GDK_KEY_Up},       {"Down", GDK_KEY_Down},
+    {"Left", GDK_KEY_Left},    {"Right", GDK_KEY_Right},   {"Home", GDK_KEY_Home},       {"End", GDK_KEY_End},
+    {"PageUp", GDK_KEY_Page_Up}, {"PageDown", GDK_KEY_Page_Down}, {"Plus", GDK_KEY_plus}, {"Minus", GDK_KEY_minus},
+    {"Comma", GDK_KEY_comma},  {"Period", GDK_KEY_period},
+};
+
+guint keyOf(const Accelerator &accelerator) {
+    const std::string &key = accelerator.key;
+    if (accelerator.function) return GDK_KEY_F1 + static_cast<guint>(accelerator.function) - 1;
+    if (key.size() == 1) return gdk_unicode_to_keyval(static_cast<guint32>(g_ascii_tolower(key[0])));
+    const auto named = NAMED_KEYS.find(key);
+    if (named == NAMED_KEYS.end()) throw std::invalid_argument("crossbind: no accelerator has the key " + key);
+    return named->second;
+}
+
+void runRole(uint64_t window, const std::string &role) {
+    if (role == "quit") {
+        app::requestQuit();
+        return;
+    }
+    const std::optional<Window> open = windowOf(window);
+    if (!open) return;
+    if (const auto command = EDITING_COMMANDS.find(role); command != EDITING_COMMANDS.end()) {
+        webkit_web_view_execute_editing_command(WEBKIT_WEB_VIEW(open->webView()), command->second);
+    } else if (role == "minimize") {
+        gtk_window_iconify(GTK_WINDOW(open->native()));
+    } else {
+        gtk_window_close(GTK_WINDOW(open->native()));
+    }
+}
+
+void activated(GtkMenuItem *item, gpointer data) {
+    const Action &action = *static_cast<Action *>(data);
+    if (!action.role.empty()) {
+        runRole(action.window, action.role);
+        return;
+    }
+    std::optional<bool> checked;
+    if (GTK_IS_CHECK_MENU_ITEM(item)) checked = gtk_check_menu_item_get_active(GTK_CHECK_MENU_ITEM(item)) != FALSE;
+    if (action.clicked && !action.id.empty()) action.clicked(action.window, action.id, checked);
+}
+
+void connect(GtkWidget *item, Action action) {
+    g_signal_connect_data(item, "activate", G_CALLBACK(activated), new Action(std::move(action)),
+                          [](gpointer data, GClosure *) { delete static_cast<Action *>(data); }, static_cast<GConnectFlags>(0));
+}
+
+void addItem(GtkMenuShell *shell, const MenuItem &page, uint64_t window, GtkAccelGroup *accelerators, const MenuClicked &clicked);
+
+// Each item goes in its shell before what may throw, so the bar destroys it with itself.
+void addMenu(GtkMenuShell *shell, const std::string &label, const std::vector<MenuItem> &items, uint64_t window, GtkAccelGroup *accelerators,
+             const MenuClicked &clicked) {
+    GtkWidget *holder = gtk_menu_item_new_with_label(label.c_str());
+    GtkWidget *menu = gtk_menu_new();
+    gtk_menu_item_set_submenu(GTK_MENU_ITEM(holder), menu);
+    gtk_menu_shell_append(shell, holder);
+    for (const auto &child : items) addItem(GTK_MENU_SHELL(menu), child, window, accelerators, clicked);
+}
+
+void addItem(GtkMenuShell *shell, const MenuItem &page, uint64_t window, GtkAccelGroup *accelerators, const MenuClicked &clicked) {
+    if (page.isSeparator) {
+        gtk_menu_shell_append(shell, gtk_separator_menu_item_new());
+        return;
+    }
+    if (page.isSubmenu) {
+        addMenu(shell, page.label, page.items, window, accelerators, clicked);
+        return;
+    }
+    GtkWidget *made = nullptr;
+    if (!page.role.empty()) {
+        const auto role = ROLES.find(page.role);
+        if (role == ROLES.end()) throw std::invalid_argument("crossbind: no menu item has the role " + page.role);
+        made = gtk_menu_item_new_with_label(page.label.empty() ? role->second.label : page.label.c_str());
+        if (!page.accelerator && role->second.key) {
+            gtk_widget_add_accelerator(made, "activate", accelerators, role->second.key, role->second.modifiers, GTK_ACCEL_VISIBLE);
+        }
+        connect(made, Action{window, "", page.role, nullptr});
+    } else {
+        made = page.checked ? gtk_check_menu_item_new_with_label(page.label.c_str()) : gtk_menu_item_new_with_label(page.label.c_str());
+        // Setting it activates the item, so before the page hears of its clicks.
+        if (page.checked) gtk_check_menu_item_set_active(GTK_CHECK_MENU_ITEM(made), *page.checked);
+        gtk_widget_set_sensitive(made, page.isEnabled);
+        connect(made, Action{window, page.id, "", clicked});
+    }
+    gtk_menu_shell_append(shell, made);
+    if (page.accelerator) {
+        const Accelerator &accelerator = *page.accelerator;
+        const auto modifiers = static_cast<GdkModifierType>((accelerator.control ? GDK_CONTROL_MASK : 0) | (accelerator.alt ? GDK_MOD1_MASK : 0) |
+                                                            (accelerator.shift ? GDK_SHIFT_MASK : 0));
+        gtk_widget_add_accelerator(made, "activate", accelerators, keyOf(accelerator), modifiers, GTK_ACCEL_VISIBLE);
+    }
+}
+
+// The page keeps the height its window gave it, so the window takes the bar's height on, unless it fills the screen.
+void keepPageHeight(GtkWindow *window, GtkWidget *webView, int barHeight) {
+    GdkWindow *shown = gtk_widget_get_window(GTK_WIDGET(window));
+    if (!shown || (gdk_window_get_state(shown) & (GDK_WINDOW_STATE_MAXIMIZED | GDK_WINDOW_STATE_FULLSCREEN))) return;
+    int width = 0;
+    gtk_window_get_size(window, &width, nullptr);
+    gtk_window_resize(window, width, gtk_widget_get_allocated_height(webView) + barHeight);
+}
+
+gboolean onPress(GtkWidget *, GdkEvent *event, gpointer) {
+    if (lastPress) gdk_event_free(lastPress);
+    lastPress = gdk_event_copy(event);
+    lastPressTime = g_get_monotonic_time();
+    return FALSE;
+}
+
+// A popup as it shows: who hears its answer, the id of the item clicked, and what goes with it.
+struct Popup {
+    std::function<void(Failure, std::optional<std::string>)> done;
+    std::shared_ptr<std::optional<std::string>> picked;
+    GtkWidget *menu;
+    GtkAccelGroup *accelerators;
+};
+
+// GTK takes the menu down before an item's activate, so the answer waits for the loop's next turn.
+void onPopupClosed(GtkMenuShell *menu, gpointer data) {
+    g_signal_handlers_disconnect_by_func(menu, reinterpret_cast<gpointer>(onPopupClosed), data);
+    g_idle_add(
+        [](gpointer data) -> gboolean {
+            std::unique_ptr<Popup> popup(static_cast<Popup *>(data));
+            isPopupOpen = false;
+            popup->done(std::nullopt, *popup->picked);
+            gtk_widget_destroy(popup->menu);
+            g_object_unref(popup->accelerators);
+            return G_SOURCE_REMOVE;
+        },
+        data);
+}
+
+}  // namespace
+
+void setDockMenu(std::vector<MenuItem>, MenuClicked, std::function<void(Failure)>) {
+    throw std::runtime_error("crossbind: a macOS app alone has a Dock menu");
+}
+
+void keepPresses(void *webView) { g_signal_connect(GTK_WIDGET(webView), "button-press-event", G_CALLBACK(onPress), nullptr); }
+
+// The menu opens at the page's point in its window's webview, which WebKitGTK zooms.
+void popupMenu(uint64_t window, std::vector<MenuItem> items, double x, double y, std::function<void(Failure, std::optional<std::string>)> done) {
+    onMainThread([window, items = std::move(items), x, y, done = std::move(done)] {
+        const std::optional<Window> open = windowOf(window);
+        GtkWidget *view = open ? GTK_WIDGET(open->webView()) : nullptr;
+        if (!view || !gtk_widget_get_realized(view)) {
+            done(std::string("crossbind: the app has no window to show a menu in"), std::nullopt);
+            return;
+        }
+        if (isPopupOpen) {
+            done(std::string("crossbind: a menu of the page's is open already"), std::nullopt);
+            return;
+        }
+        auto picked = std::make_shared<std::optional<std::string>>();
+        GtkWidget *menu = gtk_menu_new();
+        GtkAccelGroup *accelerators = gtk_accel_group_new();
+        try {
+            for (const auto &item : items) {
+                addItem(GTK_MENU_SHELL(menu), item, window, accelerators, [picked](uint64_t, std::string id, std::optional<bool>) { *picked = std::move(id); });
+            }
+        } catch (const std::exception &error) {
+            gtk_widget_destroy(menu);
+            g_object_unref(accelerators);
+            done(std::string(error.what()), std::nullopt);
+            return;
+        }
+        gtk_menu_attach_to_widget(GTK_MENU(menu), view, nullptr);
+        auto *popup = new Popup{done, picked, menu, accelerators};
+        g_signal_connect(menu, "deactivate", G_CALLBACK(onPopupClosed), popup);
+        const double zoom = webkit_web_view_get_zoom_level(WEBKIT_WEB_VIEW(view));
+        gtk_widget_show_all(menu);
+        GdkEvent *trigger = lastPress && g_get_monotonic_time() - lastPressTime < FRESH_PRESS_US ? lastPress : nullptr;
+        // The page's point in the webview's own GdkWindow: gtk_menu_popup_at_widget() takes a widget's allocation to be in
+        // that window, and so added the webview's place in its toplevel once more, the menu bar's height on X11 and with
+        // the client-side decorations' on Wayland.
+        GdkRectangle point{static_cast<int>(x * zoom), static_cast<int>(y * zoom), 1, 1};
+        gtk_menu_popup_at_rect(GTK_MENU(menu), gtk_widget_get_window(view), &point, GDK_GRAVITY_NORTH_WEST, GDK_GRAVITY_NORTH_WEST, trigger);
+        // GTK shows no menu it could not grab the pointer for, and tells of none: it closes without a click.
+        if (!gtk_widget_get_visible(gtk_widget_get_toplevel(menu))) {
+            g_signal_handlers_disconnect_by_func(menu, reinterpret_cast<gpointer>(onPopupClosed), popup);
+            delete popup;
+            gtk_widget_destroy(menu);
+            g_object_unref(accelerators);
+            done(std::nullopt, std::nullopt);
+            return;
+        }
+        isPopupOpen = true;
+    });
+}
+
+// A Linux app is a directory: the executable, and the app's files in resources/ beside it.
+std::string resourceFolder() {
+    char path[PATH_MAX];
+    const ssize_t length = readlink("/proc/self/exe", path, sizeof path);
+    const std::string executable = length > 0 ? std::string(path, static_cast<size_t>(length)) : std::string();
+    return executable.substr(0, executable.find_last_of('/')) + "/resources";
+}
+
+// The bar goes above the window's webview, in the box the host holds it in, and its accelerators come before the
+// webview's keys; no menus hide it.
+void setMenu(uint64_t window, std::vector<MenuItem> menus, MenuClicked clicked, std::function<void(Failure)> done) {
+    onMainThread([window, menus = std::move(menus), clicked = std::move(clicked), done = std::move(done)] {
+        const std::optional<Window> open = windowOf(window);
+        GtkWidget *view = open ? GTK_WIDGET(open->webView()) : nullptr;
+        GtkWidget *box = view ? gtk_widget_get_parent(view) : nullptr;
+        if (!GTK_IS_BOX(box)) {
+            done("crossbind: the page's window has no place to show its menus in");
+            return;
+        }
+        GtkWindow *shown = GTK_WINDOW(open->native());
+        GtkAccelGroup *accelerators = gtk_accel_group_new();
+        GtkWidget *next = gtk_menu_bar_new();
+        g_object_ref_sink(next);
+        try {
+            for (const auto &menu : menus) addItem(GTK_MENU_SHELL(next), menu, window, accelerators, clicked);
+        } catch (const std::exception &error) {
+            gtk_widget_destroy(next);
+            g_object_unref(next);
+            g_object_unref(accelerators);
+            done(std::string(error.what()));
+            return;
+        }
+        Bar &before = bars[window];
+        if (before.bar) gtk_widget_destroy(before.bar);
+        if (before.accelerators) {
+            gtk_window_remove_accel_group(shown, before.accelerators);
+            g_object_unref(before.accelerators);
+        }
+        // Above the webview, which the box holds at its end.
+        gtk_container_add(GTK_CONTAINER(box), next);
+        int height = 0;
+        if (!menus.empty()) {
+            gtk_widget_show_all(next);
+            gtk_widget_get_preferred_height(next, nullptr, &height);
+        }
+        g_object_unref(next);
+        gtk_window_add_accel_group(shown, accelerators);
+        before = Bar{next, accelerators};
+        keepPageHeight(shown, view, height);
+        done(std::nullopt);
+    });
+}
+
+// The bar went with its window, which held the accelerators as well.
+void dropMenus(uint64_t window) {
+    const auto found = bars.find(window);
+    if (found == bars.end()) return;
+    if (found->second.accelerators) g_object_unref(found->second.accelerators);
+    bars.erase(found);
+}
+
+}  // namespace crossbind::menu

package/native/menu.cpp

@@ -0,0 +1,196 @@
+// The page's menus, a desktop app's tray icon and the system's notifications, which crossbind/app's menu, tray and
+// notification call: the items the page gives, held to what crossbind/app holds a page to, and what each platform shows
+// of them. The host's own extension, it adds the functions of tray and notification beside menu's.
+#include "menu.h"
+
+#include "crossbind/app.h"
+
+#include <algorithm>
+#include <stdexcept>
+#include <utility>
+
+namespace crossbind::menu {
+namespace {
+
+std::string trayId;
+
+std::function<void(Failure)> answered(Call call) {
+    return [call = std::move(call)](Failure failure) {
+        if (failure) call.reject(*failure);
+        else call.resolve();
+    };
+}
+
+// The roles crossbind/app takes, which a page that went around it is held to as well.
+const std::vector<std::string> MENU_ROLES{"editMenu", "windowMenu", "undo", "redo", "cut", "copy", "paste", "selectAll", "minimize", "close", "quit"};
+constexpr int FUNCTION_KEYS = 12;
+
+Accelerator acceleratorOf(const std::string &text) {
+    Accelerator accelerator;
+    size_t start = 0;
+    for (size_t end = text.find('+'); end != std::string::npos; end = text.find('+', start)) {
+        const std::string modifier = text.substr(start, end - start);
+#ifdef __APPLE__
+        const bool isCommand = modifier == "CmdOrCtrl";
+#else
+        const bool isCommand = false;
+#endif
+        if (isCommand) {
+            accelerator.command = true;
+        } else if (modifier == "CmdOrCtrl" || modifier == "Ctrl") {
+            accelerator.control = true;
+        } else if (modifier == "Alt") {
+            accelerator.alt = true;
+        } else if (modifier == "Shift") {
+            accelerator.shift = true;
+        } else {
+            throw std::invalid_argument("crossbind: no accelerator has the modifier " + modifier);
+        }
+        start = end + 1;
+    }
+    accelerator.key = text.substr(start);
+    for (int number = 1; number <= FUNCTION_KEYS; number += 1) {
+        if (accelerator.key == "F" + std::to_string(number)) accelerator.function = number;
+    }
+    return accelerator;
+}
+
+#ifndef __APPLE__
+// A standard menu off macOS is its standard items, which each platform makes as its apps have them.
+MenuItem standardMenu(const MenuItem &menu) {
+    const bool isEdit = menu.role == "editMenu";
+    MenuItem out;
+    out.isSubmenu = true;
+    out.label = !menu.label.empty() ? menu.label : isEdit ? "Edit" : "Window";
+    const std::vector<std::string> roles = isEdit ? std::vector<std::string>{"undo", "redo", "", "cut", "copy", "paste", "", "selectAll"}
+                                                  : std::vector<std::string>{"minimize", "close"};
+    for (const auto &role : roles) {
+        MenuItem item;
+        item.role = role;
+        item.isSeparator = role.empty();
+        out.items.push_back(std::move(item));
+    }
+    return out;
+}
+#endif
+
+std::vector<MenuItem> menuItems(const Value &list) {
+    std::vector<MenuItem> out;
+    for (const Value &value : list.asArray()) {
+        MenuItem item;
+        item.label = value["label"].asString("");
+        item.id = value["id"].asString("");
+        item.role = value["role"].asString("");
+        if (!item.role.empty() && std::find(MENU_ROLES.begin(), MENU_ROLES.end(), item.role) == MENU_ROLES.end()) {
+            throw std::invalid_argument("crossbind: no menu item has the role " + item.role);
+        }
+        const std::string accelerator = value["accelerator"].asString("");
+        if (!accelerator.empty()) item.accelerator = acceleratorOf(accelerator);
+        if (!value["checked"].isNull()) item.checked = value["checked"].asBool();
+        item.isEnabled = value["enabled"].asBool(true);
+        item.isSeparator = value["type"].asString("") == "separator";
+        const Value &children = value["items"];
+        item.isSubmenu = !children.isNull();
+        if (item.isSubmenu) item.items = menuItems(children);
+#ifndef __APPLE__
+        if (item.role == "editMenu" || item.role == "windowMenu") item = standardMenu(item);
+#endif
+        out.push_back(std::move(item));
+    }
+    return out;
+}
+
+// A tray's menu and the Dock's have neither standard items nor keys, and each item but a separator has a label, as
+// crossbind/app holds a page to.
+void checkTrayItems(const std::vector<MenuItem> &items, const std::string &menu) {
+    for (const auto &item : items) {
+        if (!item.role.empty() || item.accelerator) throw std::invalid_argument("crossbind: " + menu + " takes no role or accelerator");
+        if (!item.isSeparator && item.label.empty()) throw std::invalid_argument("crossbind: " + menu + " has an item without a label");
+        checkTrayItems(item.items, menu);
+    }
+}
+
+// A click the pages hear of as the event menu: one in a window's menus reaches the page that window shows, and one in the
+// tray's menu or the Dock's the page in front that listens.
+void menuClicked(uint64_t window, std::string id, std::optional<bool> checked) {
+    Value::Object click{{"id", std::move(id)}};
+    if (checked) click.emplace_back("checked", *checked);
+    const std::string json = Value(std::move(click)).json();
+#if !defined(__ANDROID__)
+    if (window != 0) {
+        if (const std::optional<Window> open = windowOf(window)) app::emitEvent("menu", json, open->page().id());
+        return;
+    }
+#endif
+    app::emitEventToFront("menu", json);
+}
+
+// The window of the page whose call sets menus or opens one: the app's own code has none. A phone's platform refuses
+// menus itself.
+uint64_t windowOfCall(const Call &call) {
+    const uint64_t window = call.page().windowId();
+#if !defined(__ANDROID__) && !TARGET_OS_IPHONE
+    if (window == 0) throw std::invalid_argument("crossbind: " + call.name() + " sets the menus of a page's window, which the app's own code has none of");
+#endif
+    return window;
+}
+
+}  // namespace
+
+const std::string &appId() { return trayId; }
+
+}  // namespace crossbind::menu
+
+void crossbind_extension_menu(crossbind::Registry &registry) {
+    using namespace crossbind::menu;
+    using crossbind::Call;
+    trayId = registry.options()["id"].asString("");
+#if defined(__linux__) && !defined(__ANDROID__)
+    registry.onWindow([](const crossbind::Window &window) { keepPresses(window.webView()); });
+#elif defined(__APPLE__) && !TARGET_OS_IPHONE
+    registry.onWindow([](const crossbind::Window &) { answerDockMenu(); });
+#endif
+    registry.onWindowClosed([](const crossbind::Window &window) { dropMenus(window.id()); });
+#ifdef _WIN32
+    registry.onQuit(quitTray);
+#endif
+    registry.function("menu.set", [](Call call) {
+        std::vector<MenuItem> menus = menuItems(call.options()["menus"]);
+        setMenu(windowOfCall(call), std::move(menus), menuClicked, answered(call));
+    });
+    registry.function("menu.popup", [](Call call) {
+        const crossbind::Value &options = call.options();
+        std::vector<MenuItem> items = menuItems(options["items"]);
+        popupMenu(windowOfCall(call), std::move(items), options["x"].asNumber(), options["y"].asNumber(), [call](Failure failure, std::optional<std::string> id) {
+            if (failure) {
+                call.reject(*failure);
+            } else {
+                call.resolve(id ? crossbind::Value(*id) : crossbind::Value());
+            }
+        });
+    });
+    registry.function("tray.set", [](Call call) {
+        const crossbind::Value &options = call.options();
+        TrayOptions tray{options["tooltip"].asString(""), options["menu"].isNull() ? std::vector<MenuItem>() : menuItems(options["menu"])};
+        checkTrayItems(tray.menu, "tray.set's menu");
+        setTray(std::move(tray), menuClicked, answered(call));
+    });
+    registry.function("tray.remove", [](Call call) { removeTray(answered(call)); });
+    registry.function("menu.setDock", [](Call call) {
+        std::vector<MenuItem> items = menuItems(call.options()["items"]);
+        checkTrayItems(items, "menu.setDock's menu");
+        setDockMenu(std::move(items), menuClicked, answered(call));
+    });
+    // A tap of one of showNotification()'s, which the host's notification center hands over on macOS: a push's sender
+    // names its own.
+    registry.onNotification([](const crossbind::Notification &notification) {
+        if (notification.isTap() && !notification.isRemote() && notification.id().rfind(NOTIFICATION_ID_PREFIX, 0) == 0) {
+            crossbind::app::emitEventToFront("notification");
+        }
+    });
+    registry.function("notification.show", [](Call call) {
+        const std::string title = call.options()["title"].asString("");
+        if (title.empty()) throw std::invalid_argument("crossbind: notification.show takes a title");
+        showNotification({title, call.options()["body"].asString("")}, answered(call));
+    });
+}

package/native/menu.h

@@ -0,0 +1,99 @@
+#pragma once
+
+// What each platform does for the page's menus, a desktop app's tray icon and the system's notifications. Each is called
+// on the module's thread, works on the main thread and calls done there with why it failed, or nothing. A platform that
+// has no such function throws.
+#include "crossbind/extension.h"
+
+#include <functional>
+#include <optional>
+#include <string>
+#include <vector>
+
+namespace crossbind::menu {
+
+using Failure = std::optional<std::string>;
+
+// A key and its modifiers, as crossbind/app checks them: the key is A–Z, 0–9, F1–F12 or one of crossbind/app's names,
+// and CmdOrCtrl is command on macOS and control elsewhere.
+struct Accelerator {
+    bool command = false;
+    bool control = false;
+    bool alt = false;
+    bool shift = false;
+    std::string key;
+    // 1 to 12 for F1 to F12, else 0.
+    int function = 0;
+};
+
+// An item of the page's menus: a separator, a standard menu or item by its role, a submenu, or one whose clicks the page
+// hears of by its id.
+struct MenuItem {
+    std::string label;
+    std::string id;
+    std::string role;
+    std::optional<Accelerator> accelerator;
+    std::optional<bool> checked;
+    bool isSeparator = false;
+    bool isEnabled = true;
+    bool isSubmenu = false;
+    std::vector<MenuItem> items;
+};
+
+// A click of an item with an id, on the main thread: the window whose menus it is in, 0 for the tray's and the Dock's,
+// and whether a checked one now is.
+using MenuClicked = std::function<void(uint64_t window, std::string id, std::optional<bool> checked)>;
+// Sets the menus of the window of this id, on the main thread, which calls done: the bar of that window on Windows and
+// Linux, and on macOS the menu bar while it is the key window. A click of an item with an id calls clicked there.
+void setMenu(uint64_t window, std::vector<MenuItem> menus, MenuClicked clicked, std::function<void(Failure)> done);
+// The menus of a window that closed go with it, on the main thread.
+void dropMenus(uint64_t window);
+// Opens a menu of these items at the point x, y of the page of the window of this id, in CSS pixels from its top left,
+// as a right click's menu opens, on the main thread: done gets there the id of the item clicked, or none when the menu
+// closed without one. A standard item does what its role says.
+void popupMenu(uint64_t window, std::vector<MenuItem> items, double x, double y, std::function<void(Failure, std::optional<std::string> id)> done);
+// The menu a macOS app's Dock icon shows above the system's items, on the main thread, which calls done; a click of an
+// item with an id calls clicked there. None takes it away.
+void setDockMenu(std::vector<MenuItem> items, MenuClicked clicked, std::function<void(Failure)> done);
+// The app's icon in the menu bar on macOS, the notification area on Windows and a desktop's status tray on Linux, with
+// its tooltip and the menu a click opens. A click of an item with an id calls clicked, and a click of the icon that opens
+// no menu tells the page in front that listens as the event tray. Set again, it changes the icon. On the main thread,
+// which calls done.
+struct TrayOptions {
+    std::string tooltip;
+    std::vector<MenuItem> menu;
+};
+void setTray(TrayOptions options, MenuClicked clicked, std::function<void(Failure)> done);
+void removeTray(std::function<void(Failure)> done);
+// A notification of the system's, a click on which tells the page in front that listens as the event notification. On
+// the main thread, which calls done once the system has taken it.
+struct Notification {
+    std::string title;
+    std::string body;
+};
+void showNotification(Notification notification, std::function<void(Failure)> done);
+// What the identifier of each notification showNotification() shows starts with, whose taps the page hears of on macOS.
+inline constexpr char NOTIFICATION_ID_PREFIX[] = "crossbind.menu.";
+
+// The app's id, which a Linux tray names itself by on the session bus, as the build gives it in the extension's options.
+const std::string &appId();
+
+#if defined(__APPLE__) && !TARGET_OS_IPHONE
+// Gives the app's delegate the Dock's menu, none until setDockMenu() sets one, as the window opens: AppKit asks a delegate
+// that answered as it was set alone.
+void answerDockMenu();
+#endif
+
+#ifdef _WIN32
+// Takes the app's icon from the notification area as the app quits, where it would stay until a pointer passed over it.
+void quitTray();
+#endif
+
+#if defined(__linux__) && !defined(__ANDROID__)
+// The folder of a Linux app's files, resources/ beside its executable, which holds the app's icon.png.
+std::string resourceFolder();
+// Keeps the last button press of a window's webview, which popupMenu() opens from, as the window opens.
+void keepPresses(void *webView);
+#endif
+
+}  // namespace crossbind::menu