Label & LineEdit

Relevant source files

This page covers the Label control for read-only text display and the LineEdit control for single-line text input. Both are fundamental GUI building blocks in the scene system. For multi-line text editing, see TextEdit & CodeEdit. For formatted and rich-text display, see RichTextLabel. For the underlying text shaping primitives that both controls rely on, see Text Shaping System.

Label

Label (scene/gui/label.h scene/gui/label.cpp) is a Control node that renders plain, styled text. It supports multi-line display, autowrapping, text overflow, alignment, shadows, and outlines, but no inline formatting. It delegates all glyph shaping to the TextServer abstraction layer.

Class Hierarchy

Class: Label → Control → CanvasItem → Node → Object

Sources: scene/gui/label.h36-194 scene/resources/label_settings.h

Text Shaping Pipeline

Label breaks its text into Paragraph objects (one per paragraph separator, default \n), then uses TextServer (global singleton TS) to shape each paragraph into wrapped lines.

Diagram: Label _shape() call flow

Sources: scene/gui/label.cpp140-345

Key shaping properties that feed into _shape():

Property	Member	Effect
`autowrap_mode`	`autowrap_mode`	Maps to `TextServer::LineBreakFlag` combination
`text_overrun_behavior`	`overrun_behavior`	Controls ellipsis / trimming
`uppercase`	`uppercase`	Applies `TS->string_to_upper()` before shaping
`visible_characters`	`visible_chars`	Truncates shaped text when `VC_CHARS_BEFORE_SHAPING`
`structured_text_bidi_override`	`st_parser`	Passed to `structured_text_parser()`
`language`	`language`	Passed to `TS->shaped_text_add_string()`

Sources: scene/gui/label.cpp140-172 scene/gui/label.h40-81

Rendering

Label renders during NOTIFICATION_DRAW. The drawing loop in _notification calls:

_ensure_shaped() — runs _shape() if any dirty flag is set.
get_layout_data() — computes r_offset (vertical start), r_last_line, and r_line_spacing, handling vertical alignment and fill modes.
Per-line glyph iteration using TS->shaped_text_get_glyphs(line_rid).
Inline draw helpers draw_glyph_shadow_outline, draw_glyph_shadow, draw_glyph_outline, draw_glyph are called for each rendering pass.

scene/gui/label.cpp393-419 defines the four inline draw functions used by the rendering loop:

draw_glyph()              — main text
draw_glyph_shadow()       — shadow fill
draw_glyph_shadow_outline() — shadow stroke
draw_glyph_outline()      — text stroke

The visible_characters / visible_ratio mechanism trims glyphs in the draw loop using three modes (VC_CHARS_BEFORE_SHAPING, VC_CHARS_AFTER_SHAPING, VC_GLYPHS_LTR, VC_GLYPHS_RTL, VC_GLYPHS_AUTO).

Sources: scene/gui/label.cpp393-419 scene/gui/label.cpp519-622

LabelSettings Resource

LabelSettings (scene/resources/label_settings.h scene/resources/label_settings.cpp) is a sharable Resource that overrides theme properties when assigned to Label::settings. Changes emit changed, which propagates to all Label nodes sharing the resource.

Properties in LabelSettings take precedence over the ThemeCache:

LabelSettings property	Overrides theme item
`font`	`font`
`font_size`	`font_size`
`font_color`	`font_color`
`line_spacing`	`line_spacing`
`paragraph_spacing`	`paragraph_spacing`
`outline_size`	`outline_size`
`outline_color`	`font_outline_color`
`shadow_size`	`shadow_outline_size`
`shadow_color`	`font_shadow_color`
`shadow_offset`	`shadow_offset_x` / `shadow_offset_y`

LabelSettings also supports stacked outlines and stacked shadows — multiple independent outline/shadow layers added via add_stacked_outline() / add_stacked_shadow().

Sources: scene/resources/label_settings.h doc/classes/LabelSettings.xml

Key Label Properties

