Menus

Windows and Linux share the same menu definition. Menus are used in two ways:

  • Popup menus for context menus and tray menus, through jade_menu_popup.
  • Window menu bars below the title bar, through jade_set_application_menu or jade_window_set_menu.

Items are described by JadeMenuItemDesc. The library copies the item array and strings during the call, so the caller may release them immediately.

A normal decorated window without a custom menu shows the built-in Edit / View / Window / Help menus. Close Window is under Window, and About is under Help. The About dialog shows the website https://jade.run and the release repository https://github.com/JadeViewDocs/JadeView.

Capability check

Release packages enable experimental-imgui-menu by default. Custom builds may disable it; check first:

C
uint32_t caps = get_menu_capabilities();

if (caps & JADE_MENU_CAPABILITY_POPUP) {
    /* jade_menu_popup is available */
}
if (caps & JADE_MENU_CAPABILITY_BAR) {
    /* window menu bars are available */
}
MacroValueMeaning
JADE_MENU_CAPABILITY_POPUP1Independent popup menus
JADE_MENU_CAPABILITY_BAR2Window menu bars

When no menu backend is compiled in, the capability query returns 0; menu operations return 0 and set jade_last_error_code() to JADE_PLATFORM_ERROR.

C
typedef struct JadeMenuIconDesc {
    const char* icon_path;
    const uint8_t* icon_data;
    size_t icon_data_size;
    uint32_t icon_codepoint;
} JadeMenuIconDesc;

typedef struct JadeMenuItemDesc {
    const char* id;
    const char* parent_id;
    const char* label;
    const char* accelerator;
    uint32_t kind;
    uint32_t flags;
    JadeMenuIconDesc icon;
} JadeMenuItemDesc;
FieldDescription
idNon-empty ID, unique within the menu. Used by parent_id and returned in events.
parent_idParent item ID. Use NULL or an empty string for a root item.
labelDisplay text in UTF-8. A separator may use NULL.
acceleratorShortcut hint such as "Ctrl+O". Display only; it does not register a hotkey.
kind0 command, 1 submenu, 2 separator, 3 checkbox, 4 radio.
flagsBit 0 disables the item; bit 1 marks a checkbox or radio item as checked.
iconOptional JadeMenuIconDesc; all-zero means no icon.

Rules:

  • A submenu's id is the parent_id of its children. Parents must have kind=1.
  • A menu supports at most 512 items and three submenu levels.
  • Every item except a separator needs a non-empty label.

The icon field at the end of JadeMenuItemDesc describes the icon directly.

FieldDescription
icon_pathUTF-8 path to a PNG/ICO file. Used when icon_data is NULL and icon_codepoint is 0.
icon_dataPNG/ICO bytes. Copied during the call; release it after the call returns.
icon_data_sizeByte length of icon_data; must be greater than 0 when set, up to 8 MiB.
icon_codepointSegoe Fluent Icons Unicode codepoint; see the icon list. Nonzero takes precedence over image data.

Priority is icon_codepoint > icon_data > icon_path. Leave all three empty for no icon.

C
JadeMenuItemDesc items[] = {
    { "file",  NULL,   "File", NULL,    1, 0, { 0 } },
    { "open",  "file", "Open", "Ctrl+O", 0, 0,
      { NULL, open_png, sizeof(open_png), 0 } },
    { "print", "file", "Print", "Ctrl+P", 0, 0,
      { NULL, NULL, 0, 0xE749 } },
    { "quit",  "file", "Quit", NULL,    0, 0,
      { "C:/icons/quit.ico", NULL, 0, 0 } },
};

JadeMenuPosition position = { 24, 48 };
jade_menu_popup(window_id, items, 4, &position);

A window menu bar takes the same items array:

C
jade_set_application_menu(items, 4);
jade_window_set_menu(window_id, items, 4);
  • Multi-size ICO files prefer the largest frame up to 64px (64 → 48 → 32 → 16); PNG/ICO are downscaled with a high-quality filter and mipmaps to avoid aliasing in the 16 DIP menu slot.
  • Windows uses system Segoe Fluent Icons and falls back to Segoe MDL2 Assets on Windows 10. Linux has neither by default; set JADEVIEW_MENU_ICON_FONT to a compatible font.
  • Invalid icons, data above 8 MiB, or undecodable images make the menu call return 0 with JADE_INVALID_ARGUMENT.

Capabilities:

C
uint32_t caps = get_menu_capabilities();
if (caps & JADE_MENU_CAPABILITY_ICON_FILE) { /* PNG/ICO */ }
if (caps & JADE_MENU_CAPABILITY_ICON_GLYPH) { /* Segoe glyph */ }
if (caps & JADE_MENU_CAPABILITY_ICON_DATA) { /* in-memory PNG/ICO */ }

