Input and Navigation

Relevant source files

• docs/CHANGELOG.txt
• imgui.cpp
• imgui.h
• imgui_demo.cpp
• imgui_draw.cpp
• imgui_internal.h
• imgui_tables.cpp
• imgui_widgets.cpp

Overview

This document describes Dear ImGui's input handling and navigation systems. These systems enable user interaction through mouse, keyboard, and gamepad inputs, and provide keyboard/gamepad navigation for accessibility and console/TV applications. The input system manages how input events flow from platform backends into the library and how they are routed to individual widgets. The navigation system enables directional movement between UI elements without a mouse.

For information about backend implementation of input handling, see Backend Architecture. For text input specifics, see Text Input System.

---

Input Event System

Dear ImGui uses an event-based input system where platform backends submit input events to the ImGuiIO structure each frame. These events are processed during NewFrame() and consumed by widgets throughout the frame.

ImGuiIO and Input Events

The ImGuiIO structure serves as the primary interface for input data. Platform backends call event functions to submit input:

Event Function	Purpose
AddKeyEvent(ImGuiKey key, bool down)	Submit keyboard key press/release
AddKeyAnalogEvent(ImGuiKey key, bool down, float v)	Submit analog key/axis (gamepad)
AddMousePosEvent(float x, float y)	Submit mouse position
AddMouseButtonEvent(int button, bool down)	Submit mouse button press/release
AddMouseWheelEvent(float x, float y)	Submit mouse wheel movement
AddInputCharacter(unsigned int c)	Submit text input character (UTF-32)
AddFocusEvent(bool focused)	Submit window focus state

Input Event Flow

Sources: imgui.cpp6000-6300 imgui.h2200-2500 imgui_internal.h2100-2200

Input Sources

Dear ImGui distinguishes between three input sources, tracked by the ImGuiInputSource enum:

The input source affects behavior such as:

• Which navigation method is used
• Whether tooltips appear
• How activation works (click vs. space/enter)

Sources: imgui.cpp11500-12000 imgui_internal.h1450-1470

---

ID Stack System

The ID stack is fundamental to Dear ImGui's input routing. Every widget requires a unique ID within its scope to track state across frames. IDs are used for input routing, state storage, and navigation targeting.

ID Generation

IDs are generated by hashing string labels or explicit ID values. The current ID stack context affects the final hash:

Key Functions:

• PushID(const char*) / PushID(int) / PushID(void*) - Push ID component onto stack
• PopID() - Pop ID component from stack
• GetID(const char*) - Generate ID from label in current stack context
• GetItemID() - Get ID of last submitted item

The "###" operator in labels separates the visible label from the ID portion:

• "Save###save_button" → Display "Save", ID derived from "save_button"
• Multiple widgets can have same display text but different IDs

Sources: imgui.cpp8700-8900 imgui_internal.h365-368

ID Stack Scope Example

Both buttons can have label "OK" because they're in different ID stack contexts.

Sources: imgui.cpp8700-8900 imgui_demo.cpp2500-2600

---

Keyboard/Gamepad Navigation

Keyboard and gamepad navigation enables full UI control without a mouse, essential for console platforms, accessibility, and power users.

Navigation Configuration

Enable navigation via configuration flags in ImGuiIO:

Flag	Purpose
ImGuiConfigFlags_NavEnableKeyboard	Enable keyboard navigation (Tab, arrows, etc.)
ImGuiConfigFlags_NavEnableGamepad	Enable gamepad navigation
ImGuiConfigFlags_NavNoCaptureKeyboard	Don't set io.WantCaptureKeyboard during navigation

When enabled, additional output flags indicate navigation state:

• io.NavActive - Navigation is active (window has focus and can navigate)
• io.NavVisible - Navigation cursor is visible

Sources: imgui.h2200-2300 imgui.cpp154-174

Navigation Keys and Gamepad Mapping

Sources: imgui.cpp154-185 imgui_demo.cpp8500-8600

Navigation Layers

Dear ImGui uses two navigation layers that can be toggled with Alt or Gamepad Y button:

Layer	Description	Usage
ImGuiNavLayer_Main	Main layer (default)	Regular widgets, most content
ImGuiNavLayer_Menu	Menu layer	Menu bars, popups, window titles

Sources: imgui.cpp11500-11800 imgui_internal.h1420-1450

Navigation State Machine

The navigation system maintains state in ImGuiContext (accessible via g. in internal code):

Key State Variables:

• g.NavId - ID of currently navigated item
• g.NavWindow - Window containing navigated item
• g.NavLayer - Current navigation layer
• g.NavDisableHighlight - Whether to show highlight
• g.NavDisableMouseHover - Disable mouse hover during nav
• g.NavMoveDir - Direction of current move request
• g.NavMoveFlags - Flags for move request
• g.NavMoveResultLocal - Best candidate within current window
• g.NavMoveResultOther - Best candidate in other windows

Sources: imgui.cpp11500-13500 imgui_internal.h2300-2400

Directional Navigation Scoring

When a navigation direction is requested (e.g., pressing the down arrow), Dear ImGui:

1. Collects candidates - All navigable items in the current window and other windows
2. Scores candidates - Based on distance and direction alignment
3. Selects best - Lowest scoring candidate becomes the new g.NavId
4. Applies result - Updates navigation state and scrolls if necessary

The scoring algorithm prioritizes:

• Items in the requested direction
• Items with better axis alignment
• Closer items over distant ones

Sources: imgui.cpp12200-12800 imgui_internal.h3300-3350

---

Shortcuts System

The shortcuts system enables global or local keyboard shortcuts with proper input routing and conflict resolution.

Shortcut Functions

Key Functions:

