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 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 [b]bold[i]bold italic[/b]italic[/i], use [b]bold[i]bold italic[/i][/b][i]italic[/i].

Note: push_*/pop functions 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.

Tutorials¶

Properties¶

AutowrapMode	autowrap_mode	`3`
bool	bbcode_enabled	`false`
bool	clip_contents	`true` (overrides Control)
Array	custom_effects	`[]`
bool	deselect_on_focus_loss_enabled	`true`
bool	fit_content_height	`false`
String	language	`""`
bool	meta_underlined	`true`
bool	override_selected_font_color	`false`
float	percent_visible	`1.0`
bool	scroll_active	`true`
bool	scroll_following	`false`
bool	selection_enabled	`false`
StructuredTextParser	structured_text_bidi_override	`0`
Array	structured_text_bidi_override_options	`[]`
int	tab_size	`4`
String	text	`""`
TextDirection	text_direction	`0`
int	visible_characters	`-1`
VisibleCharactersBehavior	visible_characters_behavior	`0`

Methods¶

void	add_image ( Texture2D image, int width=0, int height=0, Color color=Color(1, 1, 1, 1), InlineAlignment inline_align=5 )
void	add_text ( String text )
void	append_text ( String bbcode )
void	clear ( )
int	get_character_line ( int character )
int	get_character_paragraph ( int character )
int	get_content_height ( ) const
int	get_content_width ( ) const
int	get_line_count ( ) const
float	get_line_offset ( int line )
int	get_paragraph_count ( ) const
float	get_paragraph_offset ( int paragraph )
String	get_parsed_text ( ) const
String	get_selected_text ( ) const
int	get_selection_from ( ) const
int	get_selection_to ( ) const
int	get_total_character_count ( ) const
VScrollBar	get_v_scroll_bar ( )
int	get_visible_line_count ( ) const
int	get_visible_paragraph_count ( ) const
void	install_effect ( Variant effect )
void	newline ( )
void	parse_bbcode ( String bbcode )
Dictionary	parse_expressions_for_values ( PackedStringArray expressions )
void	pop ( )
void	push_bgcolor ( Color bgcolor )
void	push_bold ( )
void	push_bold_italics ( )
void	push_cell ( )
void	push_color ( Color color )
void	push_dropcap ( String string, Font font, int size, Rect2 dropcap_margins=Rect2(0, 0, 0, 0), Color color=Color(1, 1, 1, 1), int outline_size=0, Color outline_color=Color(0, 0, 0, 0) )
void	push_fgcolor ( Color fgcolor )
void	push_font ( Font font )
void	push_font_features ( Dictionary opentype_features )
void	push_font_size ( int font_size )
void	push_indent ( int level )
void	push_italics ( )
void	push_list ( int level, ListType type, bool capitalize )
void	push_meta ( Variant data )
void	push_mono ( )
void	push_normal ( )
void	push_outline_color ( Color color )
void	push_outline_size ( int outline_size )
void	push_paragraph ( HorizontalAlignment alignment, TextDirection base_direction=0, String language="", StructuredTextParser st_parser=0 )
void	push_strikethrough ( )
void	push_table ( int columns, InlineAlignment inline_align=0 )
void	push_underline ( )
bool	remove_line ( int line )
void	scroll_to_line ( int line )
void	scroll_to_paragraph ( int paragraph )
void	set_cell_border_color ( Color color )
void	set_cell_padding ( Rect2 padding )
void	set_cell_row_background_color ( Color odd_row_bg, Color even_row_bg )
void	set_cell_size_override ( Vector2 min_size, Vector2 max_size )
void	set_table_column_expand ( int column, bool expand, int ratio )

Theme Properties¶

Color	default_color	`Color(1, 1, 1, 1)`
Color	font_outline_color	`Color(1, 1, 1, 1)`
Color	font_selected_color	`Color(0, 0, 0, 1)`
Color	font_shadow_color	`Color(0, 0, 0, 0)`
Color	selection_color	`Color(0.1, 0.1, 1, 0.8)`
Color	table_border	`Color(0, 0, 0, 0)`
Color	table_even_row_bg	`Color(0, 0, 0, 0)`
Color	table_odd_row_bg	`Color(0, 0, 0, 0)`
int	line_separation	`0`
int	outline_size	`0`
int	shadow_offset_x	`1`
int	shadow_offset_y	`1`
int	shadow_outline_size	`1`
int	table_hseparation	`3`
int	table_vseparation	`3`
Font	bold_font
Font	bold_italics_font
Font	italics_font
Font	mono_font
Font	normal_font
int	bold_font_size
int	bold_italics_font_size
int	italics_font_size
int	mono_font_size
int	normal_font_size
StyleBox	focus
StyleBox	normal

Signals¶

