Containers

The boost layer ships a family of containers — block-arg wrappers around ImGui’s Begin*/End* pairs that share three properties:

  • Block-arg shape — the body runs once per frame inside the begin/end pair. No manual End() to forget.

  • Path push — leaf widgets inside the block register under <container>/<leaf>. Every container contributes a path segment, just like window and with_id did in earlier tutorials.

  • Open-state via pending flags — state.pending_open = true queues the container to open next frame; pending_close = true closes it. Live commands imgui_open / imgui_close mutate the same flag, so app code, external drivers, and the chrome’s close-button share one channel.

This tutorial covers four representative containers: menu_bar + menu + menu_item, tab_bar + tab_item, popup, and item_tooltip. The features-side demos (examples/features/containers_*.das) cover the rest: child / group (window family), tree_node / collapsing_header (layout family), popup_modal / tooltip / combo_select / list_box (overlay family).

Source: examples/tutorial/containers.das.

Walkthrough

The recording drives all four containers with real synthetic input and self-verifies each step. It flips the General tab’s WIRE checkbox, then clicks the Audio tab header and asserts the switch by its effect: AUDIO_TAB’s MUTE starts rendering while GENERAL_TAB’s WIRE stops — a direct proof that only the open tab’s body runs. It opens the popup from the button’s pending_open flag (asserting the popup body appears), toggles the VSync checkbox inside it, closes it with the popup’s own Close button (asserting the body stops), and finally hovers the button to bring up the item_tooltip. Any step that failed to land aborts the recording.

  1options gen2
  2
  3require imgui
  4require imgui_app
  5require opengl/opengl_boost
  6require live/glfw_live
  7require live/live_api
  8require live/live_commands
  9require live/live_vars
 10require live_host
 11require imgui/imgui_live
 12require imgui/imgui_boost_runtime
 13require imgui/imgui_boost_v2
 14require imgui/imgui_widgets_builtin
 15require imgui/imgui_containers_builtin
 16require imgui/imgui_visual_aids
 17
 18// =============================================================================
 19// TUTORIAL: containers — tab_bar, menu_bar, popup, item_tooltip.
 20//
 21// Containers wrap an ImGui begin/end pair around a daslang block. They
 22// share three properties:
 23//
 24//   1. Block-arg shape: the body runs once per frame inside the begin/end.
 25//   2. Path push: leaf widgets register under "<container>/<leaf>" — every
 26//      container contributes a segment to the registry path, just like
 27//      `window` and `with_id` did in earlier tutorials.
 28//   3. Open-state via pending flags: `(state).pending_open = true` queues
 29//      the container to open next frame; `pending_close = true` reverses
 30//      it. The same flag is what `imgui_open` / `imgui_close` mutate from
 31//      outside, so all three control surfaces (app code, live commands,
 32//      and the close-button on the chrome) share one channel.
 33//
 34// STANDALONE: daslang.exe modules/dasImgui/examples/tutorial/containers.das
 35// LIVE:       daslang-live modules/dasImgui/examples/tutorial/containers.das
 36//
 37// DRIVE (when running live):
 38//   curl -X POST -d '{"name":"imgui_snapshot"}'                                                            localhost:9090/command
 39//   curl -X POST -d '{"name":"imgui_open","args":{"target":"CONT_WIN/OPTIONS_POPUP"}}'                     localhost:9090/command
 40//   curl -X POST -d '{"name":"imgui_close","args":{"target":"CONT_WIN/OPTIONS_POPUP"}}'                    localhost:9090/command
 41// =============================================================================
 42
 43[export]
 44def init() {
 45    live_create_window("dasImgui containers tutorial", 760, 560)
 46    live_imgui_init(live_window)
 47    let io & = unsafe(GetIO())
 48    GetStyle().FontScaleMain = 1.5
 49}
 50
 51[export]
 52def update() {
 53    if (!live_begin_frame()) return
 54    begin_frame()
 55
 56    ImGui_ImplGlfw_NewFrame()
 57    apply_synth_io_override()
 58    NewFrame()
 59
 60    SetNextWindowPos(ImVec2(30.0f, 30.0f), ImGuiCond.FirstUseEver)
 61    SetNextWindowSize(ImVec2(680.0f, 480.0f), ImGuiCond.FirstUseEver)
 62    window(CONT_WIN, (text = "containers", closable = false,
 63                      flags = ImGuiWindowFlags.MenuBar)) {
 64
 65        // ---- menu_bar (window must have ImGuiWindowFlags.MenuBar) ----
 66        // Each menu_item registers under "CONT_WIN/MAIN_BAR/FILE_MENU/NEW_ITEM".
 67        menu_bar(MAIN_BAR) {
 68            menu(FILE_MENU, (text = "File", enabled = true)) {
 69                menu_item(NEW_ITEM,  (text = "New",  shortcut = "Ctrl+N"))
 70                menu_item(OPEN_ITEM, (text = "Open", shortcut = "Ctrl+O"))
 71            }
 72        }
 73
 74        // ---- tab_bar — three tabs, each its own block ----
 75        // Only the active tab's block runs each frame; inactive tabs don't
 76        // even enter their body, so widgets in inactive tabs aren't in
 77        // the registry that frame.
 78        tab_bar(MAIN_TABS, (text = "MainTabs", flags = ImGuiTabBarFlags.None)) {
 79            tab_item(GENERAL_TAB, (text = "General", closable = false,
 80                                   flags = ImGuiTabItemFlags.None)) {
 81                text("Tabs share a window; only the active tab renders.")
 82                checkbox(WIRE, (text = "Wireframe"))
 83            }
 84            tab_item(AUDIO_TAB, (text = "Audio", closable = false,
 85                                 flags = ImGuiTabItemFlags.None)) {
 86                checkbox(MUTE, (text = "Mute"))
 87                slider_float(VOL, (text = "Volume"))
 88            }
 89            tab_item(INFO_TAB, (text = "Info", closable = false,
 90                                flags = ImGuiTabItemFlags.None)) {
 91                text("containers tutorial")
 92                text("each tab is a block - exclusive render")
 93            }
 94        }
 95
 96        separator(CT_SEP_1)
 97
 98        // ---- popup — opened by a pending flag ----
 99        // The button only flips the flag; the popup itself renders on the
100        // next frame when ImGui sees `pending_open = true` and runs its
101        // OpenPopup() call. The same channel handles imgui_open from
102        // outside (curl example in the DRIVE block).
103        text("Popup - open via pending_open or imgui_open:")
104        if (button(OPEN_POPUP_BTN, (text = "Open options"))) {
105            OPTIONS_POPUP.pending_open = true
106        }
107        popup(OPTIONS_POPUP, (text = "OptionsPopup",
108                              flags = ImGuiWindowFlags.None)) {
109            text("Options")
110            separator(CT_SEP_2)
111            checkbox(OPT_VSYNC, (text = "VSync"))
112            checkbox(OPT_HIDPI, (text = "HiDPI"))
113            if (button(POPUP_CLOSE_BTN, (text = "Close"))) {
114                OPTIONS_POPUP.pending_close = true
115            }
116        }
117
118        separator(CT_SEP_3)
119
120        // ---- item_tooltip — hover-gated overlay ----
121        // BeginItemTooltip auto-checks IsItemHovered() under the hood, so
122        // the block only runs while the previous widget is hovered.
123        text("Tooltip - hover the button below:")
124        button(HOVER_BTN, (text = "Hover me"))
125        item_tooltip(HOVER_TIP) {
126            text("This text appears on hover.")
127            text("Driven by BeginItemTooltip (auto-gated).")
128        }
129    }
130
131    end_of_frame()
132    Render()
133    var w, h : int
134    live_get_framebuffer_size(w, h)
135    glViewport(0, 0, w, h)
136    glClearColor(0.10f, 0.10f, 0.12f, 1.0f)
137    glClear(GL_COLOR_BUFFER_BIT)
138    live_imgui_render()
139
140    live_end_frame()
141}
142
143[export]
144def shutdown() {
145    live_imgui_shutdown()
146    live_destroy_window()
147}
148
149[export]
150def main() {
151    init()
152    while (!exit_requested()) {
153        update()
154    }
155    shutdown()
156}

