Getting ImGuiIO
GetIO
Access the ImGuiIO structure which contains mouse/keyboard/gamepad inputs, time, various configuration options/flags.
Reference to the current context’s IO structure
ImGuiIO& io = ImGui::GetIO();
if (io.WantCaptureMouse)
{
// Dear ImGui is using the mouse, don't pass events to your game
}
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);
Key identifier (e.g., ImGuiKey_A, ImGuiKey_Space)
True for key down, false for key up
AddKeyAnalogEvent
void ImGuiIO::AddKeyAnalogEvent(ImGuiKey key, bool down, float v);
Analog value (typically 0.0f to 1.0f)
AddMousePosEvent
void ImGuiIO::AddMousePosEvent(float x, float y);
-FLT_MAX, -FLT_MAX to signify no mouse.
void ImGuiIO::AddMouseButtonEvent(int button, bool down);
Mouse button (0=left, 1=right, 2=middle)
True for button down, false for button up
AddMouseWheelEvent
void ImGuiIO::AddMouseWheelEvent(float wheel_x, float wheel_y);
Horizontal wheel delta (positive = scroll left, negative = scroll right)
Vertical wheel delta (positive = scroll up, negative = scroll down)
AddMouseSourceEvent
void ImGuiIO::AddMouseSourceEvent(ImGuiMouseSource source);
Source identifier (ImGuiMouseSource_Mouse, ImGuiMouseSource_TouchScreen, or ImGuiMouseSource_Pen)
AddFocusEvent
void ImGuiIO::AddFocusEvent(bool focused);
True when application gains focus, false when it loses focus
void ImGuiIO::AddInputCharacter(unsigned int c);
void ImGuiIO::AddInputCharactersUTF8(const char* str);
ClearEventsQueue
void ImGuiIO::ClearEventsQueue();
void ImGuiIO::ClearInputKeys();
void ImGuiIO::ClearInputMouse();
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)
// ...
};
Mouse position in pixels. Set to ImVec2(-FLT_MAX, -FLT_MAX) if mouse is unavailable.
Mouse buttons state. Index 0=left, 1=right, 2=middle.
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
// ...
};
Ctrl modifier down (non-macOS) or Cmd modifier down (macOS).
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
// ...
};
Set when Dear ImGui will use mouse inputs. In this case, do not dispatch mouse inputs to your game/application.
Set when Dear ImGui will use keyboard inputs. In this case, do not dispatch keyboard inputs to your game/application.
Mobile/console: when set, you may display an on-screen keyboard. Set by Dear ImGui when it wants textual keyboard input.
MousePos has been altered, backend should reposition mouse on next frame. Rarely used! Only when io.ConfigNavMoveSetMousePos is enabled.
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