8.18.1.7. Layout

Three boost helpers — dock_left, split_h, split_v — compose into an IDE-style layout on a single panel. Each helper takes a state struct, an init value, optional bounds, and a block per pane; the resulting splits are draggable at runtime and survive live reload.

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

8.18.1.7.1. Walkthrough

The recording drives the layout with real synthetic drags on the splitter handles — no imgui_force_set. It grabs the sidebar’s right edge and pulls it wider (asserting SIDEBAR’s pixel width rose), drags the vertical handle between the Files and Editor panes (left-pane fraction rose), then drags the horizontal handle down so the editor grows and the output shrinks (top fraction rose). Each handle surfaces its own bbox as a <container>/HANDLE alias in the snapshot, so the cursor targets the real 8 px InvisibleButton; a drag that moved nothing aborts the recording at teardown.

options gen2
options _comment_hygiene = true

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_layout_builtin
require imgui/imgui_visual_aids

// =============================================================================
// TUTORIAL: layout — split_h / split_v / dock_left on a single panel.
//
// Three boost layout helpers compose into a classic IDE-style layout:
//   SIDEBAR     : dock_left   — fixed-width left rail with a draggable edge
//   SPLIT_VERT  : split_v     — splits the main area into top + bottom
//   SPLIT_MAIN  : split_h     — splits the top area into left + right
//
// Each helper takes a state struct (registered automatically), an `init`
// value, optional `bounds`, and a block (`${ ... }`) per pane. The state's
// `value` field holds either the split fraction (split_*) or the pane width
// in pixels (dock_*). All three are draggable at runtime.
//
// STANDALONE: daslang.exe modules/dasImgui/examples/tutorial/layout.das
// LIVE:       daslang-live modules/dasImgui/examples/tutorial/layout.das
//
// DRIVE (when running live):
//   curl -X POST -d '{"name":"imgui_force_set","args":{"target":"LAYOUT_WIN/SPLIT_VERT/SPLIT_MAIN","value":0.7}}' localhost:9090/command
//   curl -X POST -d '{"name":"imgui_force_set","args":{"target":"LAYOUT_WIN/SPLIT_VERT","value":0.4}}'           localhost:9090/command
//   curl -X POST -d '{"name":"imgui_force_set","args":{"target":"LAYOUT_WIN/SIDEBAR","value":220.0}}'            localhost:9090/command
//
// Note: the boost ``window(LAYOUT_WIN, ...)`` wrapper pushes the window's
// name as a path prefix on every nested widget, so live targets are
// path-qualified (no bare ``SIDEBAR``).
// =============================================================================

[export]
def init() {
    live_create_window("dasImgui layout tutorial", 1024, 720)
    live_imgui_init(live_window)
    let io & = unsafe(GetIO())
    GetStyle().FontScaleMain = 1.5
}

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

    ImGui_ImplGlfw_NewFrame()
    apply_synth_io_override()
    NewFrame()

    // One window holds the whole layout. dock_left carves out the sidebar;
    // split_v then split_h compose the main pane.
    SetNextWindowPos(ImVec2(60.0f, 60.0f), ImGuiCond.Always)
    SetNextWindowSize(ImVec2(900.0f, 600.0f), ImGuiCond.Always)
    window(LAYOUT_WIN, (text = "IDE layout",
                        closable = false,
                        flags = ImGuiWindowFlags.None)) {

        // Left rail: 200 px by default, draggable between 80 and 320 px.
        dock_left(SIDEBAR, (init = 200.0f, bounds = (80.0f, 320.0f))) {
            text("Sidebar")
            spacing(LO_SP_1)
            button(EXPLORE_BTN, (text = "Explore"))
            button(SEARCH_BTN,  (text = "Search"))
            button(SOURCE_BTN,  (text = "Source"))
        }

        // Main pane: top/bottom (split_v) where top is left/right (split_h).
        split_v(SPLIT_VERT, (init = 0.65f, bounds = (0.1f, 0.9f)),
                ${
                    split_h(SPLIT_MAIN, (init = 0.4f, bounds = (0.1f, 0.9f)),
                            ${
                                text("Files")
                                button(FILE_A_BTN, (text = "main.das"))
                                button(FILE_B_BTN, (text = "lib.das"))
                            },
                            ${
                                text("Editor")
                                text("// drag the splitters -")
                                text("// the pane bounds")
                                text("// stay clipped.")
                            })
                },
                ${
                    text("Output")
                    text("> ready.")
                    button(CLEAR_BTN, (text = "Clear output"))
                })
    }

    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()
    }
    shutdown()
}

