godot-docs/classes/class_lineedit.rst

: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/<name>/doc_classes.

.. _class_LineEdit:

LineEdit
========

**Inherits:** :ref:`Control<class_Control>` **<** :ref:`CanvasItem<class_CanvasItem>` **<** :ref:`Node<class_Node>` **<** :ref:`Object<class_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<enum_LineEdit_Align>`            | :ref:`align<class_LineEdit_property_align>`                                       | ``0``                     |
+----------------------------------------------+-----------------------------------------------------------------------------------+---------------------------+
| :ref:`bool<class_bool>`                      | :ref:`caret_blink<class_LineEdit_property_caret_blink>`                           | ``false``                 |
+----------------------------------------------+-----------------------------------------------------------------------------------+---------------------------+
| :ref:`float<class_float>`                    | :ref:`caret_blink_speed<class_LineEdit_property_caret_blink_speed>`               | ``0.65``                  |
+----------------------------------------------+-----------------------------------------------------------------------------------+---------------------------+
| :ref:`int<class_int>`                        | :ref:`caret_position<class_LineEdit_property_caret_position>`                     | ``0``                     |
+----------------------------------------------+-----------------------------------------------------------------------------------+---------------------------+
| :ref:`bool<class_bool>`                      | :ref:`clear_button_enabled<class_LineEdit_property_clear_button_enabled>`         | ``false``                 |
+----------------------------------------------+-----------------------------------------------------------------------------------+---------------------------+
| :ref:`bool<class_bool>`                      | :ref:`context_menu_enabled<class_LineEdit_property_context_menu_enabled>`         | ``true``                  |
+----------------------------------------------+-----------------------------------------------------------------------------------+---------------------------+
| :ref:`bool<class_bool>`                      | :ref:`editable<class_LineEdit_property_editable>`                                 | ``true``                  |
+----------------------------------------------+-----------------------------------------------------------------------------------+---------------------------+
| :ref:`bool<class_bool>`                      | :ref:`expand_to_text_length<class_LineEdit_property_expand_to_text_length>`       | ``false``                 |
+----------------------------------------------+-----------------------------------------------------------------------------------+---------------------------+
| :ref:`FocusMode<enum_Control_FocusMode>`     | focus_mode                                                                        | ``2`` *(parent override)* |
+----------------------------------------------+-----------------------------------------------------------------------------------+---------------------------+
| :ref:`int<class_int>`                        | :ref:`max_length<class_LineEdit_property_max_length>`                             | ``0``                     |
+----------------------------------------------+-----------------------------------------------------------------------------------+---------------------------+
| :ref:`CursorShape<enum_Control_CursorShape>` | mouse_default_cursor_shape                                                        | ``1`` *(parent override)* |
+----------------------------------------------+-----------------------------------------------------------------------------------+---------------------------+
| :ref:`float<class_float>`                    | :ref:`placeholder_alpha<class_LineEdit_property_placeholder_alpha>`               | ``0.6``                   |
+----------------------------------------------+-----------------------------------------------------------------------------------+---------------------------+
| :ref:`String<class_String>`                  | :ref:`placeholder_text<class_LineEdit_property_placeholder_text>`                 | ``""``                    |
+----------------------------------------------+-----------------------------------------------------------------------------------+---------------------------+
| :ref:`Texture<class_Texture>`                | :ref:`right_icon<class_LineEdit_property_right_icon>`                             |                           |
+----------------------------------------------+-----------------------------------------------------------------------------------+---------------------------+
| :ref:`bool<class_bool>`                      | :ref:`secret<class_LineEdit_property_secret>`                                     | ``false``                 |
+----------------------------------------------+-----------------------------------------------------------------------------------+---------------------------+
| :ref:`String<class_String>`                  | :ref:`secret_character<class_LineEdit_property_secret_character>`                 | ``"*"``                   |
+----------------------------------------------+-----------------------------------------------------------------------------------+---------------------------+
| :ref:`bool<class_bool>`                      | :ref:`selecting_enabled<class_LineEdit_property_selecting_enabled>`               | ``true``                  |
+----------------------------------------------+-----------------------------------------------------------------------------------+---------------------------+
| :ref:`bool<class_bool>`                      | :ref:`shortcut_keys_enabled<class_LineEdit_property_shortcut_keys_enabled>`       | ``true``                  |
+----------------------------------------------+-----------------------------------------------------------------------------------+---------------------------+
| :ref:`String<class_String>`                  | :ref:`text<class_LineEdit_property_text>`                                         | ``""``                    |
+----------------------------------------------+-----------------------------------------------------------------------------------+---------------------------+
| :ref:`bool<class_bool>`                      | :ref:`virtual_keyboard_enabled<class_LineEdit_property_virtual_keyboard_enabled>` | ``true``                  |
+----------------------------------------------+-----------------------------------------------------------------------------------+---------------------------+

