Attention: Here be dragons

This is the latest (unstable) version of this documentation, which may document features not available in or compatible with released stable versions of Godot.

Checking the stable version of the documentation...

RichTextLabel

Inherits: Control < CanvasItem < Node < Object

A control for displaying text that can contain different font styles, images, and basic formatting.

描述

A control for displaying text that can contain custom fonts, images, and basic formatting. RichTextLabel 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 property.

教程

属性

AutowrapMode

autowrap_mode

3

bool

bbcode_enabled

false

bool

clip_contents

true (overrides Control)

bool

context_menu_enabled

false

Array

custom_effects

[]

bool

deselect_on_focus_loss_enabled

true

bool

drag_and_drop_selection_enabled

true

bool

fit_content

false

bool

hint_underlined

true

String

language

""

bool

meta_underlined

true

int

progress_bar_delay

1000

bool

scroll_active

true

bool

scroll_following

false

bool

selection_enabled

false

bool

shortcut_keys_enabled

true

StructuredTextParser

structured_text_bidi_override

0

Array

structured_text_bidi_override_options

[]

int

tab_size

4

String

text

""

TextDirection

text_direction

0

bool

threaded

false

int

visible_characters

-1

VisibleCharactersBehavior

visible_characters_behavior

0

float

visible_ratio

1.0

Methods

void

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

void

add_text ( String text )

void

append_text ( String bbcode )

void

clear ( )

void

deselect ( )

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 )

PopupMenu

get_menu ( ) const

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 )

bool

is_menu_visible ( ) const

bool

is_ready ( ) const

void

menu_option ( int option )

void

newline ( )

void

parse_bbcode ( String bbcode )

Dictionary

parse_expressions_for_values ( PackedStringArray expressions )

void

pop ( )

void

pop_all ( )

void

pop_context ( )

void

push_bgcolor ( Color bgcolor )

void

push_bold ( )

void

push_bold_italics ( )

void

push_cell ( )

void

push_color ( Color color )

void

push_context ( )

void

push_customfx ( RichTextEffect effect, Dictionary env )

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, int font_size=0 )

void

push_font_size ( int font_size )

void

push_hint ( String description )

void

push_indent ( int level )

void

push_italics ( )

void

push_language ( String language )

void

push_list ( int level, ListType type, bool capitalize, String bullet="•" )

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, BitField<JustificationFlag> justification_flags=163, PackedFloat32Array tab_stops=PackedFloat32Array() )

void

push_strikethrough ( )

void

push_table ( int columns, InlineAlignment inline_align=0, int align_to_row=-1 )

void

push_underline ( )

bool

remove_paragraph ( int paragraph )

void

scroll_to_line ( int line )

void

scroll_to_paragraph ( int paragraph )

void

scroll_to_selection ( )

void

select_all ( )

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=1 )

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, 0)

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_h_separation

3

int

table_v_separation

3

int

text_highlight_h_padding

3

int

text_highlight_v_padding

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

信号

finished ( )

Triggered when the document is fully loaded.

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 ListType:

ListType LIST_NUMBERS = 0

Each list item has a number marker.

ListType LIST_LETTERS = 1

Each list item has a letter marker.

ListType LIST_ROMAN = 2

Each list item has a roman number marker.

ListType LIST_DOTS = 3

Each list item has a filled circle marker.

enum MenuItems:

MenuItems MENU_COPY = 0

Copies the selected text.

MenuItems MENU_SELECT_ALL = 1

Selects the whole RichTextLabel text.

MenuItems MENU_MAX = 2

Represents the size of the MenuItems enum.

Property Descriptions

AutowrapMode autowrap_mode = 3

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

bool bbcode_enabled = false

  • void set_use_bbcode ( bool value )

  • bool is_using_bbcode ( )

If true, the label uses BBCode formatting.

bool context_menu_enabled = false

  • void set_context_menu_enabled ( bool value )

  • bool is_context_menu_enabled ( )

If true, a right-click displays the context menu.

Array custom_effects = []

  • void set_effects ( Array value )

  • Array 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 = true

  • void set_deselect_on_focus_loss_enabled ( bool value )

  • bool is_deselect_on_focus_loss_enabled ( )

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

bool drag_and_drop_selection_enabled = true

  • void set_drag_and_drop_selection_enabled ( bool value )

  • bool is_drag_and_drop_selection_enabled ( )

If true, allow drag and drop of selected text.

