8.18.1.11. With id

ImGui hashes a widget’s identifier into the ID stack to detect clicks, remember imgui.ini state, and tag draw-list entries. The boost layer piggybacks on the same hash for its telemetry path. When two render sites need to share a widget identifier — composed helpers, two panes showing the same kind of control, a button rendered under two scopes — the boost ships three knobs for sorting out the collision:

  • with_id("scope") { ... } pushes "scope" onto both ImGui’s ID stack and the boost path, so two scopes contain the same widget identifier without collision.

  • widget(IDENT, (id = "x")) mangles only ImGui’s hash — useful when the daslang identifier may get renamed but the imgui.ini state and any hex_id-driven scripts must stay stable.

  • widget(IDENT, (path = "x")) replaces the registry path leaf — the daslang identifier still names the global; "x" is what external drivers target via imgui_force_set / imgui_click.

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

8.18.1.11.1. Walkthrough

  1options gen2
  2options _comment_hygiene = true
  3
  4require imgui
  5require imgui_app
  6require opengl/opengl_boost
  7require live/glfw_live
  8require live/live_api
  9require live/live_commands
 10require live/live_vars
 11require live_host
 12require imgui/imgui_live
 13require imgui/imgui_boost_runtime
 14require imgui/imgui_boost_v2
 15require imgui/imgui_widgets_builtin
 16require imgui/imgui_containers_builtin
 17require imgui/imgui_id_builtin
 18require imgui/imgui_visual_aids
 19
 20// =============================================================================
 21// TUTORIAL: with_id — scope IDs and registry paths for composed render sites.
 22//
 23// Each widget's ImGui hash is derived from its identifier — the same global
 24// rendered at two sites would hash to the same value and collide. The boost
 25// already enforces "single-global rendered exactly once per frame" at the
 26// registry level (loops want the indexed form `IDENT[i]`), but real apps
 27// still need to compose helpers that surface the same widget kind under
 28// distinct labels. Three knobs cover the cases:
 29//
 30//   with_id("scope") { ... }         — push "scope" onto BOTH the ImGui ID
 31//                                      stack AND the boost path. Distinct
 32//                                      scopes → distinct hex_ids AND distinct
 33//                                      registry paths.
 34//   widget(IDENT, (id = "x"))        — mangle ImGui's hash with "x" only;
 35//                                      telemetry path stays the bare
 36//                                      identifier (script-stable across
 37//                                      label renames; preserves imgui.ini).
 38//   widget(IDENT, (path = "x"))      — replace the telemetry path leaf with
 39//                                      "x"; the bare identifier still names
 40//                                      the daslang global. Mangles BOTH the
 41//                                      path AND the ImGui hash.
 42//
 43// STANDALONE: daslang.exe modules/dasImgui/examples/tutorial/with_id.das
 44// LIVE:       daslang-live modules/dasImgui/examples/tutorial/with_id.das
 45//
 46// DRIVE (when running live):
 47//   curl -X POST -d '{"name":"imgui_snapshot"}'                                                       localhost:9090/command
 48//   curl -X POST -d '{"name":"imgui_click","args":{"target":"ID_WIN/section_a/SAVE_BTN"}}'             localhost:9090/command
 49//   curl -X POST -d '{"name":"imgui_click","args":{"target":"ID_WIN/section_b/SAVE_BTN"}}'             localhost:9090/command
 50//   curl -X POST -d '{"name":"imgui_force_set","args":{"target":"ID_WIN/rps_stable","value":0.7}}'           localhost:9090/command
 51// =============================================================================
 52
 53[export]
 54def init() {
 55    live_create_window("dasImgui with_id tutorial", 720, 520)
 56    live_imgui_init(live_window)
 57    let io & = unsafe(GetIO())
 58    GetStyle().FontScaleMain = 1.5
 59}
 60
 61[export]
 62def update() {
 63    if (!live_begin_frame()) return
 64    begin_frame()
 65
 66    ImGui_ImplGlfw_NewFrame()
 67    apply_synth_io_override()
 68    NewFrame()
 69
 70    SetNextWindowPos(ImVec2(30.0f, 30.0f), ImGuiCond.FirstUseEver)
 71    SetNextWindowSize(ImVec2(640.0f, 440.0f), ImGuiCond.FirstUseEver)
 72    window(ID_WIN, (text = "with_id", closable = false,
 73                    flags = ImGuiWindowFlags.None)) {
 74
 75        // ---- with_id scope: same widget, two render sites ----
 76
 77        // SAVE_BTN is a single-global widget; rendering it twice without with_id
 78        // panics at end-of-frame (registry N>1). Each scope adds a path segment +
 79        // PushID, so ID_WIN/section_a/SAVE_BTN and .../section_b/... stay distinct.
 80        text("Same SAVE_BTN, two scopes:")
 81        with_id("section_a") {
 82            button(SAVE_BTN, (text = "Save in A"))
 83        }
 84        with_id("section_b") {
 85            button(SAVE_BTN, (text = "Save in B"))
 86        }
 87        text("SAVE_BTN.click_count aggregates: {SAVE_BTN.click_count}")
 88
 89        separator(WI_SEP_1)
 90
 91        // ---- Nested chains: outer scope, inner scope, leaf widget ----
 92        // The path is the chain joined by "/": ID_WIN/outer/inner/NESTED_BTN.
 93        text("Nested with_id chains:")
 94        with_id("outer") {
 95            with_id("inner") {
 96                button(NESTED_BTN, (text = "Nested deep"))
 97            }
 98        }
 99
100        separator(WI_SEP_2)
101
102        // ---- id= per-call: stable ImGui hash across label renames ----
103
104        // HASHED_BTN (the daslang identifier) drives visibility + live-reload; the
105        // imgui hash is mangled by "stable_v1", so hex_id-targeting scripts and
106        // imgui.ini state survive a rename. Telemetry path stays ID_WIN/HASHED_BTN.
107        text("Per-call id= - script-stable ImGui hash:")
108        button(HASHED_BTN, (text = "Hashed via id=", id = "stable_v1"))
109
110        separator(WI_SEP_3)
111
112        // ---- path= per-call: stable telemetry path across renames ----
113
114        // RPS_PATH is the daslang global (rename breaks the reference). "rps_stable"
115        // is the registry path leaf — the imgui_force_set / imgui_click string for
116        // external drivers; both the path AND the ImGui hash adopt "rps_stable".
117        text("Per-call path= - script-stable telemetry path:")
118        slider_float(RPS_PATH, (text = "Speed (path=)",
119                                path = "rps_stable"))
120    }
121
122    end_of_frame()
123    Render()
124    var w, h : int
125    live_get_framebuffer_size(w, h)
126    glViewport(0, 0, w, h)
127    glClearColor(0.10f, 0.10f, 0.12f, 1.0f)
128    glClear(GL_COLOR_BUFFER_BIT)
129    live_imgui_render()
130
131    live_end_frame()
132}
133
134[export]
135def shutdown() {
136    live_imgui_shutdown()
137    live_destroy_window()
138}
139
140[export]
141def main() {
142    init()
143    while (!exit_requested()) {
144        update()
145    }
146    shutdown()
147}

