8.19.21. Main menu bar

Two related v2 additions live together in this tutorial. The first is main_menu_bar(IDENT) { ... } — the screen-top bar (BeginMainMenuBar / EndMainMenuBar), distinct from menu_bar(IDENT) { ... } which attaches to the current window (BeginMenuBar, requires ImGuiWindowFlags.MenuBar). The second is the menu_item / menu_label split for the leaves under a menu:

• menu_item(IDENT, (text=, shortcut=, enabled=)) — toggleable. ToggleState.value flips on click.

• menu_label(IDENT, (text=, shortcut=, selected=, enabled=)) — static. ClickState.click_count accumulates; selected is a fixed check-mark (not driven by the click).

menu_label is the right rail for section headers (selected=false, enabled=false), permanent-check labels (selected=true), and any “do something, don’t toggle” menu entry.

main_menu_bar(MAIN_BAR) {
    menu(FILE_MENU, (text = "File", enabled = true)) {
        menu_item(MI_DARKMODE, (text = "Dark mode", shortcut = "Ctrl+D"))
        menu_item(MI_AUTOSAVE, (text = "Auto-save", shortcut = ""))
        separator(FILE_SEP)
        menu_label(FILE_HEADER, (text = "(recent files)",
                                 shortcut = "", selected = false,
                                 enabled = false))
        menu_label(FILE_RECENT1, (text = "demo.das"))
        menu_label(FILE_STAR, (text = "Star this project",
                               shortcut = "", selected = true))
    }
}

Source: modules/dasImgui/examples/tutorial/main_menu_bar.das.

8.19.21.1. Walkthrough

options gen2
options _comment_hygiene = true
options gc

require imgui
require imgui_app
require opengl/opengl_boost
require live/glfw_live
require live/live_api
require live/live_commands
require live/live_vars
require live_host
require imgui/imgui_live
require imgui/imgui_boost_runtime
require imgui/imgui_boost_v2
require imgui/imgui_widgets_builtin
require imgui/imgui_containers_builtin
require imgui/imgui_visual_aids

// =============================================================================
// TUTORIAL: main_menu_bar — top-level menu bar + menu_item vs menu_label split.
//
// Two related v2 additions live in this tutorial:
//
// 1. `main_menu_bar(IDENT) { ... }` is the screen-top bar (`BeginMainMenuBar`)
//    — distinct from `menu_bar(IDENT) { ... }` which attaches to the current
//    window (`BeginMenuBar`, requires `ImGuiWindowFlags.MenuBar`).
//
// 2. `menu_item` vs `menu_label`:
//    - menu_item(IDENT, (text=, shortcut=, enabled=)) → toggleable.
//      ToggleState.value mutates on click.
//    - menu_label(IDENT, (text=, shortcut=, selected=, enabled=)) → static.
//      ClickState.click_count accumulates; `selected` is a fixed check-mark.
//
// Use menu_label for section headers (`selected=false, enabled=false`),
// permanent-check labels (`selected=true`), and any "do something, don't
// toggle" menu entry.
//
// STANDALONE: daslang.exe modules/dasImgui/examples/tutorial/main_menu_bar.das
// LIVE:       daslang-live modules/dasImgui/examples/tutorial/main_menu_bar.das
//
// DRIVE (when running live):
//   curl -X POST -d '{"name":"imgui_click","args":{"target":"MAIN_BAR/FILE_MENU/MI_DARKMODE"}}' \
//        localhost:9090/command
// =============================================================================

[export]
def init() {
    live_create_window("dasImgui main_menu_bar tutorial", 800, 480)
    live_imgui_init(live_window)
    let io & = unsafe(GetIO())
    GetStyle().FontScaleMain = 1.4
}

