Driving from outside

Every boost widget that previous tutorials wrote registers a path in the telemetry tree (DRIVE_WIN/USER, DRIVE_WIN/SPEED, DRIVE_WIN/RUN_BTN …). That path is also an HTTP endpoint: the boost layer ships [live_command] handlers (imgui_snapshot, imgui_set, imgui_click, imgui_open, imgui_close, imgui_focus) that look up the target in the registry and queue the matching pending field on the widget’s state struct. Next frame, the render function consumes the pending field and ImGui sees the effect as if a real input device drove it.

This tutorial flips the point of view: instead of writing the daslang side, write the driver — a curl / Python / Bash script that issues JSON commands at a running daslang-live app. Every interaction the user could perform via mouse/keyboard has a curl equivalent, and the two surfaces use one in-memory model.

Source: examples/tutorial/driving_outside.das — a small target app exposing five widget kinds. The recording is driven entirely by JSON commands — no synthesized mouse moves into widget centers.

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

let PRESETS : array<string> <- ["Calm", "Mellow", "Active", "Frantic"]
var PRESET_ROW : table<int; ClickState>

// =============================================================================
// TUTORIAL: driving_outside — every boost widget is also a JSON endpoint.
//
// Previous tutorials wrote the daslang side. This one is the inverse view:
// what the JSON command surface looks like as a programming model in its
// own right. Every widget the boost layer ships registers a path in the
// telemetry tree; that path is also addressable from outside via the
// [live_command] HTTP endpoints `imgui_snapshot` / `imgui_set` /
// `imgui_click` / `imgui_open` / `imgui_close` / `imgui_focus`.
//
// The target app is small — slider + button + input + popup + combo — so
// the driving recipes are easy to spot. Every interaction the user could
// perform via mouse/keyboard has a curl equivalent.
//
// STANDALONE: daslang.exe modules/dasImgui/examples/tutorial/driving_outside.das
// LIVE:       daslang-live modules/dasImgui/examples/tutorial/driving_outside.das
//
// DRIVE (curl recipes — pair these with the RST walkthrough):
//
//   # Snapshot the world (always the first read in any driver)
//   curl -X POST -d '{"name":"imgui_snapshot"}' localhost:9090/command
//
//   # imgui_set — drive a slider value
//   curl -X POST -d '{"name":"imgui_set","args":{"target":"DRIVE_WIN/SPEED","value":7}}' \
//        localhost:9090/command
//
//   # imgui_click — fire a button
//   curl -X POST -d '{"name":"imgui_click","args":{"target":"DRIVE_WIN/RUN_BTN"}}' \
//        localhost:9090/command
//
//   # imgui_set — string into a text input
//   curl -X POST -d '{"name":"imgui_set","args":{"target":"DRIVE_WIN/USER","value":"Alice"}}' \
//        localhost:9090/command
//
//   # imgui_set — combo by selected-index
//   curl -X POST -d '{"name":"imgui_set","args":{"target":"DRIVE_WIN/PRESET","value":2}}' \
//        localhost:9090/command
//
//   # imgui_open / imgui_close — popups, closable windows, tabs
//   curl -X POST -d '{"name":"imgui_open","args":{"target":"DRIVE_WIN/STATUS_POPUP"}}' \
//        localhost:9090/command
//   curl -X POST -d '{"name":"imgui_close","args":{"target":"DRIVE_WIN/STATUS_POPUP"}}' \
//        localhost:9090/command
// =============================================================================

