ImGui integration: introduction and acknownledgements

[pthom]

Dear ImGui is the bloat free immediate GUI library that started it all!

I worked on it in 2020, by providing an interactive manual for it.

ImGui Bundle provides ImGui with lots of additional satellites libraries, in C++ and in Python.

Python bindings

The python bindings are autogenerated and thus provides very close APIs and documentations; so that porting in any direction is easy.

TIP: actually GPT Chat is able to do 80% of the work by itself, once you trained it with a few examples!

Usage of imgui with python

Its usage in ImGui Bundle, especially in Python is a joy to use; and the auto-completion works like a charm.

Build an app with the standard ImGui workflow

An imgui application in C++ can be ported to python via an almost line by line translation!
For example imgui_example_glfw_opengl3.py is an almost direct port of imgui/example_glfw_opengl3/main.cpp.

Build an app with ImmApp

Alternaltively, ImmApp (immediate App) provides an easy way to create an app with few lines of code:

from imgui_bundle import imgui, immapp

def gui():
    imgui.text("Hello, world!")

immapp.run(gui_function=gui, window_title="Hello!",  window_size_auto=True,)

Technical notes about the python bindings

The generated python bindings follow closely the ImGui API.

• imgui.h: see the python bindings stubs (i.e. declarations) inside imgui/init.pyi, and compare them with imgui.h from which they were generated.
• imgui_internal.h: see the python bindings stubs inside imgui/internal.pyi, and compare them with imgui_internal.h from which they were generated.
• glfw backend: see the glfw backend bindings

The bindings transcription adheres to the following principles:

• CamelCase to snake_case for function names and enum member names
• Enum names and member names are shortened (since all of ImGui lies in the imgui_bundle.imgui namespace): see for example TableFlags_ in Python vs ImGuiTableFlags_ in C++
• ImGui widgets functions that modify an input parameter in C++, return a tuple (changed, new_value) in python: see for example slider_float (python) vs SliderFloat (C++)

ImGui Fork

The python bindings are based on a fork of ImGui on the imgui_bundle branch (which is based on imgui's docking branch).

This fork adds a few modifications in order to make the automatic bindings generation possible. Here is the diff. Most of these modification are not worth being backported to ImGui, so that this fork will be maintained and regularly rebased on the docking branch.

DPI Handling

One final note: DPI handling is a bit cumbersome with ImGui at this time, and I had to adapt quite a lot of satellite libraries examples so that they render well on windows laptops (where their rendering was broken because the screen scaling is for example 200%).

Maybe it would be interesting to consider adding the following EmVec2 function to ImGui, so that creating DPI aware apps becomes less wordly (i.e. instead of always multiplying by ImGui::GetFontSize()).

// For reproducible results, even on HighDPI screens, always scale your widgets and windows relatively to this size.
 It is somewhat comparable to the [em CSS Unit](https://lyty.dev/css/css-unit.html).
float EmSize() { return ImGui::GetFontSize(); }

// Use EmVec2 to get an ImVec2 that is DPI aware (the em unit is equivalent to the font height). Beware, this depends on the screen resolution, and may vary between your different monitors, especially if your are using a laptop with a high DPI screen  and a standard external display
ImVec2 EmVec2(float x, float y)
{
    float em = ImGui::GetFontSize();
    return ImGui::ImVec2(em * x, em *y);
}