Skip to content

Latest commit

 

History

History
381 lines (277 loc) · 15.2 KB

hello_imgui_api.md

File metadata and controls

381 lines (277 loc) · 15.2 KB

API

HelloImGui::Run()

See hello_imgui.h.

HelloImGui::Run() will run an application with a single call.

Two 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(guiFunction, windowSize, windowTitle): simple signature in order to start a simple application with ease.

Runner params

See runner_params.h.

Diagram

RunnerParams contains all the settings and callbacks in order to run an application. The diagram below summarize all the possible settings and callbacks (which are explained in detail later in this document).

a

RunnerParams

RunnerParams is a struct that contains all the settings and callbacks needed to run an application.

Members:

  • callbacks: see runner_callbacks.h. callbacks.ShowGui() will render the gui, ShowMenus() will show the menus, etc.
  • appWindowParams: see app_window_params.h. application Window Params (position, size, title)
  • imGuiWindowParams: see imgui_window_params.h. imgui window params (use docking, showMenuBar, ProvideFullScreenWindow, etc)
  • dockingParams: see docking_params.h. dockable windows content and layout
  • appShallExit: bool, default=false. will be set to true by the app when exiting. Note: 'appShallExit' has no effect on Mobile Devices (iOS, Android) and under emscripten, since these apps shall not exit.
  • fps: _int, default = 0` when applicable, set the application refresh rate (only used on emscripten for the moment: 0 stands for "let the app or the browser decide")

Runner callbacks

See runner_callbacks.h.

RunnerCallbacks

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

Members

  • ShowGui: VoidFunction, default=empty. Fill it with a function that will add your widgets.

  • ShowMenus: VoidFunction, default=empty. A function that will render your menus. Fill it with a function that will add ImGui menus by calling: ImGui::BeginMenu(...) / ImGui::MenuItem(...) / ImGui::EndMenu()

    Notes:

    • you do not need to call ImGui::BeginMenuBar and ImGui::EndMenuBar
    • Some default menus can be provided: see ImGuiWindowParams options (showMenuBar, showMenu_App_QuitAbout, showMenu_View)

  • ShowStatus: VoidFunction, default=empty. A function that will add items to the status bar. Use small items (ImGui::Text for example), since the height of the status is 30. Also, remember to call ImGui::SameLine() between items.

  • PostInit: VoidFunction, default=empty. You can here add a function that will be called once after OpenGL and ImGui are inited

  • AnyBackendEventCallback: AnyBackendCallback, default=empty. Callbacks for events from a specific backend. Only implemented for SDL, where the event will be of type 'SDL_Event *' This callback should return true if the event was handled and shall not be processed further.

  • LoadAdditionalFonts: VoidFunction, default=_LoadDefaultFont_WithFontAwesome. A function that is called when fonts are ready to be loaded. By default, LoadDefaultFont_WithFontAwesome is called but you can copy-customize it.

  • SetupImGuiConfig: VoidFunction, default=_ImGuiDefaultSettings::SetupDefaultImGuiConfig. If needed, change ImGui config via SetupImGuiConfig (enable docking, gamepad, etc)

  • SetupImGuiStyle: VoidFunction, default=_ImGuiDefaultSettings::SetupDefaultImGuiConfig. If needed, setup your own style by providing your own SetupImGuiStyle callback

  • mobileCallbacks: MobileCallbacks. Callbacks that are called by the application when running under "Android, iOS and WinRT". Notes:

    • 'mobileCallbacks' is present only if the target device is a mobile device (iOS, Android). Use #ifdef HELLOIMGUI_MOBILEDEVICE to detect this.
    • These events are currently handled only with SDL backend.

VoidFunctionPointer can hold any void(void) function.

using VoidFunction = std::function<void(void)>

AnyEventCallback can hold any bool(void *) function. It is designed to handle callbacks for a specific backend.

using AnyEventCallback = std::function<bool(void * backendEvent)>

MobileCallbacks

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 than 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 apprpriately.

Note: on mobile devices, it is not possible to "Quit" an application, it can only be put on Pause.

  • OnDestroy: VoidFunction, default=empty. The application is being terminated by the OS.
  • OnLowMemory: VoidFunction, default=empty. The application is low on memory, free memory if possible.
  • OnPause: VoidFunction, default=empty. The application is about to enter the background.
  • OnResume: VoidFunction, default=empty. The application is has come to foreground and is now interactive.

Note: 'OnPause' and 'OnResume' are called twice consecutively under iOS (before and after entering background or foreground).

Application window params

See app_window_params.h.

AppWindowParams is a struct that defines the application window display params.

Members:

  • windowTitle: string, default="". Title of the application window
  • windowSize: ImVec2, default (800,600). Size of the window.
  • maximized: bool, default=false. If this boolean flag is true, the application window will occupy the full space of the primary screen
  • fullScreen: bool, default=false. If this boolean flag is true, the application window will be full screen, with no decorations. Note: on a mobile device, the application will always be full screen.
  • windowPosition: ImVec2, default=(-11000, -1). Position of the window if x >= -1000, else let the OS decide

ImGui window params

See imgui_window_params.h.

ImGuiWindowParams

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

Members:

  • defaultImGuiWindowType: DefaultImGuiWindowType, default=ProvideFullScreenWindow. By default, a full window is provided in the background. You can still add windows on top of it, since the Z-order of this background window is always behind

  • backgroundColor: ImVec4, default=ImVec4(0.45f, 0.55f, 0.60f, 1.00f). This is the "clearColor", only visible is defaultImGuiWindowType is NoDefaultWindow.

  • showMenuBar: bool, default=false. Show Menu bar on top of imgui main window You can customize the menu via RunnerCallbacks.ShowMenus()

  • showMenu_App: bool, default=true. If menu bar is shown, include or not the default app menu (with Quit button)

  • showMenu_View: bool, default=true. If menu bar is shown, include or not the default View menu, that enables to change the layout and set the docked windows and status bar visibility)

  • showStatusBar: bool, default=false. Flag that enable to show a Status bar at the bottom. You can customize the status bar via RunnerCallbacks.ShowStatus()

  • showStatus_Fps: bool, default=true. If set, display the FPS in the status bar.

  • configWindowsMoveFromTitleBarOnly: bool, default=true. Make windows only movable from the title bar

Default window types

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

Values:

  • ProvideFullScreenWindow: a full window is provided in the background
  • ProvideFullScreenDockSpace: a full screen dockspace is provided in the background
  • NoDefaultWindow: No default window is provided (except for ImGui's default "debug" window)

Applications assets

See hello_imgui_assets.h.

Assets Files structure

Assets located beside the application CMakeLists are embedded automatically.

For example, you can have the following project structure:

my_app/
├── CMakeLists.txt        # Your app's CMakeLists
├── assets/               # Its assets: for mobile devices and emscripten
│   └── fonts/            # they are embedded automatically by hello_imgui_add_app.cmake
│       └── my_font.ttf
├── my_app.main.cpp       # Its source code

Then you can load the asset "fonts/my_font.ttf", on all platforms.

Load Assets as data buffer

  • AssetFileData LoadAssetFileData(const char *assetPath) will load an entire asset file into memory. This works on all platforms, including android.
   struct AssetFileData
   {
       void * data = nullptr;
       size_t dataSize = 0;
   };

  • FreeAssetFileData(AssetFileData * assetFileData) will free the memory.

    Note about ImGui: "ImGui::GetIO().Fonts->AddFontFromMemoryTTF" takes ownership of the data and will free the memory for you.

Get assets path

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 cannot use standard file operations! Use LoadAssetFileData instead

Docking

See docking_params.h.

Docking Params: Example usage

Docking params: Example usage

HelloImGui::RunnerParams runnerParams;
runnerParams.imGuiWindowParams.defaultImGuiWindowType =
    HelloImGui::DefaultImGuiWindowType::ProvideFullScreenDockSpace;

runnerParams.dockingParams.dockingSplits =
{
    // First, add a bottom space whose height is 25% of the app height
    // This will split the preexisting default dockspace "MainDockSpace"
    // in two parts.
    { "MainDockSpace", "BottomSpace", ImGuiDir_Down, 0.25 },
    // Then, add a space to the left which occupies a column
    // whose width is 25% of the app height
    { "MainDockSpace", "LeftSpace", ImGuiDir_Left, 0.25 }
    // We now have three spaces: "MainDockSpace", "BottomSpace", and "LeftSpace"
};
runnerParams.dockingParams.dockableWindows =
{
    // A Window named "Main" will be placed in "MainDockSpace".
    // Its Gui is provided by the VoidFunction "MainGui"
    {"Main", "MainDockSpace", MainGui},
    // A Log  window named "Logs" will be placed in "BottomSpace".
    // Its Gui is provided by the VoidFunction "ShowLogs"
    {"Logs", "BottomSpace", ShowLogs},
    // A Command panel named "Commands" will be placed in "LeftSpace".
    // Its Gui is provided by the VoidFunction "ShowCommandsPanel"
    {"Commands", "LeftSpace", ShowCommandsPanel}
};

runnerParams.imGuiWindowParams.showMenuBar = true;
runnerParams.imGuiWindowParams.showStatusBar = true;

HelloImGui::Run(runnerParams);

Docking Splits

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.

Members:

  • initialDock: DockSpaceName (aka string)

    id of the space that should be split. At the start, there is only one Dock Space named "MainDockSpace". You should start by partitioning this space, in order to create a new dock space.

  • newDock: DockSpaceName (aka string). id of the new dock space that will be created

  • direction: ImGuiDir_ (enum with ImGuiDir_Down, ImGuiDir_Down, ImGuiDir_Left, ImGuiDir_Right). Direction where this dock space should be created

  • ratio: float, default=0.25f. Ratio of the initialDock size that should be used by the new dock space

Dockable window

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

Members:

  • label: string. Title of the window.
  • dockSpaceName: DockSpaceName (aka string). Id of the dock space where this window should initialy be placed
  • GuiFunction: VoidFuntion. Any function that will render this window's Gui.
  • isVisible: bool, default=true. Flag that indicates whether this window is visible or not.
  • canBeClosed: bool, default=true. Flag that indicates whether the user can close this window.
  • callBeginEnd: bool, default=true. Flag that indicates whether ImGui::Begin and ImGui::End calls should be added automatically (with the given "label"). Set to false if you want to call ImGui::Begin/End yourself
  • includeInViewMenu: bool, default=true. Flag that indicates whether this window should be mentioned in the view menu.
  • imGuiWindowFlags: ImGuiWindowFlags, default=0. Window flags, see enum ImGuiWindowFlags_
  • windowSize: ImVec2, default=(0.f, 0.f) (i.e let the app decide). Window size (unused if docked)
  • windowSizeCondition: ImGuiCond, default=ImGuiCond_FirstUseEver. When to apply the window size.
  • windowPos: ImVec2, default=(0.f, 0.f) (i.e let the app decide). Window position (unused if docked)
  • windowPosCondition: ImGuiCond, default=ImGuiCond_FirstUseEver. When to apply the window position.

Docking Params

DockingParams contains all the settings concerning the docking, together with the Gui functions for the docked windows.

Members:

  • dockingSplits: vector[DockingSplit]. Defines the way docking splits should be applied on the screen in order to create new Dock Spaces
  • dockableWindows: vector[DockableWindow]. List of the dockable windows, together with their Gui code
  • resetUserDockLayout: bool, default=true. Reset user layout at application startup