Input & ImGuiIO

Access input state and configure Dear ImGui input/output settings

Getting ImGuiIO

GetIO

ImGuiIO& GetIO();

Access the ImGuiIO structure which contains mouse/keyboard/gamepad inputs, time, various configuration options/flags.

Returns · ImGuiIO&

Reference to the current context’s IO structure

Example:

ImGuiIO& io = ImGui::GetIO();
if (io.WantCaptureMouse)
{
    // Dear ImGui is using the mouse, don't pass events to your game
}

Input Functions

Backends should call these functions to submit input events. Application code typically only reads the resulting state.

AddKeyEvent

void ImGuiIO::AddKeyEvent(ImGuiKey key, bool down);

Queue a new key down/up event.

key · ImGuiKey

Key identifier (e.g., ImGuiKey_A, ImGuiKey_Space)

down · bool

True for key down, false for key up

AddKeyAnalogEvent

void ImGuiIO::AddKeyAnalogEvent(ImGuiKey key, bool down, float v);

Queue a key down/up event for analog values (e.g., gamepad triggers).

v · float

Analog value (typically 0.0f to 1.0f)

AddMousePosEvent

void ImGuiIO::AddMousePosEvent(float x, float y);

Queue a mouse position update. Use -FLT_MAX, -FLT_MAX to signify no mouse.

x · float

Mouse X position

y · float

Mouse Y position

AddMouseButtonEvent

void ImGuiIO::AddMouseButtonEvent(int button, bool down);

Queue a mouse button change.

button · int

Mouse button (0=left, 1=right, 2=middle)

down · bool

True for button down, false for button up

AddMouseWheelEvent

void ImGuiIO::AddMouseWheelEvent(float wheel_x, float wheel_y);

Queue a mouse wheel update.

wheel_x · float

Horizontal wheel delta (positive = scroll left, negative = scroll right)

wheel_y · float

Vertical wheel delta (positive = scroll up, negative = scroll down)

AddMouseSourceEvent

void ImGuiIO::AddMouseSourceEvent(ImGuiMouseSource source);

Queue a mouse source change (Mouse/TouchScreen/Pen).

source · ImGuiMouseSource

Source identifier (ImGuiMouseSource_Mouse, ImGuiMouseSource_TouchScreen, or ImGuiMouseSource_Pen)

AddFocusEvent

void ImGuiIO::AddFocusEvent(bool focused);

Queue a gain/loss of focus for the application.

focused · bool

True when application gains focus, false when it loses focus

AddInputCharacter

void ImGuiIO::AddInputCharacter(unsigned int c);

Queue a new character input.

c · unsigned int

Unicode codepoint

AddInputCharactersUTF8

void ImGuiIO::AddInputCharactersUTF8(const char* str);

Queue new characters input from a UTF-8 string.

str · const char*

UTF-8 encoded string

Input Clearing

ClearEventsQueue

void ImGuiIO::ClearEventsQueue();

Clear all incoming events.

ClearInputKeys

void ImGuiIO::ClearInputKeys();

Clear current keyboard/gamepad state and current frame text input buffer. Equivalent to releasing all keys/buttons.

ClearInputMouse

void ImGuiIO::ClearInputMouse();

Clear current mouse state.

Input State Access

Mouse State

struct ImGuiIO
{
    ImVec2      MousePos;           // Mouse position
    bool        MouseDown[5];       // Mouse buttons (0=left, 1=right, 2=middle)
    float       MouseWheel;         // Mouse wheel vertical
    float       MouseWheelH;        // Mouse wheel horizontal
    ImGuiMouseSource MouseSource;   // Mouse source (Mouse/TouchScreen/Pen)
    // ...
};

MousePos · ImVec2

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

MouseDown · bool[5]

Mouse buttons state. Index 0=left, 1=right, 2=middle.

MouseWheel · float

Mouse wheel vertical: 1 unit scrolls about 5 lines text.

Keyboard Modifiers

struct ImGuiIO
{
    bool        KeyCtrl;        // Ctrl key down
    bool        KeyShift;       // Shift key down
    bool        KeyAlt;         // Alt key down
    bool        KeySuper;       // Windows/Super (non-macOS), Ctrl (macOS)
    ImGuiKeyChord KeyMods;      // Combined modifier flags
    // ...
};

KeyCtrl · bool

Ctrl modifier down (non-macOS) or Cmd modifier down (macOS).

KeyMods · ImGuiKeyChord

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

Want Capture Flags

When reading io.WantCaptureMouse or io.WantCaptureKeyboard to dispatch your inputs, it is generally easier and more correct to use their state BEFORE calling NewFrame().

struct ImGuiIO
{
    bool WantCaptureMouse;      // ImGui wants mouse input
    bool WantCaptureKeyboard;   // ImGui wants keyboard input
    bool WantTextInput;         // ImGui wants text input
    bool WantSetMousePos;       // Request mouse position change
    bool WantSaveIniSettings;   // Request .ini save
    // ...
};

WantCaptureMouse · bool

Set when Dear ImGui will use mouse inputs. In this case, do not dispatch mouse inputs to your game/application.

WantCaptureKeyboard · bool

Set when Dear ImGui will use keyboard inputs. In this case, do not dispatch keyboard inputs to your game/application.

WantTextInput · bool

Mobile/console: when set, you may display an on-screen keyboard. Set by Dear ImGui when it wants textual keyboard input.

WantSetMousePos · bool

MousePos has been altered, backend should reposition mouse on next frame. Rarely used! Only when io.ConfigNavMoveSetMousePos is enabled.

Example:

ImGuiIO& io = ImGui::GetIO();

// Before NewFrame()
if (!io.WantCaptureMouse)
{
    // Process mouse events for your game
    ProcessGameMouseInput();
}

if (!io.WantCaptureKeyboard)
{
    // Process keyboard events for your game
    ProcessGameKeyboardInput();
}

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

Configuration Fields

See ImGuiIO for complete list of configuration options.

See Also

• Keyboard - Keyboard input functions
• Mouse - Mouse input functions
• Shortcuts - Keyboard shortcuts and input routing
• ImGuiIO - Complete ImGuiIO structure reference