Widgets tour

One of every common boost widget on a single panel. The example frames as an audio-settings dialog so each widget reads contextually: a text input for the user name, a slider for volume, a checkbox for mute, a combo for codec quality, a color editor for the accent color, and a button to save.

Source: examples/tutorial/widgets_tour.das.

Walkthrough

The recording is voiced and self-verifying: each stage speaks a line while a real gesture fires under it and is asserted — typing into the name field (committed value checked), dragging VOLUME (value must change), clicking MUTED (toggle must register), opening the QUALITY combo and picking High (selection verified), setting TINT from the API (color_edit3’s picker is mouse-only, so the tour drives it via force_set and verifies the swatch took), and clicking Save (click must register). A silently broken stage aborts the recording at teardown instead of shipping.

  1options gen2
  2
  3require imgui
  4require imgui_app
  5require opengl/opengl_boost
  6require live/glfw_live
  7require live/live_api
  8require live/live_commands
  9require live/live_vars
 10require live_host
 11require imgui/imgui_live
 12require imgui/imgui_boost_runtime
 13require imgui/imgui_boost_v2
 14require imgui/imgui_widgets_builtin
 15require imgui/imgui_containers_builtin
 16require imgui/imgui_visual_aids
 17
 18// =============================================================================
 19// TUTORIAL: widgets_tour — one of every common boost widget on a single panel.
 20//
 21// Frame as an audio-settings dialog so each widget reads contextually:
 22//   USER_NAME  : input_text   — who's listening
 23//   VOLUME     : slider_float — master volume
 24//   MUTED      : checkbox     — mute toggle
 25//   QUALITY    : combo        — codec quality preset
 26//   TINT       : color_edit3  — accent color for the UI
 27//   SAVE_BTN   : button       — apply the settings
 28//
 29// Read alongside :ref:`tutorial_boost_basics` for the frame-loop shape; this
 30// tutorial only adds widgets on top of that scaffold.
 31//
 32// STANDALONE: daslang.exe modules/dasImgui/examples/tutorial/widgets_tour.das
 33// LIVE:       daslang-live modules/dasImgui/examples/tutorial/widgets_tour.das
 34//
 35// DRIVE (when running live):
 36//   curl -X POST -d '{"name":"imgui_force_set","args":{"target":"AUDIO_WIN/USER_NAME","value":"Boris"}}'        localhost:9090/command
 37//   curl -X POST -d '{"name":"imgui_force_set","args":{"target":"AUDIO_WIN/VOLUME","value":0.75}}'              localhost:9090/command
 38//   curl -X POST -d '{"name":"imgui_force_set","args":{"target":"AUDIO_WIN/MUTED","value":true}}'               localhost:9090/command
 39//   curl -X POST -d '{"name":"imgui_force_set","args":{"target":"AUDIO_WIN/QUALITY","value":2}}'                localhost:9090/command
 40//   curl -X POST -d '{"name":"imgui_force_set","args":{"target":"AUDIO_WIN/TINT","value":{"x":0.2,"y":0.8,"z":0.4}}}' localhost:9090/command
 41//   curl -X POST -d '{"name":"imgui_click","args":{"target":"AUDIO_WIN/SAVE_BTN"}}'                       localhost:9090/command
 42// =============================================================================
 43
 44[export]
 45def init() {
 46    live_create_window("dasImgui widgets tour", 1024, 720)
 47    live_imgui_init(live_window)
 48    let io & = unsafe(GetIO())
 49    GetStyle().FontScaleMain = 1.5
 50}
 51
 52[export]
 53def update() {
 54    if (!live_begin_frame()) return
 55    begin_frame()
 56
 57    ImGui_ImplGlfw_NewFrame()
 58    apply_synth_io_override()
 59    NewFrame()
 60
 61    // Sized for content with breathing room on the right + below for narrate
 62    // post-its to appear without overlapping the panel.
 63    SetNextWindowPos(ImVec2(60.0, 60.0), ImGuiCond.Always)
 64    SetNextWindowSize(ImVec2(720.0, 540.0), ImGuiCond.Always)
 65    window(AUDIO_WIN, (text = "Audio settings", closable = false,
 66                       flags = ImGuiWindowFlags.None)) {
 67        // Text input — buffer + string-mirror managed by the state struct.
 68        input_text(USER_NAME, (text = "Your name"))
 69
 70        spacing(WT_SP_1)
 71
 72        // Slider — float state with [0, 1] bounds set per-frame.
 73        VOLUME.bounds = (0.0f, 1.0f)
 74        slider_float(VOLUME, (text = "Master volume"))
 75
 76        // Checkbox — bool state, toggles on click.
 77        checkbox(MUTED, (text = "Mute"))
 78
 79        spacing(WT_SP_2)
 80
 81        // Combo — int state indexing into the items array.
 82        combo(QUALITY, (text = "Quality",
 83                        items <- ["Low", "Medium", "High", "Ultra"]))
 84
 85        spacing(WT_SP_3)
 86
 87        // Color editor — three-channel RGB, opens a picker on click.
 88        color_edit3(TINT, (text = "Accent color"))
 89
 90        spacing(WT_SP_4)
 91        separator(WT_SEP_1)
 92        spacing(WT_SP_5)
 93
 94        // Button — true on the frame the click registers; click_count accumulates.
 95        if (button(SAVE_BTN, (text = "Save settings"))) {
 96            print("save clicked: name={USER_NAME.value} vol={VOLUME.value} muted={MUTED.value} q={QUALITY.value}\n")
 97        }
 98
 99        spacing(WT_SP_6)
100        text("saves so far: {SAVE_BTN.click_count}")
101    }
102
103    end_of_frame()
104    Render()
105    var w, h : int
106    live_get_framebuffer_size(w, h)
107    glViewport(0, 0, w, h)
108    glClearColor(0.10f, 0.10f, 0.12f, 1.0f)
109    glClear(GL_COLOR_BUFFER_BIT)
110    live_imgui_render()
111
112    live_end_frame()
113}
114
115[export]
116def shutdown() {
117    live_imgui_shutdown()
118    live_destroy_window()
119}
120
121[export]
122def main() {
123    init()
124    while (!exit_requested()) {
125        update()
126    }
127    shutdown()
128}