The Python SDK still sets icon_path / icon_data / icon_codepoint inside each template item:

Python
from pathlib import Path
from jadeview_next import Menu

menu = Menu.build_from_template(runtime, [
    {"id": "print", "label": "Print", "icon_codepoint": 0xE749},
    {"id": "open", "label": "Open", "icon_path": "C:/icons/open.png"},
    {"id": "save", "label": "Save", "icon_data": Path("save.ico").read_bytes()},
])
C
int32_t jade_menu_popup(uint32_t window_id, const JadeMenuItemDesc* items,
                        uint32_t item_count, const JadeMenuPosition* position);
  • window_id is the owner window, or 0 for an ownerless popup.
  • position is JadeMenuPosition { int32_t x, y; }. It may be NULL to use the current pointer. With a window, x/y are logical pixels in the client area. Without a window, Windows uses physical screen coordinates and Linux X11 uses desktop coordinates.
  • Wayland needs a window anchor for popups; pass a valid window_id.
  • Returns 1 when the request is queued and 0 when it is rejected. Inspect jade_last_error_code() / jade_last_error_message() on failure; release the latter with jade_text_free.

Selecting a custom item emits menu-command with {"item_id":"..."}. Register the callback once at startup:

C
#include <string.h>
#include "JadeView.h"

static const char* JADEVIEW_CALL on_menu_command(uint32_t source_id, const char* data) {
    (void)source_id; /* owner Window ID; 0 for an ownerless popup */

    /* data looks like {"item_id":"quit"}; use a JSON parser in real code */
    if (strstr(data, "\"quit\"")) {
        /* quit */
    }
    return NULL;
}

void register_menu_events(void) {
    jade_on("menu-command", on_menu_command); /* call once at startup */
}

void show_edit_menu(uint32_t window_id) {
    JadeMenuItemDesc items[] = {
        { "open",     NULL,     "Open...",  "Ctrl+O", 0, 0 },
        { "recent",   NULL,     "Recent",   NULL,     1, 0 },
        { "recent-a", "recent", "a.txt",    NULL,     0, 0 },
        { "sep-1",    NULL,     NULL,       NULL,     2, 0 },
        { "wrap",     NULL,     "Wrap",     NULL,     3, 2 },
        { "quit",     NULL,     "Quit",     NULL,     0, 0 },
    };
    JadeMenuPosition position = { 24, 48 };

    if (!jade_menu_popup(window_id, items, 6, &position)) {
        /* rejected; see jade_last_error_code()/jade_last_error_message() */
    }
}

Window menu bars

C
int32_t jade_set_application_menu(const JadeMenuItemDesc* items, uint32_t item_count);
int32_t jade_window_set_menu(uint32_t window_id, const JadeMenuItemDesc* items,
                             uint32_t item_count);

Priority, highest first:

CallScope
jade_window_set_menuThe specified window only.
jade_set_application_menuEvery normal window without its own menu.
No custom menuThe built-in default menu on normal windows.
  • Every root item of a menu bar must be a submenu (kind=1).
  • item_count=0 hides the bar. jade_window_set_menu hides it for one window; jade_set_application_menu hides the default for all normal windows.
  • Built-in default items perform their native action directly and do not emit menu-command. Once a custom menu is installed, selections are delivered through menu-command.
  • The bar hides automatically in fullscreen. Borderless windows do not receive the default or application bar automatically; set one with jade_window_set_menu if needed.
C
void set_main_menu(void) {
    JadeMenuItemDesc bar[] = {
        { "file",      NULL,   "File",      NULL,     1, 0 },
        { "file-new",  "file", "New",       "Ctrl+N", 0, 0 },
        { "file-quit", "file", "Quit",      NULL,     0, 0 },
        { "view",      NULL,   "View",      NULL,     1, 0 },
        { "view-wrap", "view", "Word wrap", NULL,     3, 2 },
    };

    if (!jade_set_application_menu(bar, 5)) {
        /* failed */
    }
}

Events

EventFires whenPayload
menu-commandA custom menu item is selected{"item_id":"..."}
menu-errorAn accepted popup cannot be shown{"message":"..."}

The source ID is the owner Window ID, or 0 for an ownerless popup. menu-error reports asynchronous presentation failures; invalid arguments fail immediately with 0. See Event Types for registration.

Custom context menus

On Windows and Linux, the browser's default page context actions are drawn by JadeView; WebView settings still control whether the menu may open. For per-element control, see Window Interaction.

To customize it, listen for the DOM contextmenu event, call preventDefault(), and ask the host through IPC to call jade_menu_popup. Pass NULL to use the pointer, and handle selections through menu-command.