[export]
def init() {
    live_create_window("dasImgui driving_outside tutorial", 720, 540)
    live_imgui_init(live_window)
    var io & = unsafe(GetIO())
    io.FontGlobalScale = 1.5
}

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

    ImGui_ImplOpenGL3_NewFrame()
    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(DRIVE_WIN, (text = "driving_outside", closable = false,
                       flags = ImGuiWindowFlags.None)) {

        // ---- A text input — driven by `imgui_set` with a string value ----
        input_text(USER, (text = "User"))
        text("USER.value = \"{USER.value}\"")

        separator(DR_SEP_1)

        // ---- A slider — driven by `imgui_set` with a number value ----
        slider_int(SPEED, (text = "Speed"))
        text("SPEED.value = {SPEED.value}")

        separator(DR_SEP_2)

        // ---- A combo — driven by `imgui_set` with the selected index ----
        var preset_label = "(none)"
        if (PRESET.value >= 0 && PRESET.value < length(PRESETS)) {
            preset_label = PRESETS[PRESET.value]
        }
        combo_select(PRESET, (text = "Preset",
                              preview_value = preset_label,
                              flags = ImGuiComboFlags.None)) {
            for (i in range(length(PRESETS))) {
                let is_sel = (i == PRESET.value)
                if (selectable_label(PRESET_ROW[i], PRESETS[i], is_sel)) {
                    PRESET.value = i
                }
            }
        }
        text("PRESET = {preset_label} (idx {PRESET.value})")

        separator(DR_SEP_3)

        // ---- A button — fired by `imgui_click` ----
        if (button(RUN_BTN, (text = "Run"))) {}
        text("RUN_BTN.click_count = {RUN_BTN.click_count}")

        separator(DR_SEP_4)

        // ---- A popup — opened/closed via `imgui_open` / `imgui_close` ----
        text("STATUS_POPUP — driven by imgui_open / imgui_close.")
        popup(STATUS_POPUP, (text = "StatusPopup",
                             flags = ImGuiWindowFlags.None)) {
            text("Driven from outside via imgui_open.")
            separator(DR_SEP_5)
            text("RUN_BTN.click_count = {RUN_BTN.click_count}")
        }
    }

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

The command surface

Three dispatch levels, in order of decreasing abstraction:

L1 — synth IO: imgui_mouse_pos, imgui_mouse_button, imgui_mouse_play, imgui_key_press, imgui_key_type. The driver pretends to be a mouse or keyboard, feeding events into the ImGui input queue. Used by imgui_playwright for cursor-visible recordings.
L2 — semantic actions on registered widgets: imgui_click, imgui_focus. The framework looks up the widget by path and queues state.pending_click = true (or the equivalent). Whatever the widget’s render function would do on a real click happens next frame. No bbox lookup, no cursor motion.
L3 — value writes: imgui_set. Same lookup, queues state.has_pending = true + state.pending_value = .... The render function consumes the pending value and submits it to ImGui on the next frame.

Plus the read side and the container channel:

imgui_snapshot — full registry as JSON, the first call in any driver.
imgui_open / imgui_close — set state.pending_open / state.pending_close on container widgets (popups, closable windows, tabs, tree nodes).

Always L2/L3 first — they’re race-free under the framework’s per-frame consumption rule. Drop to L1 only when there’s no L2 counterpart (drag along a custom trajectory, paste a long string into a focused input, sustain a chord, …).

imgui_snapshot — read the world

The first call every driver makes:

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

Response shape:

{
  "frame": 412,
  "globals": {
    "DRIVE_WIN": {
      "kind": "window",
      "bbox": [30, 30, 670, 490],
      "hex_id": "0x2c1a8f4b",
      "payload": { "open": true, "size": [640, 460], ... }
    },
    "DRIVE_WIN/SPEED": {
      "kind": "slider_int",
      "bbox": [...],
      "hex_id": "0x...",
      "payload": { "value": 5, "bounds": [0, 10], ... }
    },
    "DRIVE_WIN/RUN_BTN": {
      "kind": "button",
      "bbox": [...],
      "payload": { "click_count": 0 }
    },
    ...
  },
  "io": {
    "mouse_pos": [320, 180],
    "active_widget": "..."
  }
}

Use it to:

discover what’s on screen and what kind each widget is;
read bbox for L1 mouse synthesis (when needed);
check payload for current state (test assertions);
read hex_id for fallback dispatch when the path isn’t stable.

imgui_set — value writes

imgui_set is the universal value-write endpoint — slider, checkbox, combo, color, text input, dock-window position. Type-dispatched on the value’s JSON shape:

# string into a text input
curl -X POST -d '{"name":"imgui_set","args":{"target":"DRIVE_WIN/USER","value":"Alice"}}' \
     localhost:9090/command

