godot-docs/classes/class_textline.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/TextLine.xml.

.. _class_TextLine:

TextLine
========

**Inherits:** :ref:`RefCounted<class_RefCounted>` **<** :ref:`Object<class_Object>`

Holds a line of text.

.. rst-class:: classref-introduction-group

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

Abstraction over :ref:`TextServer<class_TextServer>` for handling a single line of text.

.. rst-class:: classref-reftable-group

Properties
----------

.. table::
   :widths: auto

   +---------------------------------------------------------------------------+-----------------------------------------------------------------------------+-----------+
   | :ref:`HorizontalAlignment<enum_@GlobalScope_HorizontalAlignment>`         | :ref:`alignment<class_TextLine_property_alignment>`                         | ``0``     |
   +---------------------------------------------------------------------------+-----------------------------------------------------------------------------+-----------+
   | :ref:`Direction<enum_TextServer_Direction>`                               | :ref:`direction<class_TextLine_property_direction>`                         | ``0``     |
   +---------------------------------------------------------------------------+-----------------------------------------------------------------------------+-----------+
   | :ref:`String<class_String>`                                               | :ref:`ellipsis_char<class_TextLine_property_ellipsis_char>`                 | ``"…"``   |
   +---------------------------------------------------------------------------+-----------------------------------------------------------------------------+-----------+
   | |bitfield|\<:ref:`JustificationFlag<enum_TextServer_JustificationFlag>`\> | :ref:`flags<class_TextLine_property_flags>`                                 | ``3``     |
   +---------------------------------------------------------------------------+-----------------------------------------------------------------------------+-----------+
   | :ref:`Orientation<enum_TextServer_Orientation>`                           | :ref:`orientation<class_TextLine_property_orientation>`                     | ``0``     |
   +---------------------------------------------------------------------------+-----------------------------------------------------------------------------+-----------+
   | :ref:`bool<class_bool>`                                                   | :ref:`preserve_control<class_TextLine_property_preserve_control>`           | ``false`` |
   +---------------------------------------------------------------------------+-----------------------------------------------------------------------------+-----------+
   | :ref:`bool<class_bool>`                                                   | :ref:`preserve_invalid<class_TextLine_property_preserve_invalid>`           | ``true``  |
   +---------------------------------------------------------------------------+-----------------------------------------------------------------------------+-----------+
   | :ref:`OverrunBehavior<enum_TextServer_OverrunBehavior>`                   | :ref:`text_overrun_behavior<class_TextLine_property_text_overrun_behavior>` | ``3``     |
   +---------------------------------------------------------------------------+-----------------------------------------------------------------------------+-----------+
   | :ref:`float<class_float>`                                                 | :ref:`width<class_TextLine_property_width>`                                 | ``-1.0``  |
   +---------------------------------------------------------------------------+-----------------------------------------------------------------------------+-----------+

.. rst-class:: classref-reftable-group

Methods
-------

