8.19.32. data_table

ImGui’s tables API — BeginTable / EndTable with body-internal TableSetupColumn / TableHeadersRow / TableNextRow / TableSetColumnIndex / TableNextColumn cursor primitives — lives behind one boost container plus a family of snake_case pass-throughs in imgui/imgui_table_builtin. The container is named data_table (not table) because table is a daslang reserved keyword for the table<K;V> type constructor.

The container takes the ImGui id, the column count, the flags, an outer size and an inner width — same five arguments the cpp BeginTable takes — and brackets the matching EndTable. Inside the body, the row/column cursor calls are plain pass-throughs that resolve in the imgui_table_builtin module namespace (so the project-wide lint, which forbids raw imgui::* calls in user code, stays satisfied without an allow-list extension).

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

8.19.32.1. Walkthrough

The recording drives the sortable shape by clicking the real column headers: clicking Name flips the active sort ascending to descending; clicking Type replaces the key and re-groups the rows by type; and Shift+clicking Value adds it as a secondary key (the 2 badge), so within each type the rows break ties by value. Each click is verified against the re-rendered cell text, so a header click that failed to re-sort 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_table_builtin
require imgui/imgui_visual_aids

// =============================================================================
// TUTORIAL: data_table — boost container for ImGui's tables API.
//
// `BeginTable` / `EndTable` and the body-internal cursor calls
// (TableSetupColumn, TableHeadersRow, TableNextRow, TableSetColumnIndex,
// TableNextColumn) live behind one container + six snake_case pass-throughs
// in `imgui/imgui_table_builtin`. The container is named `data_table`
// (not `table`, which is a daslang reserved keyword for `table<K;V>`).
//
//   data_table(MY_TABLE, (text = "##split", columns = 3, flags = ...,
//                          outer_size = float2(0,0), inner_width = 0.0f)) {
//       table_setup_column("Name")
//       table_setup_column("Type")
//       table_setup_column("Value")
//       table_headers_row()
//       for (row in rows) {
//           table_next_row()
//           table_set_column_index(0); text(NAME[row], (text = ...))
//           table_set_column_index(1); text(TYPE[row], (text = ...))
//           table_set_column_index(2); text(VAL[row], (text = ...))
//       }
//   }
//
// `TableState` echoes per-call config (columns / flags / outer_size /
// inner_width). `sort_specs()` (block helper) yields the per-frame sort
// spec list — see the Sortable tables section below. Multi-select
// hand-off and custom row-bg callbacks would extend the state
// additively if added later.
//
// STANDALONE: daslang.exe modules/dasImgui/examples/tutorial/data_table.das
// LIVE:       daslang-live modules/dasImgui/examples/tutorial/data_table.das
// =============================================================================

struct private Row {
    name : string
    kind : string
    value : string
}

var private ROWS <- [
    Row(name = "alpha", kind = "int", value = "42"),
    Row(name = "beta", kind = "float", value = "3.14"),
    Row(name = "gamma", kind = "string", value = "hello"),
    Row(name = "delta", kind = "bool", value = "true"),
    Row(name = "epsilon", kind = "int", value = "-7"),
    Row(name = "zeta", kind = "float", value = "0.001")
]

// Stable column identifiers passed to table_setup_column(.., user_id=...).
// The sort comparator dispatches on user_id (not column_index) so the
// sort stays correct when the user reorders columns via drag.
let private COL_NAME = 0x0001u
let private COL_KIND = 0x0002u
let private COL_VAL  = 0x0003u

def private compare_rows(spec : TableSortSpec; a : Row; b : Row) : int {
    // Returns -1 / 0 / 1 for a-vs-b along the column the spec names.
    var ord = 0
    if (spec.column_user_id == COL_NAME) {
        if (a.name < b.name) {
            ord = -1
        } elif (a.name > b.name) {
            ord = 1
        }
    } elif (spec.column_user_id == COL_KIND) {
        if (a.kind < b.kind) {
            ord = -1
        } elif (a.kind > b.kind) {
            ord = 1
        }
    } elif (spec.column_user_id == COL_VAL) {
        if (a.value < b.value) {
            ord = -1
        } elif (a.value > b.value) {
            ord = 1
        }
    }
    if (spec.sort_direction == ImGuiSortDirection.Descending) {
        ord = -ord
    }
    return ord
}

def private sort_rows(specs : array<TableSortSpec>) {
    // Multi-key comparator: first spec that disambiguates a vs b wins; name is the total-order tiebreak.
    ROWS |> sort() $(a, b) {
        for (s in specs) {
            let ord = compare_rows(s, a, b)
            if (ord != 0) return ord < 0
        }
        return a.name < b.name
    }
}

var DT_NAME : table<int; NarrativeState>
var DT_KIND : table<int; NarrativeState>
var DT_VAL : table<int; NarrativeState>

