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

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

// =============================================================================
// TUTORIAL: widgets_tour — one of every common boost widget on a single panel.
//
// Frame as an audio-settings dialog so each widget reads contextually:
//   USER_NAME  : input_text   — who's listening
//   VOLUME     : slider_float — master volume
//   MUTED      : checkbox     — mute toggle
//   QUALITY    : combo        — codec quality preset
//   TINT       : color_edit3  — accent color for the UI
//   SAVE_BTN   : button       — apply the settings
//
// Read alongside :ref:`tutorial_boost_basics` for the frame-loop shape; this
// tutorial only adds widgets on top of that scaffold.
//
// STANDALONE: daslang.exe modules/dasImgui/examples/tutorial/widgets_tour.das
// LIVE:       daslang-live modules/dasImgui/examples/tutorial/widgets_tour.das
//
// DRIVE (when running live):
//   curl -X POST -d '{"name":"imgui_set","args":{"target":"AUDIO_WIN/USER_NAME","value":"Boris"}}'        localhost:9090/command
//   curl -X POST -d '{"name":"imgui_set","args":{"target":"AUDIO_WIN/VOLUME","value":0.75}}'              localhost:9090/command
//   curl -X POST -d '{"name":"imgui_set","args":{"target":"AUDIO_WIN/MUTED","value":true}}'               localhost:9090/command
//   curl -X POST -d '{"name":"imgui_set","args":{"target":"AUDIO_WIN/QUALITY","value":2}}'                localhost:9090/command
//   curl -X POST -d '{"name":"imgui_set","args":{"target":"AUDIO_WIN/TINT","value":{"x":0.2,"y":0.8,"z":0.4}}}' localhost:9090/command
//   curl -X POST -d '{"name":"imgui_click","args":{"target":"AUDIO_WIN/SAVE_BTN"}}'                       localhost:9090/command
// =============================================================================

[export]
def init() {
    live_create_window("dasImgui widgets tour", 1024, 720)
    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()

    // Sized for content with breathing room on the right + below for narrate
    // post-its to appear without overlapping the panel.
    SetNextWindowPos(ImVec2(60.0, 60.0), ImGuiCond.Always)
    SetNextWindowSize(ImVec2(720.0, 540.0), ImGuiCond.Always)
    window(AUDIO_WIN, (text = "Audio settings", closable = false,
                       flags = ImGuiWindowFlags.None)) {
        // Text input — buffer + string-mirror managed by the state struct.
        input_text(USER_NAME, (text = "Your name"))

        spacing(WT_SP_1)

        // Slider — float state with [0, 1] bounds set per-frame.
        VOLUME.bounds = (0.0f, 1.0f)
        slider_float(VOLUME, (text = "Master volume"))

        // Checkbox — bool state, toggles on click.
        checkbox(MUTED, (text = "Mute"))

        spacing(WT_SP_2)

        // Combo — int state indexing into the items array.
        combo(QUALITY, (text = "Quality",
                        items <- ["Low", "Medium", "High", "Ultra"]))

        spacing(WT_SP_3)

        // Color editor — three-channel RGB, opens a picker on click.
        color_edit3(TINT, (text = "Accent color"))

        spacing(WT_SP_4)
        separator(WT_SEP_1)
        spacing(WT_SP_5)

        // Button — true on the frame the click registers; click_count accumulates.
        if (button(SAVE_BTN, (text = "Save settings"))) {
            print("save clicked: name={USER_NAME.value} vol={VOLUME.value} muted={MUTED.value} q={QUALITY.value}\n")
        }

        spacing(WT_SP_6)
        text("saves so far: {SAVE_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()
}

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_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_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.