Requires

One extra module on top of the baseline boost layer:

  • imgui/imgui_containers_builtin — defines every container macro used here. The window/child/group/menu/tab/popup/tooltip surface all lives in this one module.

tab_bar / tab_item

tab_bar holds one or more tab_item blocks; ImGui owns the active-tab selection:

tab_bar(MAIN_TABS, (text = "MainTabs", flags = ImGuiTabBarFlags.None)) {
    tab_item(GENERAL_TAB, (text = "General", closable = false,
                           flags = ImGuiTabItemFlags.None)) {
        Text("Tabs share a window; only the active tab renders.")
        checkbox(WIRE, (text = "Wireframe"))
    }
    tab_item(AUDIO_TAB, (text = "Audio", ...)) { ... }
    tab_item(INFO_TAB,  (text = "Info",  ...)) { ... }
}

Only the active tab’s block runs each frame — widgets inside inactive tabs aren’t in the registry that frame, so a snapshot taken while GENERAL_TAB is active won’t list any AUDIO_TAB children. TabItemState.pending_open controls the closable-tab visibility (skip BeginTabItem entirely when open=false), but it does NOT programmatically select the active tab — that’s an ImGui internal state, set by clicking the tab header. Each tab_item registers its header’s bbox, so a driver switches tabs the way a user does: an imgui_click on the tab_item target (e.g. CONT_WIN/MAIN_TABS/AUDIO_TAB) lands on the header and selects it.

