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', ...)