8.19.13. State & telemetry

Widget state lives in daslang, not in ImGui. Every boost widget macro emits a module-scope global named by the first argument — typed as ClickState / SliderStateFloat / ToggleState / etc. The global holds the widget’s value plus any pending overrides queued by external drivers. The same global is what the registry serializes for imgui_snapshot, so the daslang side, the test side, and the external-driver side all see the same value.

Three immediate wins fall out of that design:

Auto-emit — no var SAVE_BTN : ClickState declaration to keep in sync with the call site. The macro declares it on first compile.
Read anywhere — SAVE_BTN.click_count, SPEED.value, etc. are plain daslang globals, readable from any module that requires this one.
Dotted flags — IDENT.PUBLIC / IDENT.PRIVATE / IDENT.NOTLIVE tune visibility and live-reload behavior on the emitted global without claiming new syntactic positions in the call.

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

8.19.13.1. Walkthrough

The recording drives every channel and asserts the snapshot followed: it clicks Save twice and verifies SAVE_BTN.click_count (hold_through_voice), force-sets SPEED and VOLUME from outside and verifies each value (force_set_verified), force-sets STATUS_TEXT and verifies the mirror took the string, then clicks bump and verifies the app rewrote STATUS_TEXT.value from inside (record_check_changed). Any channel that stopped reaching the snapshot would abort the recording.

options gen2
options _comment_hygiene = true
options gc

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: state_telemetry — how widget state lives in daslang, not ImGui.
//
// Each boost widget macro emits a module-scope global named by the first
// argument. The global is a typed state struct (ClickState, SliderStateInt,
// SliderStateFloat, ToggleState, ...) that holds the widget's value, plus
// any pending overrides queued by external drivers. Three immediate wins:
//
//   1. Auto-emit:        the variable is declared once, by the macro, on
//                        first compile. No "var SAVE_BTN : ClickState;"
//                        boilerplate to keep in sync with the call site.
//   2. Read anywhere:    SAVE_BTN.click_count, SPEED.value are plain
//                        globals — readable from any module that requires
//                        this one (assuming PUBLIC visibility).
//   3. Dotted flags:     IDENT.PUBLIC / IDENT.PRIVATE / IDENT.NOTLIVE
//                        modify visibility / live-reload behavior on the
//                        emitted global without claiming new syntactic
//                        positions in the call.
//
// Plus `imgui_snapshot` — the registry serializes every registered widget
// to JSON: kind, bbox, hex_id, payload (value / click_count / ...). That's
// the surface external drivers, integration tests, and visual aids see.
//
// STANDALONE: daslang.exe modules/dasImgui/examples/tutorial/state_telemetry.das
// LIVE:       daslang-live modules/dasImgui/examples/tutorial/state_telemetry.das
//
// DRIVE (when running live):
//   curl -X POST -d '{"name":"imgui_snapshot"}'                                                       localhost:9090/command
//   curl -X POST -d '{"name":"imgui_click","args":{"target":"STATE_WIN/SAVE_BTN"}}'                    localhost:9090/command
//   curl -X POST -d '{"name":"imgui_force_set","args":{"target":"STATE_WIN/SPEED","value":7}}'               localhost:9090/command
//   curl -X POST -d '{"name":"imgui_force_set","args":{"target":"STATE_WIN/STATUS_TEXT","value":"saved"}}'   localhost:9090/command
// =============================================================================