Methods
-------

+-----------------------------------+--------------------------------------------------------------------------------------------------------------------------------------+
| void                              | :ref:`append_at_cursor<class_LineEdit_method_append_at_cursor>` **(** :ref:`String<class_String>` text **)**                         |
+-----------------------------------+--------------------------------------------------------------------------------------------------------------------------------------+
| void                              | :ref:`clear<class_LineEdit_method_clear>` **(** **)**                                                                                |
+-----------------------------------+--------------------------------------------------------------------------------------------------------------------------------------+
| void                              | :ref:`delete_char_at_cursor<class_LineEdit_method_delete_char_at_cursor>` **(** **)**                                                |
+-----------------------------------+--------------------------------------------------------------------------------------------------------------------------------------+
| void                              | :ref:`delete_text<class_LineEdit_method_delete_text>` **(** :ref:`int<class_int>` from_column, :ref:`int<class_int>` to_column **)** |
+-----------------------------------+--------------------------------------------------------------------------------------------------------------------------------------+
| void                              | :ref:`deselect<class_LineEdit_method_deselect>` **(** **)**                                                                          |
+-----------------------------------+--------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`PopupMenu<class_PopupMenu>` | :ref:`get_menu<class_LineEdit_method_get_menu>` **(** **)** |const|                                                                  |
+-----------------------------------+--------------------------------------------------------------------------------------------------------------------------------------+
| void                              | :ref:`menu_option<class_LineEdit_method_menu_option>` **(** :ref:`int<class_int>` option **)**                                       |
+-----------------------------------+--------------------------------------------------------------------------------------------------------------------------------------+
| void                              | :ref:`select<class_LineEdit_method_select>` **(** :ref:`int<class_int>` from=0, :ref:`int<class_int>` to=-1 **)**                    |
+-----------------------------------+--------------------------------------------------------------------------------------------------------------------------------------+
| void                              | :ref:`select_all<class_LineEdit_method_select_all>` **(** **)**                                                                      |
+-----------------------------------+--------------------------------------------------------------------------------------------------------------------------------------+

Theme Properties
----------------

+---------------------------------+----------------------------+--------------------------------+
| :ref:`Texture<class_Texture>`   | clear                      |                                |
+---------------------------------+----------------------------+--------------------------------+
| :ref:`Color<class_Color>`       | clear_button_color         | Color( 0.88, 0.88, 0.88, 1 )   |
+---------------------------------+----------------------------+--------------------------------+
| :ref:`Color<class_Color>`       | clear_button_color_pressed | Color( 1, 1, 1, 1 )            |
+---------------------------------+----------------------------+--------------------------------+
| :ref:`Color<class_Color>`       | cursor_color               | Color( 0.94, 0.94, 0.94, 1 )   |
+---------------------------------+----------------------------+--------------------------------+
| :ref:`StyleBox<class_StyleBox>` | focus                      |                                |
+---------------------------------+----------------------------+--------------------------------+
| :ref:`Font<class_Font>`         | font                       |                                |
+---------------------------------+----------------------------+--------------------------------+
| :ref:`Color<class_Color>`       | font_color                 | Color( 0.88, 0.88, 0.88, 1 )   |
+---------------------------------+----------------------------+--------------------------------+
| :ref:`Color<class_Color>`       | font_color_selected        | Color( 0, 0, 0, 1 )            |
+---------------------------------+----------------------------+--------------------------------+
| :ref:`Color<class_Color>`       | font_color_uneditable      | Color( 0.88, 0.88, 0.88, 0.5 ) |
+---------------------------------+----------------------------+--------------------------------+
| :ref:`int<class_int>`           | minimum_spaces             | 12                             |
+---------------------------------+----------------------------+--------------------------------+
| :ref:`StyleBox<class_StyleBox>` | normal                     |                                |
+---------------------------------+----------------------------+--------------------------------+
| :ref:`StyleBox<class_StyleBox>` | read_only                  |                                |
+---------------------------------+----------------------------+--------------------------------+
| :ref:`Color<class_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_property_max_length>`.

