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 bbcode_text 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: 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.

Tutorials

Properties

boolbbcode_enabledfalse
Stringbbcode_text“”
Arraycustom_effects[  ]
boolfit_content_heightfalse
boolmeta_underlinedtrue
booloverride_selected_font_colorfalse
floatpercent_visible1.0
boolrect_clip_contenttrue (parent override)
boolscroll_activetrue
boolscroll_followingfalse
boolselection_enabledfalse
inttab_size4
Stringtext“”
intvisible_characters-1

Methods

voidadd_image ( Texture image, int width=0, int height=0 )
voidadd_text ( String text )
Errorappend_bbcode ( String bbcode )
voidclear ( )
intget_content_height ( ) const
intget_line_count ( ) const
intget_total_character_count ( ) const
VScrollBarget_v_scroll ( )
intget_visible_line_count ( ) const
voidinstall_effect ( Variant effect )
voidnewline ( )
Errorparse_bbcode ( String bbcode )
Dictionaryparse_expressions_for_values ( PoolStringArray expressions )
voidpop ( )
voidpush_align ( Align align )
voidpush_bold ( )
voidpush_bold_italics ( )
voidpush_cell ( )
voidpush_color ( Color color )
voidpush_font ( Font font )
voidpush_indent ( int level )
voidpush_italics ( )
voidpush_list ( ListType type )
voidpush_meta ( Variant data )
voidpush_mono ( )
voidpush_normal ( )
voidpush_strikethrough ( )
voidpush_table ( int columns )
voidpush_underline ( )
boolremove_line ( int line )
voidscroll_to_line ( int line )
voidset_table_column_expand ( int column, bool expand, int ratio )

Theme Properties

Fontbold_font 
Fontbold_italics_font 
Colordefault_colorColor( 1, 1, 1, 1 )
StyleBoxfocus 
Colorfont_color_selectedColor( 0.49, 0.49, 0.49, 1 )
Colorfont_color_shadowColor( 0, 0, 0, 0 )
Fontitalics_font 
intline_separation1
Fontmono_font 
StyleBoxnormal 
Fontnormal_font 
Colorselection_colorColor( 0.1, 0.1, 1, 0.8 )
intshadow_as_outline0
intshadow_offset_x1
intshadow_offset_y1
inttable_hseparation3
inttable_vseparation3

Signals

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 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.


Triggers when the mouse exits a meta tag.


  • meta_hover_started ( Variant meta )

Triggers when the mouse enters a meta tag.

Enumerations

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

Property Descriptions

  • bool bbcode_enabled
Defaultfalse
Setterset_use_bbcode(value)
Getteris_using_bbcode()

If true, the label uses BBCode formatting.


Default“”
Setterset_bbcode(value)
Getterget_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 the += operator with bbcode_text (e.g. bbcode_text += "some string") as it replaces the whole text and can cause slowdowns. Use append_bbcode for adding text instead, unless you absolutely need to close a tag that was opened in an earlier method call.


Default[  ]
Setterset_effects(value)
Getterget_effects()

The currently installed custom effects. This is an array of RichTextEffects.

To add a custom effect, it’s more convenient to use install_effect.


  • bool fit_content_height
Defaultfalse
Setterset_fit_content_height(value)
Getteris_fit_content_height_enabled()

If 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
Defaulttrue
Setterset_meta_underline(value)
Getteris_meta_underlined()

If true, the label underlines meta tags such as [url]{text}[/url].


  • bool override_selected_font_color
Defaultfalse
Setterset_override_selected_font_color(value)
Getteris_overriding_selected_font_color()

If true, the label uses the custom font color.


Default1.0
Setterset_percent_visible(value)
Getterget_percent_visible()

The range of characters to display, as a 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.


Defaulttrue
Setterset_scroll_active(value)
Getteris_scroll_active()

If true, the scrollbar is visible. Setting this to false does not block scrolling completely. See scroll_to_line.


  • bool scroll_following
Defaultfalse
Setterset_scroll_follow(value)
Getteris_scroll_following()

If true, the window scrolls down to display new content automatically.


  • bool selection_enabled
Defaultfalse
Setterset_selection_enabled(value)
Getteris_selection_enabled()

If true, the label allows text selection.


Default4
Setterset_tab_size(value)
Getterget_tab_size()

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


Default“”
Setterset_text(value)
Getterget_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 bbcode_text.


  • int visible_characters
Default-1
Setterset_visible_characters(value)
Getterget_visible_characters()

The restricted number of characters to display in the label. If -1, all characters will be displayed.

Method Descriptions

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 ( String text )

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


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

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.


  • void clear ( )

Clears the tag stack and sets bbcode_text to an empty string.


  • 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.


  • int get_total_character_count ( ) const

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


Returns the vertical scrollbar.


  • int get_visible_line_count ( ) const

Returns the number of visible lines.


  • void install_effect ( Variant effect )

Installs a custom effect. effect should be a valid RichTextEffect.


  • void newline ( )

Adds a newline tag to the tag stack.


The assignment version of append_bbcode. Clears the tag stack and inserts the new content. Returns @GlobalScope.OK if parses bbcode successfully.


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 ( Align align )

Adds an [align] tag based on the given align value. See 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 push_table for details.


  • void push_color ( Color color )

Adds a [color] tag to the tag stack.


  • void push_font ( Font font )

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


  • void push_indent ( int level )

Adds an [indent] tag to the tag stack. Multiplies level by current 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.


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


Adds a [meta] tag to the tag stack. Similar to the BBCode [url=something]{text}[/url], but supports non-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 ( int columns )

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


  • void push_underline ( )

Adds a [u] tag to the tag stack.


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 ( int line )

Scrolls the window’s top line to match line.


  • void set_table_column_expand ( int column, bool expand, 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.