Property	Type	Default	Notes
`text`	`String`	`""`	Triggers full re-shape on assignment
`paragraph_separator`	`String`	`"\\n"`	Each paragraph is a separate BiDi context
`autowrap_mode`	`AutowrapMode`	`AUTOWRAP_OFF`	Requires minimum size or container configuration
`autowrap_trim_flags`	`LineBreakFlag`	`BREAK_TRIM_START_EDGE_SPACES\|BREAK_TRIM_END_EDGE_SPACES`
`text_overrun_behavior`	`OverrunBehavior`	`OVERRUN_NO_TRIMMING`	Ellipsis / trim behavior
`ellipsis_char`	`String`	`"…"`	Custom ellipsis
`clip_text`	`bool`	`false`	Horizontal clipping without ellipsis
`horizontal_alignment`	`HorizontalAlignment`	`LEFT`
`vertical_alignment`	`VerticalAlignment`	`TOP`
`lines_skipped`	`int`	`0`	First N lines hidden
`max_lines_visible`	`int`	`-1`	Caps visible lines
`visible_characters`	`int`	`-1`	Typewriter effect
`visible_ratio`	`float`	`1.0`	Fraction equivalent to `visible_characters`
`uppercase`	`bool`	`false`	Applied before shaping
`label_settings`	`LabelSettings`	null	Shared style resource

Sources: doc/classes/Label.xml scene/gui/label.h40-81

LineEdit

LineEdit (scene/gui/line_edit.h scene/gui/line_edit.cpp) is a Control node providing a single-line editable text field. It handles keyboard input, mouse selection, clipboard integration, virtual keyboards, IME composition, and optional password masking.

Class Hierarchy

Class: LineEdit → Control → CanvasItem → Node → Object

Sources: scene/gui/line_edit.h editor/editor_log.h141

Text Input Pipeline

LineEdit processes input through gui_input(). It handles:

Keyboard events: Printable characters are inserted via insert_text_at_caret(). Special keys (Backspace, Delete, arrow keys, Home, End) manipulate the caret and selection.
Mouse events: Single-click positions caret, double-click selects word, triple-click selects all.
IME / composition: NOTIFICATION_FOCUS_ENTER opens virtual keyboard; composition strings are handled separately from committed text.
Clipboard: Ctrl+C copies, Ctrl+V pastes (with max_length enforcement), Ctrl+X cuts.
Undo/redo: LineEdit maintains its own undo stack for text edits.

Diagram: LineEdit input dispatch

Sources: scene/gui/line_edit.cpp

Password / Secret Mode

When secret = true, LineEdit displays each character replaced by secret_character (default "•"). The actual text is stored unmasked in the internal text buffer; only the display string is substituted.

The shaped text passed to TextServer uses the masked string, so cursor positioning and selection still work correctly relative to the displayed glyphs.

Key LineEdit Properties

Property	Type	Default	Notes
`text`	`String`	`""`	Emits `text_changed` on programmatic set
`placeholder_text`	`String`	`""`	Shown when empty and unfocused
`max_length`	`int`	`0`	`0` = unlimited
`editable`	`bool`	`true`	When false, acts as read-only display
`secret`	`bool`	`false`	Password masking
`secret_character`	`String`	`"•"`	Replacement character for masked input
`alignment`	`HorizontalAlignment`	`LEFT`
`caret_column`	`int`	`0`	Read/write cursor position
`caret_blink`	`bool`	`false`	Animated blink
`caret_blink_interval`	`float`	`0.65`	Blink period in seconds
`selecting_enabled`	`bool`	`true`	Mouse/keyboard text selection
`virtual_keyboard_enabled`	`bool`	`true`	Mobile/touchscreen keyboard
`text_overrun_behavior`	`OverrunBehavior`	`TRIM_CHAR`	For read-only display mode
`right_icon`	`Texture2D`	null	Icon rendered on the right edge
`flat`	`bool`	`false`	Removes stylebox border
`expand_to_text_length`	`bool`	`false`	Resizes width to fit text

LineEdit Signals

Signal	Description
`text_changed(new_text)`	Emitted on every edit
`text_submitted(new_text)`	Emitted on Enter key
`text_change_rejected(rejected_substring)`	Emitted when `max_length` prevents insert

Label vs LineEdit Comparison

Feature	Label	LineEdit
Input	None (display only)	Full keyboard + mouse
Lines	Multi-line (autowrap)	Single line only
Editing	No	Yes
Password mode	No	Yes (`secret` property)
Text shaping	`TextParagraph` / `TextServer`	`TextServer` directly
Context menu	No	Yes (cut/copy/paste/select all)
Undo/redo	No	Yes
Placeholder	No	Yes
Theming	`LabelSettings` + theme	Theme only
Scroll	No	Horizontal scroll when text exceeds width
Signals	None (text set programmatically)	`text_changed`, `text_submitted`

Text Shaping Integration

Both Label and LineEdit delegate all Unicode-aware layout to the TextServer singleton (referred to as the global TS macro in the codebase). This provides:

BiDi (bidirectional text) — automatic LTR/RTL mixing.
Complex script shaping — Arabic, Devanagari, etc.
Font feature access — OpenType features passed via font->get_opentype_features().
Line breaking — TS->shaped_text_get_line_breaks() with configurable LineBreakFlag bitfield.