item_tooltip — hover-gated overlay

ImGui’s BeginItemTooltip checks IsItemHovered() internally, so the block only runs while the immediately-preceding widget is hovered. No manual gate:

button(HOVER_BTN, (text = "Hover me"))
item_tooltip(HOVER_TIP) {
    Text("This text appears on hover.")
    Text("Driven by BeginItemTooltip (auto-gated).")
}

For tooltips whose own gating logic differs from “previous item hovered” — say, tooltips on an entire window or a custom hover state — use the lower-level tooltip(...) container and gate it manually (see examples/features/containers_overlay.das).

Standalone vs live

Same convention as previous tutorials.

Driving from outside

Path-qualified targets for every container leaf:

curl -X POST -d '{"name":"imgui_snapshot"}' localhost:9090/command
# Registers: CONT_WIN/MAIN_BAR/FILE_MENU/NEW_ITEM, CONT_WIN/MAIN_TABS/GENERAL_TAB/WIRE, ...

curl -X POST -d '{"name":"imgui_open","args":{"target":"CONT_WIN/OPTIONS_POPUP"}}' \
     localhost:9090/command
curl -X POST -d '{"name":"imgui_close","args":{"target":"CONT_WIN/OPTIONS_POPUP"}}' \
     localhost:9090/command

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

Note that menu items receive imgui_click directly — they’re click targets, not open/close targets.

Context popups

popup_context_item is the right-click-context sibling of popup — ImGui drives open/close internally based on the previous item receiving a right-click; the wrapper just gates the body on Begin returning true:

require imgui/imgui_containers_builtin

button(TARGET_BTN, (text = "Right-click me"))
popup_context_item(TARGET_CTX, (str_id = "target_ctx",
                                flags = ImGuiPopupFlags.MouseButtonRight)) {
    if (menu_item(ACTION_RENAME, (text = "Rename", shortcut = "F2"))) {
        // ...
    }
    if (menu_item(ACTION_DELETE, (text = "Delete", shortcut = "Del"))) {
        // ...
    }
}

The popup is keyed off the previously submitted item — submission order matters, and popup_context_item registers under its own path in the snapshot. Use imgui_click to drive menu items from outside.

Feature demo: examples/features/popup_context_item.das.

Next steps

So far every tutorial has assumed the standard standalone/live run. Next up is live-reload itself — the daslang-live workflow, how [live_command] / [before_reload] / [after_reload] plumb in, and what survives a reload (state structs, ImGui context, the HTTP server) versus what gets rebuilt.

See also

Full source: examples/tutorial/containers.das

Richer references:

  • examples/features/containers_window.das — window / child / group with closable second window

  • examples/features/containers_layout.das — tab_bar plus tree_node, collapsing_header

  • examples/features/containers_overlay.das — popup_modal, tooltip, combo_select, list_box

Previous tutorial: State & telemetry

Boost macros — the macro layer.