.. table::
   :widths: auto

   +-------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
   | :ref:`bool<class_bool>`       | :ref:`add_object<class_TextLine_method_add_object>` **(** :ref:`Variant<class_Variant>` key, :ref:`Vector2<class_Vector2>` size, :ref:`InlineAlignment<enum_@GlobalScope_InlineAlignment>` inline_align=5, :ref:`int<class_int>` length=1, :ref:`float<class_float>` baseline=0.0 **)** |
   +-------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
   | :ref:`bool<class_bool>`       | :ref:`add_string<class_TextLine_method_add_string>` **(** :ref:`String<class_String>` text, :ref:`Font<class_Font>` font, :ref:`int<class_int>` font_size, :ref:`String<class_String>` language="", :ref:`Variant<class_Variant>` meta=null **)**                                       |
   +-------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
   | void                          | :ref:`clear<class_TextLine_method_clear>` **(** **)**                                                                                                                                                                                                                                   |
   +-------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
   | void                          | :ref:`draw<class_TextLine_method_draw>` **(** :ref:`RID<class_RID>` canvas, :ref:`Vector2<class_Vector2>` pos, :ref:`Color<class_Color>` color=Color(1, 1, 1, 1) **)** |const|                                                                                                          |
   +-------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
   | void                          | :ref:`draw_outline<class_TextLine_method_draw_outline>` **(** :ref:`RID<class_RID>` canvas, :ref:`Vector2<class_Vector2>` pos, :ref:`int<class_int>` outline_size=1, :ref:`Color<class_Color>` color=Color(1, 1, 1, 1) **)** |const|                                                    |
   +-------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
   | :ref:`float<class_float>`     | :ref:`get_line_ascent<class_TextLine_method_get_line_ascent>` **(** **)** |const|                                                                                                                                                                                                       |
   +-------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
   | :ref:`float<class_float>`     | :ref:`get_line_descent<class_TextLine_method_get_line_descent>` **(** **)** |const|                                                                                                                                                                                                     |
   +-------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
   | :ref:`float<class_float>`     | :ref:`get_line_underline_position<class_TextLine_method_get_line_underline_position>` **(** **)** |const|                                                                                                                                                                               |
   +-------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
   | :ref:`float<class_float>`     | :ref:`get_line_underline_thickness<class_TextLine_method_get_line_underline_thickness>` **(** **)** |const|                                                                                                                                                                             |
   +-------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
   | :ref:`float<class_float>`     | :ref:`get_line_width<class_TextLine_method_get_line_width>` **(** **)** |const|                                                                                                                                                                                                         |
   +-------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
   | :ref:`Rect2<class_Rect2>`     | :ref:`get_object_rect<class_TextLine_method_get_object_rect>` **(** :ref:`Variant<class_Variant>` key **)** |const|                                                                                                                                                                     |
   +-------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
   | :ref:`Array<class_Array>`     | :ref:`get_objects<class_TextLine_method_get_objects>` **(** **)** |const|                                                                                                                                                                                                               |
   +-------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
   | :ref:`RID<class_RID>`         | :ref:`get_rid<class_TextLine_method_get_rid>` **(** **)** |const|                                                                                                                                                                                                                       |
   +-------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
   | :ref:`Vector2<class_Vector2>` | :ref:`get_size<class_TextLine_method_get_size>` **(** **)** |const|                                                                                                                                                                                                                     |
   +-------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
   | :ref:`int<class_int>`         | :ref:`hit_test<class_TextLine_method_hit_test>` **(** :ref:`float<class_float>` coords **)** |const|                                                                                                                                                                                    |
   +-------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
   | :ref:`bool<class_bool>`       | :ref:`resize_object<class_TextLine_method_resize_object>` **(** :ref:`Variant<class_Variant>` key, :ref:`Vector2<class_Vector2>` size, :ref:`InlineAlignment<enum_@GlobalScope_InlineAlignment>` inline_align=5, :ref:`float<class_float>` baseline=0.0 **)**                           |
   +-------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
   | void                          | :ref:`set_bidi_override<class_TextLine_method_set_bidi_override>` **(** :ref:`Array<class_Array>` override **)**                                                                                                                                                                        |
   +-------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
   | void                          | :ref:`tab_align<class_TextLine_method_tab_align>` **(** :ref:`PackedFloat32Array<class_PackedFloat32Array>` tab_stops **)**                                                                                                                                                             |
   +-------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+

.. rst-class:: classref-section-separator

----

.. rst-class:: classref-descriptions-group

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

.. _class_TextLine_property_alignment:

.. rst-class:: classref-property

:ref:`HorizontalAlignment<enum_@GlobalScope_HorizontalAlignment>` **alignment** = ``0``

.. rst-class:: classref-property-setget

- void **set_horizontal_alignment** **(** :ref:`HorizontalAlignment<enum_@GlobalScope_HorizontalAlignment>` value **)**
- :ref:`HorizontalAlignment<enum_@GlobalScope_HorizontalAlignment>` **get_horizontal_alignment** **(** **)**

Sets text alignment within the line as if the line was horizontal.

.. rst-class:: classref-item-separator

----

.. _class_TextLine_property_direction:

.. rst-class:: classref-property

:ref:`Direction<enum_TextServer_Direction>` **direction** = ``0``

.. rst-class:: classref-property-setget

- void **set_direction** **(** :ref:`Direction<enum_TextServer_Direction>` value **)**
- :ref:`Direction<enum_TextServer_Direction>` **get_direction** **(** **)**

Text writing direction.

.. rst-class:: classref-item-separator

----

.. _class_TextLine_property_ellipsis_char:

.. rst-class:: classref-property

:ref:`String<class_String>` **ellipsis_char** = ``"…"``

.. rst-class:: classref-property-setget

- void **set_ellipsis_char** **(** :ref:`String<class_String>` value **)**
- :ref:`String<class_String>` **get_ellipsis_char** **(** **)**

Ellipsis character used for text clipping.

.. rst-class:: classref-item-separator

----

.. _class_TextLine_property_flags:

