godot-docs/classes/class_richtextlabel.rst

.. Generated automatically by doc/tools/makerst.py in Godot's source tree.
.. DO NOT EDIT THIS FILE, but the RichTextLabel.xml source instead.
.. The source is found in doc/classes or modules/<name>/doc_classes.

.. _class_RichTextLabel:

RichTextLabel
=============

**Inherits:** :ref:`Control<class_control>` **<** :ref:`CanvasItem<class_canvasitem>` **<** :ref:`Node<class_node>` **<** :ref:`Object<class_object>`

**Category:** Core

Brief Description
-----------------

Label that displays rich text.

Member Functions
----------------

+--------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| void                                 | :ref:`add_image<class_RichTextLabel_add_image>` **(** :ref:`Texture<class_texture>` image **)**                                                                                   |
+--------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| void                                 | :ref:`add_text<class_RichTextLabel_add_text>` **(** :ref:`String<class_string>` text **)**                                                                                        |
+--------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`int<class_int>`                | :ref:`append_bbcode<class_RichTextLabel_append_bbcode>` **(** :ref:`String<class_string>` bbcode **)**                                                                            |
+--------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| void                                 | :ref:`clear<class_RichTextLabel_clear>` **(** **)**                                                                                                                               |
+--------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`int<class_int>`                | :ref:`get_line_count<class_RichTextLabel_get_line_count>` **(** **)** const                                                                                                       |
+--------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`int<class_int>`                | :ref:`get_tab_size<class_RichTextLabel_get_tab_size>` **(** **)** const                                                                                                           |
+--------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`String<class_string>`          | :ref:`get_text<class_RichTextLabel_get_text>` **(** **)**                                                                                                                         |
+--------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`int<class_int>`                | :ref:`get_total_character_count<class_RichTextLabel_get_total_character_count>` **(** **)** const                                                                                 |
+--------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`VScrollBar<class_vscrollbar>`  | :ref:`get_v_scroll<class_RichTextLabel_get_v_scroll>` **(** **)**                                                                                                                 |
+--------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`int<class_int>`                | :ref:`get_visible_line_count<class_RichTextLabel_get_visible_line_count>` **(** **)** const                                                                                       |
+--------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`bool<class_bool>`              | :ref:`is_meta_underlined<class_RichTextLabel_is_meta_underlined>` **(** **)** const                                                                                               |
+--------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`bool<class_bool>`              | :ref:`is_scroll_active<class_RichTextLabel_is_scroll_active>` **(** **)** const                                                                                                   |
+--------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`bool<class_bool>`              | :ref:`is_scroll_following<class_RichTextLabel_is_scroll_following>` **(** **)** const                                                                                             |
+--------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`bool<class_bool>`              | :ref:`is_selection_enabled<class_RichTextLabel_is_selection_enabled>` **(** **)** const                                                                                           |
+--------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| void                                 | :ref:`newline<class_RichTextLabel_newline>` **(** **)**                                                                                                                           |
+--------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`int<class_int>`                | :ref:`parse_bbcode<class_RichTextLabel_parse_bbcode>` **(** :ref:`String<class_string>` bbcode **)**                                                                              |
+--------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| void                                 | :ref:`pop<class_RichTextLabel_pop>` **(** **)**                                                                                                                                   |
+--------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| void                                 | :ref:`push_align<class_RichTextLabel_push_align>` **(** :ref:`int<class_int>` align **)**                                                                                         |
+--------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| void                                 | :ref:`push_cell<class_RichTextLabel_push_cell>` **(** **)**                                                                                                                       |
+--------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| void                                 | :ref:`push_color<class_RichTextLabel_push_color>` **(** :ref:`Color<class_color>` color **)**                                                                                     |
+--------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| void                                 | :ref:`push_font<class_RichTextLabel_push_font>` **(** :ref:`Font<class_font>` font **)**                                                                                          |
+--------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| void                                 | :ref:`push_indent<class_RichTextLabel_push_indent>` **(** :ref:`int<class_int>` level **)**                                                                                       |
+--------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| void                                 | :ref:`push_list<class_RichTextLabel_push_list>` **(** :ref:`int<class_int>` type **)**                                                                                            |
+--------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| void                                 | :ref:`push_meta<class_RichTextLabel_push_meta>` **(** :ref:`Variant<class_variant>` data **)**                                                                                    |
+--------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| void                                 | :ref:`push_table<class_RichTextLabel_push_table>` **(** :ref:`int<class_int>` columns **)**                                                                                       |
+--------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| void                                 | :ref:`push_underline<class_RichTextLabel_push_underline>` **(** **)**                                                                                                             |
+--------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`bool<class_bool>`              | :ref:`remove_line<class_RichTextLabel_remove_line>` **(** :ref:`int<class_int>` line **)**                                                                                        |
+--------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| void                                 | :ref:`scroll_to_line<class_RichTextLabel_scroll_to_line>` **(** :ref:`int<class_int>` line **)**                                                                                  |
+--------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| void                                 | :ref:`set_meta_underline<class_RichTextLabel_set_meta_underline>` **(** :ref:`bool<class_bool>` enable **)**                                                                      |
+--------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| void                                 | :ref:`set_scroll_active<class_RichTextLabel_set_scroll_active>` **(** :ref:`bool<class_bool>` active **)**                                                                        |
+--------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| void                                 | :ref:`set_scroll_follow<class_RichTextLabel_set_scroll_follow>` **(** :ref:`bool<class_bool>` follow **)**                                                                        |
+--------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| void                                 | :ref:`set_selection_enabled<class_RichTextLabel_set_selection_enabled>` **(** :ref:`bool<class_bool>` enabled **)**                                                               |
+--------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| void                                 | :ref:`set_tab_size<class_RichTextLabel_set_tab_size>` **(** :ref:`int<class_int>` spaces **)**                                                                                    |
+--------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| void                                 | :ref:`set_table_column_expand<class_RichTextLabel_set_table_column_expand>` **(** :ref:`int<class_int>` column, :ref:`bool<class_bool>` expand, :ref:`int<class_int>` ratio **)** |
+--------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| void                                 | :ref:`set_text<class_RichTextLabel_set_text>` **(** :ref:`String<class_string>` text **)**                                                                                        |
+--------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+

