ImGuiIO Structure

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.

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.

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.

Core

Windows

Widgets

Layout

Drawing

Input & Navigation

Styling

Data Structures

Overview

Getting ImGuiIO

Configuration Fields

Display Configuration

Configuration Flags

Font Configuration

File Paths

Timing Configuration

Navigation Configuration

Miscellaneous Configuration

Output Flags

Input State

Mouse State

Keyboard State

Backend Information

User Data

Metrics

Debug Options

See Also

Build docs developers (and LLMs) love

Core

Windows

Widgets

Layout

Drawing

Input & Navigation

Styling

Data Structures

​Overview

​Getting ImGuiIO

​Configuration Fields

​Display Configuration

​Configuration Flags

​Font Configuration

​File Paths

​Timing Configuration

​Navigation Configuration

​Miscellaneous Configuration

​Output Flags

​Input State

​Mouse State

​Keyboard State

​Backend Information

​User Data

​Metrics

​Debug Options

​See Also

Build docs developers (and LLMs) love

Overview

Getting ImGuiIO

Configuration Fields

Display Configuration

Configuration Flags

Font Configuration

File Paths

Timing Configuration

Navigation Configuration

Miscellaneous Configuration

Output Flags

Input State

Mouse State

Keyboard State

Backend Information

User Data

Metrics

Debug Options

See Also