[export]
def init() {
    live_create_window("dasImgui state_telemetry tutorial", 1040, 720)
    live_imgui_init(live_window)
    DisableIniPersistence()
    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()

    SetNextWindowPos(ImVec2(30.0f, 30.0f), ImGuiCond.FirstUseEver)
    SetNextWindowSize(ImVec2(640.0f, 460.0f), ImGuiCond.FirstUseEver)
    window(STATE_WIN, (text = "state & telemetry", closable = false,
                       flags = ImGuiWindowFlags.None)) {

        // ---- Auto-emit + read-anywhere ----

        // No top-of-file `var SAVE_BTN : ClickState` — the macro emits the global
        // on first `button(SAVE_BTN, ...)`. Read its fields directly: .click_count
        // (cumulative, @live-preserved) and .clicked (true the frame it fired).
        text("Auto-emit: SAVE_BTN is the macro-emitted global.")
        if (button(SAVE_BTN, (text = "Save"))) {
            // `button(...)` returns bool — clicked-this-frame. Same info
            // as SAVE_BTN.clicked, just inline.
        }
        text("SAVE_BTN.click_count = {SAVE_BTN.click_count}")

        separator(ST_SEP_1)

        // ---- Dotted flags ----

        // SPEED.PUBLIC: emit the global `var public` (not the default private)
        // so requiring modules can read SPEED.value. Path stays "SPEED" — flags
        // don't leak into the registry path.

        // VOLUME.NOTLIVE: skip @live on the emitted global, so on reload the
        // source-side initial value wins (useful when you change bounds and want
        // them to take effect immediately rather than be preserved).
        text("Dotted flags tune visibility and live-reload behavior:")
        slider_int(SPEED.PUBLIC,   (text = "Speed (int, PUBLIC)"))
        slider_float(VOLUME.NOTLIVE, (text = "Volume (NOTLIVE)"))
        text("SPEED.value = {SPEED.value}   VOLUME.value = {VOLUME.value}")

        separator(ST_SEP_2)

        // ---- text_show: app-side value mirror ----

        // text_show is the read-only mirror of text_input: its state.value string
        // is displayed, imgui_force_set drives it from outside, and the snapshot
        // exposes it under payload.value so tests can assert computed strings.
        text("text_show - app-driven status reaches the snapshot:")
        text_show(STATUS_TEXT)

        // The bump button writes a computed string into STATUS_TEXT.value.
        // Both `= "..."` and external imgui_force_set work; the
        // snapshot reflects whichever ran most recently.
        if (button(BUMP_STATUS, (text = "bump status"))) {
            STATUS_TEXT.value = "saved at frame {get_uptime()}"
        }
    }

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

8.19.13.1.1. Auto-emit

The first time button(SAVE_BTN, ...) is compiled, the macro emits the matching global at module scope:

// emitted automatically — no manual declaration
var private @live SAVE_BTN : ClickState = ClickState()

That’s why there’s no var SAVE_BTN at the top of the file. The state struct is owned by daslang — visible to grep, walkable via RTTI, persistable through the standard serializer, preserved across daslang-live reloads thanks to @live.

8.19.13.1.2. Reading state

Once emitted, the global behaves like any other daslang global — SAVE_BTN.click_count is a plain field access:

if (button(SAVE_BTN, (text = "Save"))) {
    // clicked this frame — same information as SAVE_BTN.clicked
}
text("SAVE_BTN.click_count = {SAVE_BTN.click_count}")

Two distinct value channels are available:

button(...) returns bool — true on the frame the click fired. Inline-friendly for the “do thing now” case.
SAVE_BTN.clicked is the same flag, surfaced as a field. Useful when the click handler is far from the call site, or in another module that requires this one.

Cumulative counters (click_count for buttons, changed for sliders, etc.) live alongside on the state struct. Walk imgui_boost_runtime.das for the full field list per state struct.

8.19.13.1.3. Dotted flags

A dot suffix on the identifier flips flags on the emitted global. The telemetry path uses only the bare identifier (STATE_WIN/SPEED, never STATE_WIN/SPEED.PUBLIC) — flags never leak into the path or the ImGui hash.

SPEED.PUBLIC — emit as var public instead of the default var private. Sibling modules requiring this one can then read SPEED.value directly.
VOLUME.NOTLIVE — skip the @live annotation on the emitted global. Useful when you change the slider bounds and want the source-side initial value to take effect immediately on reload rather than be preserved.
IDENT.PRIVATE — explicit default (same as no suffix). Lists cleanly when you grep for visibility intent.

Multiple flags compose: RPS.PUBLIC.NOTLIVE emits a public, non-@live global. New flags can land on demand without affecting the call syntax.

8.19.13.1.4. text_show — the app-driven mirror

text_show is the read-only counterpart to text_input — state.value is what the widget renders, and the value can be written by the app (STATUS_TEXT.value = "...") or by an external driver (imgui_force_set with a string value). Either way the snapshot exposes the current value under the standard payload.value field, so integration tests can assert on computed status strings the same way they assert slider values:

text_show(STATUS_TEXT)
if (button(BUMP_STATUS, (text = "bump status"))) {
    STATUS_TEXT.value = "saved at frame {get_uptime()}"
}

Plain = is right here: the interpolated string is freshly built on the app’s own heap, in the same context that renders the frame. The external path never touches this assignment — imgui_force_set hands the JSON string to the widget dispatcher, which stores it on the state struct for the next frame to render.

8.19.13.1.5. Standalone vs live

Same convention as previous tutorials.

8.19.13.1.6. Driving from outside

The snapshot exposes the state structs as JSON:

curl -X POST -d '{"name":"imgui_snapshot"}' localhost:9090/command

# Excerpt of the response:
#   "globals": {
#     "STATE_WIN/SAVE_BTN":    { "kind": "button", "payload": {"click_count": 2}, ... },
#     "STATE_WIN/SPEED":       { "kind": "slider_int", "payload": {"value": 7, ...}, ... },
#     "STATE_WIN/STATUS_TEXT": { "kind": "text_show", "payload": {"value": "saved at frame 12.3"}, ... }
#   }

Drivers go through the same registry — imgui_force_set looks up the target, queues the pending value on the matching state struct, and the renderer consumes it next frame:

curl -X POST -d '{"name":"imgui_force_set","args":{"target":"STATE_WIN/SPEED","value":7}}' \
     localhost:9090/command
curl -X POST -d '{"name":"imgui_force_set","args":{"target":"STATE_WIN/STATUS_TEXT","value":"hello"}}' \
     localhost:9090/command
curl -X POST -d '{"name":"imgui_click","args":{"target":"STATE_WIN/SAVE_BTN"}}' \
     localhost:9090/command

8.19.13.1.7. Next steps

So far every tutorial has used a single window(...) container. Containers come next — modal dialogs, popups, tab bars, child windows, and menus, all sharing the same block-arg pattern.