:github_url: hide .. Generated automatically by doc/tools/makerst.py in Godot's source tree. .. DO NOT EDIT THIS FILE, but the LineEdit.xml source instead. .. The source is found in doc/classes or modules//doc_classes. .. _class_LineEdit: LineEdit ======== **Inherits:** :ref:`Control` **<** :ref:`CanvasItem` **<** :ref:`Node` **<** :ref:`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 ---------- +----------------------------------------------+-----------------------------------------------------------------------------------+---------------------------+ | :ref:`Align` | :ref:`align` | ``0`` | +----------------------------------------------+-----------------------------------------------------------------------------------+---------------------------+ | :ref:`bool` | :ref:`caret_blink` | ``false`` | +----------------------------------------------+-----------------------------------------------------------------------------------+---------------------------+ | :ref:`float` | :ref:`caret_blink_speed` | ``0.65`` | +----------------------------------------------+-----------------------------------------------------------------------------------+---------------------------+ | :ref:`int` | :ref:`caret_position` | ``0`` | +----------------------------------------------+-----------------------------------------------------------------------------------+---------------------------+ | :ref:`bool` | :ref:`clear_button_enabled` | ``false`` | +----------------------------------------------+-----------------------------------------------------------------------------------+---------------------------+ | :ref:`bool` | :ref:`context_menu_enabled` | ``true`` | +----------------------------------------------+-----------------------------------------------------------------------------------+---------------------------+ | :ref:`bool` | :ref:`editable` | ``true`` | +----------------------------------------------+-----------------------------------------------------------------------------------+---------------------------+ | :ref:`bool` | :ref:`expand_to_text_length` | ``false`` | +----------------------------------------------+-----------------------------------------------------------------------------------+---------------------------+ | :ref:`FocusMode` | focus_mode | ``2`` *(parent override)* | +----------------------------------------------+-----------------------------------------------------------------------------------+---------------------------+ | :ref:`int` | :ref:`max_length` | ``0`` | +----------------------------------------------+-----------------------------------------------------------------------------------+---------------------------+ | :ref:`CursorShape` | mouse_default_cursor_shape | ``1`` *(parent override)* | +----------------------------------------------+-----------------------------------------------------------------------------------+---------------------------+ | :ref:`float` | :ref:`placeholder_alpha` | ``0.6`` | +----------------------------------------------+-----------------------------------------------------------------------------------+---------------------------+ | :ref:`String` | :ref:`placeholder_text` | ``""`` | +----------------------------------------------+-----------------------------------------------------------------------------------+---------------------------+ | :ref:`Texture` | :ref:`right_icon` | | +----------------------------------------------+-----------------------------------------------------------------------------------+---------------------------+ | :ref:`bool` | :ref:`secret` | ``false`` | +----------------------------------------------+-----------------------------------------------------------------------------------+---------------------------+ | :ref:`String` | :ref:`secret_character` | ``"*"`` | +----------------------------------------------+-----------------------------------------------------------------------------------+---------------------------+ | :ref:`bool` | :ref:`selecting_enabled` | ``true`` | +----------------------------------------------+-----------------------------------------------------------------------------------+---------------------------+ | :ref:`bool` | :ref:`shortcut_keys_enabled` | ``true`` | +----------------------------------------------+-----------------------------------------------------------------------------------+---------------------------+ | :ref:`String` | :ref:`text` | ``""`` | +----------------------------------------------+-----------------------------------------------------------------------------------+---------------------------+ | :ref:`bool` | :ref:`virtual_keyboard_enabled` | ``true`` | +----------------------------------------------+-----------------------------------------------------------------------------------+---------------------------+ Methods ------- +-----------------------------------+--------------------------------------------------------------------------------------------------------------------------------------+ | void | :ref:`append_at_cursor` **(** :ref:`String` text **)** | +-----------------------------------+--------------------------------------------------------------------------------------------------------------------------------------+ | void | :ref:`clear` **(** **)** | +-----------------------------------+--------------------------------------------------------------------------------------------------------------------------------------+ | void | :ref:`delete_char_at_cursor` **(** **)** | +-----------------------------------+--------------------------------------------------------------------------------------------------------------------------------------+ | void | :ref:`delete_text` **(** :ref:`int` from_column, :ref:`int` to_column **)** | +-----------------------------------+--------------------------------------------------------------------------------------------------------------------------------------+ | void | :ref:`deselect` **(** **)** | +-----------------------------------+--------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`PopupMenu` | :ref:`get_menu` **(** **)** |const| | +-----------------------------------+--------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`int` | :ref:`get_scroll_offset` **(** **)** |const| | +-----------------------------------+--------------------------------------------------------------------------------------------------------------------------------------+ | void | :ref:`menu_option` **(** :ref:`int` option **)** | +-----------------------------------+--------------------------------------------------------------------------------------------------------------------------------------+ | void | :ref:`select` **(** :ref:`int` from=0, :ref:`int` to=-1 **)** | +-----------------------------------+--------------------------------------------------------------------------------------------------------------------------------------+ | void | :ref:`select_all` **(** **)** | +-----------------------------------+--------------------------------------------------------------------------------------------------------------------------------------+ Theme Properties ---------------- +---------------------------------+----------------------------+--------------------------------+ | :ref:`Texture` | clear | | +---------------------------------+----------------------------+--------------------------------+ | :ref:`Color` | clear_button_color | Color( 0.88, 0.88, 0.88, 1 ) | +---------------------------------+----------------------------+--------------------------------+ | :ref:`Color` | clear_button_color_pressed | Color( 1, 1, 1, 1 ) | +---------------------------------+----------------------------+--------------------------------+ | :ref:`Color` | cursor_color | Color( 0.94, 0.94, 0.94, 1 ) | +---------------------------------+----------------------------+--------------------------------+ | :ref:`StyleBox` | focus | | +---------------------------------+----------------------------+--------------------------------+ | :ref:`Font` | font | | +---------------------------------+----------------------------+--------------------------------+ | :ref:`Color` | font_color | Color( 0.88, 0.88, 0.88, 1 ) | +---------------------------------+----------------------------+--------------------------------+ | :ref:`Color` | font_color_selected | Color( 0, 0, 0, 1 ) | +---------------------------------+----------------------------+--------------------------------+ | :ref:`Color` | font_color_uneditable | Color( 0.88, 0.88, 0.88, 0.5 ) | +---------------------------------+----------------------------+--------------------------------+ | :ref:`int` | minimum_spaces | 12 | +---------------------------------+----------------------------+--------------------------------+ | :ref:`StyleBox` | normal | | +---------------------------------+----------------------------+--------------------------------+ | :ref:`StyleBox` | read_only | | +---------------------------------+----------------------------+--------------------------------+ | :ref:`Color` | selection_color | Color( 0.49, 0.49, 0.49, 1 ) | +---------------------------------+----------------------------+--------------------------------+ Signals ------- .. _class_LineEdit_signal_text_change_rejected: - **text_change_rejected** **(** **)** Emitted when trying to append text that would overflow the :ref:`max_length`. ---- .. _class_LineEdit_signal_text_changed: - **text_changed** **(** :ref:`String` new_text **)** Emitted when the text changes. ---- .. _class_LineEdit_signal_text_entered: - **text_entered** **(** :ref:`String` new_text **)** Emitted when the user presses :ref:`@GlobalScope.KEY_ENTER` on the ``LineEdit``. Enumerations ------------ .. _enum_LineEdit_Align: .. _class_LineEdit_constant_ALIGN_LEFT: .. _class_LineEdit_constant_ALIGN_CENTER: .. _class_LineEdit_constant_ALIGN_RIGHT: .. _class_LineEdit_constant_ALIGN_FILL: 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_LineEdit_MenuItems: .. _class_LineEdit_constant_MENU_CUT: .. _class_LineEdit_constant_MENU_COPY: .. _class_LineEdit_constant_MENU_PASTE: .. _class_LineEdit_constant_MENU_CLEAR: .. _class_LineEdit_constant_MENU_SELECT_ALL: .. _class_LineEdit_constant_MENU_UNDO: .. _class_LineEdit_constant_MENU_REDO: .. _class_LineEdit_constant_MENU_MAX: 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 :ref:`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 :ref:`MenuItems` enum. Property Descriptions --------------------- .. _class_LineEdit_property_align: - :ref:`Align` **align** +-----------+------------------+ | *Default* | ``0`` | +-----------+------------------+ | *Setter* | set_align(value) | +-----------+------------------+ | *Getter* | get_align() | +-----------+------------------+ Text alignment as defined in the :ref:`Align` enum. ---- .. _class_LineEdit_property_caret_blink: - :ref:`bool` **caret_blink** +-----------+---------------------------------+ | *Default* | ``false`` | +-----------+---------------------------------+ | *Setter* | cursor_set_blink_enabled(value) | +-----------+---------------------------------+ | *Getter* | cursor_get_blink_enabled() | +-----------+---------------------------------+ If ``true``, the caret (visual cursor) blinks. ---- .. _class_LineEdit_property_caret_blink_speed: - :ref:`float` **caret_blink_speed** +-----------+-------------------------------+ | *Default* | ``0.65`` | +-----------+-------------------------------+ | *Setter* | cursor_set_blink_speed(value) | +-----------+-------------------------------+ | *Getter* | cursor_get_blink_speed() | +-----------+-------------------------------+ Duration (in seconds) of a caret's blinking cycle. ---- .. _class_LineEdit_property_caret_position: - :ref:`int` **caret_position** +-----------+----------------------------+ | *Default* | ``0`` | +-----------+----------------------------+ | *Setter* | set_cursor_position(value) | +-----------+----------------------------+ | *Getter* | get_cursor_position() | +-----------+----------------------------+ The cursor's position inside the ``LineEdit``. When set, the text may scroll to accommodate it. ---- .. _class_LineEdit_property_clear_button_enabled: - :ref:`bool` **clear_button_enabled** +-----------+---------------------------------+ | *Default* | ``false`` | +-----------+---------------------------------+ | *Setter* | set_clear_button_enabled(value) | +-----------+---------------------------------+ | *Getter* | is_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. ---- .. _class_LineEdit_property_context_menu_enabled: - :ref:`bool` **context_menu_enabled** +-----------+---------------------------------+ | *Default* | ``true`` | +-----------+---------------------------------+ | *Setter* | set_context_menu_enabled(value) | +-----------+---------------------------------+ | *Getter* | is_context_menu_enabled() | +-----------+---------------------------------+ If ``true``, the context menu will appear when right-clicked. ---- .. _class_LineEdit_property_editable: - :ref:`bool` **editable** +-----------+---------------------+ | *Default* | ``true`` | +-----------+---------------------+ | *Setter* | set_editable(value) | +-----------+---------------------+ | *Getter* | is_editable() | +-----------+---------------------+ If ``false``, existing text cannot be modified and new text cannot be added. ---- .. _class_LineEdit_property_expand_to_text_length: - :ref:`bool` **expand_to_text_length** +-----------+----------------------------------+ | *Default* | ``false`` | +-----------+----------------------------------+ | *Setter* | set_expand_to_text_length(value) | +-----------+----------------------------------+ | *Getter* | get_expand_to_text_length() | +-----------+----------------------------------+ If ``true``, the ``LineEdit`` width will increase to stay longer than the :ref:`text`. It will **not** compress if the :ref:`text` is shortened. ---- .. _class_LineEdit_property_max_length: - :ref:`int` **max_length** +-----------+-----------------------+ | *Default* | ``0`` | +-----------+-----------------------+ | *Setter* | set_max_length(value) | +-----------+-----------------------+ | *Getter* | get_max_length() | +-----------+-----------------------+ Maximum amount of characters that can be entered inside the ``LineEdit``. If ``0``, there is no limit. ---- .. _class_LineEdit_property_placeholder_alpha: - :ref:`float` **placeholder_alpha** +-----------+------------------------------+ | *Default* | ``0.6`` | +-----------+------------------------------+ | *Setter* | set_placeholder_alpha(value) | +-----------+------------------------------+ | *Getter* | get_placeholder_alpha() | +-----------+------------------------------+ Opacity of the :ref:`placeholder_text`. From ``0`` to ``1``. ---- .. _class_LineEdit_property_placeholder_text: - :ref:`String` **placeholder_text** +-----------+------------------------+ | *Default* | ``""`` | +-----------+------------------------+ | *Setter* | set_placeholder(value) | +-----------+------------------------+ | *Getter* | get_placeholder() | +-----------+------------------------+ Text shown when the ``LineEdit`` is empty. It is **not** the ``LineEdit``'s default value (see :ref:`text`). ---- .. _class_LineEdit_property_right_icon: - :ref:`Texture` **right_icon** +----------+-----------------------+ | *Setter* | set_right_icon(value) | +----------+-----------------------+ | *Getter* | get_right_icon() | +----------+-----------------------+ Sets the icon that will appear in the right end of the ``LineEdit`` if there's no :ref:`text`, or always, if :ref:`clear_button_enabled` is set to ``false``. ---- .. _class_LineEdit_property_secret: - :ref:`bool` **secret** +-----------+-------------------+ | *Default* | ``false`` | +-----------+-------------------+ | *Setter* | set_secret(value) | +-----------+-------------------+ | *Getter* | is_secret() | +-----------+-------------------+ If ``true``, every character is replaced with the secret character (see :ref:`secret_character`). ---- .. _class_LineEdit_property_secret_character: - :ref:`String` **secret_character** +-----------+-----------------------------+ | *Default* | ``"*"`` | +-----------+-----------------------------+ | *Setter* | set_secret_character(value) | +-----------+-----------------------------+ | *Getter* | get_secret_character() | +-----------+-----------------------------+ The character to use to mask secret input (defaults to "\*"). Only a single character can be used as the secret character. ---- .. _class_LineEdit_property_selecting_enabled: - :ref:`bool` **selecting_enabled** +-----------+------------------------------+ | *Default* | ``true`` | +-----------+------------------------------+ | *Setter* | set_selecting_enabled(value) | +-----------+------------------------------+ | *Getter* | is_selecting_enabled() | +-----------+------------------------------+ If ``false``, it's impossible to select the text using mouse nor keyboard. ---- .. _class_LineEdit_property_shortcut_keys_enabled: - :ref:`bool` **shortcut_keys_enabled** +-----------+----------------------------------+ | *Default* | ``true`` | +-----------+----------------------------------+ | *Setter* | set_shortcut_keys_enabled(value) | +-----------+----------------------------------+ | *Getter* | is_shortcut_keys_enabled() | +-----------+----------------------------------+ If ``false``, using shortcuts will be disabled. ---- .. _class_LineEdit_property_text: - :ref:`String` **text** +-----------+-----------------+ | *Default* | ``""`` | +-----------+-----------------+ | *Setter* | set_text(value) | +-----------+-----------------+ | *Getter* | get_text() | +-----------+-----------------+ String value of the ``LineEdit``. **Note:** Changing text using this property won't emit the :ref:`text_changed` signal. ---- .. _class_LineEdit_property_virtual_keyboard_enabled: - :ref:`bool` **virtual_keyboard_enabled** +-----------+-------------------------------------+ | *Default* | ``true`` | +-----------+-------------------------------------+ | *Setter* | set_virtual_keyboard_enabled(value) | +-----------+-------------------------------------+ | *Getter* | is_virtual_keyboard_enabled() | +-----------+-------------------------------------+ If ``true``, the native virtual keyboard is shown when focused on platforms that support it. Method Descriptions ------------------- .. _class_LineEdit_method_append_at_cursor: - void **append_at_cursor** **(** :ref:`String` text **)** Adds ``text`` after the cursor. If the resulting value is longer than :ref:`max_length`, nothing happens. ---- .. _class_LineEdit_method_clear: - void **clear** **(** **)** Erases the ``LineEdit``'s :ref:`text`. ---- .. _class_LineEdit_method_delete_char_at_cursor: - void **delete_char_at_cursor** **(** **)** Deletes one character at the cursor's current position (equivalent to pressing the ``Delete`` key). ---- .. _class_LineEdit_method_delete_text: - void **delete_text** **(** :ref:`int` from_column, :ref:`int` to_column **)** Deletes a section of the :ref:`text` going from position ``from_column`` to ``to_column``. Both parameters should be within the text's length. ---- .. _class_LineEdit_method_deselect: - void **deselect** **(** **)** Clears the current selection. ---- .. _class_LineEdit_method_get_menu: - :ref:`PopupMenu` **get_menu** **(** **)** |const| Returns the :ref:`PopupMenu` of this ``LineEdit``. By default, this menu is displayed when right-clicking on the ``LineEdit``. ---- .. _class_LineEdit_method_get_scroll_offset: - :ref:`int` **get_scroll_offset** **(** **)** |const| Returns the scroll offset due to :ref:`caret_position`, as a number of characters. ---- .. _class_LineEdit_method_menu_option: - void **menu_option** **(** :ref:`int` option **)** Executes a given action as defined in the :ref:`MenuItems` enum. ---- .. _class_LineEdit_method_select: - void **select** **(** :ref:`int` from=0, :ref:`int` to=-1 **)** Selects characters inside ``LineEdit`` between ``from`` and ``to``. By default, ``from`` is at the beginning and ``to`` at the end. :: text = "Welcome" select() # Will select "Welcome". select(4) # Will select "ome". select(2, 5) # Will select "lco". ---- .. _class_LineEdit_method_select_all: - void **select_all** **(** **)** Selects the whole :ref:`String`. .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` .. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` .. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)`