[export]
def update() {
    if (!live_begin_frame()) return
    begin_frame()

    ImGui_ImplGlfw_NewFrame()
    apply_synth_io_override()
    NewFrame()

    // The bar sits at screen top, NOT inside any window().
    main_menu_bar(MAIN_BAR) {
        menu(FILE_MENU, (text = "File", enabled = true)) {
            // Toggleable — clicking flips MI_DARKMODE.value.
            menu_item(MI_DARKMODE, (text = "Dark mode", shortcut = "Ctrl+D"))
            menu_item(MI_AUTOSAVE, (text = "Auto-save", shortcut = ""))
            separator(FILE_SEP)
            // Section header — static, disabled, no check.
            menu_label(FILE_HEADER, (text = "(recent files)",
                                     shortcut = "", selected = false,
                                     enabled = false))
            menu_label(FILE_RECENT1, (text = "demo.das"))
            menu_label(FILE_RECENT2, (text = "tour.das"))
            separator(FILE_SEP2)
            // Permanent check — selected=true makes it always-checked.
            menu_label(FILE_STAR, (text = "Star this project",
                                   shortcut = "", selected = true))
            menu_item(MI_QUIT, (text = "Quit", shortcut = "Ctrl+Q"))
        }
        menu(EDIT_MENU, (text = "Edit", enabled = true)) {
            // menu_label for an action — emits click_count, no toggle.
            menu_label(EDIT_UNDO, (text = "Undo", shortcut = "Ctrl+Z"))
            menu_label(EDIT_REDO, (text = "Redo", shortcut = "Ctrl+Y",
                                   selected = false, enabled = false))
        }
    }

    SetNextWindowPos(ImVec2(60.0, 80.0), ImGuiCond.Always)
    SetNextWindowSize(ImVec2(680.0, 320.0), ImGuiCond.Always)
    window(BODY, (text = "State readout", closable = false,
                  flags = ImGuiWindowFlags.None)) {
        text("Click items in the bar above; the snapshot updates below.")
        separator(BODY_SEP)
        text("MI_DARKMODE.value = {MI_DARKMODE.value}")
        text("MI_AUTOSAVE.value = {MI_AUTOSAVE.value}")
        text("EDIT_UNDO.click_count = {EDIT_UNDO.click_count}")
        text("MI_QUIT.value = {MI_QUIT.value}")
    }

    end_of_frame()
    Render()
    var w, h : int
    live_get_framebuffer_size(w, h)
    glViewport(0, 0, w, h)
    glClearColor(0.10f, 0.10f, 0.12f, 1.0f)
    glClear(GL_COLOR_BUFFER_BIT)
    live_imgui_render()

    live_end_frame()
}

[export]
def shutdown() {
    live_imgui_shutdown()
    live_destroy_window()
}

[export]
def main() {
    init()
    while (!exit_requested()) {
        update()
        maybe_collect_gc()
    }
    shutdown()
}

8.19.21.1.1. Requires

Baseline boost layer, no extra modules — main_menu_bar / menu_bar / menu come from imgui/imgui_containers_builtin, and menu_item / menu_label / separator from imgui/imgui_widgets_builtin.

8.19.21.1.2. main_menu_bar vs menu_bar

The two bar variants pick opposite anchor strategies:

• main_menu_bar(IDENT) { ... } attaches to the viewport — sits at the top of the screen, persists across windows, ImGui draws the chrome. Use it when there’s exactly one bar in the app.

• menu_bar(IDENT) { ... } attaches to the current window — appears inside that window’s titlebar area. The host window must have ImGuiWindowFlags.MenuBar set, or the menu_bar render is a no-op. Use it for per-document menus inside a tabbed editor, the imgui_demo’s own menu bar, or any window-local command surface.

Both expose the same menu() / menu_item / menu_label children; only the anchor differs.

8.19.21.1.3. menu_item vs menu_label

menu_item and menu_label look identical visually (text + optional shortcut + optional check-mark) but back different state structs:

• menu_item carries ToggleState — the value bool flips on every click. Use it for boolean app-state toggles (“Dark mode”, “Auto-save”, “Show hidden files”).

• menu_label carries ClickState — the click_count int accumulates without touching selected. Use it for actions (“Undo”, “Quit”, “About”) and for static labels with a fixed check (selected=true) or no check at all.

Combine selected= and enabled= on menu_label to get section headers (selected=false, enabled=false greys the entry and shows no check) or permanent-check items (selected=true, enabled=true shows the check and stays clickable).

8.19.21.1.4. Driving from outside

The full menu hierarchy is routable once a menu is open:

curl -X POST -d '{"name":"imgui_click","args":{"target":"MAIN_BAR/FILE_MENU/MI_DARKMODE"}}' \
     localhost:9090/command

The bar’s own header (MAIN_BAR) has a degenerate bbox (the chrome has no clickable “header”). The first-level menu() children (MAIN_BAR/FILE_MENU, MAIN_BAR/EDIT_MENU) DO register routable headers. Submenu items only register a bbox while their parent menu is open, so external drivers wanting to click a menu_item have to open the parent first (synth click on the header, wait one frame, then click the child). The walkthrough above does exactly this with real clicks, dropping straight DOWN the open menu’s column onto each item: a diagonal travel to an item that sits off-axis from its header would clip a sibling header, and ImGui hover-switches the open menu mid-travel (the click then lands in the wrong menu). Menu items span the full menu width, so a vertical drop at the header’s center-x always lands on the item.

8.19.21.1.5. Snapshot shape

MI_DARKMODE.value is the live toggle bool; EDIT_UNDO.click_count is the accumulating action counter. Both surface in the snapshot under their qualified path:

curl -X POST -d '{"name":"imgui_snapshot"}' localhost:9090/command \
    | jq '.globals."MAIN_BAR/FILE_MENU/MI_DARKMODE".payload'

The tutorial’s body window prints both per-frame so the state changes are visible alongside the menu interactions.

See also

Full source: modules/dasImgui/examples/tutorial/main_menu_bar.das

Integration tests: modules/dasImgui/tests/test_menu_main.das and modules/dasImgui/tests/test_menu_label_static.das.

Boost macros — the macro layer.