A control for displaying text that can contain different font styles, images, and basic formatting.
A control for displaying text that can contain custom fonts, images, and basic formatting. RichTextLabel manages these as an internal tag stack. It also adapts itself to given width/heights.
Note: newline(), push_paragraph(), "\n", "\r\n", p tag, and alignment tags start a new paragraph. Each paragraph is processed independently, in its own BiDi context. If you want to force line wrapping within paragraph, any other line breaking character can be used, for example, Form Feed (U+000C), Next Line (U+0085), Line Separator (U+2028).
Note: Assignments to text clear the tag stack and reconstruct it from the property's contents. Any edits made to text will erase previous edits made from other manual sources such as append_text() and the push_* / pop() methods.
Note: RichTextLabel doesn't support entangled BBCode tags. For example, instead of using [code skip-lint]boldbold italicitalic[/code], use [code skip-lint]boldbold italicitalic[/code].
Note: push_*/pop_* functions won't affect BBCode.
Note: While bbcode_enabled is enabled, alignment tags such as [code skip-lint][center][/code] will take priority over the horizontal_alignment setting which determines the default text alignment.
If set to something other than TextServer.AUTOWRAP_OFF, the text gets wrapped inside the node's bounding rectangle.
Note: RichTextLabels with autowrapping and fit_content enabled must have a custom maximum width configured to work correctly, either through the RichTextLabel's own Control.custom_maximum_size or as a result of a propagated maximum size from a parent Control with Control.propagate_maximum_size enabled.
Autowrap space trimming flags. See TextServer.BREAK_TRIM_START_EDGE_SPACES and TextServer.BREAK_TRIM_END_EDGE_SPACES for more info.
If true, the label uses BBCode formatting.
Note: This only affects the contents of text, not the tag stack.
The currently installed custom effects. This is an array of RichTextEffects.
To add a custom effect, it's more convenient to use install_effect().
If true, the label's minimum size will be automatically updated to fit its content, matching the behavior of Label.
Note: RichTextLabels with autowrapping and fit_content enabled must have a custom maximum width configured to work correctly, either through the RichTextLabel's own Control.custom_maximum_size or as a result of a propagated maximum size from a parent Control with Control.propagate_maximum_size enabled.
If true, the label underlines hint tags such as [code skip-lint][hint=description]{text}[/hint][/code].
Controls the text's horizontal alignment. Supports left, center, right, and fill (also known as justify).
Language code used for line-breaking and text shaping algorithms. If left empty, the current locale is used instead.
If true, the label underlines meta tags such as [code skip-lint][url]{text}[/url][/code]. These tags can call a function when clicked if meta_clicked is connected to a function.
The delay after which the loading progress bar is displayed, in milliseconds. Set to -1 to disable progress bar entirely.
Note: Progress bar is displayed only if threaded is enabled.
If true, the scrollbar is visible. Setting this to false does not block scrolling completely. See scroll_to_line().
If true, the window scrolls to display the last visible line when visible_characters or visible_ratio is changed.
The number of spaces associated with a single tab length. Does not affect \t in text tags, only indent tags.
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: If bbcode_enabled is true, it is unadvised to use the += operator with text (e.g. text += "some string") as it replaces the whole text and can cause slowdowns. It will also erase all BBCode that was added to stack using push_* methods. Use append_text() for adding text instead, unless you absolutely need to close a tag that was opened in an earlier method call.
Controls the text's vertical alignment. Supports top, center, bottom, and fill.
The number of characters to display. If set to -1, all characters are displayed. This can be useful when animating the text appearing in a dialog box.
Note: Setting this property updates visible_ratio accordingly.
Note: Characters are counted as Unicode codepoints. A single visible grapheme may contain multiple codepoints (e.g. certain emoji use three codepoints). A single codepoint may contain two UTF-16 characters, which are used in C# strings.
The clipping behavior when visible_characters or visible_ratio is set.
The fraction of characters to display, relative to the total number of characters (see get_total_character_count()). If set to 1.0, all characters are displayed. If set to 0.5, only half of the characters will be displayed. This can be useful when animating the text appearing in a dialog box.
Note: Setting this property updates visible_characters accordingly.
Adds a horizontal rule that can be used to separate content.
If width_in_percent is set, width values are percentages of the control width instead of pixels.
If height_in_percent is set, height values are percentages of the control width instead of pixels.
Adds an image's opening and closing tags to the tag stack, optionally providing a width and height to resize the image, a color to tint the image and a region to only use parts of the image.
If width or height is set to 0, the image size will be adjusted in order to keep the original aspect ratio.
If width and height are not set, but region is, the region's rect will be used.
key is an optional identifier, that can be used to modify the image via update_image().
If pad is set, and the image is smaller than the size specified by width and height, the image padding is added to match the size instead of upscaling.
Parameters width_unit and height_unit determine the units used to calculate the image width and height, respectively.
alt_text is used as the image description for assistive apps.
Parses bbcode and adds tags to the tag stack as needed.
Note: Using this method, you can't close a tag that was opened in a previous append_text() call. This is done to improve performance, especially when updating large RichTextLabels since rebuilding the whole BBCode every time would be slower. If you absolutely need to close a tag in a future method call, append the text instead of using append_text().
Returns the line number of the character position provided. Line and character numbers are both zero-indexed.
Note: If threaded is enabled, this method returns a value for the loaded part of the document. Use is_finished() or finished to determine whether document is fully loaded.
Returns the paragraph number of the character position provided. Paragraph and character numbers are both zero-indexed.
Note: If threaded is enabled, this method returns a value for the loaded part of the document. Use is_finished() or finished to determine whether document is fully loaded.
Returns the height of the content.
Note: This method always returns the full content size, and is not affected by visible_ratio and visible_characters. To get the visible content size, use get_visible_content_rect().
Note: If threaded is enabled, this method returns a value for the loaded part of the document. Use is_finished() or finished to determine whether document is fully loaded.
Returns the width of the content.
Note: This method always returns the full content size, and is not affected by visible_ratio and visible_characters. To get the visible content size, use get_visible_content_rect().
Note: If threaded is enabled, this method returns a value for the loaded part of the document. Use is_finished() or finished to determine whether document is fully loaded.
Returns the total number of lines in the text. Wrapped text is counted as multiple lines.
Note: If threaded is enabled, this method returns a value for the loaded part of the document. Use is_finished() or finished to determine whether document is fully loaded.
Returns the height of the line found at the provided index.
Note: If threaded is enabled, this method returns a value for the loaded part of the document. Use is_finished() or finished to determine whether the document is fully loaded.
Returns the vertical offset of the line found at the provided index.
Note: If threaded is enabled, this method returns a value for the loaded part of the document. Use is_finished() or finished to determine whether document is fully loaded.
Returns the indexes of the first and last visible characters for the given line, as a Vector2i.
Note: If visible_characters_behavior is set to TextServer.VC_CHARS_BEFORE_SHAPING only visible wrapped lines are counted.
Note: If threaded is enabled, this method returns a value for the loaded part of the document. Use is_finished() or finished to determine whether document is fully loaded.
Returns the width of the line found at the provided index.
Note: If threaded is enabled, this method returns a value for the loaded part of the document. Use is_finished() or finished to determine whether the document is fully loaded.
Returns the total number of paragraphs (newlines or p tags in the tag stack's text tags). Considers wrapped text as one paragraph.
Returns the vertical offset of the paragraph found at the provided index.
Note: If threaded is enabled, this method returns a value for the loaded part of the document. Use is_finished() or finished to determine whether document is fully loaded.
Returns the current selection first character index if a selection is active, -1 otherwise. Does not include BBCodes.
Returns the current selection last character index if a selection is active, -1 otherwise. Does not include BBCodes.
Returns the vertical scrollbar.
Warning: This is a required internal node, removing and freeing it may cause a crash. If you wish to hide it or any of its children, use their CanvasItem.visible property.
Returns the bounding rectangle of the visible content.
Note: This method returns a correct value only after the label has been drawn.
extends RichTextLabel
@export var background_panel: Panel
func _ready():
await draw
background_panel.position = get_visible_content_rect().position
background_panel.size = get_visible_content_rect().sizeReturns the number of visible lines.
Note: This method returns a correct value only after the label has been drawn.
Note: If threaded is enabled, this method returns a value for the loaded part of the document. Use is_finished() or finished to determine whether document is fully loaded.
Returns the number of visible paragraphs. A paragraph is considered visible if at least one of its lines is visible.
Note: This method returns a correct value only after the label has been drawn.
Note: If threaded is enabled, this method returns a value for the loaded part of the document. Use is_finished() or finished to determine whether document is fully loaded.
Installs a custom effect. This can also be done in the Inspector through the custom_effects property. effect should be a valid RichTextEffect.
Example: With the following script extending from RichTextEffect:
# effect.gd
class_name MyCustomEffect
extends RichTextEffect
var bbcode = "my_custom_effect"
# ...The above effect can be installed in RichTextLabel from a script:
# rich_text_label.gd
extends RichTextLabel
func _ready():
install_effect(MyCustomEffect.new())
# Alternatively, if not using `class_name` in the script that extends RichTextEffect:
install_effect(preload("res://effect.gd").new())If threaded is enabled, returns true if the background thread has finished text processing, otherwise always return true.
If threaded is enabled, returns true if the background thread has finished text processing, otherwise always return true.
The assignment version of append_text(). Clears the tag stack and inserts the new content.
Terminates the current tag. Use after push_* methods to close BBCodes manually. Does not need to follow add_* methods.
Terminates tags opened after the last push_context() call (including context marker), or all tags if there's no context marker on the stack.
Adds a [code skip-lint][bgcolor][/code] tag to the tag stack.
Note: The background color has padding applied by default, which is controlled using text_highlight_h_padding and text_highlight_v_padding. This can lead to overlapping highlights if background colors are placed on neighboring lines/columns, so consider setting those theme items to 0 if you want to avoid this.
Adds a [code skip-lint][font][/code] tag with a bold font to the tag stack. This is the same as adding a [code skip-lint][b][/code] tag if not currently in a [code skip-lint][i][/code] tag.
Adds a [code skip-lint][font][/code] tag with a bold italics font to the tag stack.
Adds a [code skip-lint][cell][/code] tag to the tag stack. Must be inside a [code skip-lint][table][/code] tag. See push_table() for details. Use set_table_column_expand() to set column expansion ratio, set_cell_border_color() to set cell border, set_cell_row_background_color() to set cell background, set_cell_size_override() to override cell size, and set_cell_padding() to set padding.
Adds a custom effect tag to the tag stack. The effect does not need to be in custom_effects. The environment is directly passed to the effect.
Adds a [code skip-lint][dropcap][/code] tag to the tag stack. Drop cap (dropped capital) is a decorative element at the beginning of a paragraph that is larger than the rest of the text.
Adds a [code skip-lint][fgcolor][/code] tag to the tag stack.
Note: The foreground color has padding applied by default, which is controlled using text_highlight_h_padding and text_highlight_v_padding. This can lead to overlapping highlights if foreground colors are placed on neighboring lines/columns, so consider setting those theme items to 0 if you want to avoid this.
Adds a [code skip-lint][font][/code] tag to the tag stack. Overrides default fonts for its duration.
Passing 0 to font_size will use the existing default font size.
Adds a [code skip-lint][font_size][/code] tag to the tag stack. Overrides default font size for its duration.
Adds a [code skip-lint][hint][/code] tag to the tag stack. Same as BBCode [code skip-lint][hint=something]{text}[/hint][/code].
Adds an [code skip-lint][indent][/code] tag to the tag stack. Multiplies level by current tab_size to determine new margin length.
Adds a [code skip-lint][font][/code] tag with an italics font to the tag stack. This is the same as adding an [code skip-lint][i][/code] tag if not currently in a [code skip-lint][b][/code] tag.
Adds [code skip-lint][ol][/code] or [code skip-lint][ul][/code] tag to the tag stack. Multiplies level by current tab_size to determine new margin length.
Adds a meta tag to the tag stack. Similar to the BBCode [code skip-lint]{text}[/code], but supports non-String metadata types.
If meta_underlined is true, meta tags display an underline. This behavior can be customized with underline_mode.
Note: Meta tags do nothing by default when clicked. To assign behavior when clicked, connect meta_clicked to a function that is called when the meta tag is clicked.
Adds a [code skip-lint][font][/code] tag with a monospace font to the tag stack.
Adds a [code skip-lint][font][/code] tag with a normal font to the tag stack.
Adds a [code skip-lint][outline_color][/code] tag to the tag stack. Adds text outline for its duration.
Adds a [code skip-lint][outline_size][/code] tag to the tag stack. Overrides default text outline size for its duration.
Adds a [code skip-lint][p][/code] tag to the tag stack.
Adds a [code skip-lint][s][/code] tag to the tag stack. If color's alpha value is 0.0, the current font's color with its alpha multiplied by strikethrough_alpha is used.
Adds a [code skip-lint][table=columns,inline_align][/code] tag to the tag stack. Use set_table_column_expand() to set column expansion ratio. Use push_cell() to add cells. name is used as the table name for assistive apps.
Adds a [code skip-lint][u][/code] tag to the tag stack. If color's alpha value is 0.0, the current font's color with its alpha multiplied by underline_alpha is used.
Reloads custom effects. Useful when custom_effects is modified manually.
Removes a paragraph of content from the label. Returns true if the paragraph exists.
The paragraph argument is the index of the paragraph to remove, it can take values in the interval [0, get_paragraph_count() - 1].
If no_invalidate is set to true, cache for the subsequent paragraphs is not invalidated. Use it for faster updates if deleted paragraph is fully self-contained (have no unclosed tags), or this call is part of the complex edit operation and invalidate_paragraph() will be called at the end of operation.
Select all the text.
If selection_enabled is false, no selection will occur.
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.
Updates the existing images with the key key. Only properties specified by mask bits are updated. See add_image().
Triggered when the document is fully loaded.
Note: This can happen before the text is processed for drawing. Scrolling values may not be valid until the document is drawn for the first time after this signal.
Triggered when the user clicks on content between meta (URL) tags. If the meta is defined in BBCode, e.g. [code skip-lint]Text[/code], then the parameter for this signal will always be a String type. If a particular type or an object is desired, the push_meta() method must be used to manually insert the data into the tag stack. Alternatively, you can convert the String input to the desired type based on its contents (such as calling JSON.parse() on it).
For example, the following method can be connected to meta_clicked to open clicked URLs using the user's default web browser:
# This assumes RichTextLabel's `meta_clicked` signal was connected to
# the function below using the signal connection dialog.
func _richtextlabel_on_meta_clicked(meta):
# `meta` is of Variant type, so convert it to a String to avoid script errors at run-time.
OS.shell_open(str(meta))LIST_NUMBERS = 0Each list item has a number marker.
LIST_LETTERS = 1Each list item has a letter marker.
LIST_ROMAN = 2Each list item has a roman number marker.
LIST_DOTS = 3Each list item has a filled circle marker.
MENU_COPY = 0Copies the selected text.
MENU_SELECT_ALL = 1Selects the whole RichTextLabel text.
MENU_MAX = 2Represents the size of the MenuItems enum.
META_UNDERLINE_NEVER = 0Meta tag does not display an underline, even if meta_underlined is true.
META_UNDERLINE_ALWAYS = 1If meta_underlined is true, meta tag always display an underline.
META_UNDERLINE_ON_HOVER = 2If meta_underlined is true, meta tag display an underline when the mouse cursor is over it.
UPDATE_TEXTURE = 1If this bit is set, update_image() changes image texture.
UPDATE_SIZE = 2If this bit is set, update_image() changes image size.
UPDATE_COLOR = 4If this bit is set, update_image() changes image color.
UPDATE_ALIGNMENT = 8If this bit is set, update_image() changes image inline alignment.
UPDATE_REGION = 16If this bit is set, update_image() changes image texture region.
UPDATE_PAD = 32If this bit is set, update_image() changes image padding.
UPDATE_TOOLTIP = 64If this bit is set, update_image() changes image tooltip.
UPDATE_WIDTH_UNIT = 128If this bit is set, update_image() changes the units used to calculate image size.