RichTextLabel

Inherits: Control < CanvasItem < Node < Object Label that displays rich text.

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: Assignments to bbcodetext clear the tag stack and reconstruct it from the property’s contents. Any edits made to bbcode_text will erase previous edits made from other manual sources such as append_bbcode and the `push/ pop methods. **Note:** RichTextLabel doesn’t support entangled BBCode tags. For example, instead of using[b]bold[i]bold italic[/b]italic[/i], use[b]bold[i]bold italic[/i][/b][i]italic[/i]. **Note:**push_/popfunctions won’t affect BBCode. **Note:** Unlike Label, RichTextLabel doesn’t have a *property* to horizontally align text to the center. Instead, enable bbcode_enabled and surround the text in a[center]tag as follows:[center]Example[/center]. There is currently no built-in way to vertically align text either, but this can be emulated by relying on anchors/containers and the fit_content_height property. **Note:** Unicode characters after0xffff` (such as most emoji) are not supported on Windows. They will display as unknown characters instead. This will be resolved in Godot 4.0.

Tutorials

  • BBCode in RichTextLabel
  • GUI Rich Text/BBcode Demo
  • OS Test Demo

    Properties

    Methods

    Theme Properties

    Signals

  • meta_clicked ( Variant meta ) [url={"data"="hi"}]hi[/url], then the parameter for this signal will 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.
  • meta_hover_ended ( Variant meta ) Triggers when the mouse exits a meta tag.
  • meta_hover_started ( Variant meta ) Triggers when the mouse enters a meta tag.

    Enumerations

    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.

InlineAlign:

  • INLINE_ALIGN_TOP = 0 —- Aligns top of the inline image to the top of the text.
  • INLINE_ALIGN_CENTER = 1 —- Aligns center of the inline image to the center of the text.
  • INLINE_ALIGN_BASELINE = 2 —- Aligns bottom of the inline image to the baseline of the text.
  • INLINE_ALIGN_BOTTOM = 3 —- Aligns bottom of the inline image to the bottom of the text.

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.

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

    Property Descriptions

  • bool bbcode_enabled true, the label uses BBCode formatting. Note: Trying to alter the RichTextLabel‘s text with add_text will reset this to false. Use instead append_bbcode to preserve BBCode formatting.
  • 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. Note: It is unadvised to use the += operator with bbcode_text (e.g. bbcode_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_bbcode for adding text instead, unless you absolutely need to close a tag that was opened in an earlier method call.
  • Array custom_effects RichTextEffects. install_effect.
  • bool deselect_on_focus_loss_enabled true, the selected text will be deselected when focus is lost.
  • bool fit_content_height true, the label’s height will be automatically updated to fit its content. Note: This property is used as a workaround to fix issues with RichTextLabel in Containers, but it’s unreliable in some cases and will be removed in future versions.
  • bool meta_underlined true, the label underlines meta tags such as [url]{text}[/url].
  • bool override_selected_font_color true, the label uses the custom font color.
  • float percent_visible 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 visible_characters based on current get_total_character_count.
  • bool scroll_active true, the scrollbar is visible. Setting this to false does not block scrolling completely. See scroll_to_line.
  • bool scroll_following true, the window scrolls down to display new content automatically.
  • bool selection_enabled true, the label allows text selection.
  • int tab_size \t in text tags, only indent tags.
  • String text The raw text of the label. bbcode_text.
  • int visible_characters -1, all characters will be displayed. Note: Setting this property updates percent_visible based on current get_total_character_count.

    Method Descriptions

  • add_image ( Texture image, int width=0, int height=0, InlineAlign align=2 ) width and height to resize the image. width or height is set to 0, the image size will be adjusted in order to keep the original aspect ratio.
  • add_text ( String text ) Adds raw non-BBCode-parsed text to the tag stack.
  • Error append_bbcode ( String bbcode ) 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_bbcode 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 bbcode_text instead of using append_bbcode. Note: This method internals’ can’t possibly fail, but an error code is returned for backwards compatibility, which will always be @GlobalScope.OK.
  • clear ( ) bbcode_text to an empty string.
  • deselect ( ) Clears the current selection.
  • int get_content_height ( ) const Returns the height of the content.
  • int get_line_count ( ) const Returns the total number of newlines in the tag stack’s text tags. Considers wrapped text as one line.
  • String get_selected_text ( ) Returns the current selection text. Does not include BBCodes.
  • int get_total_character_count ( ) const Returns the total number of characters from text tags. Does not include BBCodes.
  • VScrollBar get_v_scroll ( ) 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.
  • int get_visible_line_count ( ) const Returns the number of visible lines.
  • install_effect ( Variant effect ) effect should be a valid RichTextEffect.
  • newline ( ) Adds a newline tag to the tag stack.
  • Error parse_bbcode ( String bbcode ) append_bbcode. Clears the tag stack and inserts the new content. Note: This method internals’ can’t possibly fail, but an error code is returned for backwards compatibility, which will always be @GlobalScope.OK.
  • Dictionary parse_expressions_for_values ( PoolStringArray expressions ) expressions into a dictionary.
  • pop ( ) push_* methods to close BBCodes manually. Does not need to follow add_* methods.
  • push_align ( Align align ) [align] tag based on the given align value. See Align for possible values.
  • push_bold ( ) [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.
  • push_bold_italics ( ) [font] tag with a bold italics font to the tag stack.
  • push_cell ( ) [cell] tag to the tag stack. Must be inside a [table] tag. See push_table for details.
  • push_color ( Color color ) [color] tag to the tag stack.
  • push_font ( Font font ) [font] tag to the tag stack. Overrides default fonts for its duration.
  • push_indent ( int level ) [indent] tag to the tag stack. Multiplies level by current tab_size to determine new margin length.
  • push_italics ( ) [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.
  • push_list ( ListType type ) [list] tag to the tag stack. Similar to the BBCodes [ol] or [ul], but supports more list types. Not fully implemented!
  • push_meta ( Variant data ) [meta] tag to the tag stack. Similar to the BBCode [url=something]{text}[/url], but supports non-String metadata types.
  • push_mono ( ) [font] tag with a monospace font to the tag stack.
  • push_normal ( ) [font] tag with a normal font to the tag stack.
  • push_strikethrough ( ) [s] tag to the tag stack.
  • push_table ( int columns ) [table=columns] tag to the tag stack.
  • push_underline ( ) [u] tag to the tag stack.
  • bool remove_line ( int line ) true if the line exists. line argument is the index of the line to remove, it can take values in the interval [0, get_line_count() - 1].
  • scroll_to_line ( int line ) line.
  • set_table_column_expand ( int column, bool expand, int ratio ) 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. expand is false, the column will not contribute to the total ratio.

    Theme Property Descriptions

  • Color default_color The default text color.
  • Color font_color_selected selection_enabled is true.
  • Color font_color_shadow The color of the font’s shadow.
  • Color selection_color The color of the selection box.
  • int line_separation The vertical space between lines.
  • int shadow_as_outline true), the shadow will be displayed around the whole text as an outline.
  • int shadow_offset_x The horizontal offset of the font’s shadow.
  • int shadow_offset_y The vertical offset of the font’s shadow.
  • int table_hseparation The horizontal separation of elements in a table.
  • int table_vseparation The vertical separation of elements in a table.
  • Font bold_font The font used for bold text.
  • Font bold_italics_font The font used for bold italics text.
  • Font italics_font The font used for italics text.
  • Font mono_font The font used for monospace text.
  • Font normal_font The default text font.
  • StyleBox focus RichTextLabel is focused.
  • StyleBox normal RichTextLabel.