godot-docs/classes/class_label.rst

:github_url: hide

.. DO NOT EDIT THIS FILE!!!
.. Generated automatically from Godot engine sources.
.. Generator: https://github.com/godotengine/godot/tree/master/doc/tools/make_rst.py.
.. XML source: https://github.com/godotengine/godot/tree/master/doc/classes/Label.xml.

.. _class_Label:

Label
=====

**Inherits:** :ref:`Control<class_Control>` **<** :ref:`CanvasItem<class_CanvasItem>` **<** :ref:`Node<class_Node>` **<** :ref:`Object<class_Object>`

Displays plain text in a line or wrapped inside a rectangle. For formatted text, use :ref:`RichTextLabel<class_RichTextLabel>`.

Description
-----------

Label displays plain text on the screen. It gives you control over the horizontal and vertical alignment and can wrap the text inside the node's bounding rectangle. It doesn't support bold, italics, or other formatting. For that, use :ref:`RichTextLabel<class_RichTextLabel>` instead.

\ **Note:** Contrarily to most other :ref:`Control<class_Control>`\ s, Label's :ref:`Control.mouse_filter<class_Control_property_mouse_filter>` defaults to :ref:`Control.MOUSE_FILTER_IGNORE<class_Control_constant_MOUSE_FILTER_IGNORE>` (i.e. it doesn't react to mouse input events). This implies that a label won't display any configured :ref:`Control.hint_tooltip<class_Control_property_hint_tooltip>`, unless you change its mouse filter.

Tutorials
---------

- `2D Dodge The Creeps Demo <https://godotengine.org/asset-library/asset/515>`__

Properties
----------

+-----------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------+
| :ref:`AutowrapMode<enum_TextServer_AutowrapMode>`                           | :ref:`autowrap_mode<class_Label_property_autowrap_mode>`                                                 | ``0``                                                                        |
+-----------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------+
| :ref:`bool<class_bool>`                                                     | :ref:`clip_text<class_Label_property_clip_text>`                                                         | ``false``                                                                    |
+-----------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------+
| :ref:`HorizontalAlignment<enum_@GlobalScope_HorizontalAlignment>`           | :ref:`horizontal_alignment<class_Label_property_horizontal_alignment>`                                   | ``0``                                                                        |
+-----------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------+
| :ref:`LabelSettings<class_LabelSettings>`                                   | :ref:`label_settings<class_Label_property_label_settings>`                                               |                                                                              |
+-----------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------+
| :ref:`String<class_String>`                                                 | :ref:`language<class_Label_property_language>`                                                           | ``""``                                                                       |
+-----------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------+
| :ref:`int<class_int>`                                                       | :ref:`lines_skipped<class_Label_property_lines_skipped>`                                                 | ``0``                                                                        |
+-----------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------+
| :ref:`int<class_int>`                                                       | :ref:`max_lines_visible<class_Label_property_max_lines_visible>`                                         | ``-1``                                                                       |
+-----------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------+
| :ref:`MouseFilter<enum_Control_MouseFilter>`                                | mouse_filter                                                                                             | ``2`` (overrides :ref:`Control<class_Control_property_mouse_filter>`)        |
+-----------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------+
| :ref:`float<class_float>`                                                   | :ref:`percent_visible<class_Label_property_percent_visible>`                                             | ``1.0``                                                                      |
+-----------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------+
| :ref:`int<class_int>`                                                       | size_flags_vertical                                                                                      | ``4`` (overrides :ref:`Control<class_Control_property_size_flags_vertical>`) |
+-----------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------+
| :ref:`StructuredTextParser<enum_TextServer_StructuredTextParser>`           | :ref:`structured_text_bidi_override<class_Label_property_structured_text_bidi_override>`                 | ``0``                                                                        |
+-----------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------+
| :ref:`Array<class_Array>`                                                   | :ref:`structured_text_bidi_override_options<class_Label_property_structured_text_bidi_override_options>` | ``[]``                                                                       |
+-----------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------+
| :ref:`String<class_String>`                                                 | :ref:`text<class_Label_property_text>`                                                                   | ``""``                                                                       |
+-----------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------+
| :ref:`TextDirection<enum_Control_TextDirection>`                            | :ref:`text_direction<class_Label_property_text_direction>`                                               | ``0``                                                                        |
+-----------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------+
| :ref:`OverrunBehavior<enum_TextServer_OverrunBehavior>`                     | :ref:`text_overrun_behavior<class_Label_property_text_overrun_behavior>`                                 | ``0``                                                                        |
+-----------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------+
| :ref:`bool<class_bool>`                                                     | :ref:`uppercase<class_Label_property_uppercase>`                                                         | ``false``                                                                    |
+-----------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------+
| :ref:`VerticalAlignment<enum_@GlobalScope_VerticalAlignment>`               | :ref:`vertical_alignment<class_Label_property_vertical_alignment>`                                       | ``0``                                                                        |
+-----------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------+
| :ref:`int<class_int>`                                                       | :ref:`visible_characters<class_Label_property_visible_characters>`                                       | ``-1``                                                                       |
+-----------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------+
| :ref:`VisibleCharactersBehavior<enum_TextServer_VisibleCharactersBehavior>` | :ref:`visible_characters_behavior<class_Label_property_visible_characters_behavior>`                     | ``0``                                                                        |
+-----------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------+

