Inheritance #

LineEdit #

is_instantiable, Node, core, not_builtin_classes

An input field for single-line text.

LineEdit provides an input field for editing a single line of text.

- When the LineEdit control is focused using the keyboard arrow keys, it will only gain focus and not enter edit mode.

- To enter edit mode, click on the control with the mouse, see also keep_editing_on_text_submit.

- To exit edit mode, press ui_text_submit or ui_cancel (by default Escape) actions.

- Check edit, unedit, is_editing, and editing_toggled for more information.

Important:

- Focusing the LineEdit with ui_focus_next (by default Tab) or ui_focus_prev (by default Shift + Tab) or Control.grab_focus still enters edit mode (for compatibility).

LineEdit features many built-in shortcuts that are always available (Ctrl here maps to Cmd on macOS):

- Ctrl + C: Copy

- Ctrl + X: Cut

- Ctrl + V or Ctrl + Y: Paste/"yank"

- Ctrl + Z: Undo

- Ctrl + ~: Swap input direction.

- Ctrl + Shift + Z: Redo

- Ctrl + U: Delete text from the caret position to the beginning of the line

- Ctrl + K: Delete text from the caret position to the end of the line

- Ctrl + A: Select all text

- Up Arrow/Down Arrow: Move the caret to the beginning/end of the line

On macOS, some extra keyboard shortcuts are available:

- Cmd + F: Same as Right Arrow, move the caret one character right

- Cmd + B: Same as Left Arrow, move the caret one character left

- Cmd + P: Same as Up Arrow, move the caret to the previous line

- Cmd + N: Same as Down Arrow, move the caret to the next line

- Cmd + D: Same as Delete, delete the character on the right side of caret

- Cmd + H: Same as Backspace, delete the character on the left side of the caret

- Cmd + A: Same as Home, move the caret to the beginning of the line

- Cmd + E: Same as End, move the caret to the end of the line

- Cmd + Left Arrow: Same as Home, move the caret to the beginning of the line

- Cmd + Right Arrow: Same as End, move the caret to the end of the line

Note: Caret movement shortcuts listed above are not affected by shortcut_keys_enabled.

Members #

var alignment: int = 0#

Text alignment as defined in the HorizontalAlignment enum.

var caret_blink: bool = false#

If true, makes the caret blink.

var caret_blink_interval: float = 0.65#

The interval at which the caret blinks (in seconds).

var caret_column: int = 0#

The caret's column position inside the LineEdit. When set, the text may scroll to accommodate it.

var caret_force_displayed: bool = false#

If true, the LineEdit will always show the caret, even if not editing or focus is lost.

var caret_mid_grapheme: bool = false#

Allow moving caret, selecting and removing the individual composite character components.

Note: Backspace is always removing individual composite character components.

var clear_button_enabled: bool = false#

If true, the LineEdit will show a clear button if text is not empty, which can be used to clear the text quickly.

var context_menu_enabled: bool = true#

If true, the context menu will appear when right-clicked.

var deselect_on_focus_loss_enabled: bool = true#

If true, the selected text will be deselected when focus is lost.

var drag_and_drop_selection_enabled: bool = true#

If true, allow drag and drop of selected text.

var draw_control_chars: bool = false#

If true, control characters are displayed.

var editable: bool = true#

If false, existing text cannot be modified and new text cannot be added.

var emoji_menu_enabled: bool = true#

If true, "Emoji and Symbols" menu is enabled.

var expand_to_text_length: bool = false#

If true, the LineEdit width will increase to stay longer than the text. It will not compress if the text is shortened.

var flat: bool = false#

If true, the LineEdit doesn't display decoration.

var focus_mode = FOCUS_ALL#

var keep_editing_on_text_submit: bool = false#

If true, the LineEdit will not exit edit mode when text is submitted by pressing ui_text_submit action (by default: Enter or Kp Enter).

var language: String = ""#

Language code used for line-breaking and text shaping algorithms. If left empty, current locale is used instead.

var max_length: int = 0#

Maximum number of characters that can be entered inside the LineEdit. If 0, there is no limit.