• Shortcut(ImGuiKeyChord key_chord, ImGuiInputFlags flags = 0) - Test if shortcut is pressed
• SetNextItemShortcut(ImGuiKeyChord key_chord, ImGuiInputFlags flags = 0) - Assign shortcut to next item

ImGuiKeyChord: A key combined with optional modifiers:

• ImGuiKey_A - Just 'A' key
• ImGuiMod_Ctrl | ImGuiKey_S - Ctrl+S
• ImGuiMod_Ctrl | ImGuiMod_Shift | ImGuiKey_Z - Ctrl+Shift+Z

Sources: imgui.cpp9700-10100 imgui.h3000-3050

Input Routing Flags

The ImGuiInputFlags enum controls how shortcuts are routed:

Flag	Behavior
ImGuiInputFlags_None	Default routing to hovered/active item
ImGuiInputFlags_RouteActive	Route only to active item
ImGuiInputFlags_RouteFocused	Route only to focused item
ImGuiInputFlags_RouteGlobal	Route globally (when nothing is active/focused)
ImGuiInputFlags_RouteAlways	Always route (bypass regular routing)
ImGuiInputFlags_Repeat	Enable key repeat

Example Usage:

Sources: imgui_internal.h1470-1520 imgui.cpp9700-10200

---

Active ID and Input Ownership

The Active ID system tracks which widget currently "owns" input, preventing conflicts when multiple widgets want the same input.

Active ID State

Key State Variables:

• g.ActiveId - ID of currently active item (ImGuiID)
• g.ActiveIdSource - Input source that activated (Mouse/Keyboard/Gamepad)
• g.ActiveIdIsJustActivated - True on activation frame
• g.ActiveIdTimer - Time since activation
• g.ActiveIdWindow - Window containing active item

Sources: imgui.cpp9200-9500 imgui_internal.h2200-2250

Input Ownership Transfer

Widgets can "steal" active ID from others for behaviors like drag-and-drop.

Sources: imgui.cpp9200-9600 imgui_widgets.cpp500-800

---

Navigation and Focus Integration

Navigation and focus systems work together to provide keyboard control:

Window Focus:

• FocusWindow() - Set focused window
• IsWindowFocused(flags) - Check if window has focus
• SetWindowFocus() - Request focus for window

Item Focus:

• SetKeyboardFocusHere(offset = 0) - Request focus for next item (or offset items ahead)
• Items automatically gain focus when navigated to

Sources: imgui.cpp7500-7800 imgui.cpp11000-11200

---

Input Event Processing Timeline

Understanding when input is processed helps with correct API usage:

Important Timing Notes:

1. Input events are submitted BEFORE NewFrame()
2. Navigation processing happens IN NewFrame()
3. Widgets consume input DURING frame
4. Input flags like io.WantCaptureKeyboard are updated DURING frame
5. Check output flags AFTER widget calls but BEFORE Render()

Sources: imgui.cpp4500-4800 imgui.cpp6000-6300

---

Special Input Handling

Mouse Capture

When dragging, Dear ImGui can capture the mouse to track movement even outside the window:

• io.ConfigWindowsMoveFromTitleBarOnly - Restrict window dragging to title bar
• io.MouseDrawCursor - Let ImGui draw mouse cursor (for software cursor)
• io.WantCaptureMouse - Application should not process mouse input
• Backend should implement ImGuiBackendFlags_HasMouseCursors for cursor changes

Text Input Mode

• io.WantCaptureKeyboard - Application should not process keyboard
• io.WantTextInput - Text input widget is active (show on-screen keyboard)
• Platform backend should call io.AddInputCharacter() for text (not key events)

IME Support

For non-ASCII text input:

• io.SetPlatformImeDataFn - Callback to position IME window
• Backend provides platform-specific IME implementation
• Text editing widgets call the callback with cursor position

Sources: imgui.cpp6000-6200 imgui.h2300-2500 backends/imgui_impl_win32.cpp300-400

---

Navigation Configuration Options

Advanced navigation behavior can be configured via ImGuiIO:

Option	Default	Description
ConfigNavMoveSetMousePos	false	Move mouse cursor with navigation
ConfigNavCaptureKeyboard	true	Set io.WantCaptureKeyboard when navigating

Window-level navigation flags in ImGuiWindowFlags:

• ImGuiWindowFlags_NoNav - Disable all navigation in this window
• ImGuiWindowFlags_NoNavInputs - Disable navigation input (but allow focus)
• ImGuiWindowFlags_NoNavFocus - Prevent window from being focused via navigation

Item-level navigation flags in ImGuiItemFlags (internal):

• ImGuiItemFlags_NoNav - Item is not navigable
• ImGuiItemFlags_NoNavDefaultFocus - Item won't be default focus target

Sources: imgui.h2200-2300 imgui.h1650-1750 imgui_internal.h1050-1100

---

Implementation Notes for Backend Developers

When implementing a platform backend, follow this input submission pattern:

1. Poll platform events (OS messages, GLFW callbacks, SDL events)
2. Submit to ImGuiIO:

3. Call NewFrame()
4. Respect output flags:
   • Check io.WantCaptureMouse - Don't process mouse in application
   • Check io.WantCaptureKeyboard - Don't process keyboard in application
   • Check io.WantSetMousePos - Move OS cursor to io.MousePos

Gamepad Support:

• Set io.BackendFlags |= ImGuiBackendFlags_HasGamepad
• Submit analog values with AddKeyAnalogEvent(ImGuiKey_GamepadXXX, ...)
• Backend responsible for dead-zone and normalization (0.0f to 1.0f)

Sources: imgui.cpp280-360 docs/BACKENDS.md backends/imgui_impl_glfw.cpp400-600