meta_clicked ( 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 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¶

enum AutowrapMode:

AUTOWRAP_OFF = 0 --- Autowrap is disabled.
AUTOWRAP_ARBITRARY = 1 --- Wraps the text inside the node's bounding rectangle by allowing to break lines at arbitrary positions, which is useful when very limited space is available.
AUTOWRAP_WORD = 2 --- Wraps the text inside the node's bounding rectangle by soft-breaking between words.
AUTOWRAP_WORD_SMART = 3 --- Behaves similarly to AUTOWRAP_WORD, but force-breaks a word if that single word does not fit in one line.

enum ListType:

LIST_NUMBERS = 0 --- Each list item has a number marker.
LIST_LETTERS = 1 --- Each list item has a letter marker.
LIST_ROMAN = 2 --- Each list item has a roman number marker.
LIST_DOTS = 3 --- 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_FONT_SIZE = 5
ITEM_FONT_FEATURES = 6
ITEM_COLOR = 7
ITEM_OUTLINE_SIZE = 8
ITEM_OUTLINE_COLOR = 9
ITEM_UNDERLINE = 10
ITEM_STRIKETHROUGH = 11
ITEM_PARAGRAPH = 12
ITEM_INDENT = 13
ITEM_LIST = 14
ITEM_TABLE = 15
ITEM_FADE = 16
ITEM_SHAKE = 17
ITEM_WAVE = 18
ITEM_TORNADO = 19
ITEM_RAINBOW = 20
ITEM_BGCOLOR = 21
ITEM_FGCOLOR = 22
ITEM_META = 23
ITEM_DROPCAP = 24
ITEM_CUSTOMFX = 25

enum VisibleCharactersBehavior:

VC_CHARS_BEFORE_SHAPING = 0 --- Trims text before the shaping. e.g, increasing visible_characters value is visually identical to typing the text.
VC_CHARS_AFTER_SHAPING = 1 --- Displays glyphs that are mapped to the first visible_characters characters from the beginning of the text.
VC_GLYPHS_AUTO = 2 --- Displays percent_visible glyphs, starting from the left or from the right, depending on Control.layout_direction value.
VC_GLYPHS_LTR = 3 --- Displays percent_visible glyphs, starting from the left.
VC_GLYPHS_RTL = 4 --- Displays percent_visible glyphs, starting from the right.

Property Descriptions¶

AutowrapMode autowrap_mode

Default	`3`
Setter	set_autowrap_mode(value)
Getter	get_autowrap_mode()

If set to something other than AUTOWRAP_OFF, the text gets wrapped inside the node's bounding rectangle. To see how each mode behaves, see AutowrapMode.

bool bbcode_enabled

Default	`false`
Setter	set_use_bbcode(value)
Getter	is_using_bbcode()

If true, the label uses BBCode formatting.

Array custom_effects

Default	`[]`
Setter	set_effects(value)
Getter	get_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 deselect_on_focus_loss_enabled

Default	`true`
Setter	set_deselect_on_focus_loss_enabled(value)
Getter	is_deselect_on_focus_loss_enabled()

If true, the selected text will be deselected when focus is lost.

bool fit_content_height

Default	`false`
Setter	set_fit_content_height(value)
Getter	is_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.

String language

Default	`""`
Setter	set_language(value)
Getter	get_language()

Language code used for line-breaking and text shaping algorithms, if left empty current locale is used instead.

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

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.

float percent_visible

Default	`1.0`
Setter	set_percent_visible(value)
Getter	get_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.

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

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.

bool selection_enabled

Default	`false`
Setter	set_selection_enabled(value)
Getter	is_selection_enabled()

If true, the label allows text selection.

StructuredTextParser structured_text_bidi_override

Default	`0`
Setter	set_structured_text_bidi_override(value)
Getter	get_structured_text_bidi_override()

Set BiDi algorithm override for the structured text.

Array structured_text_bidi_override_options

Default	`[]`
Setter	set_structured_text_bidi_override_options(value)
Getter	get_structured_text_bidi_override_options()

Set additional options for BiDi override.

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.

String text

Default	`""`
Setter	set_text(value)
Getter	get_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: 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.

TextDirection text_direction

Default	`0`
Setter	set_text_direction(value)
Getter	get_text_direction()

Base text writing direction.

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.

Note: Setting this property updates percent_visible based on current get_total_character_count.

VisibleCharactersBehavior visible_characters_behavior

Default	`0`
Setter	set_visible_characters_behavior(value)
Getter	get_visible_characters_behavior()

Sets the clipping behavior when visible_characters or percent_visible is set. See VisibleCharactersBehavior for more info.

Method Descriptions¶

void add_image ( Texture2D image, int width=0, int height=0, Color color=Color(1, 1, 1, 1), InlineAlignment inline_align=5 )

Adds an image's opening and closing tags to the tag stack, optionally providing a width and height to resize the image and a color to tint 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.

void append_text ( String bbcode )

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.

void clear ( )

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

int get_character_line ( int character )

Returns the line number of the character position provided.

int get_character_paragraph ( int character )

Returns the paragraph number of the character position provided.

int get_content_height ( ) const

Returns the height of the content.

int get_content_width ( ) const

Returns the width of the content.

int get_line_count ( ) const

Returns the total number of lines in the text. Wrapped text is counted as multiple lines.

float get_line_offset ( int line )

Returns the vertical offset of the line found at the provided index.

int get_paragraph_count ( ) const

Returns the total number of paragraphs (newlines or p tags in the tag stack's text tags). Considers wrapped text as one paragraph.

float get_paragraph_offset ( int paragraph )

Returns the vertical offset of the paragraph found at the provided index.

String get_parsed_text ( ) const

Returns the text without BBCode mark-up.

String get_selected_text ( ) const

Returns the current selection text. Does not include BBCodes.

int get_selection_from ( ) const

Returns the current selection first character index if a selection is active, -1 otherwise. Does not include BBCodes.

int get_selection_to ( ) const

Returns the current selection last character index if a selection is active, -1 otherwise. 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_bar ( )

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.

int get_visible_paragraph_count ( ) const

Returns the number of visible paragraphs. A paragraph is considered visible if at least one of its lines is visible.

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.

void parse_bbcode ( String bbcode )

The assignment version of append_text. Clears the tag stack and inserts the new content.

Dictionary parse_expressions_for_values ( 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_bgcolor ( Color bgcolor )

Adds a [bgcolor] tag to the tag stack.

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_dropcap ( String string, Font font, int size, Rect2 dropcap_margins=Rect2(0, 0, 0, 0), Color color=Color(1, 1, 1, 1), int outline_size=0, Color outline_color=Color(0, 0, 0, 0) )

Adds a [dropcap] 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.

void push_fgcolor ( Color fgcolor )

Adds a [fgcolor] 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_font_features ( Dictionary opentype_features )

Adds a [ot_feature] tag to the tag stack. Overrides default OpenType font feature for its duration.

void push_font_size ( int font_size )

Adds a [font_size] tag to the tag stack. Overrides default font size 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.

void push_list ( int level, ListType type, bool capitalize )

Adds [ol] or [ul] tag to the tag stack. Multiplies level by current tab_size to determine new margin length.

void push_meta ( Variant data )

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_outline_color ( Color color )

Adds a [outline_color] tag to the tag stack. Adds text outline for its duration.

void push_outline_size ( int outline_size )

Adds a [outline_size] tag to the tag stack. Overrides default text outline size for its duration.

void push_paragraph ( HorizontalAlignment alignment, TextDirection base_direction=0, String language="", StructuredTextParser st_parser=0 )

Adds a [p] tag to the tag stack.

void push_strikethrough ( )

Adds a [s] tag to the tag stack.

void push_table ( int columns, InlineAlignment inline_align=0 )

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

void push_underline ( )

Adds a [u] tag to the tag stack.

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

Scrolls the window's top line to match line.

void scroll_to_paragraph ( int paragraph )

Scrolls the window's top line to match first line of the paragraph.

void set_cell_border_color ( Color color )

Sets color of a table cell border.

void set_cell_padding ( Rect2 padding )

Sets inner padding of a table cell.

void set_cell_row_background_color ( Color odd_row_bg, Color even_row_bg )

Sets color of a table cell. Separate colors for alternating rows can be specified.

void set_cell_size_override ( Vector2 min_size, Vector2 max_size )

Sets minimum and maximum size overrides for a table cell.

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.

Theme Property Descriptions¶

Color default_color

Default

Color(1, 1, 1, 1)

The default text color.

Color font_outline_color

Default

Color(1, 1, 1, 1)

The default tint of text outline.

Color font_selected_color

Default

Color(0, 0, 0, 1)

The color of selected text, used when selection_enabled is true.

Color font_shadow_color

Default

Color(0, 0, 0, 0)

The color of the font's shadow.

Color selection_color

Default

Color(0.1, 0.1, 1, 0.8)

The color of the selection box.

Color table_border

Default

Color(0, 0, 0, 0)

The default cell border color.

Color table_even_row_bg

Default

Color(0, 0, 0, 0)

The default background color for even rows.

Color table_odd_row_bg

Default

Color(0, 0, 0, 0)

The default background color for odd rows.

int line_separation

Default

0

The vertical space between lines.

int outline_size

Default

0

The size of the text outline.

int shadow_offset_x

Default

1

The horizontal offset of the font's shadow.

int shadow_offset_y

Default

1

The vertical offset of the font's shadow.

int shadow_outline_size

Default

1

The size of the shadow outline.

int table_hseparation

Default

3

The horizontal separation of elements in a table.

int table_vseparation

Default

3

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.

int bold_font_size

The font size used for bold text.

int bold_italics_font_size

The font size used for bold italics text.

int italics_font_size

The font size used for italics text.

int mono_font_size

The font size used for monospace text.

int normal_font_size

The default text font size.

StyleBox focus

The background used when the RichTextLabel is focused. The focus StyleBox is displayed over the base StyleBox, so a partially transparent StyleBox should be used to ensure the base StyleBox remains visible. A StyleBox that represents an outline or an underline works well for this purpose. To disable the focus visual effect, assign a StyleBoxEmpty resource. Note that disabling the focus visual effect will harm keyboard/controller navigation usability, so this is not recommended for accessibility reasons.

StyleBox normal

The normal background for the RichTextLabel.