When a limit is defined, characters that would exceed max_length are truncated. This happens both for existing text contents when setting the max length, or for new text inserted in the LineEdit, including pasting.

If any input text is truncated, the text_change_rejected signal is emitted with the truncated substring as parameter:

GDScript

text = "Hello world"
max_length = 5
# `text` becomes "Hello".
max_length = 10
text += " goodbye"
# `text` becomes "Hello good".
# `text_change_rejected` is emitted with "bye" as parameter.

C#

Text = "Hello world";
MaxLength = 5;
// `Text` becomes "Hello".
MaxLength = 10;
Text += " goodbye";
// `Text` becomes "Hello good".
// `text_change_rejected` is emitted with "bye" as parameter.

var middle_mouse_paste_enabled: bool = true#

If false, using middle mouse button to paste clipboard will be disabled.

Note: This method is only implemented on Linux.

var mouse_default_cursor_shape = CURSOR_IBEAM#

var placeholder_text: String = ""#

Text shown when the LineEdit is empty. It is not the LineEdit's default value (see text).

var right_icon: Texture2D#

Sets the icon that will appear in the right end of the LineEdit if there's no text, or always, if clear_button_enabled is set to false.

var secret: bool = false#

If true, every character is replaced with the secret character (see secret_character).

var secret_character: String = "•"#

The character to use to mask secret input. Only a single character can be used as the secret character. If it is longer than one character, only the first one will be used. If it is empty, a space will be used instead.

var select_all_on_focus: bool = false#

If true, the LineEdit will select the whole text when it gains focus.

var selecting_enabled: bool = true#

If false, it's impossible to select the text using mouse nor keyboard.

var shortcut_keys_enabled: bool = true#

If true, shortcut keys for context menu items are enabled, even if the context menu is disabled.

var structured_text_bidi_override = STRUCTURED_TEXT_DEFAULT#

Set BiDi algorithm override for the structured text.

var structured_text_bidi_override_options: Array = []#

Set additional options for BiDi override.

var text: String = ""#

String value of the LineEdit.

Note: Changing text using this property won't emit the text_changed signal.

var text_direction = TEXT_DIRECTION_AUTO#

Base text writing direction.

var virtual_keyboard_enabled: bool = true#

If true, the native virtual keyboard is shown when focused on platforms that support it.

var virtual_keyboard_type = KEYBOARD_TYPE_DEFAULT#

Specifies the type of virtual keyboard to show.

Methods #

func _ready():
    var menu = get_menu()
    # Remove all items after "Redo".
    menu.item_count = menu.get_item_index(MENU_REDO) + 1
    # Add custom items.
    menu.add_separator()
    menu.add_item("Insert Date", MENU_MAX + 1)
    # Connect callback.
    menu.id_pressed.connect(_on_item_pressed)

func _on_item_pressed(id):
    if id == MENU_MAX + 1:
        insert_text_at_caret(Time.get_date_string_from_system())

public override void _Ready()
{
    var menu = GetMenu();
    // Remove all items after "Redo".
    menu.ItemCount = menu.GetItemIndex(LineEdit.MenuItems.Redo) + 1;
    // Add custom items.
    menu.AddSeparator();
    menu.AddItem("Insert Date", LineEdit.MenuItems.Max + 1);
    // Add event handler.
    menu.IdPressed += OnItemPressed;
}

public void OnItemPressed(int id)
{
    if (id == LineEdit.MenuItems.Max + 1)
    {
        InsertTextAtCaret(Time.GetDateStringFromSystem());
    }
}

text = "Welcome"
select() # Will select "Welcome".
select(4) # Will select "ome".
select(2, 5) # Will select "lco".

Text = "Welcome";
Select(); // Will select "Welcome".
Select(4); // Will select "ome".
Select(2, 5); // Will select "lco".

Annotations #

Constants #

const MENU_CUT = 0 enum MenuItems#

Cuts (copies and clears) the selected text.

const MENU_COPY = 1 enum MenuItems#

Copies the selected text.

const MENU_PASTE = 2 enum MenuItems#

