hello_imgui (C++)

Hello ImGui: the app runner. It creates the window and the rendering backend, and runs the loop, on desktop, mobile and the web.

Start with: HelloImGui::Run, RunnerParams, HelloImGui::GetRunnerParams, HelloImGui::LoadFont, DockableWindow, HelloImGui::Log.

hello_imgui/hello_imgui.h¶

HelloImGui::Run¶

void Run(RunnerParams &runnerParams);

void Run(const SimpleRunnerParams &simpleParams);

void Run( const VoidFunction &guiFunction, const std::string &windowTitle = "", bool windowSizeAuto = false, bool windowRestorePreviousGeometry = false, const ScreenSize &windowSize = DefaultWindowSize, float fpsIdle = 10.f, bool topMost = false );

HelloImGui::Run(RunnerParams &): full signature, the most customizable version.
Runs an application whose params and Gui are provided by runnerParams.

                  hello_imgui.h continued                                                                //

=========================== HelloImGui::Run ==================================
HelloImGui::Run() will run an application with a single call.
Three signatures are provided:

• HelloImGui::Run(RunnerParams &): full signature, the most customizable version.
  Runs an application whose params and Gui are provided by runnerParams.

• HelloImGui::Run(const SimpleRunnerParams&):
  Runs an application, using simpler params.

• HelloImGui::Run(guiFunction, windowTitle, windowSize, windowSizeAuto=False, restoreLastWindowGeometry=False, fpsIdle=10)
  Runs an application, by providing the Gui function, the window title, etc.
  Although the API is extremely simple, it is highly customizable, and you can set many options by filling the elements in the RunnerParams struct, or in the simpler SimpleRunnerParams.
  HelloImGui::GetRunnerParams() will return the runnerParams of the current application.

HelloImGui::GetRunnerParams¶

RunnerParams* GetRunnerParams();

GetRunnerParams(): a convenience function that will return the runnerParams of the current application

=========================== HelloImGui::ManualRender ==================================
============================== Utility functions ===============================

HelloImGui::IsUsingHelloImGui¶

bool IsUsingHelloImGui();

IsUsingHelloImGui(): returns True if the application is using HelloImGui

HelloImGui::InitGlLoader¶

bool InitGlLoader();

InitGlLoader(): initializes HelloImGui’s OpenGL function loader (GLAD).
Required ONLY when using HelloImGui’s image / texture helpers (ImageAndSizeFromAsset, CreateTextureGpuFromRgbaData, anything that uploads to a TextureGpuOpenGl) OUTSIDE a HelloImGui::Run() context.
Inside Run(), the loader is initialized automatically.

Typical use case: hosting imgui_md in a pure GLFW + PyOpenGL Python backend, or in a vanilla Dear ImGui glfw+opengl3 C++ app.

Preconditions:

• A GL context must be current (created by your own GLFW/SDL2/etc).

• HelloImGui must be compiled with HELLOIMGUI_USE_GLFW3 or HELLOIMGUI_USE_SDL2.

Returns True on success, False if no supported platform backend was compiled in. Idempotent: safe to call repeatedly.

Note: only the OpenGL3 standalone path is supported. Metal, Vulkan and
DirectX11/12 require device handles that HelloImGui’s runner would normally create — they are not usable outside Run().

HelloImGui::FrameRate¶

float FrameRate(float durationForMean = 0.5f);

FrameRate(durationForMean = 0.5): Returns the current FrameRate.
May differ from ImGui::GetIO().FrameRate, since one can choose the duration for the calculation of the mean value of the fps
Returns the current FrameRate. May differ from ImGui::GetIO().FrameRate, since one can choose the duration for the calculation of the mean value of the fps (Will only lead to accurate values if you call it at each frame)

HelloImGui::GetImGuiTestEngine¶

ImGuiTestEngine* GetImGuiTestEngine();

ImGuiTestEngine* GetImGuiTestEngine(): returns a pointer to the global instance of ImGuiTestEngine that was initialized by HelloImGui (iif ImGui Test Engine is active).

HelloImGui::GetBackendDescription¶

std::string GetBackendDescription();

GetBackendDescription(): returns a string with the backend info
Could be for example:
“Glfw - OpenGL3”
“Glfw - Metal”
“Sdl - Vulkan”

HelloImGui::ChangeWindowSize¶

void ChangeWindowSize(const ScreenSize &windowSize);

ChangeWindowSize(const ScreenSize &windowSize): sets the window size (useful if you want to change the window size during execution)

HelloImGui::UseWindowFullMonitorWorkArea¶

void UseWindowFullMonitorWorkArea();

UseWindowFullMonitorWorkArea(): sets the window size to the monitor work area (useful if you want to change the window size during execution)

HelloImGui::SwitchLayout¶

void SwitchLayout(const std::string& layoutName);

SwitchLayout(layoutName)
Changes the application current layout. Only used in advanced cases when several layouts are available, i.e. if you filled runnerParams.alternativeDockingLayouts.

============================== Layout Utils =============================
In advanced cases when several layouts are available, you can switch between layouts.
See demo inside https://github.com/pthom/hello_imgui/tree/master/src/hello_imgui_demos/hello_imgui_demodocking/hello_imgui_demodocking.main.cpp

HelloImGui::CurrentLayoutName¶

std::string CurrentLayoutName();

CurrentLayoutName(): returns the name of the current layout

HelloImGui::AddDockableWindow¶

void AddDockableWindow(const DockableWindow& dockableWindow, bool forceDockspace = false);

AddDockableWindow(): will add a dockable window to the current layout.
Will dock the window to the dockspace it belongs to if forceDockspace is True, otherwise will dock it to the last space it was docked to (using saved settings)

HelloImGui::RemoveDockableWindow¶

void RemoveDockableWindow(const std::string& dockableWindowName);

RemoveDockableWindow(): will remove a dockable window from the current layout. (dockableWindowName is the label of the window, as provided in the DockableWindow struct)

HelloImGui::SaveUserPref¶

void SaveUserPref(const std::string& userPrefName, const std::string& userPrefContent);