# int into a slider
curl -X POST -d '{"name":"imgui_set","args":{"target":"DRIVE_WIN/SPEED","value":7}}' \
     localhost:9090/command

# int into a combo (selected index)
curl -X POST -d '{"name":"imgui_set","args":{"target":"DRIVE_WIN/PRESET","value":2}}' \
     localhost:9090/command

# array-of-floats into a color picker
curl -X POST -d '{"name":"imgui_set","args":{"target":"DRIVE_WIN/TINT","value":[0.2,0.7,0.4]}}' \
     localhost:9090/command

Under the hood: the registered dispatcher for the widget’s state struct unpacks the JSON, type-checks it against the state’s value field, flips has_pending = true, stores pending_value. The render function picks it up next frame; ImGui submits the new value through its own UpdateValue path.

imgui_click — fire a click

imgui_click doesn’t synthesize a mouse event — it sets state.pending_click = true on the registered ClickState (or its equivalent on selectable / menu_item):

curl -X POST -d '{"name":"imgui_click","args":{"target":"DRIVE_WIN/RUN_BTN"}}' \
     localhost:9090/command

The button’s render function returns true next frame just like a real click would, the click_count increments, the daslang side sees both the inline if (button(...)) and RUN_BTN.clicked / RUN_BTN.click_count as expected. No mouse position has to land on the button.

imgui_open / imgui_close — containers

Containers expose an open-state channel through state.pending_open and state.pending_close. imgui_open flips pending_open; imgui_close flips pending_close. The next frame’s render function applies the change:

curl -X POST -d '{"name":"imgui_open","args":{"target":"DRIVE_WIN/STATUS_POPUP"}}' \
     localhost:9090/command
curl -X POST -d '{"name":"imgui_close","args":{"target":"DRIVE_WIN/STATUS_POPUP"}}' \
     localhost:9090/command

The same channel handles popups, closable windows, tabs (closable-tab visibility specifically — see tutorial_containers for the tab-item caveat), tree nodes, and collapsing headers.

The flow on a single command

Every command runs the same path:

daslang-live HTTP server receives POST /command.
Routes by name to the registered [live_command] handler.
Handler looks up target in the registry’s path map (or hex_id reverse map).
Mutates the matching state struct’s pending field; returns {"ok": true, ...} on the HTTP response.
Next frame the script’s update() runs; the widget’s render function sees the pending flag, applies it, ImGui responds, the updated state is observable from the next imgui_snapshot.

So commands are one-frame-delayed by design — there’s no ambiguity about which frame’s state corresponds to a given response. For test harnesses that need to read the result, the canonical pattern is: command, then await_quiescent (waits a frame), then imgui_snapshot.

Standalone vs live

The HTTP server only exists under daslang-live. Standalone daslang.exe runs the same script but the live-command endpoints aren’t bound — drive-from-outside scenarios require the live host.

Driving from outside (recap)

A complete drive sequence for this tutorial’s app:

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

# Write each widget kind
curl -X POST -d '{"name":"imgui_set","args":{"target":"DRIVE_WIN/USER","value":"Alice"}}' \
     localhost:9090/command
curl -X POST -d '{"name":"imgui_set","args":{"target":"DRIVE_WIN/SPEED","value":7}}' \
     localhost:9090/command
curl -X POST -d '{"name":"imgui_set","args":{"target":"DRIVE_WIN/PRESET","value":2}}' \
     localhost:9090/command
curl -X POST -d '{"name":"imgui_click","args":{"target":"DRIVE_WIN/RUN_BTN"}}' \
     localhost:9090/command
curl -X POST -d '{"name":"imgui_open","args":{"target":"DRIVE_WIN/STATUS_POPUP"}}' \
     localhost:9090/command

The recording at the top of this page runs this exact sequence — no mouse moves, just JSON commands. Every effect you see in the APNG is the result of an imgui_set / imgui_click / imgui_open flowing through the state-struct pending channel.

Next steps

Now that the JSON-driven view is explicit, the visual aids tour walks through every overlay the recordings used: highlight, mouse trail, cursor sprite, narrate, key HUD, focus rect — all [live_command]-wrapped so the same curl pattern reaches them.