Inherits: Control < CanvasItem < Node < Object
Label that displays rich text.
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: 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.
bool | bbcode_enabled | false |
String | bbcode_text | "" |
Array | custom_effects | [ ] |
bool | fit_content_height | false |
bool | meta_underlined | true |
bool | override_selected_font_color | false |
float | percent_visible | 1.0 |
bool | rect_clip_content |
true (parent override)
|
bool | scroll_active | true |
bool | scroll_following | false |
bool | selection_enabled | false |
int | tab_size | 4 |
String | text | "" |
int | visible_characters | -1 |
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 |
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.
Triggers when the mouse enters a meta tag.
enum Align:
enum ListType:
enum ItemType:
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.
Note: It is unadvised to use +=
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.
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.
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.
Default | true |
Setter | set_meta_underline(value) |
Getter | is_meta_underlined() |
If true
, the label underlines meta tags such as [url]{text}[/url]
.
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 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.
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.
Default | false |
Setter | set_scroll_follow(value) |
Getter | is_scroll_following() |
If true
, the window scrolls down to display new content automatically.
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.
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.
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.
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.
Clears the tag stack and sets bbcode_text to an empty string.
Returns the height of the content.
Returns the total number of newlines in the tag stack's text tags. Considers wrapped text as one line.
Returns the total number of characters from text tags. Does not include BBCodes.
Returns the vertical scrollbar.
Returns the number of visible lines.
Installs a custom effect. effect
should be a valid RichTextEffect.
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.
Terminates the current tag. Use after push_*
methods to close BBCodes manually. Does not need to follow add_*
methods.
Adds an [align]
tag based on the given align
value. See Align for possible values.
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.
Adds a [font]
tag with a bold italics font to the tag stack.
Adds a [cell]
tag to the tag stack. Must be inside a [table]
tag. See push_table for details.
Adds a [color]
tag to the tag stack.
Adds a [font]
tag to the tag stack. Overrides default fonts for its duration.
Adds an [indent]
tag to the tag stack. Multiplies level
by current tab_size to determine new margin length.
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.
Adds a [font]
tag with a monospace font to the tag stack.
Adds a [font]
tag with a normal font to the tag stack.
Adds a [s]
tag to the tag stack.
Adds a [table=columns]
tag to the tag stack.
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]
.
Scrolls the window's top line to match line
.
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.
© 2014–2020 Juan Linietsky, Ariel Manzur, Godot Engine contributors
Licensed under the MIT License.
https://docs.godotengine.org/en/3.2/classes/class_richtextlabel.html