Dear ImGui Bundle documentation

C++ / Python porting advices

General advices

ImGui is a C++ library that was ported to Python. In order to work with it, you will often refer to its manual, which shows example code in C++.

In order to translate from C++ to Python:

Change the function names and parameters' names from CamelCase to snake_case
Change the way the output are handled.
1. in C++ ImGui::RadioButton modifies its second parameter (which is passed by address) and returns true if the user clicked the radio button.
2. In python, the (possibly modified) value is transmitted via the return: imgui.radio_button returns a Tuple[bool, str] which contains (user_clicked, new_value).
if porting some code that uses static variables, use the @immapp.static decorator. In this case, this decorator simply adds a variable value at the function scope. It is preserved between calls. Normally, this variable should be accessed via demo_radio_button.value, however the first line of the function adds a synonym named static for more clarity. Do not overuse them! Static variable suffer from almost the same shortcomings as global variables, so you should prefer to modify an application state.

Example:

C++

void DemoRadioButton()
{
    static int value = 0;
    ImGui::RadioButton("radio a", &value, 0); ImGui::SameLine();
    ImGui::RadioButton("radio b", &value, 1); ImGui::SameLine();
    ImGui::RadioButton("radio c", &value, 2);
}

Python

@immapp.static(value=0)
def demo_radio_button():
    static = demo_radio_button
    clicked, static.value = imgui.radio_button("radio a", static.value, 0)
    imgui.same_line()
    clicked, static.value = imgui.radio_button("radio b", static.value, 1)
    imgui.same_line()
    clicked, static.value = imgui.radio_button("radio c", static.value, 2)

Enums and TextInput

In the example below, two differences are important:

InputText functions:

imgui.input_text (Python) is equivalent to ImGui::InputText (C++)

In C++, it uses two parameters for the text: the text pointer, and its length.
In Python, you can simply pass a string, and get back its modified value in the returned tuple.

Enums handling:

ImGuiInputTextFlags_ (C++) corresponds to imgui.InputTextFlags_ (python) and it is an enum (note the trailing underscore).
ImGuiInputTextFlags (C++) corresponds to imgui.InputTextFlags (python) and it is an int (note: no trailing underscore)

You will find many similar enums.

The dichotomy between int and enums, enables you to write flags that are a combinations of values from the enum (see example below).

Example

C++

void DemoInputTextUpperCase()
{
    static char text[64] = "";
    ImGuiInputTextFlags flags = (
        ImGuiInputTextFlags_CharsUppercase
        | ImGuiInputTextFlags_CharsNoBlank
    );
    /*bool changed = */ ImGui::InputText("Upper case, no spaces", text, 64, flags);
}

Python

@immapp.static(text="")
def demo_input_text_decimal() -> None:
    static = demo_input_text_decimal
    flags:imgui.InputTextFlags = (
            imgui.InputTextFlags_.chars_uppercase.value
          | imgui.InputTextFlags_.chars_no_blank.value
        )
    changed, static.text = imgui.input_text("Upper case, no spaces", static.text, flags)

Note: in C++, by using imgui_stdlib.h, it is also possible to write:

#include "imgui/misc/cpp/imgui_stdlib.h"

void DemoInputTextUpperCase_StdString()
{
    static std::string text;
    ImGuiInputTextFlags flags = (
        ImGuiInputTextFlags_CharsUppercase
        | ImGuiInputTextFlags_CharsNoBlank
    );
    /*bool changed = */ ImGui::InputText("Upper case, no spaces", &text, flags);
}

Python context managers:

In C++, you would write:

ImGui::Begin("My Window")
ImGui::Text("Hello World");
ImGui::End(); // ImGui::End() should be called even if ImGui::Begin() returns false

In Python, the module imgui_ctx provides a lot of context managers that automatically call imgui.end(), imgui.end_child(), etc., when the context is exited, so that you can write:

from imgui_bundle import imgui, imgui_ctx

with imgui_ctx.begin("My Window"): # imgui.end() called automatically
    imgui.text("Hello World")

Of course, you can choose to use the standard API by using the module imgui:

imgui.begin("My Window")
imgui.text("Hello World")
imgui.end()

see demo_python_context_manager.py

Advanced glfw callbacks

When using the glfw backend, you can set advanced callbacks on all glfw events.

Below is an example that triggers a callback whenever the window size is changed:

import imgui_bundle
import glfw   # always import glfw *after* imgui_bundle!!!


# define a callback
def my_window_size_callback(window: glfw._GLFWwindow, w: int, h: int):
    print(f"Window size changed to {w}x{h}")


# Get the glfw window used by hello imgui
window = imgui_bundle.glfw_utils.glfw_window_hello_imgui()
glfw.set_window_size_callback(window, my_window_size_callback)

Caution

It is important to import glfw after imgui_bundle, since - upon import - imgui_bundle informs glfw that it shall use its own version of the glfw dynamic library.

Debug native C++ in python scripts

ImGui Bundle provides tooling to help you debug the C++ side, when you encounter a bug that is difficult to diagnose from Python.

It can be used in two steps:

Edit the file pybind_native_debug/pybind_native_debug.py. Change its content so that it runs the python code you would like to debug. Make sure it works when you run it as a python script.
Now, debug the C++ project pybind_native_debug which is defined in the directory pybind_native_debug/. This will run your python code from C++, and you can debug the C++ side (place breakpoints, watch variables, etc).

Example: this issue on macOS was solved thanks to this.