ImGuiIO Structure

Main configuration and I/O structure for Dear ImGui

Overview

The ImGuiIO structure is the main configuration and I/O interface between your application and Dear ImGui. It contains:

• Configuration options and flags
• Input state (mouse, keyboard, gamepad)
• Output flags (WantCaptureMouse, WantCaptureKeyboard, etc.)
• Time and framerate information

Getting ImGuiIO

ImGuiIO& io = ImGui::GetIO();

See GetIO for details.

Configuration Fields

Display Configuration

DisplaySize · ImVec2

Main display size in pixels. May change every frame.

DisplayFramebufferScale · ImVec2 · default: "(1, 1)"

For retina displays where window coordinates differ from framebuffer coordinates. Affects font density.

DeltaTime · float · default: "1.0f/60.0f"

Time elapsed since last frame, in seconds. May change every frame.

Example:

ImGuiIO& io = ImGui::GetIO();
io.DisplaySize = ImVec2(1920.0f, 1080.0f);
io.DisplayFramebufferScale = ImVec2(2.0f, 2.0f); // Retina
io.DeltaTime = 1.0f / 60.0f;

Configuration Flags

ConfigFlags · ImGuiConfigFlags · default: "0"

See ImGuiConfigFlags_ enum. Set by user/application.

BackendFlags · ImGuiBackendFlags · default: "0"

See ImGuiBackendFlags_ enum. Set by backend to communicate features supported.

enum ImGuiConfigFlags_
{
    ImGuiConfigFlags_None                   = 0,
    ImGuiConfigFlags_NavEnableKeyboard      = 1 << 0,   // Enable keyboard navigation
    ImGuiConfigFlags_NavEnableGamepad       = 1 << 1,   // Enable gamepad navigation
    ImGuiConfigFlags_NoMouse                = 1 << 4,   // Disable mouse inputs
    ImGuiConfigFlags_NoMouseCursorChange    = 1 << 5,   // Don't alter mouse cursor
    ImGuiConfigFlags_NoKeyboard             = 1 << 6,   // Disable keyboard inputs
    ImGuiConfigFlags_IsSRGB                 = 1 << 20,  // Application is SRGB-aware
    ImGuiConfigFlags_IsTouchScreen          = 1 << 21,  // Using touch screen
};

Example:

ImGuiIO& io = ImGui::GetIO();
io.ConfigFlags |= ImGuiConfigFlags_NavEnableKeyboard;
io.ConfigFlags |= ImGuiConfigFlags_NavEnableGamepad;

Font Configuration

Fonts · ImFontAtlas*

Font atlas: load, rasterize and pack fonts into a single texture.

FontDefault · ImFont* · default: "NULL"

Font to use on NewFrame(). NULL uses Fonts->Fonts[0].

FontAllowUserScaling · bool · default: "false"

Allow user scaling text with Ctrl+Wheel.

File Paths

IniFilename · const char* · default: "imgui.ini"

Path to .ini file for saving/loading settings. Set NULL to disable.

LogFilename · const char* · default: "imgui_log.txt"

Path to .log file (default for LogToFile when no file specified).

Default “imgui.ini” is relative to current working directory! Most apps should lock this to an absolute path.

Timing Configuration

IniSavingRate · float · default: "5.0f"

Minimum time between saving positions/sizes to .ini file, in seconds.

MouseDoubleClickTime · float · default: "0.30f"

Time for a double-click, in seconds.

MouseDoubleClickMaxDist · float · default: "6.0f"

Distance threshold to stay in to validate a double-click, in pixels.

MouseDragThreshold · float · default: "6.0f"

Distance threshold before considering we are dragging.

KeyRepeatDelay · float · default: "0.275f"

When holding a key/button, time before it starts repeating, in seconds.

KeyRepeatRate · float · default: "0.050f"

When holding a key/button, rate at which it repeats, in seconds.

Navigation Configuration

ConfigNavSwapGamepadButtons · bool · default: "false"

Swap Activate/Cancel (A/B) buttons, matching Nintendo/Japanese style.

ConfigNavMoveSetMousePos · bool · default: "false"

Directional/tabbing navigation teleports the mouse cursor.

ConfigNavCaptureKeyboard · bool · default: "true"

Sets io.WantCaptureKeyboard when io.NavActive is set.

ConfigNavEscapeClearFocusItem · bool · default: "true"

Pressing Escape can clear focused item + navigation.

ConfigNavCursorVisibleAuto · bool · default: "true"

Using directional navigation key makes the cursor visible.

Miscellaneous Configuration

MouseDrawCursor · bool · default: "false"

Request ImGui to draw a mouse cursor for you (software cursor).

ConfigMacOSXBehaviors · bool · default: "defined(__APPLE__)"

Swap Cmd/Ctrl keys + OS X style text editing, etc.

ConfigInputTextCursorBlink · bool · default: "true"

Enable blinking cursor in InputText.

ConfigInputTextEnterKeepActive · bool · default: "false"

[BETA] Pressing Enter keeps item active and selects contents.

