Graphical User Interfaces (GUI)¶

Datoviz includes a built-in immediate-mode GUI system based on Dear ImGui, accessible directly from Python. This system allows you to build interactive widgets like buttons, sliders, checkboxes, tables, and trees.

Warning

The GUI API currently mirrors the underlying C API closely. While powerful, it is relatively low-level and may be simplified in a future version.

Enabling GUI¶

To use GUI elements, the Figure must be created with gui=True:

figure = app.figure(gui=True)

You must then register a GUI callback using @app.connect(figure) and name the function on_gui.

Immediate Mode¶

The GUI is immediate-mode: widgets are recreated from scratch at every frame. Their state (e.g. a checkbox value) must be stored and updated explicitly between frames. Use dvz.Out() to define mutable state values:

from datoviz import Out
checked = Out(True)

if dvz.gui_checkbox('Check me', checked):
    print('Checked:', checked.value)

Common Widgets¶

Note

You'll find the full list of GUI functions in the API reference.

Buttons¶

dvz.gui_button('Click me', width, height)

Returns True if pressed during this frame.

Sliders¶

slider = Out(25.0)
dvz.gui_slider('My slider', 0.0, 100.0, slider)

Also supports vec2, vec3, vec4 versions for multi-axis sliders.

Checkboxes¶

checked = Out(True)
dvz.gui_checkbox('Checkbox', checked)

Tables¶

dvz.gui_table('Table', rows, cols, labels, selected, flags)

labels is a list of strings (rows * cols), selected is a boolean array tracking selected rows (must be defined outside the GUI callback functions for data persistence).

Trees¶

if dvz.gui_node('Parent'):
    dvz.gui_selectable('Child')
    dvz.gui_pop()

Use dvz.gui_clicked() to detect clicks on selectable items.

Color Picker¶

color = dvz.vec3(0.5, 0.2, 0.7)
dvz.gui_colorpicker('Color', color, 0)

Layout Helpers¶

dvz.gui_pos(pos, pivot): position next dialog in pixels
dvz.gui_size(size): set size of next dialog
dvz.gui_begin(title, flags): start a new dialog
dvz.gui_end(): end current dialog

Example¶

import numpy as np

import datoviz as dvz
from datoviz import Out, vec2, vec3

# Dialog width.
w = 300

labels = ['col0', 'col1', 'col2', '0', '1', '2', '3', '4', '5']
rows = 2
cols = 3
selected = np.array([False, True], dtype=np.bool)

# IMPORTANT: these values need to be defined outside of the GUI callback.
checked = Out(True)
color = vec3(0.7, 0.5, 0.3)

slider = Out(25.0)  # Warning: needs to be a float as it is passed to a function expecting a float

# GUI callback function, called at every frame. This is using Dear ImGui, an immediate-mode
# GUI system. This means the GUI is recreated from scratch at every frame.


app = dvz.App()
# NOTE: at the moment, you must indicate gui=True if you intend to use a GUI in a figure
figure = app.figure(gui=True)


@app.connect(figure)
def on_gui(ev):
    # Set the size of the next GUI dialog.
    dvz.gui_pos(vec2(25, 25), vec2(0, 0))
    dvz.gui_size(vec2(w + 20, 550))

    # Start a GUI dialog, specifying a dialog title.
    dvz.gui_begin('My GUI', 0)

    # Add a button. The function returns whether the button was pressed during this frame.
    if dvz.gui_button('Button', w, 30):
        print('button clicked')

    # Create a tree, this call returns True if this node is unfolded.
    if dvz.gui_node('Item 1'):
        # Display an item in the tree.
        dvz.gui_selectable('Hello inside item 1')
        # Return True if this item was clicked.
        if dvz.gui_clicked():
            print('clicked sub item 1')
        # Go up one level.
        dvz.gui_pop()

    if dvz.gui_node('Item 2'):
        if dvz.gui_node('Item 2.1'):
            dvz.gui_selectable('Hello inside item 2')
            if dvz.gui_clicked():
                print('clicked sub item 2')
            dvz.gui_pop()
        dvz.gui_pop()

    if dvz.gui_table('table', rows, cols, labels, selected, 0):
        print('Selected rows:', np.nonzero(selected)[0])

    if dvz.gui_checkbox('Checkbox', checked):
        print('Checked status:', checked.value)

    if dvz.gui_colorpicker('Color picker', color, 0):
        print('Color:', color)

    if dvz.gui_slider('Slider', 0.0, 100.0, slider):
        print('Slider value:', slider.value)

    # End the GUI dialog.
    dvz.gui_end()


app.run()
app.destroy()

This example demonstrates several widgets including a button, tree, table, color picker, and slider.

Summary¶

Feature	Notes
Built-in GUI	Immediate mode, updated every frame
API Style	Low-level, mirrors C API closely
Widgets	Buttons, sliders, tables, trees, color pickers, etc.
State	Use `Out(...)` to track mutable widget values
Rendering	GUI renders as an overlay inside the figure window