# How to Handle Mouse and Keyboard Input Dispatch Between Dear ImGui and Your Application

> Learn to dispatch mouse and keyboard input between Dear ImGui and your app. Initialize a platform backend, forward events to ImGuiIO, and chain custom callbacks for seamless integration.

- Repository: [omar/imgui](https://github.com/ocornut/imgui)
- Tags: how-to-guide
- Published: 2026-07-29

---

**To handle mouse and keyboard input dispatch between Dear ImGui and your application, initialize a platform backend (such as GLFW or Win32) to capture native OS events, forward them to ImGui via the `ImGuiIO` event APIs, and optionally chain custom callbacks to process the same events in your application logic.**

Dear ImGui uses a platform-agnostic input system that requires you to handle mouse and keyboard input dispatch between Dear ImGui and your application through dedicated backend implementations. The library receives raw hardware events via platform-specific backends like [`imgui_impl_glfw.cpp`](https://github.com/ocornut/imgui/blob/main/imgui_impl_glfw.cpp) or [`imgui_impl_win32.cpp`](https://github.com/ocornut/imgui/blob/main/imgui_impl_win32.cpp), which translate native windowing system messages into ImGui's internal event format. Understanding this dispatch pipeline is essential for building interactive applications where both ImGui widgets and your custom rendering logic must respond to user input.

## Understanding the Platform Backend Architecture

Dear ImGui delegates all platform-specific input handling to **backend implementations** that bridge your operating system's windowing API with ImGui's abstract `ImGuiIO` interface. These backends install native event callbacks during initialization, translate OS-specific messages (such as GLFW mouse buttons or Win32 `WM_*` messages) into portable events, and feed them to the current context through the `Add*Event` API family.

### The Event Translation Pipeline

When you initialize a backend like GLFW, the system establishes a data flow from raw OS events to ImGui's internal state:

1. **Native Callback Installation** – The backend replaces your window system's event callbacks with wrapper functions (e.g., `ImGui_ImplGlfw_InstallCallbacks` in [`backends/imgui_impl_glfw.cpp`](https://github.com/ocornut/imgui/blob/main/backends/imgui_impl_glfw.cpp)).
2. **Event Translation** – Each wrapper converts native parameters into ImGui-compatible data structures.
3. **ImGui Ingestion** – Wrappers call specific `ImGuiIO` methods: `AddMouseButtonEvent` for clicks, `AddMousePosEvent` for cursor movement, `AddKeyEvent` for keyboard state changes, and `AddInputCharacter` for text entry.

## Implementing Input Dispatch with GLFW

The GLFW backend demonstrates the canonical pattern for handling mouse and keyboard input dispatch between Dear ImGui and your application. Located in [`backends/imgui_impl_glfw.cpp`](https://github.com/ocornut/imgui/blob/main/backends/imgui_impl_glfw.cpp), this implementation supports both exclusive ImGui processing and shared event consumption.

### Basic Initialization with Automatic Callbacks

For applications where ImGui handles all input, initialize the backend with automatic callback installation:

```cpp
// Create context and configure IO
ImGui::CreateContext();
ImGuiIO& io = ImGui::GetIO();
io.ConfigFlags |= ImGuiConfigFlags_NavEnableKeyboard;

// Initialize GLFW backend (true = install callbacks)
ImGui_ImplGlfw_InitForOpenGL(window, true);
ImGui_ImplOpenGL3_Init("#version 150");

```

Setting the second parameter to `true` invokes `ImGui_ImplGlfw_InstallCallbacks`, which stores your existing GLFW callbacks internally and registers ImGui's wrapper functions for mouse, keyboard, and scroll events.

### Chaining Custom Application Callbacks

When your application requires access to raw input events alongside ImGui, enable callback chaining to preserve both processing paths:

```cpp
// Install your custom callback first
GLFWmousebuttonfun prevCallback = glfwSetMouseButtonCallback(window, MyMouseButtonCallback);

// Initialize ImGui (stores prevCallback internally)
ImGui_ImplGlfw_InitForOpenGL(window, true);

// Enable chaining so ImGui wrappers call your callbacks
ImGui_ImplGlfw_SetCallbacksChainForAllWindows(true);

```

With chaining enabled, ImGui's wrapper functions (defined in [`backends/imgui_impl_glfw.cpp`](https://github.com/ocornut/imgui/blob/main/backends/imgui_impl_glfw.cpp)) invoke your stored previous callbacks before calling `io.AddMouseButtonEvent` and related functions. This allows your application logic to process mouse coordinates and button states while still feeding the same events to ImGui's widget system.

## Core ImGuiIO Event APIs

The `ImGuiIO` structure provides atomic methods for injecting specific event types, which backends call after translating native windowing messages:

- **Mouse buttons**: `io.AddMouseButtonEvent(button, bool down)` processes clicks.
- **Cursor position**: `io.AddMousePosEvent(x, y)` updates mouse coordinates.
- **Scroll wheels**: `io.AddMouseWheelEvent(x, y)` handles horizontal and vertical scrolling.
- **Keyboard**: `io.AddKeyEvent(key, bool down)` registers key state changes, often paired with `io.SetKeyEventNativeData` for platform-specific key codes.
- **Text input**: `io.AddInputCharacter(c)` accepts Unicode character values from the OS text input system.

These functions queue events for the current frame, which `ImGui::NewFrame` processes to update widget states and navigation.

## Managing Multiple Viewports and Contexts

For multi-window applications using **ImGui viewports**, the GLFW backend maintains an internal map (`g_ContextMap`) that associates each `GLFWwindow*` with its active `ImGuiContext*`. When processing events, the backend retrieves the correct context via `ImGui_ImplGlfw_GetBackendData(window)` before calling the `Add*Event` functions. This architecture ensures that input events route to the appropriate ImGui instance even when multiple windows and contexts exist simultaneously.

## Controlling Mouse Cursor Behavior

By default, ImGui updates the OS mouse cursor shape based on hover states (text input, resize handles, etc.). To handle mouse and keyboard input dispatch between Dear ImGui and your application without cursor interference, disable automatic cursor management:

```cpp
io.ConfigFlags |= ImGuiConfigFlags_NoMouseCursorChange;
// Or completely disable mouse input processing:
io.ConfigFlags |= ImGuiConfigFlags_NoMouse;

```

The `ImGui_ImplGlfw_UpdateMouseCursor` function (called during `ImGui_ImplGlfw_NewFrame`) checks these flags before invoking `glfwSetCursor` to modify the system cursor appearance.

## Win32 Backend Considerations

If using the Win32 backend ([`backends/imgui_impl_win32.cpp`](https://github.com/ocornut/imgui/blob/main/backends/imgui_impl_win32.cpp)), the pattern remains identical but uses message procedures rather than GLFW callbacks. The entry point `ImGui_ImplWin32_WndProcHandler` processes `WM_LBUTTONDOWN`, `WM_KEYDOWN`, and related messages, calling the same `ImGuiIO` event APIs. For pointer device discrimination (pen versus touch), the Win32 backend additionally injects `io.AddMouseSourceEvent` to distinguish between input types.

## Summary

- **Initialize backends** using `ImGui_ImplGlfw_InitForOpenGL` or `ImGui_ImplWin32_Init` to establish the event translation layer.
- **Enable callback chaining** with `ImGui_ImplGlfw_SetCallbacksChainForAllWindows` when your application needs parallel access to input events.
- **Use `ImGuiIO` event APIs** (`AddMouseButtonEvent`, `AddKeyEvent`, etc.) to manually inject events if implementing custom backends.
- **Manage multiple contexts** through the backend's internal window-to-context mapping for viewport support.
- **Configure cursor behavior** via `ImGuiConfigFlags_NoMouseCursorChange` to prevent ImGui from modifying system cursor states.

## Frequently Asked Questions

### How do I prevent ImGui from consuming all mouse input?

Set `ImGuiConfigFlags_NoMouse` in `io.ConfigFlags` to disable ImGui's internal mouse processing, or enable callback chaining in the GLFW backend using `ImGui_ImplGlfw_SetCallbacksChainForAllWindows(true)` to ensure your application's callbacks execute alongside ImGui's event processing.

### Can I use multiple ImGui contexts with different windows?

Yes. The GLFW backend maintains a global `g_ContextMap` that associates each `GLFWwindow*` with its corresponding `ImGuiContext*`. When events arrive, `ImGui_ImplGlfw_GetBackendData` retrieves the correct context, ensuring input dispatch routes to the appropriate instance even with multiple active viewports.

### How do I disable ImGui's automatic cursor changes?

Set `io.ConfigFlags |= ImGuiConfigFlags_NoMouseCursorChange` before calling `ImGui_ImplGlfw_NewFrame`. This prevents `ImGui_ImplGlfw_UpdateMouseCursor` from calling `glfwSetCursor`, allowing your application to maintain full control over the OS cursor appearance.

### What is the difference between `AddKeyEvent` and `AddInputCharacter`?

`AddKeyEvent` registers physical key state changes (e.g., "A key pressed") for keyboard navigation and shortcuts, while `AddInputCharacter` submits text input values (e.g., the Unicode character 'a') for text widgets. The former handles hardware scancodes; the latter handles OS text composition and character encoding.