bool fit_content = false

  • void set_fit_content ( bool value )

  • bool is_fit_content_enabled ( )

If true, the label's minimum size will be automatically updated to fit its content, matching the behavior of Label.

bool hint_underlined = true

  • void set_hint_underline ( bool value )

  • bool is_hint_underlined ( )

If true, the label underlines hint tags such as [hint=description]{text}[/hint].

String language = ""

  • void set_language ( String value )

  • String get_language ( )

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

bool meta_underlined = true

  • void set_meta_underline ( bool value )

  • bool is_meta_underlined ( )

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

int progress_bar_delay = 1000

  • void set_progress_bar_delay ( int value )

  • int get_progress_bar_delay ( )

The delay after which the loading progress bar is displayed, in milliseconds. Set to -1 to disable progress bar entirely.

Note: Progress bar is displayed only if threaded is enabled.

bool scroll_active = true

  • void set_scroll_active ( bool value )

  • bool 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 = false

  • void set_scroll_follow ( bool value )

  • bool is_scroll_following ( )

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

bool selection_enabled = false

  • void set_selection_enabled ( bool value )

  • bool is_selection_enabled ( )

If true, the label allows text selection.

bool shortcut_keys_enabled = true

  • void set_shortcut_keys_enabled ( bool value )

  • bool is_shortcut_keys_enabled ( )

If true, shortcut keys for context menu items are enabled, even if the context menu is disabled.

StructuredTextParser structured_text_bidi_override = 0

Set BiDi algorithm override for the structured text.

Array structured_text_bidi_override_options = []

  • void set_structured_text_bidi_override_options ( Array value )

  • Array get_structured_text_bidi_override_options ( )

Set additional options for BiDi override.

int tab_size = 4

  • void set_tab_size ( int value )

  • int 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 = ""

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 = 0

Base text writing direction.

bool threaded = false

  • void set_threaded ( bool value )

  • bool is_threaded ( )

If true, text processing is done in a background thread.

int visible_characters = -1

  • void set_visible_characters ( int value )

  • int get_visible_characters ( )

The number of characters to display. If set to -1, all characters are displayed. This can be useful when animating the text appearing in a dialog box.

Note: Setting this property updates visible_ratio accordingly.

VisibleCharactersBehavior visible_characters_behavior = 0

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

float visible_ratio = 1.0

  • void set_visible_ratio ( float value )

  • float get_visible_ratio ( )

The fraction of characters to display, relative to the total number of characters (see get_total_character_count). If set to 1.0, all characters are displayed. If set to 0.5, only half of the characters will be displayed. This can be useful when animating the text appearing in a dialog box.

Note: Setting this property updates visible_characters accordingly.

Method Descriptions

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

Adds an image's opening and closing tags to the tag stack, optionally providing a width and height to resize the image, a color to tint the image and a region to only use parts of the image.

If width or height is set to 0, the image size will be adjusted in order to keep the original aspect ratio.

If width and height are not set, but region is, the region's rect will be used.

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.

Note: This method will not modify text, but setting text to an empty string also clears the stack.

void deselect ( )

Clears the current selection.

int get_character_line ( int character )

Returns the line number of the character position provided.

Note: If threaded is enabled, this method returns a value for the loaded part of the document. Use is_ready or finished to determine whether document is fully loaded.

int get_character_paragraph ( int character )

Returns the paragraph number of the character position provided.

Note: If threaded is enabled, this method returns a value for the loaded part of the document. Use is_ready or finished to determine whether document is fully loaded.

int get_content_height ( ) const

Returns the height of the content.

Note: If threaded is enabled, this method returns a value for the loaded part of the document. Use is_ready or finished to determine whether document is fully loaded.

int get_content_width ( ) const

Returns the width of the content.

Note: If threaded is enabled, this method returns a value for the loaded part of the document. Use is_ready or finished to determine whether document is fully loaded.

int get_line_count ( ) const

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

Note: If threaded is enabled, this method returns a value for the loaded part of the document. Use is_ready or finished to determine whether document is fully loaded.

float get_line_offset ( int line )

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

Note: If threaded is enabled, this method returns a value for the loaded part of the document. Use is_ready or finished to determine whether document is fully loaded.

PopupMenu get_menu ( ) const

Returns the PopupMenu of this RichTextLabel. By default, this menu is displayed when right-clicking on the RichTextLabel.

You can add custom menu items or remove standard ones. Make sure your IDs don't conflict with the standard ones (see MenuItems). For example:

