8.18.1.4. Display widgets

dasImgui’s read-only display family wraps ImGui’s two main output widgets into the v2 boost surface. progress_bar wraps ImGui::ProgressBar with a ProgressBarState payload carrying {fraction, size, overlay}; image wraps ImGui::Image with the full uv0 / uv1 / tint_col / border_col quartet plus a uint64 reinterpret of the texture handle for snapshot readability.

progress_bar(PB_STATIC, (fraction = 0.33f,
                         size = float2(-1.0f, 0.0f),
                         overlay = "33%"))

image(IMG_PLAIN, (user_texture_id = font_tex,
                  size = float2(96.0f, 96.0f),
                  uv0 = float2(0.0f, 0.0f),
                  uv1 = float2(1.0f, 1.0f),
                  tint_col = float4(1.0f, 1.0f, 1.0f, 1.0f),
                  border_col = float4(0.0f, 0.0f, 0.0f, 0.0f)))

Display widgets are read-only, so they don’t need a caller-side ident — call them anonymously and only the parent window(DISPLAY_WIN, ...) registers a routable entry. This example names each one (PB_STATIC / PB_DRIVEN / PB_FIXED / IMG_PLAIN / IMG_TINT) so every widget registers its own snapshot path — which is what lets the recording assert each one’s output (the static bar on screen, the driven bar’s fraction sweeping, the images present).

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

8.18.1.4.1. Walkthrough

The recording narrates the three progress bars and two images while the middle bar’s fraction sweeps under a sine wave. These widgets take no input, so the self-check is on their output: the static bar and both images are asserted on screen, and the driven bar’s fraction is asserted to change over time - so a bar that stopped rendering or a sine that stopped sweeping would abort the recording.

options gen2
options _comment_hygiene = true

require math
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: display_widgets — boost v2 visual-output widgets.
//
// progress_bar wraps ImGui::ProgressBar with a ProgressBarState payload
// carrying {fraction, size, overlay}. image wraps ImGui::Image with full
// uv0/uv1/tint_col/border_col + a uint64 reinterpret of the texture handle
// for snapshot readability.
//
// The image() example uses the ImGui font atlas texture (always available),
// so this tutorial runs without any external asset.
//
// STANDALONE: daslang.exe modules/dasImgui/examples/tutorial/display_widgets.das
// LIVE:       daslang-live modules/dasImgui/examples/tutorial/display_widgets.das
//
// DRIVE (when running live):
//   curl -X POST -d '{"name":"imgui_snapshot"}' localhost:9090/command \
//        | jq '.globals."DISPLAY_WIN".payload'
// =============================================================================

var private g_phase : float = 0.0f

[export]
def init() {
    live_create_window("dasImgui display widgets", 940, 680)
    live_imgui_init(live_window)
    let io & = unsafe(GetIO())
    GetStyle().FontScaleMain = 1.4
}

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

    ImGui_ImplGlfw_NewFrame()
    apply_synth_io_override()
    NewFrame()

    g_phase += 0.01f
    let driven_frac = 0.5f + 0.5f * sin(g_phase)

    SetNextWindowPos(ImVec2(60.0, 60.0), ImGuiCond.Always)
    SetNextWindowSize(ImVec2(680.0, 420.0), ImGuiCond.Always)
    window(DISPLAY_WIN, (text = "Display widgets", closable = false,
                         flags = ImGuiWindowFlags.None)) {
        separator_text("progress_bar")

        // Static bar - 33% with auto-formatted overlay.
        progress_bar(PB_STATIC, (fraction = 0.33f,
                                 size = float2(-1.0f, 0.0f),
                                 overlay = "33%"))

        // Driven bar - sine-wave fraction, default overlay.
        progress_bar(PB_DRIVEN, (fraction = driven_frac,
                                 size = float2(-1.0f, 0.0f),
                                 overlay = ""))

        // Fixed-width bar with custom overlay text.
        progress_bar(PB_FIXED, (fraction = 0.75f,
                                size = float2(240.0f, 0.0f),
                                overlay = "loading..."))

        separator_text("image")

        // Use the ImGui font atlas as our texture — always built by frame 1.
        let io & = unsafe(GetIO())
        if (io.Fonts.TexData == null) {
            text("Font atlas not ready — wait for first frame.")
        } else {
            text("image() against the font atlas - varying uv + tint per call.")
            image(IMG_PLAIN, (user_texture_id = io.Fonts.TexRef,
                              size = float2(96.0f, 96.0f),
                              uv0 = float2(0.0f, 0.0f),
                              uv1 = float2(1.0f, 1.0f),
                              tint_col = float4(1.0f, 1.0f, 1.0f, 1.0f),
                              border_col = float4(0.0f, 0.0f, 0.0f, 0.0f)))
            same_line(SL_IMG)
            image(IMG_TINT, (user_texture_id = io.Fonts.TexRef,
                             size = float2(96.0f, 96.0f),
                             uv0 = float2(0.0f, 0.0f),
                             uv1 = float2(1.0f, 1.0f),
                             tint_col = float4(0.3f, 0.9f, 0.6f, 1.0f),
                             border_col = float4(1.0f, 1.0f, 1.0f, 0.5f)))
        }
    }

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

8.18.1.4.1.1. Requires

Baseline boost layer (imgui/imgui_boost_v2 re-exports the rail family from imgui/imgui_widgets_builtin). No extra modules.

8.18.1.4.1.2. progress_bar

ProgressBarState mirrors the call-site values verbatim. fraction holds the raw call-site value (no clamp at the state level); ImGui clamps to [0, 1] for the rendered bar, but the snapshot payload reflects whatever the caller passed — so out-of-range inputs surface in the snapshot for assertion. Pass a negative value for indeterminate animation. size is the ImGui ImVec2: -1.0f for the X component fills available width; explicit pixels for fixed width. overlay is the centered label drawn on top of the bar — leave empty for the auto-formatted percentage.

8.18.1.4.1.3. image

ImageState exposes user_texture_id as a uint64 so the snapshot can carry the texture handle as a readable number (raw void? would serialize as a pointer string). All four uv0 / uv1 / tint_col / border_col defaults match the C++ ImGui::Image defaults so an unset call is the identity render. The tutorial uses the ImGui font atlas (GetIO().Fonts.TexID) as a guaranteed-available texture; production code passes a user_texture_id from your renderer that targets a real GPU resource.

8.18.1.4.1.4. Snapshot shape

Each named widget registers its own snapshot entry, so a rail’s state is readable directly. Probe with:

curl -X POST -d '{"name":"imgui_snapshot"}' localhost:9090/command \
    | jq '.globals."DISPLAY_WIN/PB_DRIVEN".payload'

That returns the driven bar’s {fraction, size, overlay} — useful for snapshot-driven regression tests when you want to assert PB_DRIVEN’s fraction matches the sine-driven value (the recording does exactly that, via record_check_changed). Left anonymous, a widget folds into a line-keyed entry under the window instead.