----

.. _class_LineEdit_signal_text_changed:

- **text_changed** **(** :ref:`String<class_String>` new_text **)**

Emitted when the text changes.

----

.. _class_LineEdit_signal_text_entered:

- **text_entered** **(** :ref:`String<class_String>` new_text **)**

Emitted when the user presses :ref:`@GlobalScope.KEY_ENTER<class_@GlobalScope_constant_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<class_String_method_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_LineEdit_MenuItems>` enum.

Property Descriptions
---------------------

.. _class_LineEdit_property_align:

- :ref:`Align<enum_LineEdit_Align>` **align**

+-----------+------------------+
| *Default* | ``0``            |
+-----------+------------------+
| *Setter*  | set_align(value) |
+-----------+------------------+
| *Getter*  | get_align()      |
+-----------+------------------+

Text alignment as defined in the :ref:`Align<enum_LineEdit_Align>` enum.

----

.. _class_LineEdit_property_caret_blink:

- :ref:`bool<class_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<class_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<class_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<class_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<class_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<class_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<class_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<class_LineEdit_property_text>`. It will **not** compress if the :ref:`text<class_LineEdit_property_text>` is shortened.

----

.. _class_LineEdit_property_max_length:

- :ref:`int<class_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<class_float>` **placeholder_alpha**

+-----------+------------------------------+
| *Default* | ``0.6``                      |
+-----------+------------------------------+
| *Setter*  | set_placeholder_alpha(value) |
+-----------+------------------------------+
| *Getter*  | get_placeholder_alpha()      |
+-----------+------------------------------+

Opacity of the :ref:`placeholder_text<class_LineEdit_property_placeholder_text>`. From ``0`` to ``1``.

----

.. _class_LineEdit_property_placeholder_text:

- :ref:`String<class_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_text>`).

----

.. _class_LineEdit_property_right_icon:

- :ref:`Texture<class_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<class_LineEdit_property_text>`, or always, if :ref:`clear_button_enabled<class_LineEdit_property_clear_button_enabled>` is set to ``false``.

----

.. _class_LineEdit_property_secret:

- :ref:`bool<class_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>`).

----

.. _class_LineEdit_property_secret_character:

- :ref:`String<class_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<class_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<class_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<class_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<class_LineEdit_signal_text_changed>` signal.

----

.. _class_LineEdit_property_virtual_keyboard_enabled:

- :ref:`bool<class_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<class_String>` text **)**

Adds ``text`` after the cursor. If the resulting value is longer than :ref:`max_length<class_LineEdit_property_max_length>`, nothing happens.

----

.. _class_LineEdit_method_clear:

- void **clear** **(** **)**

Erases the ``LineEdit``'s :ref:`text<class_LineEdit_property_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<class_int>` from_column, :ref:`int<class_int>` to_column **)**

Deletes a section of the :ref:`text<class_LineEdit_property_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<class_PopupMenu>` **get_menu** **(** **)** |const|

Returns the :ref:`PopupMenu<class_PopupMenu>` of this ``LineEdit``. By default, this menu is displayed when right-clicking on the ``LineEdit``.

----

.. _class_LineEdit_method_menu_option:

- void **menu_option** **(** :ref:`int<class_int>` option **)**

Executes a given action as defined in the :ref:`MenuItems<enum_LineEdit_MenuItems>` enum.

----

.. _class_LineEdit_method_select:

- void **select** **(** :ref:`int<class_int>` from=0, :ref:`int<class_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<class_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.)`