Methods
-------

+-----------------------+--------------------------------------------------------------------------------------------------------------+
| :ref:`int<class_int>` | :ref:`get_line_count<class_Label_method_get_line_count>` **(** **)** |const|                                 |
+-----------------------+--------------------------------------------------------------------------------------------------------------+
| :ref:`int<class_int>` | :ref:`get_line_height<class_Label_method_get_line_height>` **(** :ref:`int<class_int>` line=-1 **)** |const| |
+-----------------------+--------------------------------------------------------------------------------------------------------------+
| :ref:`int<class_int>` | :ref:`get_total_character_count<class_Label_method_get_total_character_count>` **(** **)** |const|           |
+-----------------------+--------------------------------------------------------------------------------------------------------------+
| :ref:`int<class_int>` | :ref:`get_visible_line_count<class_Label_method_get_visible_line_count>` **(** **)** |const|                 |
+-----------------------+--------------------------------------------------------------------------------------------------------------+

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

+---------------------------------+----------------------------------------------------------------------------+-----------------------+
| :ref:`Color<class_Color>`       | :ref:`font_color<class_Label_theme_color_font_color>`                      | ``Color(1, 1, 1, 1)`` |
+---------------------------------+----------------------------------------------------------------------------+-----------------------+
| :ref:`Color<class_Color>`       | :ref:`font_outline_color<class_Label_theme_color_font_outline_color>`      | ``Color(1, 1, 1, 1)`` |
+---------------------------------+----------------------------------------------------------------------------+-----------------------+
| :ref:`Color<class_Color>`       | :ref:`font_shadow_color<class_Label_theme_color_font_shadow_color>`        | ``Color(0, 0, 0, 0)`` |
+---------------------------------+----------------------------------------------------------------------------+-----------------------+
| :ref:`int<class_int>`           | :ref:`line_spacing<class_Label_theme_constant_line_spacing>`               | ``3``                 |
+---------------------------------+----------------------------------------------------------------------------+-----------------------+
| :ref:`int<class_int>`           | :ref:`outline_size<class_Label_theme_constant_outline_size>`               | ``0``                 |
+---------------------------------+----------------------------------------------------------------------------+-----------------------+
| :ref:`int<class_int>`           | :ref:`shadow_offset_x<class_Label_theme_constant_shadow_offset_x>`         | ``1``                 |
+---------------------------------+----------------------------------------------------------------------------+-----------------------+
| :ref:`int<class_int>`           | :ref:`shadow_offset_y<class_Label_theme_constant_shadow_offset_y>`         | ``1``                 |
+---------------------------------+----------------------------------------------------------------------------+-----------------------+
| :ref:`int<class_int>`           | :ref:`shadow_outline_size<class_Label_theme_constant_shadow_outline_size>` | ``1``                 |
+---------------------------------+----------------------------------------------------------------------------+-----------------------+
| :ref:`Font<class_Font>`         | :ref:`font<class_Label_theme_font_font>`                                   |                       |
+---------------------------------+----------------------------------------------------------------------------+-----------------------+
| :ref:`int<class_int>`           | :ref:`font_size<class_Label_theme_font_size_font_size>`                    |                       |
+---------------------------------+----------------------------------------------------------------------------+-----------------------+
| :ref:`StyleBox<class_StyleBox>` | :ref:`normal<class_Label_theme_style_normal>`                              |                       |
+---------------------------------+----------------------------------------------------------------------------+-----------------------+

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

