Docking

ImGui’s native docking lets the user grab a window’s tab and drop it into a side pane, the bottom pane, or even pop it out to a free-floating window — all preserved across runs through imgui.ini. The dasImgui boost layer wraps the C++ surface in two macros: dockspace (the full-viewport dockable region) and dock_window (each dockable panel inside it). A small DockBuilder helper seeds a 3-pane initial layout so first-run users see something meaningful before they start dragging tabs around.

Source: examples/tutorial/docking.das.

Walkthrough

options gen2

require imgui
require imgui_app
require glfw/glfw_boost
require opengl/opengl_boost
require live/glfw_live
require live/live_api
require live/live_commands
require live/live_vars
require live/opengl_live
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_docking_builtin
require imgui/imgui_visual_aids

// =============================================================================
// TUTORIAL: docking — full-viewport dockspace + draggable Begin/End windows.
//
// Three things compose to make dockable UI:
//   1. `io.ConfigFlags |= ImGuiConfigFlags.DockingEnable` in `init()` — turns
//      on ImGui's docking machinery for the whole session.
//   2. `dockspace(DOCK_ROOT, (flags=...))` in the frame loop — wraps
//      DockSpaceOverViewport so the whole window becomes a dock target, and
//      captures the returned `state.dock_id` for the layout helper to use.
//   3. `dock_window(NAME, (text=..., closable=..., flags=...))` per panel —
//      Begin/End-wrapped windows that ImGui dynamically docks/undocks based
//      on the user dragging their tab.
//
// The DockBuilder helper (`setup_default_layout`) seeds a 3-pane layout on
// the first frame so the user sees an arranged UI without having to drag
// tabs manually. After the first run, dock state persists via ImGui's
// `imgui.ini` — drag a tab anywhere and the layout sticks.
//
// STANDALONE: daslang.exe modules/dasImgui/examples/tutorial/docking.das
// LIVE:       daslang-live modules/dasImgui/examples/tutorial/docking.das
//
// DRIVE (when running live):
//   curl -X POST -d '{"name":"imgui_undock","args":{"target":"DOCK_ROOT/OUTPUT"}}'    localhost:9090/command
//   curl -X POST -d '{"name":"imgui_set_window_pos","args":{"target":"DOCK_ROOT/OUTPUT","value":{"x":580,"y":220,"w":360,"h":220}}}' localhost:9090/command
//   curl -X POST -d '{"name":"imgui_dock_reset","args":{"target":"DOCK_ROOT"}}'        localhost:9090/command
//   curl -X POST -d '{"name":"imgui_close","args":{"target":"DOCK_ROOT/OUTPUT"}}'      localhost:9090/command
//
// Note: dockspace is a [container] that pushes its identifier onto the registry
// path, so dock_window targets are path-qualified (``DOCK_ROOT/<name>``).
// =============================================================================

def setup_default_layout(dock_id : uint) {
    //! Seed a 3-pane layout on the first frame:
    //!     +-----------+--------------------+
    //!     |           |                    |
    //!     |           |       Source       |
    //!     | Explorer  |                    |
    //!     |           +--------------------+
    //!     |           |                    |
    //!     |           |       Output       |
    //!     +-----------+--------------------+
    //! Each pane's window-title string MUST match the corresponding
    //! `dock_window`'s `text=` field; that's how ImGui ties dockable windows
    //! to dock nodes.
    DockBuilderRemoveNode(dock_id)
    DockBuilderAddDockSpaceNode(dock_id, ImGuiDockNodeFlags.None)
    let vp = GetMainViewport()
    DockBuilderSetNodeSize(dock_id, ImVec2(vp.Size.x, vp.Size.y))
    var left_id : uint = 0u
    var right_id : uint = 0u
    DockBuilderSplitNode(dock_id, ImGuiDir.Left, 0.25f, left_id, right_id)
    var top_id : uint = 0u
    var bottom_id : uint = 0u
    DockBuilderSplitNode(right_id, ImGuiDir.Up, 0.6f, top_id, bottom_id)
    DockBuilderDockWindow("Explorer", left_id)
    DockBuilderDockWindow("Source",   top_id)
    DockBuilderDockWindow("Output",   bottom_id)
    DockBuilderFinish(dock_id)
}

