Text Input System

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
• imstb_rectpack.h
• imstb_textedit.h
• imstb_truetype.h

Purpose and Scope

The Text Input System manages all text editing functionality in Dear ImGui, including single-line and multi-line text fields, undo/redo operations, clipboard integration, IME (Input Method Editor) support for international text input, and text selection. This system bridges user input events with STB textedit library functionality to provide a complete text editing experience.

For information about input routing and keyboard navigation, see Input and Navigation. For widget-level behaviors, see Widget System.

---

Architecture Overview

The text input system consists of three main layers:

1. Public API Layer - User-facing functions (InputText(), InputTextMultiline(), InputTextWithHint())
2. State Management Layer - ImGuiInputTextState maintains editing state across frames
3. Text Edit Engine - STB textedit provides cursor movement, selection, undo/redo

Sources: imgui_widgets.cpp3700-5400 imgui_internal.h1050-1090 imstb_textedit.h1-280

---

Core Components

ImGuiInputTextState

ImGuiInputTextState is the central structure that maintains all state for an active text editing widget. It persists across frames as long as the widget remains active.

Field	Type	Purpose
Ctx	ImGuiContext*	Parent UI context
Stb	ImStbTexteditState	STB textedit state (cursor, selection, undo)
ID	ImGuiID	Widget ID owning this state
CurLenW, CurLenA	int	Buffer lengths in wchar and UTF-8
TextW	ImVector<ImWchar>	Internal edit buffer (UTF-16/UTF-32)
TextA	ImVector<char>	Temporary UTF-8 buffer for callbacks
InitialTextA	ImVector<char>	Backup of user buffer at focus time
BufCapacityA	int	User buffer capacity
Scroll	ImVec2	Scrolling position
CursorAnim	float	Cursor blink timer
Flags	ImGuiInputTextFlags	Copy of InputText() flags
Edited	bool	Was edited this frame
ReloadUserBuf	bool	User buffer needs reload (undo/callback)

The state is stored in g.InputTextState and activated when a text field becomes active.

Sources: imgui_internal.h1050-1090

---

STB Textedit Integration

Dear ImGui uses a modified version of STB textedit (imstb_textedit.h) for core text editing operations. This library provides:

• Cursor positioning and movement
• Selection handling
• Undo/redo stack management
• Word boundary detection
• Mouse click/drag handling

The macros STB_TEXTEDIT_* are defined to integrate STB textedit with ImGui's internal structures.

Sources: imstb_textedit.h1-1800 imgui_widgets.cpp3700-3900

---

Text Input Flow

Frame-by-Frame Operation

Sources: imgui_widgets.cpp4100-5300

---

Input Processing Pipeline

Input events flow through several filtering and processing stages:

Sources: imgui_widgets.cpp3920-4000 imgui_widgets.cpp4500-4800

---

ImGuiInputTextCallbackData

When callbacks are triggered, they receive an ImGuiInputTextCallbackData structure:

Field	Type	Purpose
EventFlag	ImGuiInputTextFlags	Which callback event triggered
Flags	ImGuiInputTextFlags	Copy of all InputText flags
EventChar	ImWchar	Character input (for CharFilter)
EventKey	ImGuiKey	Key pressed (for Completion/History)
Buf	char*	Text buffer pointer
BufTextLen	int	Text length in UTF-8
BufSize	int	Buffer size
BufDirty	bool	Set to true if you modify Buf
CursorPos	int	Cursor position in UTF-8 bytes
SelectionStart, SelectionEnd	int	Selection range
ID	ImGuiID	Widget ID (v1.92.6+)
EventActivated	bool	Widget was just activated (v1.92.6+)

Helper Methods:

• DeleteChars(int pos, int bytes_count) - Delete bytes from buffer
• InsertChars(int pos, const char* text, const char* text_end) - Insert text
• SelectAll() - Select all text
• ClearSelection() - Clear selection
• HasSelection() - Check if selection exists
• SetSelection(int start, int end) - Set selection range (v1.92.6+)

Sources: imgui.h2230-2280

---

Input Text Flags

Key flags controlling text input behavior:

Input Filtering

• ImGuiInputTextFlags_CharsDecimal - Allow 0-9, '.', '+', '-'
• ImGuiInputTextFlags_CharsHexadecimal - Allow 0-9, A-F, a-f
• ImGuiInputTextFlags_CharsScientific - Allow scientific notation
• ImGuiInputTextFlags_CharsUppercase - Convert to uppercase
• ImGuiInputTextFlags_CharsNoBlank - Filter out spaces, tabs

