| github_url: | hide |
|---|
Inherits: :ref:`Control<class_Control>` < :ref:`CanvasItem<class_CanvasItem>` < :ref:`Node<class_Node>` < :ref:`Object<class_Object>`
Label that displays rich text.
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: 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.
| :ref:`Font<class_Font>` | bold_font | |
| :ref:`Font<class_Font>` | bold_italics_font | |
| :ref:`Color<class_Color>` | default_color | Color( 1, 1, 1, 1 ) |
| :ref:`StyleBox<class_StyleBox>` | focus | |
| :ref:`Color<class_Color>` | font_color_selected | Color( 0.49, 0.49, 0.49, 1 ) |
| :ref:`Color<class_Color>` | font_color_shadow | Color( 0, 0, 0, 0 ) |
| :ref:`Font<class_Font>` | italics_font | |
| :ref:`int<class_int>` | line_separation | 1 |
| :ref:`Font<class_Font>` | mono_font | |
| :ref:`StyleBox<class_StyleBox>` | normal | |
| :ref:`Font<class_Font>` | normal_font | |
| :ref:`Color<class_Color>` | selection_color | Color( 0.1, 0.1, 1, 0.8 ) |
| :ref:`int<class_int>` | shadow_as_outline | 0 |
| :ref:`int<class_int>` | shadow_offset_x | 1 |
| :ref:`int<class_int>` | shadow_offset_y | 1 |
| :ref:`int<class_int>` | table_hseparation | 3 |
| :ref:`int<class_int>` | table_vseparation | 3 |
- meta_clicked ( :ref:`Variant<class_Variant>` meta )
Triggered when the user clicks on content between meta 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.
- meta_hover_ended ( :ref:`Variant<class_Variant>` meta )
Triggers when the mouse exits a meta tag.
- meta_hover_started ( :ref:`Variant<class_Variant>` meta )
Triggers when the mouse enters a meta tag.
enum Align:
- ALIGN_LEFT = 0 --- Makes text left aligned.
- ALIGN_CENTER = 1 --- Makes text centered.
- ALIGN_RIGHT = 2 --- Makes text right aligned.
- ALIGN_FILL = 3 --- Makes text fill width.
enum ListType:
- LIST_NUMBERS = 0 --- Each list item has a number marker.
- LIST_LETTERS = 1 --- Each list item has a letter marker.
- LIST_DOTS = 2 --- Each list item has a filled circle marker.
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_FADE = 12
- ITEM_SHAKE = 13
- ITEM_WAVE = 14
- ITEM_TORNADO = 15
- ITEM_RAINBOW = 16
- ITEM_CUSTOMFX = 18
- ITEM_META = 17
- :ref:`bool<class_bool>` bbcode_enabled
| Default | false |
| Setter | set_use_bbcode(value) |
| Getter | is_using_bbcode() |
If true, the label uses BBCode formatting.
- :ref:`String<class_String>` bbcode_text
| Default | "" |
| 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.
Note: It is unadvised to use += operator with bbcode_text (e.g. bbcode_text += "some string") as it replaces the whole text and can cause slowdowns. Use :ref:`append_bbcode<class_RichTextLabel_method_append_bbcode>` for adding text instead.
- :ref:`Array<class_Array>` custom_effects
| Default | [ ] |
| Setter | set_effects(value) |
| Getter | get_effects() |
The currently installed custom effects. This is an array of :ref:`RichTextEffect<class_RichTextEffect>`s.
To add a custom effect, it's more convenient to use :ref:`install_effect<class_RichTextLabel_method_install_effect>`.
- :ref:`bool<class_bool>` meta_underlined
| Default | true |
| Setter | set_meta_underline(value) |
| Getter | is_meta_underlined() |
If true, the label underlines meta tags such as [url]{text}[/url].
- :ref:`bool<class_bool>` override_selected_font_color
| Default | false |
| Setter | set_override_selected_font_color(value) |
| Getter | is_overriding_selected_font_color() |
If true, the label uses the custom font color.
- :ref:`float<class_float>` percent_visible
| Default | 1.0 |
| Setter | set_percent_visible(value) |
| Getter | get_percent_visible() |
The range of characters to display, as a :ref:`float<class_float>` between 0.0 and 1.0. When assigned an out of range value, it's the same as assigning 1.0.
Note: Setting this property updates :ref:`visible_characters<class_RichTextLabel_property_visible_characters>` based on current :ref:`get_total_character_count<class_RichTextLabel_method_get_total_character_count>`.
- :ref:`bool<class_bool>` scroll_active
| Default | true |
| Setter | set_scroll_active(value) |
| Getter | is_scroll_active() |
If true, the scrollbar is visible. Setting this to false does not block scrolling completely. See :ref:`scroll_to_line<class_RichTextLabel_method_scroll_to_line>`.
- :ref:`bool<class_bool>` scroll_following
| Default | false |
| Setter | set_scroll_follow(value) |
| Getter | is_scroll_following() |
If true, the window scrolls down to display new content automatically.
- :ref:`bool<class_bool>` selection_enabled
| Default | false |
| Setter | set_selection_enabled(value) |
| Getter | is_selection_enabled() |
If true, the label allows text selection.
- :ref:`int<class_int>` tab_size
| Default | 4 |
| 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.
| Default | "" |
| 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>`.
- :ref:`int<class_int>` visible_characters
| Default | -1 |
| Setter | set_visible_characters(value) |
| Getter | get_visible_characters() |
The restricted number of characters to display in the label. If -1, all characters will be displayed.
- void add_image ( :ref:`Texture2D<class_Texture2D>` image, :ref:`int<class_int>` width=0, :ref:`int<class_int>` height=0 )
Adds an image's opening and closing tags to the tag stack, optionally providing a width and height to resize the image.
If width or height is set to 0, the image size will be adjusted in order to keep the original aspect ratio.
- void add_text ( :ref:`String<class_String>` text )
Adds raw non-BBCode-parsed text to the tag stack.
- :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, :ref:`@GlobalScope.OK<class_@GlobalScope_constant_OK>` if successful.
- void clear ( )
Clears the tag stack and sets :ref:`bbcode_text<class_RichTextLabel_property_bbcode_text>` to an empty string.
- :ref:`int<class_int>` get_content_height ( )
Returns the height of the content.
- :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.
- :ref:`int<class_int>` get_total_character_count ( ) const
Returns the total number of characters from text tags. Does not include BBCodes.
- :ref:`VScrollBar<class_VScrollBar>` get_v_scroll ( )
Returns the vertical scrollbar.
- :ref:`int<class_int>` get_visible_line_count ( ) const
Returns the number of visible lines.
- void install_effect ( :ref:`Variant<class_Variant>` effect )
Installs a custom effect. effect should be a valid :ref:`RichTextEffect<class_RichTextEffect>`.
- void newline ( )
Adds a newline tag to the tag stack.
- :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 :ref:`@GlobalScope.OK<class_@GlobalScope_constant_OK>` if parses bbcode successfully.
- :ref:`Dictionary<class_Dictionary>` parse_expressions_for_values ( :ref:`PackedStringArray<class_PackedStringArray>` expressions )
Parses BBCode parameter expressions into a dictionary.
- void pop ( )
Terminates the current tag. Use after push_* methods to close BBCodes manually. Does not need to follow add_* methods.
- void push_align ( :ref:`Align<enum_RichTextLabel_Align>` align )
Adds an [align] tag based on the given align value. See :ref:`Align<enum_RichTextLabel_Align>` for possible values.
- void push_bold ( )
Adds a [font] tag with a bold font to the tag stack. This is the same as adding a [b] tag if not currently in a [i] tag.
- void push_bold_italics ( )
Adds a [font] tag with a bold italics font to the tag stack.
- 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.
- void push_color ( :ref:`Color<class_Color>` color )
Adds a [color] tag to the tag stack.
- void push_font ( :ref:`Font<class_Font>` font )
Adds a [font] tag to the tag stack. Overrides default fonts for its duration.
- void push_indent ( :ref:`int<class_int>` level )
Adds an [indent] tag to the tag stack. Multiplies level by current :ref:`tab_size<class_RichTextLabel_property_tab_size>` to determine new margin length.
- void push_italics ( )
Adds a [font] tag with a italics font to the tag stack. This is the same as adding a [i] tag if not currently in a [b] tag.
- 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!
- 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.
- void push_mono ( )
Adds a [font] tag with a monospace font to the tag stack.
- void push_normal ( )
Adds a [font] tag with a normal font to the tag stack.
- void push_strikethrough ( )
Adds a [s] tag to the tag stack.
- void push_table ( :ref:`int<class_int>` columns )
Adds a [table=columns] tag to the tag stack.
- void push_underline ( )
Adds a [u] tag to the tag stack.
- :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.
The line argument is the index of the line to remove, it can take values in the interval [0, get_line_count() - 1].
- void scroll_to_line ( :ref:`int<class_int>` line )
Scrolls the window's top line to match line.
- void set_table_column_expand ( :ref:`int<class_int>` column, :ref:`bool<class_bool>` expand, :ref:`int<class_int>` ratio )
Edits the selected column's 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.
If expand is false, the column will not contribute to the total ratio.