Signals
-------

.. _class_RichTextLabel_meta_clicked:

- **meta_clicked** **(** :ref:`Nil<class_nil>` meta **)**

Triggered when the user clicks on content between url tags. If the meta is defined in text, e.g. ``[url={"data"="hi"}]hi[/url]``, then the parameter for this signal will be a :ref:`String<class_string>` type. If a particular type or an object is desired, the :ref:`push_meta<class_RichTextLabel_push_meta>` method must be used to manually insert the data into the tag stack.

.. _class_RichTextLabel_meta_hover_ended:

- **meta_hover_ended** **(** :ref:`Nil<class_nil>` meta **)**

Triggers when the mouse exits a meta tag.

.. _class_RichTextLabel_meta_hover_started:

- **meta_hover_started** **(** :ref:`Nil<class_nil>` meta **)**

Triggers when the mouse enters a meta tag.


Member Variables
----------------

  .. _class_RichTextLabel_bbcode_enabled:

- :ref:`bool<class_bool>` **bbcode_enabled** - If ``true`` the label uses BBCode formatting. Default value: ``false``.

  .. _class_RichTextLabel_bbcode_text:

- :ref:`String<class_string>` **bbcode_text** - The label's text in BBCode format. Is not representative of manual modifications to the internal tag stack. Erases changes made by other methods when edited.

  .. _class_RichTextLabel_override_selected_font_color:

- :ref:`bool<class_bool>` **override_selected_font_color** - If ``true`` the label uses the custom font color. Default value: ``false``.

  .. _class_RichTextLabel_percent_visible:

- :ref:`float<class_float>` **percent_visible** - The text's visibility, as a :ref:`float<class_float>` between 0.0 and 1.0.

  .. _class_RichTextLabel_visible_characters:

- :ref:`int<class_int>` **visible_characters** - The restricted number of characters to display in the label.


Numeric Constants
-----------------