Pastes the clipboard text over the selected text (or at the caret's position).

Non-printable escape characters are automatically stripped from the OS clipboard via String.strip_escapes.

const MENU_CLEAR = 3 enum MenuItems#

Erases the whole LineEdit text.

const MENU_SELECT_ALL = 4 enum MenuItems#

Selects the whole LineEdit text.

const MENU_UNDO = 5 enum MenuItems#

Undoes the previous action.

const MENU_REDO = 6 enum MenuItems#

Reverse the last undo action.

const MENU_SUBMENU_TEXT_DIR = 7 enum MenuItems#

ID of "Text Writing Direction" submenu.

const MENU_DIR_INHERITED = 8 enum MenuItems#

Sets text direction to inherited.

const MENU_DIR_AUTO = 9 enum MenuItems#

Sets text direction to automatic.

const MENU_DIR_LTR = 10 enum MenuItems#

Sets text direction to left-to-right.

const MENU_DIR_RTL = 11 enum MenuItems#

Sets text direction to right-to-left.

const MENU_DISPLAY_UCC = 12 enum MenuItems#

Toggles control character display.

const MENU_SUBMENU_INSERT_UCC = 13 enum MenuItems#

ID of "Insert Control Character" submenu.

const MENU_INSERT_LRM = 14 enum MenuItems#

Inserts left-to-right mark (LRM) character.

const MENU_INSERT_RLM = 15 enum MenuItems#

Inserts right-to-left mark (RLM) character.

const MENU_INSERT_LRE = 16 enum MenuItems#

Inserts start of left-to-right embedding (LRE) character.

const MENU_INSERT_RLE = 17 enum MenuItems#

Inserts start of right-to-left embedding (RLE) character.

const MENU_INSERT_LRO = 18 enum MenuItems#

Inserts start of left-to-right override (LRO) character.

const MENU_INSERT_RLO = 19 enum MenuItems#

Inserts start of right-to-left override (RLO) character.

const MENU_INSERT_PDF = 20 enum MenuItems#

Inserts pop direction formatting (PDF) character.

const MENU_INSERT_ALM = 21 enum MenuItems#

Inserts Arabic letter mark (ALM) character.

const MENU_INSERT_LRI = 22 enum MenuItems#

Inserts left-to-right isolate (LRI) character.

const MENU_INSERT_RLI = 23 enum MenuItems#

Inserts right-to-left isolate (RLI) character.

const MENU_INSERT_FSI = 24 enum MenuItems#

Inserts first strong isolate (FSI) character.

const MENU_INSERT_PDI = 25 enum MenuItems#

Inserts pop direction isolate (PDI) character.

const MENU_INSERT_ZWJ = 26 enum MenuItems#

Inserts zero width joiner (ZWJ) character.

const MENU_INSERT_ZWNJ = 27 enum MenuItems#

Inserts zero width non-joiner (ZWNJ) character.

const MENU_INSERT_WJ = 28 enum MenuItems#

Inserts word joiner (WJ) character.

const MENU_INSERT_SHY = 29 enum MenuItems#

Inserts soft hyphen (SHY) character.

const MENU_EMOJI_AND_SYMBOL = 30 enum MenuItems#

Opens system emoji and symbol picker.

const MENU_MAX = 31 enum MenuItems#

Represents the size of the MenuItems enum.

const KEYBOARD_TYPE_DEFAULT = 0 enum VirtualKeyboardType#

Default text virtual keyboard.

const KEYBOARD_TYPE_MULTILINE = 1 enum VirtualKeyboardType#

Multiline virtual keyboard.

const KEYBOARD_TYPE_NUMBER = 2 enum VirtualKeyboardType#

Virtual number keypad, useful for PIN entry.

const KEYBOARD_TYPE_NUMBER_DECIMAL = 3 enum VirtualKeyboardType#

Virtual number keypad, useful for entering fractional numbers.

const KEYBOARD_TYPE_PHONE = 4 enum VirtualKeyboardType#

Virtual phone number keypad.

const KEYBOARD_TYPE_EMAIL_ADDRESS = 5 enum VirtualKeyboardType#

Virtual keyboard with additional keys to assist with typing email addresses.

const KEYBOARD_TYPE_PASSWORD = 6 enum VirtualKeyboardType#

Virtual keyboard for entering a password. On most platforms, this should disable autocomplete and autocapitalization.

Note: This is not supported on Web. Instead, this behaves identically to KEYBOARD_TYPE_DEFAULT.

const KEYBOARD_TYPE_URL = 7 enum VirtualKeyboardType#

Virtual keyboard with additional keys to assist with typing URLs.

Constructors #

Enums #

MenuItems#

VirtualKeyboardType#

Operators #

Signals #

signal editing_toggled(toggled_on: bool)#

Emitted when the LineEdit switches in or out of edit mode.

signal text_change_rejected(rejected_substring: String)#

Emitted when appending text that overflows the max_length. The appended text is truncated to fit max_length, and the part that couldn't fit is passed as the rejected_substring argument.

signal text_changed(new_text: String)#

Emitted when the text changes.

signal text_submitted(new_text: String)#

Emitted when the user presses the ui_text_submit action (by default: Enter or Kp Enter) while the LineEdit has focus.

Theme Items #

self["theme_override_colors/caret_color"] = Color(0.95, 0.95, 0.95, 1) as Color#

Color of the LineEdit's caret (text cursor). This can be set to a fully transparent color to hide the caret entirely.

self["theme_override_colors/clear_button_color"] = Color(0.875, 0.875, 0.875, 1) as Color#

Color used as default tint for the clear button.

self["theme_override_colors/clear_button_color_pressed"] = Color(1, 1, 1, 1) as Color#

Color used for the clear button when it's pressed.

self["theme_override_colors/font_color"] = Color(0.875, 0.875, 0.875, 1) as Color#

Default font color.

self["theme_override_colors/font_outline_color"] = Color(0, 0, 0, 1) as Color#

The tint of text outline of the LineEdit.

self["theme_override_colors/font_placeholder_color"] = Color(0.875, 0.875, 0.875, 0.6) as Color#

Font color for placeholder_text.

self["theme_override_colors/font_selected_color"] = Color(1, 1, 1, 1) as Color#

Font color for selected text (inside the selection rectangle).

self["theme_override_colors/font_uneditable_color"] = Color(0.875, 0.875, 0.875, 0.5) as Color#

Font color when editing is disabled.

self["theme_override_colors/selection_color"] = Color(0.5, 0.5, 0.5, 1) as Color#

Color of the selection rectangle.

self["theme_override_constants/caret_width"] = 1 as int#

The caret's width in pixels. Greater values can be used to improve accessibility by ensuring the caret is easily visible, or to ensure consistency with a large font size.

self["theme_override_constants/minimum_character_width"] = 4 as int#

Minimum horizontal space for the text (not counting the clear button and content margins). This value is measured in count of 'M' characters (i.e. this number of 'M' characters can be displayed without scrolling).

self["theme_override_constants/outline_size"] = 0 as int#

The size of the text outline.

Note: If using a font with FontFile.multichannel_signed_distance_field enabled, its FontFile.msdf_pixel_range must be set to at least twice the value of outline_size for outline rendering to look correct. Otherwise, the outline may appear to be cut off earlier than intended.

self["theme_override_fonts/font"] = font as Font#

Font used for the text.

self["theme_override_font_sizes/font_size"] = font_size as int#

Font size of the LineEdit's text.

self["theme_override_icons/clear"] = icon as Texture2D#

Texture for the clear button. See clear_button_enabled.

self["theme_override_styles/focus"] = style as StyleBox#

Background used when LineEdit has GUI focus. The focus StyleBox is displayed over the base StyleBox, so a partially transparent StyleBox should be used to ensure the base StyleBox remains visible. A StyleBox that represents an outline or an underline works well for this purpose. To disable the focus visual effect, assign a StyleBoxEmpty resource. Note that disabling the focus visual effect will harm keyboard/controller navigation usability, so this is not recommended for accessibility reasons.

self["theme_override_styles/normal"] = style as StyleBox#

Default background for the LineEdit.

self["theme_override_styles/read_only"] = style as StyleBox#

Background used when LineEdit is in read-only mode (editable is set to false).

Tutorials #