Visual Behavior

• ImGuiInputTextFlags_Password - Display as '*' characters
• ImGuiInputTextFlags_ReadOnly - Read-only mode, no editing
• ImGuiInputTextFlags_DisplayEmptyRefVal - Display empty value differently

Editing Behavior

• ImGuiInputTextFlags_AllowTabInput - Allow Tab character input
• ImGuiInputTextFlags_CtrlEnterForNewLine - Ctrl+Enter for newline (multiline)
• ImGuiInputTextFlags_NoHorizontalScroll - Disable horizontal scroll
• ImGuiInputTextFlags_AlwaysOverwrite - Overwrite mode
• ImGuiInputTextFlags_AutoSelectAll - Select all when focused

Callbacks

• ImGuiInputTextFlags_CallbackCompletion - Tab key pressed
• ImGuiInputTextFlags_CallbackHistory - Up/Down arrows pressed
• ImGuiInputTextFlags_CallbackAlways - Every frame
• ImGuiInputTextFlags_CallbackCharFilter - Character input
• ImGuiInputTextFlags_CallbackEdit - Any edit occurred
• ImGuiInputTextFlags_CallbackResize - Buffer capacity needs increase

Sources: imgui.h1375-1425

---

IME (Input Method Editor) Support

IME allows input of complex scripts (Chinese, Japanese, Korean) using composition:

Platform IME Data

ImGuiPlatformImeData communicates IME window position to the platform:

The platform backend calls io.PlatformSetImeDataFn to position the IME composition window near the text cursor.

Sources: imgui.h2800-2820 imgui_widgets.cpp4900-5100

---

Key Features

Undo/Redo System

STB textedit provides built-in undo/redo with configurable depth:

• Undo: Ctrl+Z
• Redo: Ctrl+Y or Ctrl+Shift+Z
• Undo state stored in ImStbTexteditState.undo_state[]
• Character data in ImStbTexteditState.undo_char[]
• Depth: STB_TEXTEDIT_UNDOSTATECOUNT (default 99)

Sources: imstb_textedit.h100-106 imgui_widgets.cpp3700-3750

---

Selection and Clipboard

Selection Features:

• Mouse drag selection with auto-scroll
• Shift+navigation key selection
• Double-click selects word
• Triple-click selects line (multiline)
• All platforms use standard shortcuts (macOS uses Cmd instead of Ctrl)

Sources: imgui_widgets.cpp4700-4900 imgui.cpp142-152

---

Word Wrapping (Multiline)

For InputTextMultiline() with ImGuiInputTextFlags_WordWrap:

Word wrapping changes in v1.92.6:

• Try not to wrap in middle of punctuation
• Try not to wrap between punctuation and digit
• Keep blanks at end of line rather than beginning of next

Sources: imgui_widgets.cpp5100-5300 docs/CHANGELOG.txt193-202

---

Internal Implementation Details

InputTextEx() Function Signature

This is the internal function that implements all text input variants.

Sources: imgui_internal.h3050-3060 imgui_widgets.cpp4100-5400

---

Character Filtering Function

InputTextFilterCharacter() filters and transforms input characters based on flags:

Handles:

• Character set restrictions (decimal, hex, etc.)
• Case transformation (uppercase)
• Blank filtering
• Password masking
• Callback-based filtering

Sources: imgui_widgets.cpp3920-4050

---

Text Size Calculation

Calculates text dimensions for layout and scrolling, accounting for word wrap.

Sources: imgui_widgets.cpp4050-4100

---

Usage Examples

Basic Text Input

Multiline with Word Wrap

Filtered Input with Callback

Password Field

Sources: imgui_demo.cpp2400-2700

---

Related Systems

• Input and Navigation - Keyboard input routing and focus management
• Widget System - Active ID system and widget interaction
• Drawing System - Text rendering and cursor visualization

---

Technical Notes

UTF-8 vs Wide Character Handling

ImGui maintains two parallel buffers:

• TextW (ImWchar) - Internal editing buffer, UTF-16 or UTF-32
• TextA (char) - UTF-8 buffer for user and callbacks

This allows efficient editing while maintaining UTF-8 compatibility with user code.

State Persistence

ImGuiInputTextState is stored in g.InputTextState and persists only while a text field is active. When a field loses focus, its state is cleared.

Temporary Deactivation

ImGuiInputTextDeactivateData briefly stores text from a deactivating field when another field steals the active ID, allowing proper cleanup.

Sources: imgui_internal.h1050-1090 imgui_internal.h1100-1110