8.18.1.8. Layout primitives

ImGui’s layout cursor advances after every widget — each button, text, or other rail bumps the cursor to the next line by default. Four boost rails move the cursor without rendering anything visible:

same_line(IDENT) — keep the next widget on the current row (wraps ImGui::SameLine).
spacing(IDENT) — insert one line of vertical gap.
new_line(IDENT) — advance one full text-line of vertical space.
dummy((size = float2(x, y))) — reserve arbitrary cursor space without rendering.

All four accept the [widget]-style optional IDENT; the tutorial shows IDENTs on same_line / spacing / new_line (useful when playwright tests assert their snapshot entries) and the anonymous dummy form (cursor reservation that no test targets).

All four share EmptyMarkerState — the payload is {}, but the snapshot still records that the marker fired, so playwright tests can assert "spacing#3 was rendered between button A and button B".

if (button(BTN_A, (text = "A"))) { /* ... */ }
same_line(SL_AB)
if (button(BTN_B, (text = "B"))) { /* ... */ }
same_line(SL_BC)
if (button(BTN_C, (text = "C"))) { /* ... */ }

spacing(SP_TOP)
new_line(NL_INSERT)
dummy((size = float2(0.0f, 40.0f)))

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

8.18.1.8.1. Walkthrough

The markers render nothing, so the recording’s self-check is that each named marker fired: it narrates the same_line row while asserting the three buttons and both same_line markers are on screen, then the spacing and new_line markers in turn (record_check_rendered on each). A marker that silently dropped out of the layout would abort the recording.

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_visual_aids

// =============================================================================
// TUTORIAL: layout_primitives — boost v2 cursor-positioning widgets.
//
// Layout markers move the imgui cursor without rendering anything. They share
// EmptyMarkerState — payload is `{}`, but the snapshot still records the
// widget existed, so playwright can assert "spacing#3 was rendered".
//
// Covers: same_line / new_line / spacing / dummy
//
// STANDALONE: daslang.exe modules/dasImgui/examples/tutorial/layout_primitives.das
// LIVE:       daslang-live modules/dasImgui/examples/tutorial/layout_primitives.das
// =============================================================================

[export]
def init() {
    live_create_window("dasImgui layout primitives", 1000, 640)
    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()

    SetNextWindowPos(ImVec2(60.0, 60.0), ImGuiCond.Always)
    SetNextWindowSize(ImVec2(600.0, 360.0), ImGuiCond.Always)
    window(LAYOUT_WIN, (text = "Layout primitives", closable = false,
                        flags = ImGuiWindowFlags.None)) {
        text("Three buttons on one row - same_line() keeps them inline.")
        if (button(BTN_A, (text = "A"))) {
            print("A\n")
        }
        same_line(SL_AB)
        if (button(BTN_B, (text = "B"))) {
            print("B\n")
        }
        same_line(SL_BC)
        if (button(BTN_C, (text = "C"))) {
            print("C\n")
        }

        spacing(SP_TOP)
        text("spacing() inserts a small vertical gap (1 line).")

        spacing(SP_MID)
        spacing(SP_MID2)
        spacing(SP_MID3)
        text("Three spacing() calls stack; cheap if you don't want a Dummy.")

        new_line(NL_INSERT)
        text("new_line() == one full text-line of vertical space.")

        dummy((size = float2(0.0f, 40.0f)))
        text("dummy(size) reserves arbitrary cursor space.")
    }

    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.8.1.1. Requires

Baseline boost layer (imgui/imgui_boost_v2 re-exports imgui/imgui_layout_builtin). No extra modules.

8.18.1.8.1.2. When to reach for each

same_line is the workhorse — every multi-column row, every label-then-input pattern uses it. Pass an explicit offset if the next widget needs a column-aligned position; default packs against the previous item.

spacing is a minimal 1-line gap — cheaper to read than dummy when you just want breathing room between sections. Stack three of them if you want a slightly larger gap without committing to a fixed pixel height.

new_line is conceptually \n at the layout level — one full text line. Useful when the current row had a tall widget and you want the next row to start fresh from the left margin without accumulating Y from the tall content.

dummy(size) reserves an arbitrary rectangle. Pass size = float2(0, 40) for a 40-pixel-tall invisible spacer. The X component can pre-allocate a horizontal slot too — useful for grid-like alignment when widgets vary in width.

8.18.1.8.1.3. Snapshot shape

Each layout marker registers an entry under its ident with kind "empty_marker":

curl -X POST -d '{"name":"imgui_snapshot"}' localhost:9090/command \
    | jq '.globals."LAYOUT_WIN/SL_AB"'

Tests that want to verify “this layout was produced” can walk the snapshot and confirm the markers fired in the expected order — see modules/dasImgui/tests/test_layout_primitives.das for the assertion shape.