8.18.1.11.1.1. Requires

One extra module on top of the baseline boost layer:

  • imgui/imgui_id_builtin — defines with_id(s) { ... } and wires the id= / path= named-arg sugar for every widget macro.

8.18.1.11.1.2. The single-render rule

Single-global widgets render exactly once per frame. Two violations collapse into one runtime panic at end-of-frame:

  • Single-global widget inside a for loop (would render N times) — the boost macro can usually catch this lexically and macro_error at expansion with a fixit pointing at the indexed form IDENT[i] / IDENT[key] (see Widgets tour for the indexed form).

  • Single-global widget called from two distinct sites (e.g. shown in two windows at once) — when the macro can’t see the second site lexically, the runtime registry catches it and panics.

with_id is the explicit ID-stack push for case 2 when the indexed form can’t reach (composed helpers, sub-tree data-driven structure).

8.18.1.11.1.3. with_id scopes

Each with_id("scope") { ... } block pushes "scope" onto two stacks: ImGui’s ID stack (so child widgets get distinct hashes) and the boost registry path (so child entries register under distinct paths). Both pop on block exit:

with_id("section_a") {
    button(SAVE_BTN, (text = "Save in A"))
}
with_id("section_b") {
    button(SAVE_BTN, (text = "Save in B"))
}

