LineEdit

Inherits: Control < CanvasItem < Node < Object

Control that provides single-line string editing.

Description

LineEdit provides a single-line string editor, used for text fields.

It features many built-in shortcuts which will always be available (Ctrl here maps to Command on macOS):

  • Ctrl + C: Copy
  • Ctrl + X: Cut
  • Ctrl + V or Ctrl + Y: Paste/“yank”
  • Ctrl + Z: Undo
  • Ctrl + Shift + Z: Redo
  • Ctrl + U: Delete text from the cursor position to the beginning of the line
  • Ctrl + K: Delete text from the cursor position to the end of the line
  • Ctrl + A: Select all text
  • Up/Down arrow: Move the cursor to the beginning/end of the line

On macOS, some extra keyboard shortcuts are available:

  • Ctrl + F: Like the right arrow key, move the cursor one character right
  • Ctrl + B: Like the left arrow key, move the cursor one character left
  • Ctrl + P: Like the up arrow key, move the cursor to the previous line
  • Ctrl + N: Like the down arrow key, move the cursor to the next line
  • Ctrl + D: Like the Delete key, delete the character on the right side of cursor
  • Ctrl + H: Like the Backspace key, delete the character on the left side of the cursor
  • Command + Left arrow: Like the Home key, move the cursor to the beginning of the line
  • Command + Right arrow: Like the End key, move the cursor to the end of the line

Properties

Alignalign0
boolcaret_blinkfalse
floatcaret_blink_speed0.65
intcaret_position0
boolclear_button_enabledfalse
boolcontext_menu_enabledtrue
booleditabletrue
boolexpand_to_text_lengthfalse
FocusModefocus_mode2 (parent override)
intmax_length0
CursorShapemouse_default_cursor_shape1 (parent override)
floatplaceholder_alpha0.6
Stringplaceholder_text“”
Textureright_icon 
boolsecretfalse
Stringsecret_character“*”
boolselecting_enabledtrue
boolshortcut_keys_enabledtrue
Stringtext“”
boolvirtual_keyboard_enabledtrue

Methods

voidappend_at_cursor ( String text )
voidclear ( )
voiddelete_char_at_cursor ( )
voiddelete_text ( int from_column, int to_column )
voiddeselect ( )
PopupMenuget_menu ( ) const
intget_scroll_offset ( ) const
voidmenu_option ( int option )
voidselect ( int from=0, int to=-1 )
voidselect_all ( )

Theme Properties

Textureclear 
Colorclear_button_colorColor( 0.88, 0.88, 0.88, 1 )
Colorclear_button_color_pressedColor( 1, 1, 1, 1 )
Colorcursor_colorColor( 0.94, 0.94, 0.94, 1 )
StyleBoxfocus 
Fontfont 
Colorfont_colorColor( 0.88, 0.88, 0.88, 1 )
Colorfont_color_selectedColor( 0, 0, 0, 1 )
Colorfont_color_uneditableColor( 0.88, 0.88, 0.88, 0.5 )
intminimum_spaces12
StyleBoxnormal 
StyleBoxread_only 
Colorselection_colorColor( 0.49, 0.49, 0.49, 1 )

Signals

  • text_change_rejected ( )

Emitted when trying to append text that would overflow the max_length.


  • text_changed ( String new_text )

Emitted when the text changes.


  • text_entered ( String new_text )

Emitted when the user presses @GlobalScope.KEY_ENTER on the LineEdit.

Enumerations

enum Align:

  • ALIGN_LEFT = 0 —- Aligns the text on the left-hand side of the LineEdit.
  • ALIGN_CENTER = 1 —- Centers the text in the middle of the LineEdit.
  • ALIGN_RIGHT = 2 —- Aligns the text on the right-hand side of the LineEdit.
  • ALIGN_FILL = 3 —- Stretches whitespaces to fit the LineEdit‘s width.

