Skip to content

GUI

GUI controls

dvz_gui()

Create a new GUI dialog.

DvzGui* dvz_gui(DvzCanvas* canvas, char* title, int flags);
Parameter Type Description
canvas DvzCanvas* the canvas
title char* the GUI title
flags int optional flags
returns DvzGui* GUI

dvz_gui_checkbox()

Add a checkbox control.

void dvz_gui_checkbox(DvzGui* gui, char* name, bool value);
Parameter Type Description
gui DvzGui* the GUI
name char* the control label
value bool whether the checkbox is initially checked

dvz_gui_slider_float()

Add a slider for float number input.

void dvz_gui_slider_float(
    DvzGui* gui, char* name, float vmin, float vmax, float value);
Parameter Type Description
gui DvzGui* the GUI
name char* the control label
vmin float the minimum value
vmax float the maximum value
value float the initial value

dvz_gui_slider_int()

Add a slider for integer input.

void dvz_gui_slider_int(
    DvzGui* gui, char* name, int vmin, int vmax, int value);
Parameter Type Description
gui DvzGui* the GUI
name char* the control label
vmin int the minimum value
vmax int the maximum value
value int the initial value

dvz_gui_label()

Add a static, non-modifiable label.

void dvz_gui_label(DvzGui* gui, char* name, char* text);
Parameter Type Description
gui DvzGui* the GUI
name char* the control label
text char* the control text

dvz_gui_textbox()

Add a textbox control for text input.

void dvz_gui_textbox(DvzGui* gui, char* name, char* value);
Parameter Type Description
gui DvzGui* the GUI
name char* the control label
value char* the initial text

dvz_gui_button()

Add a button.

void dvz_gui_button(DvzGui* gui, char* name, int flags);
Parameter Type Description
gui DvzGui* the GUI
name char* the control label
flags int optional flags

dvz_gui_colormap()

Add a colormap image.

void dvz_gui_colormap(DvzGui* gui, DvzColormap cmap);
Parameter Type Description
gui DvzGui* the GUI
cmap DvzColormap the colormap

dvz_gui_demo()

Display the Dear ImGUI demo with all supported controls.

void dvz_gui_demo(DvzGui* gui);
Parameter Type Description
gui DvzGui* the GUI

dvz_gui_destroy()

Destroy a GUI.

void dvz_gui_destroy(DvzGui* gui);
Parameter Type Description
gui DvzGui* the GUI

Implementing a new control

Dear ImGui provides an impressive number of controls. Using it directly requires to write custom C++ callback functions. To simplify the creation of simple GUIs, Datoviz provides a simple declarative API that allows to specify in advance basic GUI dialogs. This is particularly convenient when using the Python bindings, since there is no need to wrap C++ code nor to call Python code at every frame.

Note

You can still use Dear ImGui directly, there is an example in the How to guides.

Here is a short checklist for Datoviz contributors who'd like to implement a new control in the Dear ImGui wrapper.

Note

This procedure is subject to change in an upcoming version.

  • controls.h:
    • Add the DvzGuiControlType enum
    • If there are control parameters:
      • Create a DvzGuiControlXXX typedef struct
      • Declare the struct
      • Add it to the DvzGuiControlUnion union
    • Declare the new dvz_gui_xxx() function, and write the docstring
  • controls.c:
    • Write the body of the dvz_gui_xxx() function
  • gui.cpp:
    • In show_control(), add a new switch case and call _show_xxx()
    • Implement _show_xxx()
  • test_canvas.c:
    • In test_canvas_gui_1(), add the new control with a call to dvz_gui_xxx()
    • Try the next test with DVZ_INTERACT=1 ./manage.sh test test_canvas_gui_1
  • cydatoviz.pxd:
    • After # FUNCTION START, add void dvz_gui_xxx() (no need to put the arguments, the Cython bindings generator will do it automatically)
  • pydatoviz.pyx:
    • Update the _CONTROLS dictionary
    • In Gui.control(), add a new if statement and make the binding
    • In _get_ev_args(), add a new if statement and make the callback argument binding
  • Run ./manage.sh cython
  • Test in a Python example gui.control('xxx', 'name', ...)