.. rst-class:: classref-property

|bitfield|\<:ref:`JustificationFlag<enum_TextServer_JustificationFlag>`\> **flags** = ``3``

.. rst-class:: classref-property-setget

- void **set_flags** **(** |bitfield|\<:ref:`JustificationFlag<enum_TextServer_JustificationFlag>`\> value **)**
- |bitfield|\<:ref:`JustificationFlag<enum_TextServer_JustificationFlag>`\> **get_flags** **(** **)**

Line alignment rules. For more info see :ref:`TextServer<class_TextServer>`.

.. rst-class:: classref-item-separator

----

.. _class_TextLine_property_orientation:

.. rst-class:: classref-property

:ref:`Orientation<enum_TextServer_Orientation>` **orientation** = ``0``

.. rst-class:: classref-property-setget

- void **set_orientation** **(** :ref:`Orientation<enum_TextServer_Orientation>` value **)**
- :ref:`Orientation<enum_TextServer_Orientation>` **get_orientation** **(** **)**

Text orientation.

.. rst-class:: classref-item-separator

----

.. _class_TextLine_property_preserve_control:

.. rst-class:: classref-property

:ref:`bool<class_bool>` **preserve_control** = ``false``

.. rst-class:: classref-property-setget

- void **set_preserve_control** **(** :ref:`bool<class_bool>` value **)**
- :ref:`bool<class_bool>` **get_preserve_control** **(** **)**

If set to ``true`` text will display control characters.

.. rst-class:: classref-item-separator

----

.. _class_TextLine_property_preserve_invalid:

.. rst-class:: classref-property

:ref:`bool<class_bool>` **preserve_invalid** = ``true``

.. rst-class:: classref-property-setget

- void **set_preserve_invalid** **(** :ref:`bool<class_bool>` value **)**
- :ref:`bool<class_bool>` **get_preserve_invalid** **(** **)**

If set to ``true`` text will display invalid characters.

.. rst-class:: classref-item-separator

----

.. _class_TextLine_property_text_overrun_behavior:

.. rst-class:: classref-property

:ref:`OverrunBehavior<enum_TextServer_OverrunBehavior>` **text_overrun_behavior** = ``3``

.. rst-class:: classref-property-setget

- void **set_text_overrun_behavior** **(** :ref:`OverrunBehavior<enum_TextServer_OverrunBehavior>` value **)**
- :ref:`OverrunBehavior<enum_TextServer_OverrunBehavior>` **get_text_overrun_behavior** **(** **)**

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

.. rst-class:: classref-item-separator

----

.. _class_TextLine_property_width:

.. rst-class:: classref-property

:ref:`float<class_float>` **width** = ``-1.0``

.. rst-class:: classref-property-setget

- void **set_width** **(** :ref:`float<class_float>` value **)**
- :ref:`float<class_float>` **get_width** **(** **)**

Text line width.

.. rst-class:: classref-section-separator

----

.. rst-class:: classref-descriptions-group

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

.. _class_TextLine_method_add_object:

.. rst-class:: classref-method

:ref:`bool<class_bool>` **add_object** **(** :ref:`Variant<class_Variant>` key, :ref:`Vector2<class_Vector2>` size, :ref:`InlineAlignment<enum_@GlobalScope_InlineAlignment>` inline_align=5, :ref:`int<class_int>` length=1, :ref:`float<class_float>` baseline=0.0 **)**

Adds inline object to the text buffer, ``key`` must be unique. In the text, object is represented as ``length`` object replacement characters.

.. rst-class:: classref-item-separator

----

.. _class_TextLine_method_add_string:

.. rst-class:: classref-method

:ref:`bool<class_bool>` **add_string** **(** :ref:`String<class_String>` text, :ref:`Font<class_Font>` font, :ref:`int<class_int>` font_size, :ref:`String<class_String>` language="", :ref:`Variant<class_Variant>` meta=null **)**

Adds text span and font to draw it.

.. rst-class:: classref-item-separator

----

.. _class_TextLine_method_clear:

.. rst-class:: classref-method

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

Clears text line (removes text and inline objects).

.. rst-class:: classref-item-separator

----

.. _class_TextLine_method_draw:

.. rst-class:: classref-method

void **draw** **(** :ref:`RID<class_RID>` canvas, :ref:`Vector2<class_Vector2>` pos, :ref:`Color<class_Color>` color=Color(1, 1, 1, 1) **)** |const|

Draw text into a canvas item at a given position, with ``color``. ``pos`` specifies the top left corner of the bounding box.