ConfigDragClickToInputText · bool · default: "false"

[BETA] Enable turning DragXXX widgets into text input with a simple click-release.

ConfigWindowsResizeFromEdges · bool · default: "true"

Enable resizing windows from their edges and lower-left corner.

ConfigWindowsMoveFromTitleBarOnly · bool · default: "false"

Only allow moving windows when clicking on their title bar.

ConfigMemoryCompactTimer · float · default: "60.0f"

Timer (in seconds) to free transient windows/tables memory buffers when unused. Set to -1.0f to disable.

Output Flags

When reading these flags to dispatch your inputs, it is generally easier to use their state BEFORE calling NewFrame().

WantCaptureMouse · bool

Set when Dear ImGui will use mouse inputs. Don’t dispatch mouse to your game when true.

WantCaptureKeyboard · bool

Set when Dear ImGui will use keyboard inputs. Don’t dispatch keyboard to your game when true.

WantTextInput · bool

Mobile/console: when set, you may display an on-screen keyboard.

WantSetMousePos · bool

MousePos has been altered, backend should reposition mouse. Rarely used!

WantSaveIniSettings · bool

When manual .ini save is active (io.IniFilename == NULL), this notifies you to save. Clear this flag yourself after saving!

NavActive · bool

Keyboard/Gamepad navigation is currently allowed.

NavVisible · bool

Keyboard/Gamepad navigation highlight is visible and allowed.

Framerate · float

Estimate of application framerate (rolling average), in frames per second.

Example:

ImGuiIO& io = ImGui::GetIO();

// Before NewFrame()
if (!io.WantCaptureMouse)
    ProcessGameMouseInput();

if (!io.WantCaptureKeyboard)
    ProcessGameKeyboardInput();

ImGui::NewFrame();
// ... ImGui code ...

Input State

Backends should use AddXXXEvent() functions to submit input. These fields are maintained by ImGui.

Mouse State

MousePos · ImVec2

Mouse position in pixels. Set to ImVec2(-FLT_MAX, -FLT_MAX) if unavailable.

MouseDown · bool[5]

Mouse buttons state (0=left, 1=right, 2=middle + extras).

MouseWheel · float

Mouse wheel vertical: 1 unit scrolls about 5 lines.

MouseWheelH · float

Mouse wheel horizontal.

MouseSource · ImGuiMouseSource

Mouse actual input peripheral (Mouse/TouchScreen/Pen).

Keyboard State

KeyCtrl · bool

Keyboard modifier down: Ctrl (non-macOS), Cmd (macOS).

KeyShift · bool

Keyboard modifier down: Shift.

KeyAlt · bool

Keyboard modifier down: Alt.

KeySuper · bool

Keyboard modifier down: Windows/Super (non-macOS), Ctrl (macOS).

KeyMods · ImGuiKeyChord

Combined key modifiers flags (updated by NewFrame()).

KeysData · ImGuiKeyData[ImGuiKey_NamedKey_COUNT]

Key state for all known keys. Use IsKeyXXX() functions to access.

Backend Information

BackendPlatformName · const char*

Platform backend name (informational only).

BackendRendererName · const char*

Renderer backend name (informational only).

BackendPlatformUserData · void*

User data for platform backend.

BackendRendererUserData · void*

User data for renderer backend.

User Data

UserData · void* · default: "NULL"

Store your own data.

Example:

struct MyAppData {
    int some_value;
    float another_value;
};

MyAppData my_data;
ImGuiIO& io = ImGui::GetIO();
io.UserData = &my_data;

// Later:
MyAppData* data = (MyAppData*)io.UserData;

Metrics

MetricsRenderVertices · int

Vertices output during last call to Render().

MetricsRenderIndices · int

Indices output during last call to Render().

MetricsRenderWindows · int

Number of visible windows.

MetricsActiveWindows · int

Number of active windows.

MouseDelta · ImVec2

Mouse delta. Zero if either current or previous position are invalid.

Debug Options

ConfigErrorRecovery · bool · default: "true"

Enable error recovery support.

ConfigErrorRecoveryEnableAssert · bool · default: "true"

Enable asserts on recoverable errors.

ConfigErrorRecoveryEnableDebugLog · bool · default: "true"

Enable debug log output on recoverable errors.

ConfigErrorRecoveryEnableTooltip · bool · default: "true"

Enable tooltip on recoverable errors.

ConfigDebugIsDebuggerPresent · bool · default: "false"

Enable various tools calling IM_DEBUG_BREAK().

ConfigDebugHighlightIdConflicts · bool · default: "true"

Highlight and show error when multiple items have conflicting identifiers.

ConfigDebugBeginReturnValueOnce · bool · default: "false"

First-time calls to Begin()/BeginChild() will return false.

ConfigDebugBeginReturnValueLoop · bool · default: "false"

Some calls to Begin()/BeginChild() will return false, cycling through window depths.

See Also

• Input - Input event functions
• Keyboard - Keyboard input
• Mouse - Mouse input
• ImGuiPlatformIO - Platform-specific functions