8.18.1.7.1.1. Requires

Same backend + boost layer as Widgets tour, with two extra modules pulled in:

imgui/imgui_containers_builtin — the window macro that wraps the layout (boost window is more featureful than raw Begin/End; it provides closable, flags, registered state, and an implicit End at block exit).
imgui/imgui_layout_builtin — the layout helpers themselves (split_h, split_v, dock_left).

8.18.1.7.1.2. Init and shutdown

Identical to Widgets tour. 1024x720 window, font scale 1.5, standard live-reload pair.

8.18.1.7.1.3. The frame loop

Standard dasImgui v2 shape. apply_synth_io_override() between ImGui_ImplGlfw_NewFrame and NewFrame is required again so the driver script can synth drags against the splitters without the real GLFW mouse winning the IO race.

8.18.1.7.1.4. Layout helpers

The panel composes three helpers, nested:

window(LAYOUT_WIN, (text = "IDE layout", ...)) {
    dock_left(SIDEBAR, (init = 200.0f, bounds = (80.0f, 320.0f))) {
        // sidebar contents
    }
    split_v(SPLIT_VERT, (init = 0.65f, bounds = (0.1f, 0.9f)),
        ${ split_h(SPLIT_MAIN, ...) { ... } },
        ${ /* bottom pane */ })
}

dock_left carves a fixed-width column off the left edge. Its state.value is the pane width in pixels — clamped to the bounds tuple at drag time. After dock_left’s block, ImGui’s cursor is on the SameLine to the right of the rail, so subsequent content flows into the remaining area without explicit positioning.

split_v and split_h each take two block arguments rather than one. The ${ ... } literal is a block-with-no-args, and the boost macro takes the helpers’ panes by position. Their state.value is the first pane’s fraction of the available space, clamped to bounds (so init = 0.65f means the top half occupies 65% of the height).

8.18.1.7.1.5. Standalone vs live

Same as Widgets tour — main() runs the loop standalone; daslang-live invokes init / update / shutdown directly.

8.18.1.7.1.6. Driving from outside

Every helper’s state struct is targetable by name. Drag without a mouse:

curl -X POST -d '{"name":"imgui_force_set","args":{"target":"LAYOUT_WIN/SIDEBAR","value":260.0}}' \
     localhost:9090/command
curl -X POST -d '{"name":"imgui_force_set","args":{"target":"LAYOUT_WIN/SPLIT_VERT/SPLIT_MAIN","value":0.6}}' \
     localhost:9090/command

value is the same type the user would set by dragging — pixels for dock_*, fraction for split_*. Targets are path-qualified by the enclosing window/split chain (no bare SIDEBAR).

Each helper also exposes its drag handle’s geometry as a <container>/HANDLE alias in the snapshot, so a driver can perform a real drag instead of setting the fraction directly — LAYOUT_WIN/SIDEBAR/HANDLE and likewise for each split. The drag playwright helper targets it by bbox centre; this is how the recording above drives every split.

8.18.1.7.1.7. Scope wrappers

Three stateless block-arg wrappers in imgui/imgui_scope_builtin cover the leftover Push/Pop idioms ImGui uses for ad-hoc layout overrides. Each brackets the block with the corresponding ImGui Push/Pop pair and takes no state — they read like inline scopes:

require imgui/imgui_scope_builtin

// Indent / Unindent — nest content under a heading.
with_indent(0.0f) {       // 0.0f defers to style IndentSpacing
    Text("Bullet child")
}
with_indent(40.0f) {      // explicit pixel offset
    Text("Hard-indented")
}

// PushItemWidth / PopItemWidth — scope a widget-width override.
with_item_width(120.0f) {
    slider_float(NARROW, (text = "narrow", bounds = (0.0f, 1.0f)))
}
with_item_width(-60.0f) { // negative = right-edge minus N
    slider_float(STRETCH, (text = "stretch", bounds = (0.0f, 1.0f)))
}

// PushTextWrapPos / PopTextWrapPos — scope where long text wraps.
with_text_wrap_pos(0.0f) { TextUnformatted(LIPSUM) }   // window right edge
with_text_wrap_pos(200.0f) { TextUnformatted(LIPSUM) } // wrap at 200 px

Feature demos: modules/dasImgui/examples/features/with_indent.das, modules/dasImgui/examples/features/with_item_width.das, modules/dasImgui/examples/features/with_text_wrap_pos.das.

8.18.1.7.1.8. Next steps

Docking is next — full ImGui dockspaces and the dock helpers that ride on top of them.