Wrapping tab bar

ImGui’s native tab_bar keeps its headers on one row: when they overflow the width it shrinks and ellipsizes the labels, or scrolls them behind arrows. It never wraps. wrap_tab_bar / wrap_tab_item are the container that does — the header strip flows onto as many rows as the width needs, and only the active tab’s body is drawn.

wrap_tab_bar(WTB_BAR) {
    wrap_tab_item("physics") { text("...") }
    wrap_tab_item("camera")  { text("...") }
    // ... as many as you like; they wrap across rows
}

Three things make it tick:

The active tab is an INDEX (like combo), carried in the container’s value payload. imgui_force_set {"value":N} selects tab N programmatically; a real click on a header selects it interactively (see below).
Only the active tab’s body renders. Each wrap_tab_item invokes its block only while its index is active — an inactive tab’s leaves aren’t submitted to ImGui, so a snapshot shows them rendered:false.
The strip is laid out a frame behind. The body renders after the whole header strip, so the strip uses the labels collected on the previous frame. A changed label set appears one frame late (never visible for a stable list). Keep tab declaration order stable.

Source: examples/tutorial/wrap_tab_bar.das.

Walkthrough

options gen2

require imgui/imgui_harness

// =============================================================================
// TUTORIAL: wrap_tab_bar / wrap_tab_item — a multi-row, WRAPPING tab bar.
//
//   wrap_tab_bar(WTB_BAR) {
//       wrap_tab_item("physics") { <body> }
//       wrap_tab_item("camera")  { <body> }
//       ...
//   }
//
// ImGui's native `tab_bar` shrinks/ellipsizes or scrolls its headers when they
// overflow the width; `wrap_tab_bar` instead wraps them onto as many rows as
// needed and shows only the active tab's body. The active tab is an INDEX
// (like `combo`) — `imgui_force_set {"value":N}` selects tab N. Because the
// body renders after the whole header strip, the strip is laid out from the
// labels seen on the PREVIOUS frame: a changed label set appears one frame late
// (never visible for a stable list). Keep tab declaration order stable.
//
// The narrow window below forces the headers to wrap across rows.
//
// STANDALONE: daslang.exe modules/dasImgui/examples/tutorial/wrap_tab_bar.das
// LIVE:       daslang-live modules/dasImgui/examples/tutorial/wrap_tab_bar.das
//
// DRIVE (when running live) — select the "lava" tab (index 2):
//   curl -X POST -d '{"name":"imgui_force_set","args":{"target":"WTB_WIN/WTB_BAR","value":2}}' \
//        localhost:9090/command
// =============================================================================

[export]
def init() {
    harness_init("wrap_tab_bar tutorial", 380, 520)
}

[export]
def update() {
    if (!harness_begin_frame()) {
        return
    }
    harness_new_frame()

    // deliberately narrow so the eight headers wrap onto multiple rows
    SetNextWindowSize(ImVec2(340.0f, 480.0f), ImGuiCond.FirstUseEver)
    window(WTB_WIN, (text = "wrap_tab_bar tutorial", closable = false, flags = ImGuiWindowFlags.None)) {
        text(WTB_LEAD, (text = "Eight categories in a narrow panel - the native"))
        text(WTB_LEAD2, (text = "TabBar would ellipsize/scroll; wrap_tab_bar flows them."))
        separator()

        wrap_tab_bar(WTB_BAR) {
            wrap_tab_item("physics") {
                text(WTB_B0, (text = "physics - gravity, restitution, drag"))
            }
            wrap_tab_item("camera") {
                text(WTB_B1, (text = "camera - zoom, follow, lookahead"))
            }
            wrap_tab_item("lava") {
                text(WTB_B2, (text = "lava - speed, scale, warp, crust"))
            }
            wrap_tab_item("cinders") {
                text(WTB_B3, (text = "cinders - brightness, density, rise"))
            }
            wrap_tab_item("audio") {
                text(WTB_B4, (text = "audio - master gain, music, sfx"))
            }
            wrap_tab_item("lighting") {
                text(WTB_B5, (text = "lighting - ambient, noise, scale"))
            }
            wrap_tab_item("grid") {
                text(WTB_B6, (text = "grid - size, angle, snap step"))
            }
            wrap_tab_item("misc") {
                text(WTB_B7, (text = "misc - everything else"))
            }
        }
    }

    harness_end_frame()
}

[export]
def shutdown() {
    harness_shutdown()
}

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

Requires

imgui/imgui_harness — the tutorial uses the harness_* lifecycle. wrap_tab_bar / wrap_tab_item live in imgui/imgui_containers_builtin (pulled in by the harness).

Selecting a tab by name

Each header is a real button, and the strip registers it as a clickable alias under the bar’s path — WTB_WIN/WTB_BAR/<label> — so a driver, test, or recording can select a tab with a real synthetic click, by name, exactly like a user clicking the header:

curl -X POST -d '{"name":"imgui_click","args":{"target":"WTB_WIN/WTB_BAR/lava"}}' \
     localhost:9090/command

The click drives ImGui’s own input path into the header button, which sets the active index — no different from a mouse click. This is the do-what-it-teaches form the tutorial recording uses (clicking lava, then grid on the second row, then back to physics), and each switch is verified by the selected tab’s body appearing. The index is also settable directly with imgui_force_set {"value":N} when you want to drive it without a gesture.

Why an index, not ImGui’s tab state

Native tab_bar lets ImGui own selection internally; the boost wrapper only observes it. wrap_tab_bar is drawn from primitives (a wrapped strip of buttons), so it owns its own active index as plain state — which is why it can expose value for snapshot + imgui_force_set, and why each header can be a named click target. The trade is that it is not ImGui’s native tab visual; it is the right tool when you have more tab categories than fit one row.

Standalone vs live

Same convention as the other tutorials.