The two renders show up in the snapshot as ID_WIN/section_a/SAVE_BTN and ID_WIN/section_b/SAVE_BTN — distinct paths AND distinct ImGui hashes. SAVE_BTN.click_count is one global; clicks on either button increment the same counter. If you need separate counters, switch to SAVE_BTN[key] indexed-widget form instead.

8.18.1.11.1.4. Nested chains

with_id chains nest. Each scope contributes one path segment, and the leaf widget’s registry path is the chain joined by /:

with_id("outer") {
    with_id("inner") {
        button(NESTED_BTN, (text = "Nested deep"))
    }
}
// registry path: ID_WIN/outer/inner/NESTED_BTN

with_id doesn’t register a container entry of its own — only the path segment. The leaf widget’s entry is what shows up in the snapshot.

8.18.1.11.1.5. Per-call id= — stable hash across renames

The daslang identifier is the source-of-truth name for a widget — it defines the global, drives live-reload visibility, and determines how the variable is referenced elsewhere in the program. The ImGui hash and the registry path are conventions built on top.

id="x" decouples the ImGui hash from the identifier:

button(HASHED_BTN, (text = "Hashed via id=", id = "stable_v1"))

Telemetry path is still ID_WIN/HASHED_BTN (the bare identifier); ImGui’s hash is mangled by "stable_v1" via PushID/PopID wrapping the render call. Practical wins:

  • imgui.ini stability — rename HASHED_BTN to SAVE_BUTTON_V2 in source, and imgui.ini’s open/close state for this button still matches the same ImGui hash; users don’t lose their layout.

  • Hex_id-driven scripts — external drivers that target widgets by the hex_id field in the snapshot keep working across daslang identifier renames.

8.18.1.11.1.6. Per-call path= — stable registry path across renames

path="x" is the inverse case — keep the daslang identifier internal, expose a stable string to external drivers:

slider_float(RPS_PATH, (text = "Speed (path=)", path = "rps_stable"))

The registry path becomes ID_WIN/rps_stable (the bare identifier is NOT registered). RPS_PATH is still the daslang global — rename it without breaking script drivers. path= also mangles the ImGui hash since widget_prelude does PushID(widget_ident) and widget_ident is the overridden value.

8.18.1.11.1.7. Standalone vs live

Same convention as previous tutorials: daslang for standalone or daslang-live to keep the live-reload server running.

8.18.1.11.1.8. Driving from outside

The registry paths shown above are exactly what external drivers target:

curl -X POST -d '{"name":"imgui_click","args":{"target":"ID_WIN/section_a/SAVE_BTN"}}' \
     localhost:9090/command
curl -X POST -d '{"name":"imgui_click","args":{"target":"ID_WIN/section_b/SAVE_BTN"}}' \
     localhost:9090/command
curl -X POST -d '{"name":"imgui_force_set","args":{"target":"ID_WIN/rps_stable","value":0.7}}' \
     localhost:9090/command

Note the third targets rps_stable (the path= override), not the RPS_PATH identifier — the override replaces the bare-identifier path entry, so the bare-name target would return “no such widget.”

8.18.1.11.1.9. Next steps

State and telemetry come next — the registered widget state structs that back every boost widget, how dotted flags on the identifier (RPS.PUBLIC.NOTLIVE) tune cross-module visibility and live-reload behavior, and the auto-emit hook that surfaces app-side values to the snapshot.

See also

Full source: modules/dasImgui/examples/tutorial/with_id.das

Richer reference: modules/dasImgui/examples/features/id_override.das — the features-side demo with the same surface plus a same-state shared-button demonstration.

Integration test: modules/dasImgui/tests/test_id_override.das.

Previous tutorial: With style

Boost macros — the macro layer.