Requires

The require block matches Boost basics exactly — backend (imgui_app / glfw / opengl), live host (live/*), and the v2 boost layer (imgui_live, imgui_boost_runtime, imgui_boost_v2, imgui_widgets_builtin, imgui_containers_builtin for the window(...) block container). One extra line pulls in imgui/imgui_visual_aids so the post-it narrate overlay the driver script paints into the recording is available at render time.

Init and shutdown

init() opens a 1024x720 GLFW window via live_create_window and hands the handle to live_imgui_init. It also bumps io.FontGlobalScale to 1.5 so the recorded APNG reads at typical Sphinx HTML widths without zooming. shutdown() mirrors the pair in reverse order.

The frame loop

update() follows the standard dasImgui v2 shape — see Boost basics for the line-by-line breakdown. The only addition is a single call to apply_synth_io_override() between ImGui_ImplGlfw_NewFrame and NewFrame. The GLFW backend polls real OS mouse data every focused frame and would otherwise win the IO race against any synthesized event the driver script posted just before. The override re-asserts the synth IO so live-driven clicks land at the right widget.

Widgets

All six widgets live inside a single window(AUDIO_WIN, ...) boost container — same pattern Boost basics introduced, so leaves register at AUDIO_WIN/<ident>:

window(AUDIO_WIN, (text = "Audio settings", closable = false,
                   flags = ImGuiWindowFlags.None)) {
    input_text(USER_NAME, (text = "Your name"))
    slider_float(VOLUME, (text = "Master volume"))
    checkbox(MUTED, (text = "Mute"))
    combo(QUALITY, (text = "Quality", items <- ["Low", "Medium", "High", "Ultra"]))
    color_edit3(TINT, (text = "Accent color"))
    if (button(SAVE_BTN, (text = "Save settings"))) { ... }
}

Each boost macro declares the named global the first time it expands and registers it under the path-prefixed name. The slider’s range comes from a plain field assignment one line above the macro call: VOLUME.bounds = (0.0f, 1.0f). The combo’s item list moves into the named argument with items <- because string arrays are non-copyable. SAVE_BTN.click_count accumulates across frames — handy for assertions in a test harness.

Standalone vs live

main() runs the loop directly when invoked as daslang.exe widgets_tour.das. Under daslang-live the host calls init / update / shutdown itself; main is ignored. Every state struct (USER_NAME, VOLUME, MUTED, QUALITY, TINT, SAVE_BTN) carries @live by default, so live-reloading the source preserves the widget contents.

Driving from outside

Under daslang-live the boost layer exposes imgui_force_set and imgui_click over localhost:9090. The top of the source file lists one curl invocation per widget. Each target is path-qualified:

curl -X POST -d '{"name":"imgui_force_set","args":{"target":"AUDIO_WIN/USER_NAME","value":"Boris"}}' \
     localhost:9090/command

For color_edit3, value is a JSON object with x / y / z fields — from_JV reads float3 from object form, not array form. For combo, value is the zero-based index into the items array.

Next steps

Layout helpers — splitters, columns, child windows — are next on top of the same widget set. To write your own widget kind on the same rails — a rotary knob, an XY-pad, a meter — see Custom widgets.

See also

Full source: examples/tutorial/widgets_tour.das

Richer reference: examples/features/inputs_*.das — every widget with every option exercised, against the same boost layer.

Previous tutorial: Boost basics

Next tutorial: Custom widgets

Boost macros — the macro layer.

Builtin widgets — widget reference.