.. _class_Label_property_autowrap_mode:

- :ref:`AutowrapMode<enum_TextServer_AutowrapMode>` **autowrap_mode**

+-----------+--------------------------+
| *Default* | ``0``                    |
+-----------+--------------------------+
| *Setter*  | set_autowrap_mode(value) |
+-----------+--------------------------+
| *Getter*  | get_autowrap_mode()      |
+-----------+--------------------------+

If set to something other than :ref:`TextServer.AUTOWRAP_OFF<class_TextServer_constant_AUTOWRAP_OFF>`, the text gets wrapped inside the node's bounding rectangle. If you resize the node, it will change its height automatically to show all the text. To see how each mode behaves, see :ref:`AutowrapMode<enum_TextServer_AutowrapMode>`.

----

.. _class_Label_property_clip_text:

- :ref:`bool<class_bool>` **clip_text**

+-----------+----------------------+
| *Default* | ``false``            |
+-----------+----------------------+
| *Setter*  | set_clip_text(value) |
+-----------+----------------------+
| *Getter*  | is_clipping_text()   |
+-----------+----------------------+

If ``true``, the Label only shows the text that fits inside its bounding rectangle and will clip text horizontally.

----

.. _class_Label_property_horizontal_alignment:

- :ref:`HorizontalAlignment<enum_@GlobalScope_HorizontalAlignment>` **horizontal_alignment**

+-----------+---------------------------------+
| *Default* | ``0``                           |
+-----------+---------------------------------+
| *Setter*  | set_horizontal_alignment(value) |
+-----------+---------------------------------+
| *Getter*  | get_horizontal_alignment()      |
+-----------+---------------------------------+

Controls the text's horizontal alignment. Supports left, center, right, and fill, or justify. Set it to one of the :ref:`HorizontalAlignment<enum_@GlobalScope_HorizontalAlignment>` constants.

----

.. _class_Label_property_label_settings:

- :ref:`LabelSettings<class_LabelSettings>` **label_settings**

+----------+---------------------------+
| *Setter* | set_label_settings(value) |
+----------+---------------------------+
| *Getter* | get_label_settings()      |
+----------+---------------------------+

----

.. _class_Label_property_language:

- :ref:`String<class_String>` **language**

+-----------+---------------------+
| *Default* | ``""``              |
+-----------+---------------------+
| *Setter*  | set_language(value) |
+-----------+---------------------+
| *Getter*  | get_language()      |
+-----------+---------------------+

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

----

.. _class_Label_property_lines_skipped:

- :ref:`int<class_int>` **lines_skipped**

+-----------+--------------------------+
| *Default* | ``0``                    |
+-----------+--------------------------+
| *Setter*  | set_lines_skipped(value) |
+-----------+--------------------------+
| *Getter*  | get_lines_skipped()      |
+-----------+--------------------------+

The node ignores the first ``lines_skipped`` lines before it starts to display text.

----

.. _class_Label_property_max_lines_visible:

- :ref:`int<class_int>` **max_lines_visible**

+-----------+------------------------------+
| *Default* | ``-1``                       |
+-----------+------------------------------+
| *Setter*  | set_max_lines_visible(value) |
+-----------+------------------------------+
| *Getter*  | get_max_lines_visible()      |
+-----------+------------------------------+

Limits the lines of text the node shows on screen.

----

.. _class_Label_property_percent_visible:

- :ref:`float<class_float>` **percent_visible**

+-----------+----------------------------+
| *Default* | ``1.0``                    |
+-----------+----------------------------+
| *Setter*  | set_percent_visible(value) |
+-----------+----------------------------+
| *Getter*  | get_percent_visible()      |
+-----------+----------------------------+

Limits the amount of visible characters. If you set ``percent_visible`` to 0.5, only up to half of the text's characters will display on screen. Useful to animate the text in a dialog box.

\ **Note:** Setting this property updates :ref:`visible_characters<class_Label_property_visible_characters>` based on current :ref:`get_total_character_count<class_Label_method_get_total_character_count>`.