SaveUserPref(string userPrefName, string userPrefContent):
Shall be called in the callback runnerParams.callbacks.BeforeExit

============================== User prefs Utils =============================
You may store additional user settings in the application settings.
This is provided as a convenience only, and it is not intended to store large quantities of text data. Use sparingly.

HelloImGui::LoadUserPref¶

std::string LoadUserPref(const std::string& userPrefName);

string LoadUserPref(string& userPrefName)
Shall be called in the callback runnerParams.callbacks.PostInit

HelloImGui::ShowViewMenu¶

void ShowViewMenu(RunnerParams & runnerParams);

ShowViewMenu(RunnerParams & runnerParams): shows the View menu (where you can select the layout and docked windows visibility

============================== Menus defaults =============================
Hello ImGui provides a default menu and status bar, which you can customize by using the params: RunnerParams.imGuiWindowParams. showMenuBar / showMenu_App / showMenu_View
If you want to fully customize the menu:

• set showMenuBar to True, then set showMenu_App and showMenu_View params to False

• implement the callback RunnerParams.callbacks.ShowMenus: it can optionally call ShowViewMenu and ShowAppMenu (see below).

HelloImGui::ShowAppMenu¶

void ShowAppMenu(RunnerParams & runnerParams);

ShowAppMenu(RunnerParams & runnerParams): shows the default App menu (including the Quit item)

hello_imgui/hello_imgui_assets.h¶

Handling screens with high DPI¶

AssetFileData (struct)¶

HelloImGui::LoadAssetFileData¶

AssetFileData LoadAssetFileData(const char *assetPath);

LoadAssetFileData(const char *assetPath)`
Will load an entire asset file into memory. This works on all platforms, including android.
You have to call FreeAssetFileData to free the memory, except if you use
ImGui::GetIO().Fonts->AddFontFromMemoryTTF, which will take ownership of the data and free it for you.
This function can be redirected with setLoadAssetFileDataFunction. If not redirected, it calls DefaultLoadAssetFileData.

HelloImGui::FreeAssetFileData¶

void FreeAssetFileData(AssetFileData * assetFileData);

FreeAssetFileData(AssetFileData *)
Will free the memory.
Note: “ImGui::GetIO().Fonts->AddFontFromMemoryTTF” takes ownership of the data and will free the memory for you.

HelloImGui::DefaultLoadAssetFileData¶

AssetFileData DefaultLoadAssetFileData(const char *assetPath);

This function actually performs the asset load, as described in
LoadAssetFileData

HelloImGui::AssetFileFullPath¶

std::string AssetFileFullPath(const std::string& assetRelativeFilename, bool assertIfNotFound = true);

std::string AssetFileFullPath(const std::string& assetRelativeFilename) will return the path to assets.

This works under all platforms except Android
For compatibility with Android and other platforms, prefer to use LoadAssetFileData whenever possible.

• Under iOS it will give a path in the app bundle (/private/XXX/....)

• Under emscripten, it will be stored in the virtual filesystem at “/”

• Under Android, assetFileFullPath is not implemented, and will throw an error: assets can be compressed under android, and you can’t use standard file operations!
  Use LoadAssetFileData instead

HelloImGui::AssetExists¶

bool AssetExists(const std::string& assetRelativeFilename);

Returns True if this asset file exists

HelloImGui::SetAssetsFolder¶

void SetAssetsFolder(const std::string& folder);

Sets the assets folder location (when using this, automatic assets installation on mobile platforms may not work)

HelloImGui::AddAssetsSearchPath¶

void AddAssetsSearchPath(const std::string& folder);

Add a folder to the asset search paths.

Assets search paths provide additional locations where assets can be found, giving a unified view across multiple folders. When loading an asset, the search order is:

1. The main assets folder (set by SetAssetsFolder(), or the default platform-specific locations such as exe_folder/assets)

2. Each search path added by AddAssetsSearchPath(), in order

3. Other built-in platform-specific fallback locations
   The first match wins. This is useful when assets are split across directories — for example, core assets (fonts, icons) in one folder and demo-specific assets (extra images, specialty fonts) in another.
   Note: search paths are a runtime-only mechanism. Unlike the main assets folder (which CMake can bundle into the application for mobile/emscripten), search path folders are not automatically embedded at compile time.
   They are intended for desktop or Python usage where the filesystem is directly accessible.

HelloImGui::ClearAssetsSearchPaths¶

void ClearAssetsSearchPaths();

Remove all previously added search paths.

HelloImGui::GetAssetsSearchPaths¶

const std::vector<std::string>& GetAssetsSearchPaths();

Return the current list of search paths.

HelloImGui::overrideAssetsFolder¶

void overrideAssetsFolder(const char* folder);

synonym of SetAssetsFolder

hello_imgui/hello_imgui_logger.h¶

LogLevel (enum)¶

HelloImGui::Log¶

void Log(LogLevel level, char const* const format, ...);

HelloImGui::LogClear¶

void LogClear();

HelloImGui::LogGui¶

void LogGui(ImVec2 size=ImVec2(0.f, 0.f));

}

hello_imgui/image_from_asset.h¶

Images from the assets¶

Images are loaded when first displayed, and then cached (they will be freed just before the application exits).
For example, given this files structure:

├── CMakeLists.txt
├── assets/
│         └── my_image.jpg
└── my_app.main.cpp

then, you can display “my_image.jpg”, using:

HelloImGui::ImageFromAsset("my_image.jpg");

HelloImGui::ImageFromAsset¶

void ImageFromAsset(const char *assetPath, const ImVec2& size = ImVec2(0, 0), const ImVec2& uv0 = ImVec2(0, 0), const ImVec2& uv1 = ImVec2(1,1));

HelloImGui::ImageFromAsset(const char *assetPath, size, ...): will display a static image from the assets.

HelloImGui::ImageFromAssetWithBg¶

void ImageFromAssetWithBg(const char *assetPath, const ImVec2& size = ImVec2(0, 0), const ImVec2& uv0 = ImVec2(0, 0), const ImVec2& uv1 = ImVec2(1,1), const ImVec4& tint_col = ImVec4(1,1,1,1), const ImVec4& border_col = ImVec4(0,0,0,0));

HelloImGui::ImageFromAsset(const char *assetPath, size, ...): will display a static image from the assets, with a colored background and a border.

HelloImGui::ImageButtonFromAsset¶

bool ImageButtonFromAsset(const char *assetPath, const ImVec2& size = ImVec2(0, 0), const ImVec2& uv0 = ImVec2(0, 0), const ImVec2& uv1 = ImVec2(1,1), int frame_padding = -1, const ImVec4& bg_col = ImVec4(0,0,0,0), const ImVec4& tint_col = ImVec4(1,1,1,1));

bool HelloImGui::ImageButtonFromAsset(const char *assetPath, size, ...): will display a button using an image from the assets.

HelloImGui::ImTextureIdFromAsset¶

ImTextureID ImTextureIdFromAsset(const char *assetPath);

ImTextureID HelloImGui::ImTextureIdFromAsset(assetPath): will return a texture ID for an image loaded from the assets.

HelloImGui::ImageSizeFromAsset¶

ImVec2 ImageSizeFromAsset(const char *assetPath);

ImVec2 HelloImGui::ImageSizeFromAsset(assetPath): will return the size of an image loaded from the assets.

ImageAndSize (struct)¶

HelloImGui::ImageAndSize HelloImGui::ImageAndSizeFromAsset(assetPath): will return the texture ID and the size of an image loaded from the assets.

HelloImGui::ImageAndSizeFromAsset¶

ImageAndSize ImageAndSizeFromAsset(const char *assetPath);

HelloImGui::ImageProportionalSize¶

ImVec2 ImageProportionalSize(const ImVec2& askedSize, const ImVec2& imageSize);

ImVec2 HelloImGui::ImageProportionalSize(askedSize, imageSize): will return the displayed size of an image.

• if askedSize.x or askedSize.y is 0, then the corresponding dimension will be computed from the image size, keeping the aspect ratio.

• if askedSize.x>0 and askedSize.y> 0, then the image will be scaled to fit exactly the askedSize, thus potentially changing the aspect ratio.
  Note: this function is used internally by ImageFromAsset and ImageButtonFromAsset, so you don’t need to call it directly.

HelloImGui::FreeImageCache¶

void FreeImageCache();

HelloImGui::FreeImageCache(): clears the asset image cache shared by ImageFromAsset, ImageAndSizeFromAsset and ImageAndSizeFromEncodedData.
Inside a HelloImGui::Run() context this is called automatically at shutdown. When using imgui_md (or any of the helpers above) without Run(), the cache lives until process exit unless you call this manually before destroying your GL context.

To upload raw RGBA pixel data to a caller-owned GPU texture, see HelloImGui::CreateTextureGpuFromRgbaData() in texture_gpu.h.

hello_imgui/texture_gpu.h¶

TextureGpu (struct)¶

Opaque RAII handle owning a GPU texture.

The GPU resource is freed when the last reference to this object is dropped (no separate delete_texture call). Hold the handle in Python for as long as you want to display the texture.

Threading: must be created from the GUI thread, while a live rendering backend (OpenGL/Metal/Vulkan/DirectX11) is initialized.

hello_imgui/imgui_theme.h¶

ImGuiTheme_ (enum)¶

HelloImGui::ImGuiTheme_Name¶

const char* ImGuiTheme_Name(ImGuiTheme_ theme);

HelloImGui::ImGuiTheme_FromName¶

ImGuiTheme_ ImGuiTheme_FromName(const char* themeName);

HelloImGui::ThemeToStyle¶

ImGuiStyle ThemeToStyle(ImGuiTheme_ theme);

HelloImGui::ApplyTheme¶

void ApplyTheme(ImGuiTheme_ theme);

ImGuiThemeTweaks (struct)¶

ImGuiThemeTweaks::ImGuiThemeTweaks¶

ImGuiThemeTweaks();

ImGuiTweakedTheme (struct)¶

ImGuiTweakedTheme::ImGuiTweakedTheme¶

ImGuiTweakedTheme(ImGuiTheme_ theme = ImGuiTheme_DarculaDarker, const ImGuiThemeTweaks& tweaks = ImGuiThemeTweaks())

            : Theme(theme), Tweaks(tweaks);

HelloImGui::TweakedThemeThemeToStyle¶

ImGuiStyle TweakedThemeThemeToStyle(const ImGuiTweakedTheme& tweaked_theme);

HelloImGui::ApplyTweakedTheme¶

void ApplyTweakedTheme(const ImGuiTweakedTheme& tweaked_theme);

PushTweakedTheme() / PopTweakedTheme()¶

Push and pop a tweaked theme
Note: If you want the theme to apply globally to a window, you need to apply it
before calling ImGui::Begin
For example, within Hello ImGui, given a dockable window, you should set this option: myDockableWindow.callBeginEnd = False; And then: - call ImGuiTheme::PushTweakedTheme - call ImGui::Begin - display your content - call ImGui::End - call ImGuiTheme::PopTweakedTheme
See demo inside src/hello_imgui_demos/hello_imgui_demodocking/hello_imgui_demodocking.main.cpp: look at GuiWindowAlternativeTheme()

HelloImGui::PushTweakedTheme¶

void PushTweakedTheme(const ImGuiTweakedTheme& tweaked_theme);

HelloImGui::PopTweakedTheme¶

void PopTweakedTheme();

HelloImGui::ShowThemeTweakGui¶

bool ShowThemeTweakGui(ImGuiTweakedTheme *tweaked_theme);

Show the theme selection listbox, the theme tweak widgets, as well as ImGui::ShowStyleEditor. Returns True if modified (Warning, when using ShowStyleEditor, no info about modification is transmitted)

Some tweakable themes¶

HelloImGui::SoDark¶

ImGuiStyle SoDark(float hue);

HelloImGui::ShadesOfGray¶

ImGuiStyle ShadesOfGray(float rounding=0.f, float value_multiplier_front=1.f, float value_multiplier_bg=1.f);

HelloImGui::Darcula¶

ImGuiStyle Darcula( float rounding=1.f, float hue=-1.f, float saturation_multiplier=1.f, float value_multiplier_front=1.f, float value_multiplier_bg=1.f, float alpha_bg_transparency=1.f );

hello_imgui/hello_imgui_theme.h¶

HelloImGui::ShowThemeTweakGuiWindow¶

void ShowThemeTweakGuiWindow(bool* p_open = nullptr);

}

hello_imgui/hello_imgui_font.h¶

Font loading¶

HelloImGui::LoadFont() loads a font from the assets folder, which exists on every platform (desktop, mobile, browser), where ImGui::GetIO().Fonts->AddFontFromFileTTF() needs a file path.
Its parameters can also merge the font into the previous one, or load its color glyphs.
Fonts are loaded at their nominal size: the scaling to the screen’s DPI is applied at display time by ImGui (ImGui::GetStyle().FontScaleDpi, set by the runner).

FontLoadingParams (struct)¶

Font loading parameters: several options are available (color, merging, range, ...)

HelloImGui::LoadFont¶

ImFont* LoadFont( const std::string & fontFilename, float fontSize, const FontLoadingParams & params = __srcmlcpp_brace_init__());

HelloImGui::LoadFontTTF¶

ImFont* LoadFontTTF( const std::string & fontFilename, float fontSize, ImFontConfig config = ImFontConfig() );

Loads a font from the assets, with an ImGui font config

HelloImGui::LoadFontTTF_WithFontAwesomeIcons¶

ImFont* LoadFontTTF_WithFontAwesomeIcons( const std::string & fontFilename, float fontSize, ImFontConfig configFont = ImFontConfig() );

Loads a font from the assets and merges the icons of Font Awesome into it (Font Awesome 4 or 6, as set by RunnerParams.callbacks.defaultIconFont)

hello_imgui/runner_params.h¶

PlatformBackendType (enum)¶

Platform backend type (SDL, GLFW)
They are listed in the order of preference when FirstAvailable is selected.

RendererBackendType (enum)¶

Rendering backend type (OpenGL3, Metal, Vulkan, DirectX11, DirectX12)
They are listed in the order of preference when FirstAvailable is selected.

HelloImGui::PlatformBackendTypeToString¶

std::string PlatformBackendTypeToString(PlatformBackendType platformBackendType);

HelloImGui::RendererBackendTypeToString¶

std::string RendererBackendTypeToString(RendererBackendType rendererBackendType);

IniFolderType (enum)¶

IniFolderType is an enum which describes where is the base path to store the ini file for the application settings.

You can use IniFolderLocation(iniFolderType) to get the corresponding path.

RunnerParams contains the following members, which are used to compute the ini file location:

    iniFolderType           (IniFolderType::CurrentFolder by default)
    iniFilename             (empty string by default)

iniFilename_useAppWindowTitle
    (True by default: iniFilename is derived from
     appWindowParams.windowTitle)

iniFilename may contain a subfolder (which will be created inside the iniFolderType folder if needed)

HelloImGui::IniFolderLocation¶

std::string IniFolderLocation(IniFolderType iniFolderType);

Returns the path corresponding to the given IniFolderType

FpsIdlingMode (enum)¶

FpsIdlingMode is an enum that describes the different modes of idling when rendering the GUI.

• Sleep:
  The application sleeps when idling in order to reduce CPU usage.

• EarlyReturn:
  Rendering returns immediately when idling.
  This is designed for event-driven or real-time applications, including Jupyter/async usage and web applications.
  Avoid using EarlyReturn inside a tight CPU loop without pauses, as it may cause excessive CPU consumption.

• Auto:
  Use platform-specific default behavior.
  On most native platforms, it will sleep.
  On Emscripten, Render() will always return immediately to avoid blocking the main browser thread.

Note: you can override the default behavior by explicitly choosing Sleep or EarlyReturn.

FpsIdling (struct)¶

FpsIdling is a struct that contains parameters controlling the application’s frame pacing, idling behavior, and performance.

It provides tools to:

• lower CPU/GPU usage during inactivity,

• control maximum refresh speed,

• enable/disable synchronization to the monitor refresh rate,

• adapt frame pacing for special environments (notebooks, web, etc.).

HelloImGui::IniSettingsLocation¶

std::optional<std::string> IniSettingsLocation(const RunnerParams& runnerParams);

IniSettingsLocation returns the path to the ini file for the application settings.

HelloImGui::HasIniSettings¶

bool HasIniSettings(const RunnerParams& runnerParams);

HasIniSettings returns True if the ini file for the application settings exists.

HelloImGui::DeleteIniSettings¶

void DeleteIniSettings(const RunnerParams& runnerParams);

DeleteIniSettings deletes the ini file for the application settings.

SimpleRunnerParams (struct)¶

SimpleRunnerParams is a struct that contains simpler params adapted for simple use cases.
For example, this is sufficient to run an application: ```cpp None MyGui() { ImGui::Text(“Hello, world”); if (ImGui::Button(“Exit”)) HelloImGui::GetRunnerParams()->appShallExit = True; }

int main(){
    auto params = HelloImGui::SimpleRunnerParams {
        .guiFunction = MyGui, .windowSizeAuto = True, .windowTitle = "Example"
    };
    HelloImGui::Run(params);
}
```

SimpleRunnerParams::ToRunnerParams¶

RunnerParams ToRunnerParams() const;

hello_imgui/app_window_params.h¶

FullScreenMode (enum)¶

WindowSizeState (enum)¶

WindowPositionMode (enum)¶

EmscriptenKeyboardElement (enum)¶

WindowSizeMeasureMode (enum)¶

WindowGeometry (struct)¶

WindowGeometry is a struct that defines the window geometry.

EdgeInsets (struct)¶

If there is a notch on the iPhone, you should not display inside these insets

AppWindowParams (struct)¶

AppWindowParams is a struct that defines the application window display params.
See https://raw.githubusercontent.com/pthom/hello_imgui/master/src/hello_imgui/doc_src/hello_imgui_diagram.jpg for details.

hello_imgui/screen_bounds.h¶

Screen coordinates and high DPI screens¶

ScreenPosition and ScreenSize are in “Screen Coordinates”:
Screen coordinates might differ from real pixel on high dpi screens; but this depends on the OS.

• For example, on apple a retina screenpixel size 3456x2052 might be seen as 1728x1026 in screen coordinates

• Under windows, ScreenCoordinates correspond to pixels, even on high density screens

ScreenBounds (struct)¶

ScreenBounds::TopLeftCorner¶

ScreenPosition TopLeftCorner() const;

ScreenBounds::BottomRightCorner¶

ScreenPosition BottomRightCorner() const;

ScreenBounds::Center¶

ScreenPosition Center() const;

ScreenBounds::Contains¶

bool Contains(ScreenPosition pixel) const;

ScreenBounds::WinPositionCentered¶

ScreenPosition WinPositionCentered(ScreenSize windowSize) const;

ScreenBounds::DistanceFromPixel¶

int DistanceFromPixel(ScreenPosition point) const;

ScreenBounds::EnsureWindowFitsThisMonitor¶

ScreenBounds EnsureWindowFitsThisMonitor(ScreenBounds windowBoundsOriginal) const;

hello_imgui/imgui_window_params.h¶

DefaultImGuiWindowType (enum)¶

DefaultImGuiWindowType is an enum class that defines whether a full screen background window is provided or not

ImGuiWindowParams (struct)¶

ImGuiWindowParams is a struct that defines the ImGui inner windows params
These settings affect the imgui inner windows inside the application window.
In order to change the application window settings, change the AppWindowsParams

hello_imgui/runner_callbacks.h¶

HelloImGui::EmptyVoidFunction¶

inline VoidFunction EmptyVoidFunction();

                      hello_imgui/runner_callbacks.h continued                                               //

HelloImGui::SequenceFunctions¶

VoidFunction SequenceFunctions(const VoidFunction& f1, const VoidFunction& f2);

SequenceFunctions: returns a function that will call f1 and f2 in sequence

HelloImGui::EmptyEventCallback¶

inline AnyEventCallback EmptyEventCallback();

HelloImGui::EmptyConfirmExitCallback¶

inline ConfirmExitCallback EmptyConfirmExitCallback();

MobileCallbacks (struct)¶

MobileCallbacks is a struct that contains callbacks that are called by the application when running under “Android, iOS and WinRT”.
These events are specific to mobile and embedded devices that have different requirements from your usual desktop application.
These events must be handled quickly, since often the OS needs an immediate response and will terminate your process shortly after sending the event if you do not handle them appropriately.
On mobile devices, it is not possible to “Quit” an application, it can only be put on Pause.

EdgeToolbarType (enum)¶

EdgeToolbarType: location of an Edge Toolbar

EdgeToolbarOptions (struct)¶

EdgeToolbar (struct)¶

EdgeToolbar :a toolbar that can be placed on the edges of the App window
It will be placed in a non-dockable window

HelloImGui::AllEdgeToolbarTypes¶

std::vector<EdgeToolbarType> AllEdgeToolbarTypes();

HelloImGui::EdgeToolbarTypeName¶

std::string EdgeToolbarTypeName(EdgeToolbarType e);

DefaultIconFont (enum)¶

HelloImGui can optionally merge an icon font (FontAwesome 4 or 6) to the default font

• you need to include manually icons_font_awesome_4.h or icons_font_awesome_6.h:
  #include “hello_imgui/icons_font_awesome_6.h” or #include “hello_imgui/icons_font_awesome_4.h”

RunnerCallbacks (struct)¶

RunnerCallbacks is a struct that contains the callbacks that are called by the application

RunnerCallbacks::AddEdgeToolbar¶

void AddEdgeToolbar(EdgeToolbarType edgeToolbarType, VoidFunction guiFunction, const EdgeToolbarOptions& options = EdgeToolbarOptions());

AddEdgeToolbar: Add a toolbar that can be placed on the edges of the App window

RunnerCallbacks::EnqueuePostInit¶

void EnqueuePostInit(const VoidFunction& callback);

EnqueuePostInit: Add a function that will be called once after OpenGL and ImGui are inited, but before the backend callback are initialized. (this will modify the PostInit callback by appending the new callback (using SequenceFunctions)

RunnerCallbacks::EnqueueBeforeExit¶

void EnqueueBeforeExit(const VoidFunction& callback);

EnqueueBeforeExit: Add a function that will be called once before exiting (when OpenGL and ImGui are still inited) (this will modify the BeforeExit callback by appending the new callback (using SequenceFunctions)

HelloImGui::AppendCallback¶

VoidFunction AppendCallback(const VoidFunction& previousCallback, const VoidFunction& newCallback);

AppendCallback: legacy synonym for SequenceFunctions

hello_imgui/docking_params.h¶

HelloImGui makes it easy to use dockable windows¶

(based on ImGui docking branch).
You can define several layouts and switch between them: each layout which will remember the user modifications and the list of opened windows
HelloImGui will then provide a “View” menu with options to show/hide the dockable windows, restore the default layout, switch between layouts, etc.

• Source for this example: https://github.com/pthom/hello_imgui/tree/master/src/hello_imgui_demos/hello_imgui_demodocking

• Video explanation on YouTube (5 minutes)
  The different available layouts are provided inside RunnerParams via the two members below:

struct RunnerParams
{
   ...
   // default layout of the application
   DockingParams dockingParams;
   // optional alternative layouts
   std::vector<DockingParams> alternativeDockingLayouts;
   ...
};

And DockingParams contains members that define a layout:

struct DockingParams
{
   // displayed name of the layout
   std::string layoutName = "Default";
   // list of splits
   // (which define spaces where the windows will be placed)
   std::vector<DockingSplit> dockingSplits;
   // list of windows
   // (with their gui code, and specifying in which space they will be placed)
   std::vector<DockableWindow> dockableWindows;
   ...
};

Inside DockingParams, the member dockingSplits specifies the layout, and the member dockableWindows specifies the list of dockable windows, along with their default location, and their code (given by lambdas).
Below is an example that shows how to instantiate a layout:

1. First, define the docking splits:

std::vector<HelloImGui::DockingSplit> CreateDefaultDockingSplits()
{
   //   Here, we want to split "MainDockSpace" (which is provided automatically)
   //   into three zones, like this:
   //    ___________________________________________
   //    |        |                                |
   //    | Command|                                |
   //    | Space  |    MainDockSpace               |
   //    |        |                                |
   //    |        |                                |
   //    |        |                                |
   //    -------------------------------------------
   //    |     MiscSpace                           |
   //    -------------------------------------------
   //
   // add a space named "MiscSpace" whose height is 25% of the app height.
   // This will split the preexisting default dockspace "MainDockSpace" in two parts.
   HelloImGui::DockingSplit splitMainMisc;
   splitMainMisc.initialDock = "MainDockSpace";
   splitMainMisc.newDock = "MiscSpace";
   splitMainMisc.direction = ImGuiDir_Down;
   splitMainMisc.ratio = 0.25;
   // Then, add a space to the left which occupies a column
   // whose width is 25% of the app width
   HelloImGui::DockingSplit splitMainCommand;
   splitMainCommand.initialDock = "MainDockSpace";
   splitMainCommand.newDock = "CommandSpace";
   splitMainCommand.direction = ImGuiDir_Left;
   splitMainCommand.ratio = 0.25;
   std::vector<HelloImGui::DockingSplit> splits {splitMainMisc, splitMainCommand};
   return splits;
}

2. Then, define the dockable windows:

std::vector<HelloImGui::DockableWindow> CreateDockableWindows(AppState& appState)
{
   // A Command panel named "Commands" will be placed in "CommandSpace".
   // Its Gui is provided calls "CommandGui"
   HelloImGui::DockableWindow commandsWindow;
   commandsWindow.label = "Commands";
   commandsWindow.dockSpaceName = "CommandSpace";
   commandsWindow.GuiFunction = [&] { CommandGui(appState); };
   // A Log window named "Logs" will be placed in "MiscSpace".
   // It uses the HelloImGui logger gui
   HelloImGui::DockableWindow logsWindow;
   logsWindow.label = "Logs";
   logsWindow.dockSpaceName = "MiscSpace";
   logsWindow.GuiFunction = [] { HelloImGui::LogGui(); };
   ...
}

3. Finally, fill the RunnerParams

HelloImGui::RunnerParams runnerParams;
runnerParams.imGuiWindowParams.defaultImGuiWindowType =
   HelloImGui::DefaultImGuiWindowType::ProvideFullScreenDockSpace;
runnerParams.dockingParams.dockingSplits = CreateDefaultDockingSplits();
runnerParams.dockingParams.dockableWindows = CreateDockableWindows();
HelloImGui::Run(runnerParams);

DockingSplit (struct)¶

DockingSplit is a struct that defines the way the docking splits should be applied on the screen in order to create new Dock Spaces.
DockingParams contains a vector<DockingSplit> in order to partition the screen at your will.

DockingSplit::DockingSplit¶

DockingSplit(const DockSpaceName& initialDock_ = "", const DockSpaceName& newDock_ = "", ImGuiDir direction_ = ImGuiDir_Down, float ratio_ = 0.25f, ImGuiDockNodeFlags nodeFlags_ = ImGuiDockNodeFlags_None) : initialDock(initialDock_), newDock(newDock_), direction(direction_), ratio(ratio_), nodeFlags(nodeFlags_);

Constructor

DockableWindow (struct)¶

DockableWindow is a struct that represents a window that can be docked.

DockableWindow::DockableWindow¶

DockableWindow( const std::string & label_ = "", const DockSpaceName & dockSpaceName_ = "", const VoidFunction guiFunction_ = EmptyVoidFunction(), bool isVisible_ = true, bool canBeClosed_ = true) : label(label_), dockSpaceName(dockSpaceName_), GuiFunction(guiFunction_), isVisible(isVisible_), canBeClosed(canBeClosed_);

--------------- Constructor ------------------------------
Constructor

DockingLayoutCondition (enum)¶

DockingParams (struct)¶

DockingParams contains all the settings concerning the docking:

• list of splits

• list of dockable windows

DockingParams::dockableWindowOfName¶

DockableWindow * dockableWindowOfName(const std::string& name);

DockableWindow * dockableWindowOfName(const std::string & name): returns a pointer to a dockable window

DockingParams::focusDockableWindow¶

bool focusDockableWindow(const std::string& windowName);

bool focusDockableWindow(const std::string& name): will focus a dockable window (and make its tab visible if needed)

DockingParams::dockSpaceIdFromName¶

std::optional<ImGuiID> dockSpaceIdFromName(const std::string& dockSpaceName);

optional\<ImGuiID> dockSpaceIdFromName(const std::string& dockSpaceName): returns the ImGuiID corresponding to the dockspace with this name

RunnerParams (struct)¶

RunnerParams contains the settings and callbacks needed to run an application.

hello_imgui/backend_pointers.h¶

BackendPointers (struct)¶

BackendPointers is a struct that contains optional pointers to the backend implementations (for SDL and GLFW).

These pointers will be filled when the application starts, and you can use them to customize your application behavior using the selected backend.

Note: If using the Metal, Vulkan or DirectX rendering backend, you can find some interesting pointers inside src/hello_imgui/internal/backend_impls/rendering_metal.h src/hello_imgui/internal/backend_impls/rendering_vulkan.h src/hello_imgui/internal/backend_impls/rendering_dx11.h src/hello_imgui/internal/backend_impls/rendering_dx12.h

hello_imgui/renderer_backend_options.h¶

OpenGlOptions (struct)¶

OpenGlOptions contains advanced options used at the startup of OpenGL.
These parameters are reserved for advanced users.
By default, Hello ImGui will select reasonable default values, and these parameters are not used.
Use at your own risk, as they make break the multi-platform compatibility of your application!
All these parameters are platform dependent.
For real multiplatform examples, see hello_imgui/src/hello_imgui/internal/backend_impls/opengl_setup_helper/opengl_setup_glfw.cpp and hello_imgui/src/hello_imgui/internal/backend_impls/opengl_setup_helper/opengl_setup_sdl.cpp

How to set those values manually: you may set them manually: (1) Either by setting them programmatically in your application (set their values in runnerParams.rendererBackendOptions.openGlOptions) (2) Either by setting them in a hello_imgui.ini file in the current folder, or any of its parent folders. (this is useful when you want to set them for a specific app or set of apps, without modifying the app code)
See hello_imgui/hello_imgui_example.ini for an example of such a file.
Note: if several methods are used, the order of priority is (1) > (2)

HelloImGui::hasEdrSupport¶

bool hasEdrSupport();

bool hasEdrSupport():
Check whether extended dynamic range (EDR), i.e. the ability to reproduce intensities exceeding the standard dynamic range from 0.0-1.0, is supported.

To leverage EDR support, you need to set requestFloatBuffer=True in RendererBackendOptions.

This currently returns False on all backends except Metal, where it checks whether this is supported on the current displays.
On the other backends, a display’s capabilities can only be queried once a window exists, which is too late here: set requestFloatBuffer=True and read it back instead (see below).

RendererBackendOptions (struct)¶

RendererBackendOptions is a struct that contains options for the renderer backend (Metal, Vulkan, DirectX, OpenGL)

OpenGlOptionsFilled_ (struct)¶

(Private structure, not part of the public API)
OpenGlOptions after selecting the default platform-dependent values + after applying the user settings

Submodule imgui_default_settings¶

imgui_default_settings (struct)¶

imgui_default_settings::LoadDefaultFont_WithFontAwesomeIcons¶

void LoadDefaultFont_WithFontAwesomeIcons();

LoadDefaultFont_WithFontAwesome will load from assets/fonts and reverts to the imgui embedded font if not found.

imgui_default_settings::SetupDefaultImGuiConfig¶

void SetupDefaultImGuiConfig();

imgui_default_settings::SetupDefaultImGuiStyle¶

void SetupDefaultImGuiStyle();

    }

Submodule manual_render¶

manual_render (struct)¶

manual_render::SetupFromRunnerParams¶

void SetupFromRunnerParams(RunnerParams& runnerParams);

Initializes the rendering with the full customizable RunnerParams.
This will initialize the platform backend (SDL, Glfw, etc.) and the rendering backend (OpenGL, Vulkan, etc.).
A reference to the user’s RunnerParams is kept internally (similar to HelloImGui::Run).

HelloImGui::ManualRender is a namespace that groups functions, allowing fine-grained control over the rendering process:

• It is customizable like HelloImGui::Run: initialize it with RunnerParams or SimpleRunnerParams

• ManualRender::Render() will render the application for one frame:

• Ensure that ManualRender::Render() is triggered regularly (e.g., through a loop or other mechanism) to maintain responsiveness. This method must be called on the main thread.
  A typical use case is:
  C++ cpp HelloImGui::RunnerParams runnerParams; runnerParams.callbacks.ShowGui = ...; // your GUI function // Optionally, choose between Sleep, EarlyReturn, or Auto for fps idling mode: // runnerParams.fpsIdling.fpsIdlingMode = HelloImGui::FpsIdlingMode::Sleep; // or EarlyReturn, Auto HelloImGui::ManualRender::SetupFromRunnerParams(runnerParams); while (!HelloImGui::GetRunnerParams()->appShallExit) { HelloImGui::ManualRender::Render(); } HelloImGui::ManualRender::TearDown(); Python: python runnerParams = HelloImGui.RunnerParams() runnerParams.callbacks.show_gui = ... # your GUI function while not hello_imgui.get_runner_params().app_shall_exit: hello_imgui.manual_render.render() hello_imgui.manual_render.tear_down() Notes:

1. Depending on the configuration (runnerParams.fpsIdling.fpsIdlingMode), HelloImGui may enter an idle state to reduce CPU usage, if no events are received (e.g., no input or interaction).
   In this case, Render() will either sleep or return immediately.
   By default,

   • On Emscripten, ManualRender::Render() will return immediately to avoid blocking the main thread.

   • On other platforms, it will sleep

2. If initialized with RunnerParams, a reference to the user’s RunnerParams is kept (which can be accessed with HelloImGui::GetRunnerParams()).

manual_render::SetupFromSimpleRunnerParams¶

void SetupFromSimpleRunnerParams(const SimpleRunnerParams& simpleParams);

Initializes the rendering with SimpleRunnerParams.
This will initialize the platform backend (SDL, Glfw, etc.) and the rendering backend (OpenGL, Vulkan, etc.).

manual_render::SetupFromGuiFunction¶

void SetupFromGuiFunction( const VoidFunction& guiFunction, const std::string& windowTitle = "", bool windowSizeAuto = false, bool windowRestorePreviousGeometry = false, const ScreenSize& windowSize = DefaultWindowSize, float fpsIdle = 10.f, bool topMost = false );

Initializes the renderer with a simple GUI function and additional parameters.
This will initialize the platform backend (SDL, Glfw, etc.) and the rendering backend (OpenGL, Vulkan, etc.).

manual_render::Render¶

void Render();

Renders the current frame. Should be called regularly to maintain the application’s responsiveness.

manual_render::TearDown¶

void TearDown();

Tears down the renderer and releases all associated resources.
This will release the platform backend (SDL, Glfw, etc.) and the rendering backend (OpenGL, Vulkan, etc.).
After calling TearDown(), the InitFromXXX can be called with new parameters.

}

HelloImGui::image_and_size_from_encoded_data¶

Create a texture from encoded image data (PNG, JPEG, BMP, GIF, etc.).

• data: bytes containing the encoded image

• cache_key: if non-empty, the texture is cached and reused on subsequent calls with the same key
  Returns an ImageAndSize with texture_id and size.

HelloImGui::create_texture_gpu_from_rgba_data¶

Upload an HxWx4 uint8 RGBA numpy array to a new GPU texture.

• rgba must be a contiguous numpy array of dtype uint8 with shape (height, width, 4). The pixel data is read once during the upload; the numpy array does not need to outlive the call.

• Returns an owning TextureGpu handle. Drop the last reference to free the GPU resource.

Threading: must be called from the GUI thread, while a live rendering backend is initialized (i.e. inside the gui callback, or after hello_imgui.run has set up the backend).

hello_imgui/dpi_aware.h¶

DpiAwareParams (struct)¶

Hello ImGui will try its best to automatically handle DPI scaling for you.

Parameter to change the scaling behavior:

• dpiWindowSizeFactor: factor by which window size should be multiplied
  By default, Hello ImGui will compute it automatically, when it is set to 0.

How to set manually:
If it fails (i.e. your window and/or fonts are too big or too small), you may set them manually: (1) Either by setting them programmatically in your application (set their values in runnerParams.dpiAwareParams) (2) Either by setting them in a hello_imgui.ini file. See hello_imgui/hello_imgui_example.ini for more info
Note: if several methods are used, the order of priority is (1) > (2)

For more information, see the documentation on DPI handling, here: https://pthom.github.io/hello_imgui/book/doc_api.html#handling-screens-with-high-dpi

HelloImGui::EmToVec2¶

ImVec2 EmToVec2(float x, float y);

ImVec2 EmToVec2(ImVec2 v);

Special care must be taken in order to correctly handle screen with high DPI (for example, almost all recent laptops screens).
Using ImVec2 with fixed values is almost always a bad idea if you intend your application to be used on high DPI screens!
Otherwise, widgets might be misplaced or too small on different screens and/or OS.
Instead, you should use scale your widgets and windows relatively to the font size, as is done with the em CSS Unit.
HelloImGui::EmToVec2() returns an ImVec2 that you can use to size or place your widgets in a DPI independent way.
Values are in multiples of the font size (i.e. as in the em CSS unit).

HelloImGui::EmSize¶

float EmSize();

float EmSize(float nbLines);

HelloImGui::EmSize() returns the visible font size on the screen.

HelloImGui::PixelsToEm¶

ImVec2 PixelsToEm(ImVec2 pixels);

HelloImGui::PixelToEm() converts a Vec2 in pixels coord to a Vec2 in em units

HelloImGui::PixelSizeToEm¶

float PixelSizeToEm(float pixelSize);

HelloImGui::PixelSizeToEm() converts a size in pixels coord to a size in em units

HelloImGui::GetDpiAwareParams¶

DpiAwareParams* GetDpiAwareParams();

Returns the current DpiAwareParams, which are used for font loading and window size scaling

HelloImGui::DpiWindowSizeFactor¶

float DpiWindowSizeFactor();

DpiWindowSizeFactor() is the factor by which window size should be multiplied to get a similar visible size on different OSes.
It returns ApplicationScreenPixelPerInch / 96 under windows and linux. Under macOS, it will return 1.

Legacy API, you should use RunnerParams.dpiAwareParams instead

hello_imgui/remote_params.h¶

RemoteParams (struct)¶

RemoteParams is a struct that contains the settings for displaying the application on a remote device. using https://github.com/sammyfreg/netImgui or using https://github.com/ggerganov/imgui-ws
Those features are experimental and not supported with the standard version of HelloImGui,

hello_imgui/hello_imgui_widgets.h¶

HelloImGui::BeginGroupColumn¶

void BeginGroupColumn();

calls ImGui::BeginGroup()

HelloImGui::EndGroupColumn¶

void EndGroupColumn();

calls ImGui::EndGroup() + ImGui::SameLine()

HelloImGui::WidgetWithResizeHandle¶

ImVec2 WidgetWithResizeHandle( const char* id, VoidFunction widgetGuiFunction, float handleSizeEm = 1.0f, std::optional<VoidFunction> onItemResized = std::nullopt, std::optional<VoidFunction> onItemHovered = std::nullopt );

WidgetWithResizeHandle: adds a resize handle to a widget
Example usage with ImPlot:
None gui()

       {
           static ImVec2 widget_size(200, 200);

       auto myWidgetFunction = []()

           {
               if (ImPlot::BeginPlot("My Plot", widget_size)) {
                   ImPlot::PlotLine("My Line", x.data(), y.data(), 1000);
                   ImPlot::EndPlot();
               }
           };
           widget_size = widget_with_resize_handle("plot", myWidgetFunction);
       }

InputTextData (struct)¶

InputTextResizable: displays a resizable text input widget

The InputTextResizable widget allows you to create a text input field that can be resized by the user.
It supports both single-line and multi-line text input.
Note: the size of the widget is expressed in em units.
Usage example:
C++: cpp // Somewhere in the application state (static) InputTextData textInput("My text", True, ImVec2(10, 3)); // In the GUI function bool changed = InputTextResizable("Label", &textInput); Python: python # Somewhere in the application state text_input = hello_imgui.InputTextData("My text", multiline=True, size_em=ImVec2(10, 3)) # In the GUI function changed = hello_imgui.input_text_resizable("Label", text_input)

InputTextData::InputTextData¶

InputTextData(const std::string& text = "", bool multiline = false, ImVec2 size_em = ImVec2(0, 0)) : Text(text), Multiline(multiline), SizeEm(size_em);

HelloImGui::InputTextResizable¶

bool InputTextResizable(const char* label, InputTextData* textInput);

HelloImGui::InputTextDataToDict¶

DictTypeInputTextData InputTextDataToDict(const InputTextData& data);

HelloImGui::InputTextDataFromDict¶

InputTextData InputTextDataFromDict(const DictTypeInputTextData& dict);

to/from string¶

HelloImGui::InputTextDataToString¶

std::string InputTextDataToString(const InputTextData& data);

HelloImGui::InputTextDataFromString¶

InputTextData InputTextDataFromString(const std::string& str);