godotengine/godot-docs
1
0
Fork 0
mirror of https://github.com/godotengine/godot-docs.git synced 2026-01-03 05:48:42 +03:00
Code Issues Packages Projects Releases Wiki Activity
Files
286ce78e08db3ec09524bc1be2adaeb45f7a482c
godot-docs/classes/class_richtextlabel.rst
Rémi Verschelde f70354d01c Sync classref with changes from godotengine/godot#24640
2019-01-07 10:14:12 +01:00

562 lines
30 KiB
ReStructuredText
Raw Blame History

.. 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.
Properties
----------
+-----------------------------+------------------------------------------------------------------------------------------------+
| :ref:`bool<class_bool>` | :ref:`bbcode_enabled<class_RichTextLabel_property_bbcode_enabled>` |
+-----------------------------+------------------------------------------------------------------------------------------------+
| :ref:`String<class_String>` | :ref:`bbcode_text<class_RichTextLabel_property_bbcode_text>` |
+-----------------------------+------------------------------------------------------------------------------------------------+
| :ref:`bool<class_bool>` | :ref:`meta_underlined<class_RichTextLabel_property_meta_underlined>` |
+-----------------------------+------------------------------------------------------------------------------------------------+
| :ref:`bool<class_bool>` | :ref:`override_selected_font_color<class_RichTextLabel_property_override_selected_font_color>` |
+-----------------------------+------------------------------------------------------------------------------------------------+
| :ref:`float<class_float>` | :ref:`percent_visible<class_RichTextLabel_property_percent_visible>` |
+-----------------------------+------------------------------------------------------------------------------------------------+
| :ref:`bool<class_bool>` | :ref:`scroll_active<class_RichTextLabel_property_scroll_active>` |
+-----------------------------+------------------------------------------------------------------------------------------------+
| :ref:`bool<class_bool>` | :ref:`scroll_following<class_RichTextLabel_property_scroll_following>` |
+-----------------------------+------------------------------------------------------------------------------------------------+
| :ref:`bool<class_bool>` | :ref:`selection_enabled<class_RichTextLabel_property_selection_enabled>` |
+-----------------------------+------------------------------------------------------------------------------------------------+
| :ref:`int<class_int>` | :ref:`tab_size<class_RichTextLabel_property_tab_size>` |
+-----------------------------+------------------------------------------------------------------------------------------------+
| :ref:`String<class_String>` | :ref:`text<class_RichTextLabel_property_text>` |
+-----------------------------+------------------------------------------------------------------------------------------------+
| :ref:`int<class_int>` | :ref:`visible_characters<class_RichTextLabel_property_visible_characters>` |
+-----------------------------+------------------------------------------------------------------------------------------------+
Methods
-------
+---------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| void | :ref:`add_image<class_RichTextLabel_method_add_image>` **(** :ref:`Texture<class_Texture>` image **)** |
+---------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| void | :ref:`add_text<class_RichTextLabel_method_add_text>` **(** :ref:`String<class_String>` text **)** |
+---------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`Error<enum_@GlobalScope_Error>` | :ref:`append_bbcode<class_RichTextLabel_method_append_bbcode>` **(** :ref:`String<class_String>` bbcode **)** |
+---------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| void | :ref:`clear<class_RichTextLabel_method_clear>` **(** **)** |
+---------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`int<class_int>` | :ref:`get_content_height<class_RichTextLabel_method_get_content_height>` **(** **)** |
+---------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`int<class_int>` | :ref:`get_line_count<class_RichTextLabel_method_get_line_count>` **(** **)** const |
+---------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`int<class_int>` | :ref:`get_total_character_count<class_RichTextLabel_method_get_total_character_count>` **(** **)** const |
+---------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`VScrollBar<class_VScrollBar>` | :ref:`get_v_scroll<class_RichTextLabel_method_get_v_scroll>` **(** **)** |
+---------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`int<class_int>` | :ref:`get_visible_line_count<class_RichTextLabel_method_get_visible_line_count>` **(** **)** const |
+---------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| void | :ref:`newline<class_RichTextLabel_method_newline>` **(** **)** |
+---------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`Error<enum_@GlobalScope_Error>` | :ref:`parse_bbcode<class_RichTextLabel_method_parse_bbcode>` **(** :ref:`String<class_String>` bbcode **)** |
+---------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| void | :ref:`pop<class_RichTextLabel_method_pop>` **(** **)** |
+---------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| void | :ref:`push_align<class_RichTextLabel_method_push_align>` **(** :ref:`Align<enum_RichTextLabel_Align>` align **)** |
+---------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| void | :ref:`push_cell<class_RichTextLabel_method_push_cell>` **(** **)** |
+---------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| void | :ref:`push_color<class_RichTextLabel_method_push_color>` **(** :ref:`Color<class_Color>` color **)** |
+---------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| void | :ref:`push_font<class_RichTextLabel_method_push_font>` **(** :ref:`Font<class_Font>` font **)** |
+---------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| void | :ref:`push_indent<class_RichTextLabel_method_push_indent>` **(** :ref:`int<class_int>` level **)** |
+---------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| void | :ref:`push_list<class_RichTextLabel_method_push_list>` **(** :ref:`ListType<enum_RichTextLabel_ListType>` type **)** |
+---------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| void | :ref:`push_meta<class_RichTextLabel_method_push_meta>` **(** :ref:`Variant<class_Variant>` data **)** |
+---------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| void | :ref:`push_strikethrough<class_RichTextLabel_method_push_strikethrough>` **(** **)** |
+---------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| void | :ref:`push_table<class_RichTextLabel_method_push_table>` **(** :ref:`int<class_int>` columns **)** |
+---------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| void | :ref:`push_underline<class_RichTextLabel_method_push_underline>` **(** **)** |
+---------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`bool<class_bool>` | :ref:`remove_line<class_RichTextLabel_method_remove_line>` **(** :ref:`int<class_int>` line **)** |
+---------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| void | :ref:`scroll_to_line<class_RichTextLabel_method_scroll_to_line>` **(** :ref:`int<class_int>` line **)** |
+---------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| void | :ref:`set_table_column_expand<class_RichTextLabel_method_set_table_column_expand>` **(** :ref:`int<class_int>` column, :ref:`bool<class_bool>` expand, :ref:`int<class_int>` ratio **)** |
+---------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
Theme Properties
----------------
+---------------------------------+---------------------+
| :ref:`Font<class_Font>` | bold_font |
+---------------------------------+---------------------+
| :ref:`Font<class_Font>` | bold_italics_font |
+---------------------------------+---------------------+
| :ref:`Color<class_Color>` | default_color |
+---------------------------------+---------------------+
| :ref:`StyleBox<class_StyleBox>` | focus |
+---------------------------------+---------------------+
| :ref:`Color<class_Color>` | font_color_selected |
+---------------------------------+---------------------+
| :ref:`Color<class_Color>` | font_color_shadow |
+---------------------------------+---------------------+
| :ref:`Font<class_Font>` | italics_font |
+---------------------------------+---------------------+
| :ref:`int<class_int>` | line_separation |
+---------------------------------+---------------------+
| :ref:`Font<class_Font>` | mono_font |
+---------------------------------+---------------------+
| :ref:`StyleBox<class_StyleBox>` | normal |
+---------------------------------+---------------------+
| :ref:`Font<class_Font>` | normal_font |
+---------------------------------+---------------------+
| :ref:`Color<class_Color>` | selection_color |
+---------------------------------+---------------------+
| :ref:`int<class_int>` | shadow_as_outline |
+---------------------------------+---------------------+
| :ref:`int<class_int>` | shadow_offset_x |
+---------------------------------+---------------------+
| :ref:`int<class_int>` | shadow_offset_y |
+---------------------------------+---------------------+
| :ref:`int<class_int>` | table_hseparation |
+---------------------------------+---------------------+
| :ref:`int<class_int>` | table_vseparation |
+---------------------------------+---------------------+
Signals
-------
.. _class_RichTextLabel_signal_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_method_push_meta>` method must be used to manually insert the data into the tag stack.
.. _class_RichTextLabel_signal_meta_hover_ended:
- **meta_hover_ended** **(** :ref:`Nil<class_Nil>` meta **)**
Triggers when the mouse exits a meta tag.
.. _class_RichTextLabel_signal_meta_hover_started:
- **meta_hover_started** **(** :ref:`Nil<class_Nil>` meta **)**
Triggers when the mouse enters a meta tag.
Enumerations
------------
.. _enum_RichTextLabel_Align:
.. _class_RichTextLabel_constant_ALIGN_LEFT:
.. _class_RichTextLabel_constant_ALIGN_CENTER:
.. _class_RichTextLabel_constant_ALIGN_RIGHT:
.. _class_RichTextLabel_constant_ALIGN_FILL:
enum **Align**:
- **ALIGN_LEFT** = **0**
- **ALIGN_CENTER** = **1**
- **ALIGN_RIGHT** = **2**
- **ALIGN_FILL** = **3**
.. _enum_RichTextLabel_ListType:
.. _class_RichTextLabel_constant_LIST_NUMBERS:
.. _class_RichTextLabel_constant_LIST_LETTERS:
.. _class_RichTextLabel_constant_LIST_DOTS:
enum **ListType**:
- **LIST_NUMBERS** = **0**
- **LIST_LETTERS** = **1**
- **LIST_DOTS** = **2**
.. _enum_RichTextLabel_ItemType:
.. _class_RichTextLabel_constant_ITEM_FRAME:
.. _class_RichTextLabel_constant_ITEM_TEXT:
.. _class_RichTextLabel_constant_ITEM_IMAGE:
.. _class_RichTextLabel_constant_ITEM_NEWLINE:
.. _class_RichTextLabel_constant_ITEM_FONT:
.. _class_RichTextLabel_constant_ITEM_COLOR:
.. _class_RichTextLabel_constant_ITEM_UNDERLINE:
.. _class_RichTextLabel_constant_ITEM_STRIKETHROUGH:
.. _class_RichTextLabel_constant_ITEM_ALIGN:
.. _class_RichTextLabel_constant_ITEM_INDENT:
.. _class_RichTextLabel_constant_ITEM_LIST:
.. _class_RichTextLabel_constant_ITEM_TABLE:
.. _class_RichTextLabel_constant_ITEM_META:
enum **ItemType**:
- **ITEM_FRAME** = **0**
- **ITEM_TEXT** = **1**
- **ITEM_IMAGE** = **2**
- **ITEM_NEWLINE** = **3**
- **ITEM_FONT** = **4**
- **ITEM_COLOR** = **5**
- **ITEM_UNDERLINE** = **6**
- **ITEM_STRIKETHROUGH** = **7**
- **ITEM_ALIGN** = **8**
- **ITEM_INDENT** = **9**
- **ITEM_LIST** = **10**
- **ITEM_TABLE** = **11**
- **ITEM_META** = **12**
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_property_bbcode_text>` clear the tag stack and reconstruct it from the property's contents. Any edits made to :ref:`bbcode_text<class_RichTextLabel_property_bbcode_text>` will erase previous edits made from other manual sources such as :ref:`append_bbcode<class_RichTextLabel_method_append_bbcode>` and the ``push_*`` / :ref:`pop<class_RichTextLabel_method_pop>` methods.
Tutorials
---------
- :doc:`../tutorials/gui/bbcode_in_richtextlabel`
Property Descriptions
---------------------
.. _class_RichTextLabel_property_bbcode_enabled:
- :ref:`bool<class_bool>` **bbcode_enabled**
+----------+-----------------------+
| *Setter* | set_use_bbcode(value) |
+----------+-----------------------+
| *Getter* | is_using_bbcode() |
+----------+-----------------------+
If ``true``, the label uses BBCode formatting. Default value: ``false``.
.. _class_RichTextLabel_property_bbcode_text:
- :ref:`String<class_String>` **bbcode_text**
+----------+-------------------+
| *Setter* | set_bbcode(value) |
+----------+-------------------+
| *Getter* | get_bbcode() |
+----------+-------------------+
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_property_meta_underlined:
- :ref:`bool<class_bool>` **meta_underlined**
+----------+---------------------------+
| *Setter* | set_meta_underline(value) |
+----------+---------------------------+
| *Getter* | is_meta_underlined() |
+----------+---------------------------+
If ``true``, the label underlines meta tags such as ``[url]{text}[/url]``. Default value: ``true``.
.. _class_RichTextLabel_property_override_selected_font_color:
- :ref:`bool<class_bool>` **override_selected_font_color**
+----------+-----------------------------------------+
| *Setter* | set_override_selected_font_color(value) |
+----------+-----------------------------------------+
| *Getter* | is_overriding_selected_font_color() |
+----------+-----------------------------------------+
If ``true``, the label uses the custom font color. Default value: ``false``.
.. _class_RichTextLabel_property_percent_visible:
- :ref:`float<class_float>` **percent_visible**
+----------+----------------------------+
| *Setter* | set_percent_visible(value) |
+----------+----------------------------+
| *Getter* | get_percent_visible() |
+----------+----------------------------+
The text's visibility, as a :ref:`float<class_float>` between 0.0 and 1.0.
.. _class_RichTextLabel_property_scroll_active:
- :ref:`bool<class_bool>` **scroll_active**
+----------+--------------------------+
| *Setter* | set_scroll_active(value) |
+----------+--------------------------+
| *Getter* | is_scroll_active() |
+----------+--------------------------+
If ``true``, the scrollbar is visible. Does not block scrolling completely. See :ref:`scroll_to_line<class_RichTextLabel_method_scroll_to_line>`. Default value: ``true``.
.. _class_RichTextLabel_property_scroll_following:
- :ref:`bool<class_bool>` **scroll_following**
+----------+--------------------------+
| *Setter* | set_scroll_follow(value) |
+----------+--------------------------+
| *Getter* | is_scroll_following() |
+----------+--------------------------+
If ``true``, the window scrolls down to display new content automatically. Default value: ``false``.
.. _class_RichTextLabel_property_selection_enabled:
- :ref:`bool<class_bool>` **selection_enabled**
+----------+------------------------------+
| *Setter* | set_selection_enabled(value) |
+----------+------------------------------+
| *Getter* | is_selection_enabled() |
+----------+------------------------------+
If ``true``, the label allows text selection.
.. _class_RichTextLabel_property_tab_size:
- :ref:`int<class_int>` **tab_size**
+----------+---------------------+
| *Setter* | set_tab_size(value) |
+----------+---------------------+
| *Getter* | get_tab_size() |
+----------+---------------------+
The number of spaces associated with a single tab length. Does not affect "\\t" in text tags, only indent tags.
.. _class_RichTextLabel_property_text:
- :ref:`String<class_String>` **text**
+----------+-----------------+
| *Setter* | set_text(value) |
+----------+-----------------+
| *Getter* | get_text() |
+----------+-----------------+
The raw text of the label.
When set, 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_property_bbcode_text>`.
.. _class_RichTextLabel_property_visible_characters:
- :ref:`int<class_int>` **visible_characters**
+----------+-------------------------------+
| *Setter* | set_visible_characters(value) |
+----------+-------------------------------+
| *Getter* | get_visible_characters() |
+----------+-------------------------------+
The restricted number of characters to display in the label.
Method Descriptions
-------------------
.. _class_RichTextLabel_method_add_image:
- void **add_image** **(** :ref:`Texture<class_Texture>` image **)**
Adds an image's opening and closing tags to the tag stack.
.. _class_RichTextLabel_method_add_text:
- void **add_text** **(** :ref:`String<class_String>` text **)**
Adds raw non-bbcode-parsed text to the tag stack.
.. _class_RichTextLabel_method_append_bbcode:
- :ref:`Error<enum_@GlobalScope_Error>` **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_method_clear:
- void **clear** **(** **)**
Clears the tag stack and sets :ref:`bbcode_text<class_RichTextLabel_property_bbcode_text>` to an empty string.
.. _class_RichTextLabel_method_get_content_height:
- :ref:`int<class_int>` **get_content_height** **(** **)**
Returns the height of the content.
.. _class_RichTextLabel_method_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_method_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_method_get_v_scroll:
- :ref:`VScrollBar<class_VScrollBar>` **get_v_scroll** **(** **)**
Returns the vertical scrollbar.
.. _class_RichTextLabel_method_get_visible_line_count:
- :ref:`int<class_int>` **get_visible_line_count** **(** **)** const
Returns the number of visible lines.
.. _class_RichTextLabel_method_newline:
- void **newline** **(** **)**
Adds a newline tag to the tag stack.
.. _class_RichTextLabel_method_parse_bbcode:
- :ref:`Error<enum_@GlobalScope_Error>` **parse_bbcode** **(** :ref:`String<class_String>` bbcode **)**
The assignment version of :ref:`append_bbcode<class_RichTextLabel_method_append_bbcode>`. Clears the tag stack and inserts the new content. Returns ``OK`` if parses ``bbcode`` successfully.
.. _class_RichTextLabel_method_pop:
- void **pop** **(** **)**
Terminates the current tag. Use after ``push_*`` methods to close bbcodes manually. Does not need to follow ``add_*`` methods.
.. _class_RichTextLabel_method_push_align:
- void **push_align** **(** :ref:`Align<enum_RichTextLabel_Align>` align **)**
Adds an alignment tag based on the given ``align`` value. See :ref:`Align<enum_RichTextLabel_Align>` for possible values.
.. _class_RichTextLabel_method_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_method_push_table>` for details.
.. _class_RichTextLabel_method_push_color:
- void **push_color** **(** :ref:`Color<class_Color>` color **)**
Adds a ``[color]`` tag to the tag stack.
.. _class_RichTextLabel_method_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_method_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_method_push_list:
- void **push_list** **(** :ref:`ListType<enum_RichTextLabel_ListType>` 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_method_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_method_push_strikethrough:
- void **push_strikethrough** **(** **)**
Adds a ``[s]`` tag to the tag stack.
.. _class_RichTextLabel_method_push_table:
- void **push_table** **(** :ref:`int<class_int>` columns **)**
Adds a ``[table=columns]`` tag to the tag stack.
.. _class_RichTextLabel_method_push_underline:
- void **push_underline** **(** **)**
Adds a ``[u]`` tag to the tag stack.
.. _class_RichTextLabel_method_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_method_scroll_to_line:
- void **scroll_to_line** **(** :ref:`int<class_int>` line **)**
Scrolls the window's top line to match ``line``.
.. _class_RichTextLabel_method_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.
Reference in New Issue View Git Blame Copy Permalink