.. rst-class:: classref-item-separator

----

.. _class_TextLine_method_draw_outline:

.. rst-class:: classref-method

void **draw_outline** **(** :ref:`RID<class_RID>` canvas, :ref:`Vector2<class_Vector2>` pos, :ref:`int<class_int>` outline_size=1, :ref:`Color<class_Color>` color=Color(1, 1, 1, 1) **)** |const|

Draw text into a canvas item at a given position, with ``color``. ``pos`` specifies the top left corner of the bounding box.

.. rst-class:: classref-item-separator

----

.. _class_TextLine_method_get_line_ascent:

.. rst-class:: classref-method

:ref:`float<class_float>` **get_line_ascent** **(** **)** |const|

Returns the text ascent (number of pixels above the baseline for horizontal layout or to the left of baseline for vertical).

.. rst-class:: classref-item-separator

----

.. _class_TextLine_method_get_line_descent:

.. rst-class:: classref-method

:ref:`float<class_float>` **get_line_descent** **(** **)** |const|

Returns the text descent (number of pixels below the baseline for horizontal layout or to the right of baseline for vertical).

.. rst-class:: classref-item-separator

----

.. _class_TextLine_method_get_line_underline_position:

.. rst-class:: classref-method

:ref:`float<class_float>` **get_line_underline_position** **(** **)** |const|

Returns pixel offset of the underline below the baseline.

.. rst-class:: classref-item-separator

----

.. _class_TextLine_method_get_line_underline_thickness:

.. rst-class:: classref-method

:ref:`float<class_float>` **get_line_underline_thickness** **(** **)** |const|

Returns thickness of the underline.

.. rst-class:: classref-item-separator

----

.. _class_TextLine_method_get_line_width:

.. rst-class:: classref-method

:ref:`float<class_float>` **get_line_width** **(** **)** |const|

Returns width (for horizontal layout) or height (for vertical) of the text.

.. rst-class:: classref-item-separator

----

.. _class_TextLine_method_get_object_rect:

.. rst-class:: classref-method

:ref:`Rect2<class_Rect2>` **get_object_rect** **(** :ref:`Variant<class_Variant>` key **)** |const|

Returns bounding rectangle of the inline object.

.. rst-class:: classref-item-separator

----

.. _class_TextLine_method_get_objects:

.. rst-class:: classref-method

:ref:`Array<class_Array>` **get_objects** **(** **)** |const|

Returns array of inline objects.

.. rst-class:: classref-item-separator

----

.. _class_TextLine_method_get_rid:

.. rst-class:: classref-method

:ref:`RID<class_RID>` **get_rid** **(** **)** |const|

Returns TextServer buffer RID.

.. rst-class:: classref-item-separator

----

.. _class_TextLine_method_get_size:

.. rst-class:: classref-method

:ref:`Vector2<class_Vector2>` **get_size** **(** **)** |const|

Returns size of the bounding box of the text.

.. rst-class:: classref-item-separator

----

.. _class_TextLine_method_hit_test:

.. rst-class:: classref-method

:ref:`int<class_int>` **hit_test** **(** :ref:`float<class_float>` coords **)** |const|

Returns caret character offset at the specified pixel offset at the baseline. This function always returns a valid position.

.. rst-class:: classref-item-separator

----

.. _class_TextLine_method_resize_object:

.. rst-class:: classref-method

:ref:`bool<class_bool>` **resize_object** **(** :ref:`Variant<class_Variant>` key, :ref:`Vector2<class_Vector2>` size, :ref:`InlineAlignment<enum_@GlobalScope_InlineAlignment>` inline_align=5, :ref:`float<class_float>` baseline=0.0 **)**

Sets new size and alignment of embedded object.

.. rst-class:: classref-item-separator

----

.. _class_TextLine_method_set_bidi_override:

.. rst-class:: classref-method

void **set_bidi_override** **(** :ref:`Array<class_Array>` override **)**

Overrides BiDi for the structured text.

Override ranges should cover full source text without overlaps. BiDi algorithm will be used on each range separately.

.. rst-class:: classref-item-separator

----

.. _class_TextLine_method_tab_align:

.. rst-class:: classref-method

void **tab_align** **(** :ref:`PackedFloat32Array<class_PackedFloat32Array>` tab_stops **)**

Aligns text to the given tab-stops.

.. |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.)`
.. |bitfield| replace:: :abbr:`BitField (This value is an integer composed as a bitmask of the following flags.)`