func _ready():
    var menu = get_menu()
    # Remove "Select All" item.
    menu.remove_item(MENU_SELECT_ALL)
    # Add custom items.
    menu.add_separator()
    menu.add_item("Duplicate Text", MENU_MAX + 1)
    # Connect callback.
    menu.id_pressed.connect(_on_item_pressed)

func _on_item_pressed(id):
    if id == MENU_MAX + 1:
        add_text("\n" + get_parsed_text())

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 Window.visible property.

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.

Note: If threaded is enabled, this method returns a value for the loaded part of the document. Use is_ready or finished to determine whether document is fully loaded.

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.

Note: If threaded is enabled, this method returns a value for the loaded part of the document. Use is_ready or finished to determine whether document is fully loaded.

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.

Note: If threaded is enabled, this method returns a value for the loaded part of the document. Use is_ready or finished to determine whether document is fully loaded.

void install_effect ( Variant effect )

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

bool is_menu_visible ( ) const

Returns whether the menu is visible. Use this instead of get_menu().visible to improve performance (so the creation of the menu is avoided).

bool is_ready ( ) const

If threaded is enabled, returns true if the background thread has finished text processing, otherwise always return true.

void menu_option ( int option )

Executes a given action as defined in the MenuItems enum.

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 pop_all ( )

Terminates all tags opened by push_* methods.

void pop_context ( )

Terminates tags opened after the last push_context call (including context marker), or all tags if there's no context marker on the stack.

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_context ( )

Adds a context marker to the tag stack. See pop_context.

void push_customfx ( RichTextEffect effect, Dictionary env )

Adds a custom effect tag to the tag stack. The effect does not need to be in custom_effects. The environment is directly passed to the effect.

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, int font_size=0 )

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

Passing 0 to font_size will use the existing default font size.

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_hint ( String description )

Adds a [hint] tag to the tag stack. Same as BBCode [hint=something]{text}[/hint].

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 an italics font to the tag stack. This is the same as adding an [i] tag if not currently in a [b] tag.

void push_language ( String language )

Adds language code used for text shaping algorithm and Open-Type font features.

void push_list ( int level, ListType type, bool capitalize, String bullet="•" )

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, BitField<JustificationFlag> justification_flags=163, PackedFloat32Array tab_stops=PackedFloat32Array() )

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, int align_to_row=-1 )

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

void push_underline ( )

Adds a [u] tag to the tag stack.

bool remove_paragraph ( int paragraph )

Removes a paragraph of content from the label. Returns true if the paragraph exists.

The paragraph argument is the index of the paragraph to remove, it can take values in the interval [0, get_paragraph_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 scroll_to_selection ( )

Scrolls to the beginning of the current selection.

void select_all ( )

Select all the text.

If selection_enabled is false, no selection will occur.

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=1 )

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 = Color(1, 1, 1, 1)

The default text color.

Color font_outline_color = Color(1, 1, 1, 1)

The default tint of text outline.

Color font_selected_color = Color(0, 0, 0, 0)

The color of selected text, used when selection_enabled is true. If equal to Color(0, 0, 0, 0), it will be ignored.

Color font_shadow_color = Color(0, 0, 0, 0)

The color of the font's shadow.

Color selection_color = Color(0.1, 0.1, 1, 0.8)

The color of the selection box.

Color table_border = Color(0, 0, 0, 0)

The default cell border color.

Color table_even_row_bg = Color(0, 0, 0, 0)

The default background color for even rows.

Color table_odd_row_bg = Color(0, 0, 0, 0)

The default background color for odd rows.

int line_separation = 0

The vertical space between lines.

int outline_size = 0

The size of the text outline.

Note: If using a font with FontFile.multichannel_signed_distance_field enabled, its FontFile.msdf_pixel_range must be set to at least twice the value of outline_size for outline rendering to look correct. Otherwise, the outline may appear to be cut off earlier than intended.

int shadow_offset_x = 1

The horizontal offset of the font's shadow.

int shadow_offset_y = 1

The vertical offset of the font's shadow.

int shadow_outline_size = 1

The size of the shadow outline.

int table_h_separation = 3

The horizontal separation of elements in a table.

int table_v_separation = 3

The vertical separation of elements in a table.

int text_highlight_h_padding = 3

The horizontal padding around a highlighting and background color box.

int text_highlight_v_padding = 3

The vertical padding around a highlighting and background color box.

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.