RichTextLabel

Inherits: Control < CanvasItem < Node < Object

Category: Core

Brief Description

Label that displays rich text.

Methods

void add_image ( Texture image )
void add_text ( String text )
Error append_bbcode ( String bbcode )
void clear ( )
int get_content_height ( )
int get_line_count ( ) const
int get_total_character_count ( ) const
VScrollBar get_v_scroll ( )
int get_visible_line_count ( ) const
void newline ( )
Error parse_bbcode ( String bbcode )
void pop ( )
void push_align ( Align align )
void push_cell ( )
void push_color ( Color color )
void push_font ( Font font )
void push_indent ( int level )
void push_list ( ListType type )
void push_meta ( Variant data )
void push_strikethrough ( )
void push_table ( int columns )
void push_underline ( )
bool remove_line ( int line )
void scroll_to_line ( int line )
void set_table_column_expand ( int column, bool expand, int ratio )

Theme Properties

Font bold_font
Font bold_italics_font
Color default_color
StyleBox focus
Color font_color_selected
Color font_color_shadow
Font italics_font
int line_separation
Font mono_font
StyleBox normal
Font normal_font
Color selection_color
int shadow_as_outline
int shadow_offset_x
int shadow_offset_y
int table_hseparation
int table_vseparation

Signals

  • meta_clicked ( Nil meta )

Triggered when the user clicks on content between [url] 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 ( Nil meta )

Triggers when the mouse exits a meta tag.

  • meta_hover_started ( Nil meta )

Triggers when the mouse enters a meta tag.

Enumerations

enum Align:

  • ALIGN_LEFT = 0
  • ALIGN_CENTER = 1
  • ALIGN_RIGHT = 2
  • ALIGN_FILL = 3

enum ListType:

  • LIST_NUMBERS = 0
  • LIST_LETTERS = 1
  • LIST_DOTS = 2

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_META = 12

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

Property Descriptions

  • bool bbcode_enabled
Setter set_use_bbcode(value)
Getter is_using_bbcode()

If true, the label uses BBCode formatting. Default value: false.

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.

  • bool meta_underlined
Setter set_meta_underline(value)
Getter is_meta_underlined()

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

  • bool override_selected_font_color
Setter set_override_selected_font_color(value)
Getter is_overriding_selected_font_color()

If true, the label uses the custom font color. Default value: false.

Setter set_percent_visible(value)
Getter get_percent_visible()

The text’s visibility, as a float between 0.0 and 1.0.

  • bool scroll_active
Setter set_scroll_active(value)
Getter is_scroll_active()

If true, the scrollbar is visible. Does not block scrolling completely. See scroll_to_line. Default value: true.

  • bool scroll_following
Setter set_scroll_follow(value)
Getter is_scroll_following()

If true, the window scrolls down to display new content automatically. Default value: false.

  • bool selection_enabled
Setter set_selection_enabled(value)
Getter is_selection_enabled()

If true, the label allows text selection.

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.

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

  • int visible_characters
Setter set_visible_characters(value)
Getter get_visible_characters()

The restricted number of characters to display in the label.

Method Descriptions

Adds an image’s opening and closing tags to the tag stack.

  • 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, OK if successful.

  • void clear ( )

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

  • int get_content_height ( )

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 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 OK if parses bbcode successfully.

  • 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 alignment tag based on the given align value. See Align for possible values.

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

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

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

Columns with a false expand will not contribute to the total ratio.