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 Color( 1, 1, 1, 1 )
StyleBox focus  
Color font_color_selected Color( 0.49, 0.49, 0.49, 1 )
Color font_color_shadow Color( 0, 0, 0, 0 )
Font italics_font  
int line_separation 1
Font mono_font  
StyleBox normal  
Font normal_font  
Color selection_color Color( 0.1, 0.1, 1, 0.8 )
int shadow_as_outline 0
int shadow_offset_x 1
int shadow_offset_y 1
int table_hseparation 3
int table_vseparation 3

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: 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
Default false
Setter set_use_bbcode(value)
Getter is_using_bbcode()

If true, the label uses BBCode formatting.

Default “”
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
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.

Default 1.0
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
Default true
Setter set_scroll_active(value)
Getter is_scroll_active()

If true, the scrollbar is visible. 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.

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.

Default “”
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
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.

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, @GlobalScope.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 @GlobalScope.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 [align] 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 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.