- **ALIGN_LEFT** = **0**
- **ALIGN_CENTER** = **1**
- **ALIGN_RIGHT** = **2**
- **ALIGN_FILL** = **3**
- **LIST_NUMBERS** = **0**
- **LIST_LETTERS** = **1**
- **LIST_DOTS** = **2**
- **ITEM_FRAME** = **0**
- **ITEM_TEXT** = **1**
- **ITEM_IMAGE** = **2**
- **ITEM_NEWLINE** = **3**
- **ITEM_FONT** = **4**
- **ITEM_COLOR** = **5**
- **ITEM_UNDERLINE** = **6**
- **ITEM_ALIGN** = **7**
- **ITEM_INDENT** = **8**
- **ITEM_LIST** = **9**
- **ITEM_TABLE** = **10**
- **ITEM_META** = **11**

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

Rich text can contain custom text, fonts, images and some basic formatting. The label manages these as an internal tag stack. It also adapts itself to given width/heights.

Note that assignments to :ref:`bbcode_text<class_RichTextLabel_bbcode_text>` clear the tag stack and reconstruct it from the property's contents. Any edits made to :ref:`bbcode_text<class_RichTextLabel_bbcode_text>` will erase previous edits made from other manual sources such as :ref:`append_bbcode<class_RichTextLabel_append_bbcode>` and the ``push\_\*`` / :ref:`pop<class_RichTextLabel_pop>` methods.

Member Function Description
---------------------------

.. _class_RichTextLabel_add_image:

- void **add_image** **(** :ref:`Texture<class_texture>` image **)**

Adds an image's opening and closing tags to the tag stack.

.. _class_RichTextLabel_add_text:

- void **add_text** **(** :ref:`String<class_string>` text **)**

Adds raw non-bbcode-parsed text to the tag stack.

.. _class_RichTextLabel_append_bbcode:

- :ref:`int<class_int>` **append_bbcode** **(** :ref:`String<class_string>` bbcode **)**

Parses ``bbcode`` and adds tags to the tag stack as needed. Returns the result of the parsing, ``OK`` if successful.

.. _class_RichTextLabel_clear:

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

Clears the tag stack and sets :ref:`bbcode_text<class_RichTextLabel_bbcode_text>` to an empty string.

.. _class_RichTextLabel_get_line_count:

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

Returns the total number of newlines in the tag stack's text tags. Considers wrapped text as one line.

.. _class_RichTextLabel_get_tab_size:

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

Returns the number of spaces associated with a single tab length. Does not affect "\t" in text tags, only indent tags.

.. _class_RichTextLabel_get_text:

- :ref:`String<class_string>` **get_text** **(** **)**

Returns the raw content of :ref:`bbcode_text<class_RichTextLabel_bbcode_text>`.

.. _class_RichTextLabel_get_total_character_count:

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

Returns the total number of characters from text tags. Does not include bbcodes.

.. _class_RichTextLabel_get_v_scroll:

- :ref:`VScrollBar<class_vscrollbar>` **get_v_scroll** **(** **)**

Returns the vertical scrollbar.

.. _class_RichTextLabel_get_visible_line_count:

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

Returns the number of visible lines.

.. _class_RichTextLabel_is_meta_underlined:

- :ref:`bool<class_bool>` **is_meta_underlined** **(** **)** const

Returns ``true`` if the label underlines meta tags such as url{text}.

.. _class_RichTextLabel_is_scroll_active:

- :ref:`bool<class_bool>` **is_scroll_active** **(** **)** const

Returns ``true`` if the scrollbar is visible. Does not block scrolling completely. See :ref:`scroll_to_line<class_RichTextLabel_scroll_to_line>`.

.. _class_RichTextLabel_is_scroll_following:

- :ref:`bool<class_bool>` **is_scroll_following** **(** **)** const

Returns ``true`` if the window scrolls down to display new content automatically.

.. _class_RichTextLabel_is_selection_enabled:

- :ref:`bool<class_bool>` **is_selection_enabled** **(** **)** const

Returns ``true`` if the label allows text selection.

.. _class_RichTextLabel_newline:

- void **newline** **(** **)**

Adds a newline tag to the tag stack.

.. _class_RichTextLabel_parse_bbcode:

- :ref:`int<class_int>` **parse_bbcode** **(** :ref:`String<class_string>` bbcode **)**

The assignment version of :ref:`append_bbcode<class_RichTextLabel_append_bbcode>`. Clears the tag stack and inserts the new content. Returns ``OK`` if parses ``bbcode`` successfully.

.. _class_RichTextLabel_pop:

- void **pop** **(** **)**