enum MenuItems:

  • MENU_CUT = 0 —- Cuts (copies and clears) the selected text.
  • MENU_COPY = 1 —- Copies the selected text.
  • MENU_PASTE = 2 —- Pastes the clipboard text over the selected text (or at the cursor’s position).

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

  • MENU_CLEAR = 3 —- Erases the whole LineEdit text.
  • MENU_SELECT_ALL = 4 —- Selects the whole LineEdit text.
  • MENU_UNDO = 5 —- Undoes the previous action.
  • MENU_REDO = 6 —- Reverse the last undo action.
  • MENU_MAX = 7 —- Represents the size of the MenuItems enum.

Property Descriptions

Default0
Setterset_align(value)
Getterget_align()

Text alignment as defined in the Align enum.


Defaultfalse
Settercursor_set_blink_enabled(value)
Gettercursor_get_blink_enabled()

If true, the caret (visual cursor) blinks.


Default0.65
Settercursor_set_blink_speed(value)
Gettercursor_get_blink_speed()

Duration (in seconds) of a caret’s blinking cycle.


  • int caret_position
Default0
Setterset_cursor_position(value)
Getterget_cursor_position()

The cursor’s position inside the LineEdit. When set, the text may scroll to accommodate it.


  • bool clear_button_enabled
Defaultfalse
Setterset_clear_button_enabled(value)
Getteris_clear_button_enabled()

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


  • bool context_menu_enabled
Defaulttrue
Setterset_context_menu_enabled(value)
Getteris_context_menu_enabled()

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


Defaulttrue
Setterset_editable(value)
Getteris_editable()

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


  • bool expand_to_text_length
Defaultfalse
Setterset_expand_to_text_length(value)
Getterget_expand_to_text_length()

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


  • int max_length
Default0
Setterset_max_length(value)
Getterget_max_length()

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


Default0.6
Setterset_placeholder_alpha(value)
Getterget_placeholder_alpha()

Opacity of the placeholder_text. From 0 to 1.


Default“”
Setterset_placeholder(value)
Getterget_placeholder()

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


Setterset_right_icon(value)
Getterget_right_icon()

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.


Defaultfalse
Setterset_secret(value)
Getteris_secret()

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


Default“*”
Setterset_secret_character(value)
Getterget_secret_character()

The character to use to mask secret input (defaults to “*“). Only a single character can be used as the secret character.


  • bool selecting_enabled
Defaulttrue
Setterset_selecting_enabled(value)
Getteris_selecting_enabled()

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


  • bool shortcut_keys_enabled
Defaulttrue
Setterset_shortcut_keys_enabled(value)
Getteris_shortcut_keys_enabled()

If false, using shortcuts will be disabled.


Default“”
Setterset_text(value)
Getterget_text()

String value of the LineEdit.

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


  • bool virtual_keyboard_enabled
Defaulttrue
Setterset_virtual_keyboard_enabled(value)
Getteris_virtual_keyboard_enabled()

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

Method Descriptions

  • void append_at_cursor ( String text )

Adds text after the cursor. If the resulting value is longer than max_length, nothing happens.


  • void clear ( )

Erases the LineEdit‘s text.


  • void delete_char_at_cursor ( )

Deletes one character at the cursor’s current position (equivalent to pressing the Delete key).


  • void delete_text ( int from_column, int to_column )

Deletes a section of the text going from position from_column to to_column. Both parameters should be within the text’s length.


  • void deselect ( )

Clears the current selection.


Returns the PopupMenu of this LineEdit. By default, this menu is displayed when right-clicking on the LineEdit.


  • int get_scroll_offset ( ) const

Returns the scroll offset due to caret_position, as a number of characters.


  • void menu_option ( int option )

Executes a given action as defined in the MenuItems enum.


  • void select ( int from=0, int to=-1 )

Selects characters inside LineEdit between from and to. By default, from is at the beginning and to at the end.

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

  • void select_all ( )

Selects the whole String.