[export]
def init() {
    live_create_window("dasImgui data_table tutorial", 860, 540)
    live_imgui_init(live_window)
    // Deterministic FirstUseEver layout for the recording: disable imgui.ini so a
    // prior session's window pos/size can't drift the framing. Tutorial-scoped on
    // purpose - not a blanket change to live_imgui_init.
    DisableIniPersistence()
    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()

    SetNextWindowPos(ImVec2(30.0f, 30.0f), ImGuiCond.FirstUseEver)
    SetNextWindowSize(ImVec2(640.0f, 380.0f), ImGuiCond.FirstUseEver)
    window(DT_WIN, (text = "data_table", closable = false,
                    flags = ImGuiWindowFlags.None)) {
        text(DT_HEADER, (text = "Three columns, six rows, frozen header. Click headers to sort; Shift+click for multi-column."))

        let tflags = (ImGuiTableFlags.BordersOuter |
                      ImGuiTableFlags.RowBg |
                      ImGuiTableFlags.Resizable |
                      ImGuiTableFlags.Reorderable |
                      ImGuiTableFlags.Hideable |
                      ImGuiTableFlags.Sortable |
                      ImGuiTableFlags.SortMulti |
                      ImGuiTableFlags.ScrollY)
        data_table(DT_TABLE, (text = "##rows", columns = 3,
                              flags = tflags,
                              outer_size = float2(0.0f, 0.0f),
                              inner_width = 0.0f)) {
            table_setup_scroll_freeze(0, 1)
            table_setup_column("Name",  ImGuiTableColumnFlags.DefaultSort, 0.0f, COL_NAME)
            table_setup_column("Type",  ImGuiTableColumnFlags.None,        0.0f, COL_KIND)
            table_setup_column("Value", ImGuiTableColumnFlags.None,        0.0f, COL_VAL)
            table_headers_row()

            sort_specs() $(specs) {
                sort_rows(specs)
            }

            for (i in range(length(ROWS))) {
                table_next_row()
                table_set_column_index(0)
                text(DT_NAME[i], (text = ROWS[i].name))
                table_set_column_index(1)
                text(DT_KIND[i], (text = ROWS[i].kind))
                table_set_column_index(2)
                text(DT_VAL[i], (text = ROWS[i].value))
            }
        }
    }

    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.32.1.1. Requires

One extra module on top of the baseline boost layer:

imgui/imgui_table_builtin — the data_table container plus the table_* snake_case primitives the body calls into, the TableSortSpec struct and the sort_specs helper.

8.19.32.1.2. Container shape

data_table follows the same named-tuple convention as the other containers (window / child / tab_bar):

data_table(MY_TABLE, (text = "##rows", columns = 3,
                       flags = ImGuiTableFlags.Borders,
                       outer_size = float2(0.0f, 0.0f),
                       inner_width = 0.0f)) {
    // body
}

text is the ImGui id (use the ##suffix convention to keep it out of the visible label). columns is the column count; outer_size = float2(0,0) lets ImGui auto-size; inner_width = 0.0f means “no explicit inner width” (use the outer width).

8.19.32.1.3. Body primitives

The body cursor calls are plain def public wrappers — same arguments as the underlying ImGui calls, snake_case names:

table_setup_column(text, flags?, init_width_or_weight?, user_id?) — declare a column before the header row.
table_setup_scroll_freeze(cols, rows) — pin the first N columns / M rows during scrolling.
table_headers_row() — submit the header row using the table_setup_column labels.
table_header(text) / table_angled_headers_row() — a single custom header cell, and the rotated-label header row.
table_next_row(flags?, min_row_height?) — start the next row.
table_set_column_index(col) -> bool — jump to a specific column; returns true when the column is visible.
table_next_column() -> bool — advance one column (or wrap to next row); also returns the visibility bool.
table_set_bg_color(target, color, column_n?) — paint a row or cell background.
table_get_column_count() / table_get_column_index() / table_get_row_index() / table_get_column_name(col?) / table_get_column_flags(col?) — cursor and layout queries.

TableState (the container’s state struct) echoes per-call config — columns, flags, outer_size, inner_width — so snapshot consumers can read the table’s shape without parsing the daslang call site. Multi-select hand-off remains deferred — pinned ImGui 1.92.6 exposes BeginMultiSelect / ImGuiMultiSelectIO, but the boost-wrapper hand-off has not been designed yet. A custom row-bg callback API would extend the state additively if added later.

8.19.32.1.4. Sortable tables

The tutorial table uses the full sortable shape — Sortable | SortMulti | Reorderable | Hideable flags on the table, a stable user_id on each table_setup_column, and a sort_specs() block-arg helper inside the body that ImGui fires when the sort state goes dirty.

ImGuiTableFlags.Sortable enables single-column sort (click any header). Adding ImGuiTableFlags.SortMulti enables multi-column sort (Shift+click a second header to append a secondary sort key).
table_setup_column("Name", flags, init_width_or_weight, user_id = COL_NAME) tags the column with a stable identifier (a uint). The sort comparator dispatches on column_user_id rather than column_index, so the sort stays correct after the user reorders columns via drag.
sort_specs() $(specs) { ... } is the wrapper that captures the ImGui TableGetSortSpecs() data, converts each ImGuiTableColumnSortSpecs entry into a daslang-friendly TableSortSpec (with column_index, column_user_id, sort_order, sort_direction), invokes the body block with the array, and auto-clears the SpecsDirty flag on return. The block only fires when ImGui reports dirty (header click), so the comparator cost is paid once per sort change rather than every frame.

The block-body comparator pattern walks the specs in priority order and returns on the first spec that disambiguates a pair — sort_order = 0 is the primary key, sort_order = 1 is the first tiebreak, and so on. A final tiebreak on a unique field (here: name) keeps the order total.

For a complete standalone example (inventory table with id / name / qty columns and a multi-key comparator), see modules/dasImgui/examples/features/sort_specs.das.

8.19.32.1.5. Why the name

table is a daslang reserved keyword — the type constructor for table<K;V> (the hash-map type). Defining a function or container named table is a parse error. data_table follows the standard UI-library term (Material’s DataTable, Bootstrap’s table, etc.) and disambiguates from the type namespace at every call site.

8.19.32.1.6. Standalone vs live

Same convention as previous tutorials. daslang.exe runs the table once and exits at exit_requested(). daslang-live keeps the window open and reloads on source edits.