[export]
def init() {
    live_create_window("dasImgui docking tutorial", 1024, 720)
    live_imgui_init(live_window)
    var io & = unsafe(GetIO())
    io.FontGlobalScale = 1.5
    // The single flag that turns docking on for the whole session. Without
    // this, DockSpace() / DockSpaceOverViewport() render nothing.
    io.ConfigFlags |= ImGuiConfigFlags.DockingEnable
}

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

    ImGui_ImplOpenGL3_NewFrame()
    ImGui_ImplGlfw_NewFrame()
    apply_synth_io_override()
    NewFrame()

    // Full-viewport dockspace. PassthruCentralNode lets the OS-window
    // background show through the unsplit center (irrelevant here — we
    // split everything — but it's the conventional default).
    dockspace(DOCK_ROOT, (flags = ImGuiDockNodeFlags.PassthruCentralNode)) {
        // Seed the layout once per session. has_initial_layout flips false on
        // imgui_dock_reset; the renderer then re-runs setup. dock_id is
        // captured by the dockspace wrapper before this block runs.
        if (!DOCK_ROOT.has_initial_layout && DOCK_ROOT.dock_id != 0u) {
            setup_default_layout(DOCK_ROOT.dock_id)
            DOCK_ROOT.has_initial_layout = true
        }
        dock_window(EXPLORER, (text = "Explorer", closable = false,
                               flags = ImGuiWindowFlags.None)) {
            text("Files")
            button(REFRESH_BTN, (text = "Refresh"))
        }
        dock_window(SOURCE, (text = "Source", closable = false,
                             flags = ImGuiWindowFlags.None)) {
            text("// drag tabs to rearrange")
            text("// — layout sticks via imgui.ini")
            button(SAVE_BTN, (text = "Save"))
        }
        dock_window(OUTPUT, (text = "Output", closable = true,
                             flags = ImGuiWindowFlags.None)) {
            text("> ready.")
            button(CLEAR_BTN, (text = "Clear"))
        }
    }

    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)
    ImGui_ImplOpenGL3_RenderDrawData(GetDrawData())

    live_end_frame()
}

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

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

Requires

Same backend + boost layer as Layout, but layout helpers are replaced by the docking module:

imgui/imgui_docking_builtin — the dockspace and dock_window macros, plus the DockBuilder* bindings cherry-picked from ImGui’s internal API.

The flag that lights it up

ImGui docking is gated by a single io flag. Without it, DockSpace calls render nothing and dock_window panels behave like ordinary windows:

io.ConfigFlags |= ImGuiConfigFlags.DockingEnable

This goes in init() once per session.

Seeding the layout

ImGui will happily start with every dockable window stacked in a single tab-bar — the user is expected to drag tabs into place. For a tutorial we ship a default arrangement via DockBuilder:

DockBuilderRemoveNode(dock_id)                          // clear any prior state
DockBuilderAddDockSpaceNode(dock_id, flags)             // fresh dockspace root
DockBuilderSetNodeSize(dock_id, ImVec2(vp.Size.x, vp.Size.y))
var left_id, right_id : uint
DockBuilderSplitNode(dock_id, ImGuiDir.Left, 0.25f, left_id, right_id)
var top_id, bottom_id : uint
DockBuilderSplitNode(right_id, ImGuiDir.Up, 0.6f, top_id, bottom_id)
DockBuilderDockWindow("Explorer", left_id)
DockBuilderDockWindow("Source",   top_id)
DockBuilderDockWindow("Output",   bottom_id)
DockBuilderFinish(dock_id)

DockBuilderDockWindow matches by window title string — the same string you pass to dock_window(NAME, (text = "Explorer")). The boost macro doesn’t auto-derive the title from the identifier so the binding is explicit.

The setup is gated on state.has_initial_layout so it runs once per session — or after imgui_dock_reset flips the flag back to false.

The frame loop

The dockspace(DOCK_ROOT, ...) macro wraps DockSpaceOverViewport — the dock region is the entire OS window. Inside its block, each dock_window(NAME, ...) is a Begin/End-wrapped panel that participates in the docking system. Path-prefixing works the same as containers (window / child / tab_bar): dock_window(EXPLORER) { button(REFRESH_BTN, ...) } registers the button under DOCK_ROOT/EXPLORER/REFRESH_BTN.

The closable = true option (on OUTPUT here) wires the X-button in the tab to state.open — closing the panel without rebuilding the layout.

Standalone vs live

Same as previous tutorials — main() runs the loop standalone; daslang-live invokes init / update / shutdown directly. ImGui’s docking state is preserved across reloads because the ImGui context survives reload (imgui_live serializes the context pointer through the reload, and the dock state lives inside that context).

Driving from outside

Four live commands cover the docking surface. Targets are path-qualified — the dockspace pushes its name onto the path, so panel targets are DOCK_ROOT/<name>:

# Pop Output out into a floating window
curl -X POST -d '{"name":"imgui_undock","args":{"target":"DOCK_ROOT/OUTPUT"}}' \
     localhost:9090/command

# Reposition the floating window (also works on docked windows — ImGui ignores
# the SetNextWindowPos while a window is docked, so this is most useful after
# imgui_undock). w/h are optional.
curl -X POST -d '{"name":"imgui_set_window_pos","args":{"target":"DOCK_ROOT/OUTPUT","value":{"x":580,"y":220,"w":360,"h":220}}}' \
     localhost:9090/command

# Reset the dockspace back to the default layout
curl -X POST -d '{"name":"imgui_dock_reset","args":{"target":"DOCK_ROOT"}}' \
     localhost:9090/command

# Close the OUTPUT panel (X-button equivalent — closable=true required)
curl -X POST -d '{"name":"imgui_close","args":{"target":"DOCK_ROOT/OUTPUT"}}' \
     localhost:9090/command

imgui_dock is the inverse of imgui_undock — it takes a value of type uint (a dock-node id from a prior DockBuilder* call) and re-docks the panel into that node. imgui_set_window_pos is the companion you’ll usually pair with imgui_undock, since a freshly undocked window picks its position from imgui.ini (or (0,0) if the window has never floated).

Next steps

Style scopes are next — with_style for pushing colors and metrics across a sub-tree of widgets, balanced pop, and how nesting stacks.