----

.. _class_Label_property_structured_text_bidi_override:

- :ref:`StructuredTextParser<enum_TextServer_StructuredTextParser>` **structured_text_bidi_override**

+-----------+------------------------------------------+
| *Default* | ``0``                                    |
+-----------+------------------------------------------+
| *Setter*  | set_structured_text_bidi_override(value) |
+-----------+------------------------------------------+
| *Getter*  | get_structured_text_bidi_override()      |
+-----------+------------------------------------------+

Set BiDi algorithm override for the structured text.

----

.. _class_Label_property_structured_text_bidi_override_options:

- :ref:`Array<class_Array>` **structured_text_bidi_override_options**

+-----------+--------------------------------------------------+
| *Default* | ``[]``                                           |
+-----------+--------------------------------------------------+
| *Setter*  | set_structured_text_bidi_override_options(value) |
+-----------+--------------------------------------------------+
| *Getter*  | get_structured_text_bidi_override_options()      |
+-----------+--------------------------------------------------+

Set additional options for BiDi override.

----

.. _class_Label_property_text:

- :ref:`String<class_String>` **text**

+-----------+-----------------+
| *Default* | ``""``          |
+-----------+-----------------+
| *Setter*  | set_text(value) |
+-----------+-----------------+
| *Getter*  | get_text()      |
+-----------+-----------------+

The text to display on screen.

----

.. _class_Label_property_text_direction:

- :ref:`TextDirection<enum_Control_TextDirection>` **text_direction**

+-----------+---------------------------+
| *Default* | ``0``                     |
+-----------+---------------------------+
| *Setter*  | set_text_direction(value) |
+-----------+---------------------------+
| *Getter*  | get_text_direction()      |
+-----------+---------------------------+

Base text writing direction.

----

.. _class_Label_property_text_overrun_behavior:

- :ref:`OverrunBehavior<enum_TextServer_OverrunBehavior>` **text_overrun_behavior**

+-----------+----------------------------------+
| *Default* | ``0``                            |
+-----------+----------------------------------+
| *Setter*  | set_text_overrun_behavior(value) |
+-----------+----------------------------------+
| *Getter*  | get_text_overrun_behavior()      |
+-----------+----------------------------------+

Sets the clipping behavior when the text exceeds the node's bounding rectangle. See :ref:`OverrunBehavior<enum_TextServer_OverrunBehavior>` for a description of all modes.

----

.. _class_Label_property_uppercase:

- :ref:`bool<class_bool>` **uppercase**

+-----------+----------------------+
| *Default* | ``false``            |
+-----------+----------------------+
| *Setter*  | set_uppercase(value) |
+-----------+----------------------+
| *Getter*  | is_uppercase()       |
+-----------+----------------------+

If ``true``, all the text displays as UPPERCASE.

----

.. _class_Label_property_vertical_alignment:

- :ref:`VerticalAlignment<enum_@GlobalScope_VerticalAlignment>` **vertical_alignment**

+-----------+-------------------------------+
| *Default* | ``0``                         |
+-----------+-------------------------------+
| *Setter*  | set_vertical_alignment(value) |
+-----------+-------------------------------+
| *Getter*  | get_vertical_alignment()      |
+-----------+-------------------------------+

Controls the text's vertical alignment. Supports top, center, bottom, and fill. Set it to one of the :ref:`VerticalAlignment<enum_@GlobalScope_VerticalAlignment>` constants.

----

.. _class_Label_property_visible_characters:

- :ref:`int<class_int>` **visible_characters**

+-----------+-------------------------------+
| *Default* | ``-1``                        |
+-----------+-------------------------------+
| *Setter*  | set_visible_characters(value) |
+-----------+-------------------------------+
| *Getter*  | get_visible_characters()      |
+-----------+-------------------------------+

Restricts the number of characters to display. Set to -1 to disable.

\ **Note:** Setting this property updates :ref:`percent_visible<class_Label_property_percent_visible>` based on current :ref:`get_total_character_count<class_Label_method_get_total_character_count>`.

----

.. _class_Label_property_visible_characters_behavior:

- :ref:`VisibleCharactersBehavior<enum_TextServer_VisibleCharactersBehavior>` **visible_characters_behavior**