Label wraps each paragraph into a TextParagraph-equivalent flow using raw TS RID calls and stores results in Paragraph::lines_rid (a Vector<RID>). LineEdit uses a single TextServer RID for its single visible line.

For detailed documentation of the TextServer API, TextLine, and TextParagraph, see Text Shaping System.

Sources: scene/gui/label.cpp140-238 scene/resources/text_paragraph.cpp scene/resources/text_line.cpp

Label & LineEdit

Relevant source files

Label

Class Hierarchy

Class: Label → Control → CanvasItem → Node → Object

Sources: scene/gui/label.h36-194 scene/resources/label_settings.h

Text Shaping Pipeline

Label breaks its text into Paragraph objects (one per paragraph separator, default \n), then uses TextServer (global singleton TS) to shape each paragraph into wrapped lines.

Diagram: Label _shape() call flow

Sources: scene/gui/label.cpp140-345

Key shaping properties that feed into _shape():

Property	Member	Effect
`autowrap_mode`	`autowrap_mode`	Maps to `TextServer::LineBreakFlag` combination
`text_overrun_behavior`	`overrun_behavior`	Controls ellipsis / trimming
`uppercase`	`uppercase`	Applies `TS->string_to_upper()` before shaping
`visible_characters`	`visible_chars`	Truncates shaped text when `VC_CHARS_BEFORE_SHAPING`
`structured_text_bidi_override`	`st_parser`	Passed to `structured_text_parser()`
`language`	`language`	Passed to `TS->shaped_text_add_string()`

Sources: scene/gui/label.cpp140-172 scene/gui/label.h40-81

Rendering

Label renders during NOTIFICATION_DRAW. The drawing loop in _notification calls:

_ensure_shaped() — runs _shape() if any dirty flag is set.
get_layout_data() — computes r_offset (vertical start), r_last_line, and r_line_spacing, handling vertical alignment and fill modes.
Per-line glyph iteration using TS->shaped_text_get_glyphs(line_rid).
Inline draw helpers draw_glyph_shadow_outline, draw_glyph_shadow, draw_glyph_outline, draw_glyph are called for each rendering pass.

scene/gui/label.cpp393-419 defines the four inline draw functions used by the rendering loop:

draw_glyph()              — main text
draw_glyph_shadow()       — shadow fill
draw_glyph_shadow_outline() — shadow stroke
draw_glyph_outline()      — text stroke

Sources: scene/gui/label.cpp393-419 scene/gui/label.cpp519-622

LabelSettings Resource

Properties in LabelSettings take precedence over the ThemeCache:

LabelSettings property	Overrides theme item
`font`	`font`
`font_size`	`font_size`
`font_color`	`font_color`
`line_spacing`	`line_spacing`
`paragraph_spacing`	`paragraph_spacing`
`outline_size`	`outline_size`
`outline_color`	`font_outline_color`
`shadow_size`	`shadow_outline_size`
`shadow_color`	`font_shadow_color`
`shadow_offset`	`shadow_offset_x` / `shadow_offset_y`

LabelSettings also supports stacked outlines and stacked shadows — multiple independent outline/shadow layers added via add_stacked_outline() / add_stacked_shadow().

Sources: scene/resources/label_settings.h doc/classes/LabelSettings.xml

Key Label Properties

Property	Type	Default	Notes
`text`	`String`	`""`	Triggers full re-shape on assignment
`paragraph_separator`	`String`	`"\\n"`	Each paragraph is a separate BiDi context
`autowrap_mode`	`AutowrapMode`	`AUTOWRAP_OFF`	Requires minimum size or container configuration
`autowrap_trim_flags`	`LineBreakFlag`	`BREAK_TRIM_START_EDGE_SPACES\|BREAK_TRIM_END_EDGE_SPACES`
`text_overrun_behavior`	`OverrunBehavior`	`OVERRUN_NO_TRIMMING`	Ellipsis / trim behavior
`ellipsis_char`	`String`	`"…"`	Custom ellipsis
`clip_text`	`bool`	`false`	Horizontal clipping without ellipsis
`horizontal_alignment`	`HorizontalAlignment`	`LEFT`
`vertical_alignment`	`VerticalAlignment`	`TOP`
`lines_skipped`	`int`	`0`	First N lines hidden
`max_lines_visible`	`int`	`-1`	Caps visible lines
`visible_characters`	`int`	`-1`	Typewriter effect
`visible_ratio`	`float`	`1.0`	Fraction equivalent to `visible_characters`
`uppercase`	`bool`	`false`	Applied before shaping
`label_settings`	`LabelSettings`	null	Shared style resource