Terminates the current tag. Use after ``push\_\*`` methods to close bbcodes manually. Does not need to follow ``add\_\*`` methods.

.. _class_RichTextLabel_push_align:

- void **push_align** **(** :ref:`int<class_int>` align **)**

Adds a ``[right]`` tag to the tag stack.

.. _class_RichTextLabel_push_cell:

- void **push_cell** **(** **)**

Adds a ``[cell]`` tag to the tag stack. Must be inside a table tag. See :ref:`push_table<class_RichTextLabel_push_table>` for details.

.. _class_RichTextLabel_push_color:

- void **push_color** **(** :ref:`Color<class_color>` color **)**

Adds a ``[color]`` tag to the tag stack.

.. _class_RichTextLabel_push_font:

- void **push_font** **(** :ref:`Font<class_font>` font **)**

Adds a ``[font]`` tag to the tag stack. Overrides default fonts for its duration.

.. _class_RichTextLabel_push_indent:

- void **push_indent** **(** :ref:`int<class_int>` level **)**

Adds an ``[indent]`` tag to the tag stack. Multiplies "level" by current tab_size to determine new margin length.

.. _class_RichTextLabel_push_list:

- void **push_list** **(** :ref:`int<class_int>` type **)**

Adds a list tag to the tag stack. Similar to the bbcodes ``[ol]`` or ``[ul]``, but supports more list types. Not fully implemented!

.. _class_RichTextLabel_push_meta:

- void **push_meta** **(** :ref:`Variant<class_variant>` data **)**

Adds a meta tag to the tag stack. Similar to the bbcode ``[url=something]{text}[/url]``, but supports non-:ref:`String<class_string>` metadata types.

.. _class_RichTextLabel_push_table:

- void **push_table** **(** :ref:`int<class_int>` columns **)**

Adds a ``[table=columns]`` tag to the tag stack.

.. _class_RichTextLabel_push_underline:

- void **push_underline** **(** **)**

Adds a ``[u]`` tag to the tag stack.

.. _class_RichTextLabel_remove_line:

- :ref:`bool<class_bool>` **remove_line** **(** :ref:`int<class_int>` line **)**

Removes a line of content from the label. Returns ``true`` if the line exists.

.. _class_RichTextLabel_scroll_to_line:

- void **scroll_to_line** **(** :ref:`int<class_int>` line **)**

Scrolls the window's top line to match ``line``.

.. _class_RichTextLabel_set_meta_underline:

- void **set_meta_underline** **(** :ref:`bool<class_bool>` enable **)**

If ``true`` will underline meta tags such as the url bbcode. Default value: ``true``.

.. _class_RichTextLabel_set_scroll_active:

- void **set_scroll_active** **(** :ref:`bool<class_bool>` active **)**

If ``false`` the vertical scrollbar is hidden. Default value: ``true``.

.. _class_RichTextLabel_set_scroll_follow:

- void **set_scroll_follow** **(** :ref:`bool<class_bool>` follow **)**

If ``true`` the window scrolls to reveal new content. Default value: ``false``.

.. _class_RichTextLabel_set_selection_enabled:

- void **set_selection_enabled** **(** :ref:`bool<class_bool>` enabled **)**

If ``true`` text can be selected.

.. _class_RichTextLabel_set_tab_size:

- void **set_tab_size** **(** :ref:`int<class_int>` spaces **)**

Sets the current tab length in spaces. Use with :ref:`push_indent<class_RichTextLabel_push_indent>` to redefine indent length.

.. _class_RichTextLabel_set_table_column_expand:

- void **set_table_column_expand** **(** :ref:`int<class_int>` column, :ref:`bool<class_bool>` expand, :ref:`int<class_int>` ratio **)**

Edits the selected columns expansion options. If ``expand`` is ``true``, the column expands in proportion to its expansion ratio versus the other columns' ratios.

For example, 2 columns with ratios 3 and 4 plus 70 pixels in available width would expand 30 and 40 pixels, respectively.

Columns with a ``false`` expand will not contribute to the total ratio.

.. _class_RichTextLabel_set_text:

- void **set_text** **(** :ref:`String<class_string>` text **)**

Clears the tag stack and adds a raw text tag to the top of it. Does not parse bbcodes. Does not modify :ref:`bbcode_text<class_RichTextLabel_bbcode_text>`.