+-----------+----------------------------------------+
| *Default* | ``0``                                  |
+-----------+----------------------------------------+
| *Setter*  | set_visible_characters_behavior(value) |
+-----------+----------------------------------------+
| *Getter*  | get_visible_characters_behavior()      |
+-----------+----------------------------------------+

Sets the clipping behavior when :ref:`visible_characters<class_Label_property_visible_characters>` or :ref:`percent_visible<class_Label_property_percent_visible>` is set. See :ref:`VisibleCharactersBehavior<enum_TextServer_VisibleCharactersBehavior>` for more info.

Method Descriptions
-------------------

.. _class_Label_method_get_line_count:

- :ref:`int<class_int>` **get_line_count** **(** **)** |const|

Returns the amount of lines of text the Label has.

----

.. _class_Label_method_get_line_height:

- :ref:`int<class_int>` **get_line_height** **(** :ref:`int<class_int>` line=-1 **)** |const|

Returns the height of the line ``line``.

If ``line`` is set to ``-1``, returns the biggest line height.

If there're no lines returns font size in pixels.

----

.. _class_Label_method_get_total_character_count:

- :ref:`int<class_int>` **get_total_character_count** **(** **)** |const|

Returns the total number of printable characters in the text (excluding spaces and newlines).

----

.. _class_Label_method_get_visible_line_count:

- :ref:`int<class_int>` **get_visible_line_count** **(** **)** |const|

Returns the number of lines shown. Useful if the ``Label``'s height cannot currently display all lines.

Theme Property Descriptions
---------------------------

.. _class_Label_theme_color_font_color:

- :ref:`Color<class_Color>` **font_color**

+-----------+-----------------------+
| *Default* | ``Color(1, 1, 1, 1)`` |
+-----------+-----------------------+

Default text :ref:`Color<class_Color>` of the ``Label``.

----

.. _class_Label_theme_color_font_outline_color:

- :ref:`Color<class_Color>` **font_outline_color**

+-----------+-----------------------+
| *Default* | ``Color(1, 1, 1, 1)`` |
+-----------+-----------------------+

The tint of text outline.

----

.. _class_Label_theme_color_font_shadow_color:

- :ref:`Color<class_Color>` **font_shadow_color**

+-----------+-----------------------+
| *Default* | ``Color(0, 0, 0, 0)`` |
+-----------+-----------------------+

:ref:`Color<class_Color>` of the text's shadow effect.

----

.. _class_Label_theme_constant_line_spacing:

- :ref:`int<class_int>` **line_spacing**

+-----------+-------+
| *Default* | ``3`` |
+-----------+-------+

Vertical space between lines in multiline ``Label``.

----

.. _class_Label_theme_constant_outline_size:

- :ref:`int<class_int>` **outline_size**

+-----------+-------+
| *Default* | ``0`` |
+-----------+-------+

Text outline size.

----

.. _class_Label_theme_constant_shadow_offset_x:

- :ref:`int<class_int>` **shadow_offset_x**

+-----------+-------+
| *Default* | ``1`` |
+-----------+-------+

The horizontal offset of the text's shadow.

----

.. _class_Label_theme_constant_shadow_offset_y:

- :ref:`int<class_int>` **shadow_offset_y**

+-----------+-------+
| *Default* | ``1`` |
+-----------+-------+

The vertical offset of the text's shadow.

----

.. _class_Label_theme_constant_shadow_outline_size:

- :ref:`int<class_int>` **shadow_outline_size**

+-----------+-------+
| *Default* | ``1`` |
+-----------+-------+

The size of the shadow outline.

----

.. _class_Label_theme_font_font:

- :ref:`Font<class_Font>` **font**

:ref:`Font<class_Font>` used for the ``Label``'s text.

----

.. _class_Label_theme_font_size_font_size:

- :ref:`int<class_int>` **font_size**

Font size of the ``Label``'s text.

----

.. _class_Label_theme_style_normal:

- :ref:`StyleBox<class_StyleBox>` **normal**

Background :ref:`StyleBox<class_StyleBox>` for the ``Label``.

.. |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.)`
.. |constructor| replace:: :abbr:`constructor (This method is used to construct a type.)`
.. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)`
.. |operator| replace:: :abbr:`operator (This method describes a valid operator to use with this type as left-hand operand.)`