Sources: doc/classes/Label.xml scene/gui/label.h40-81

LineEdit

Class Hierarchy

Class: LineEdit → Control → CanvasItem → Node → Object

Sources: scene/gui/line_edit.h editor/editor_log.h141

Text Input Pipeline

LineEdit processes input through gui_input(). It handles:

Keyboard events: Printable characters are inserted via insert_text_at_caret(). Special keys (Backspace, Delete, arrow keys, Home, End) manipulate the caret and selection.
Mouse events: Single-click positions caret, double-click selects word, triple-click selects all.
IME / composition: NOTIFICATION_FOCUS_ENTER opens virtual keyboard; composition strings are handled separately from committed text.
Clipboard: Ctrl+C copies, Ctrl+V pastes (with max_length enforcement), Ctrl+X cuts.
Undo/redo: LineEdit maintains its own undo stack for text edits.

Diagram: LineEdit input dispatch

Sources: scene/gui/line_edit.cpp

Password / Secret Mode

The shaped text passed to TextServer uses the masked string, so cursor positioning and selection still work correctly relative to the displayed glyphs.

Key LineEdit Properties

Property	Type	Default	Notes
`text`	`String`	`""`	Emits `text_changed` on programmatic set
`placeholder_text`	`String`	`""`	Shown when empty and unfocused
`max_length`	`int`	`0`	`0` = unlimited
`editable`	`bool`	`true`	When false, acts as read-only display
`secret`	`bool`	`false`	Password masking
`secret_character`	`String`	`"•"`	Replacement character for masked input
`alignment`	`HorizontalAlignment`	`LEFT`
`caret_column`	`int`	`0`	Read/write cursor position
`caret_blink`	`bool`	`false`	Animated blink
`caret_blink_interval`	`float`	`0.65`	Blink period in seconds
`selecting_enabled`	`bool`	`true`	Mouse/keyboard text selection
`virtual_keyboard_enabled`	`bool`	`true`	Mobile/touchscreen keyboard
`text_overrun_behavior`	`OverrunBehavior`	`TRIM_CHAR`	For read-only display mode
`right_icon`	`Texture2D`	null	Icon rendered on the right edge
`flat`	`bool`	`false`	Removes stylebox border
`expand_to_text_length`	`bool`	`false`	Resizes width to fit text

LineEdit Signals

Signal	Description
`text_changed(new_text)`	Emitted on every edit
`text_submitted(new_text)`	Emitted on Enter key
`text_change_rejected(rejected_substring)`	Emitted when `max_length` prevents insert

Label vs LineEdit Comparison

Feature	Label	LineEdit
Input	None (display only)	Full keyboard + mouse
Lines	Multi-line (autowrap)	Single line only
Editing	No	Yes
Password mode	No	Yes (`secret` property)
Text shaping	`TextParagraph` / `TextServer`	`TextServer` directly
Context menu	No	Yes (cut/copy/paste/select all)
Undo/redo	No	Yes
Placeholder	No	Yes
Theming	`LabelSettings` + theme	Theme only
Scroll	No	Horizontal scroll when text exceeds width
Signals	None (text set programmatically)	`text_changed`, `text_submitted`

Text Shaping Integration

Both Label and LineEdit delegate all Unicode-aware layout to the TextServer singleton (referred to as the global TS macro in the codebase). This provides:

BiDi (bidirectional text) — automatic LTR/RTL mixing.
Complex script shaping — Arabic, Devanagari, etc.
Font feature access — OpenType features passed via font->get_opentype_features().
Line breaking — TS->shaped_text_get_line_breaks() with configurable LineBreakFlag bitfield.

For detailed documentation of the TextServer API, TextLine, and TextParagraph, see Text Shaping System.

Sources: scene/gui/label.cpp140-238 scene/resources/text_paragraph.cpp scene/resources/text_line.cpp

Label & LineEdit

Label

Class Hierarchy

Text Shaping Pipeline

Rendering

LabelSettings Resource

Key Label Properties

LineEdit

Class Hierarchy

Text Input Pipeline

Password / Secret Mode

Key LineEdit Properties

LineEdit Signals

Label vs LineEdit Comparison

Text Shaping Integration

On this page

Label & LineEdit

Label

Class Hierarchy

Text Shaping Pipeline

Rendering

LabelSettings Resource

Key Label Properties

LineEdit

Class Hierarchy

Text Input Pipeline

Password / Secret Mode

Key LineEdit Properties

LineEdit Signals

Label vs LineEdit Comparison

Text Shaping Integration

On this page