Skip to content
Download
API reference

TextParagraph

Inherits: Shared < Object

Holds a paragraph of text.

Abstraction over TextShaping for handling a single paragraph of text.

TypeNameDefault
HorizontalAlignmentalignment0
TextShaping.LineBreakFlagbreak_flags3
Stringcustom_punctuation""
TextShaping.Directiondirection0
Stringellipsis_char"…"
TextShaping.JustificationFlagjustification_flags163
floatline_spacing0.0
intmax_lines_visible-1
TextShaping.Orientationorientation0
boolpreserve_controlfalse
boolpreserve_invalidtrue
TextShaping.OverrunBehaviortext_overrun_behavior0
floatwidth-1.0
ReturnsMethod
booladd_object(key, size, inline_align, length, baseline)
booladd_string(text, font, font_size, language, meta)
voidclear()
voidclear_dropcap()
voiddraw(canvas, pos, color, dc_color, oversampling)
voiddraw_dropcap(canvas, pos, color, oversampling)
voiddraw_dropcap_outline(canvas, pos, outline_size, color, oversampling)
voiddraw_line(canvas, pos, line, color, oversampling)
voiddraw_line_outline(canvas, pos, line, outline_size, color, oversampling)
voiddraw_outline(canvas, pos, outline_size, color, dc_color, oversampling)
TextParagraphduplicate()
intget_dropcap_lines()
RIDget_dropcap_rid()
Vector2get_dropcap_size()
TextShaping.Directionget_inferred_direction()
floatget_line_ascent(line)
intget_line_count()
floatget_line_descent(line)
Rect2get_line_object_rect(line, key)
Arrayget_line_objects(line)
Vector2iget_line_range(line)
RIDget_line_rid(line)
Vector2get_line_size(line)
floatget_line_underline_position(line)
floatget_line_underline_thickness(line)
floatget_line_width(line)
Vector2get_non_wrapped_size()
Vector2iget_range()
RIDget_rid()
Vector2get_size()
boolhas_object(key)
inthit_test(coords)
boolresize_object(key, size, inline_align, baseline)
voidset_bidi_override(override)
boolset_dropcap(text, font, font_size, dropcap_margins, language)
voidtab_align(tab_stops)

HorizontalAlignment alignment = 0

Setter/getter: set_alignment(), get_alignment()

Paragraph horizontal alignment.

TextShaping.LineBreakFlag break_flags = 3

Setter/getter: set_break_flags(), get_break_flags()

Line breaking rules. For more info see TextShaping.

String custom_punctuation = ""

Setter/getter: set_custom_punctuation(), get_custom_punctuation()

Custom punctuation character list, used for word breaking. If set to empty string, server defaults are used.

TextShaping.Direction direction = 0

Setter/getter: set_direction(), get_direction()

Text writing direction.

String ellipsis_char = "…"

Setter/getter: set_ellipsis_char(), get_ellipsis_char()

Ellipsis character used for text clipping.

TextShaping.JustificationFlag justification_flags = 163

Setter/getter: set_justification_flags(), get_justification_flags()

Line fill alignment rules.

float line_spacing = 0.0

Setter/getter: set_line_spacing(), get_line_spacing()

Additional vertical spacing between lines (in pixels), spacing is added to line descent. This value can be negative.

int max_lines_visible = -1

Setter/getter: set_max_lines_visible(), get_max_lines_visible()

Limits the lines of text shown.

TextShaping.Orientation orientation = 0

Setter/getter: set_orientation(), get_orientation()

Text orientation.

bool preserve_control = false

Setter/getter: set_preserve_control(), get_preserve_control()

If set to true text will display control characters.

bool preserve_invalid = true

Setter/getter: set_preserve_invalid(), get_preserve_invalid()

If set to true text will display invalid characters.

TextShaping.OverrunBehavior text_overrun_behavior = 0

Setter/getter: set_text_overrun_behavior(), get_text_overrun_behavior()

The clipping behavior when the text exceeds the paragraph’s set width.

float width = -1.0

Setter/getter: set_width(), get_width()

Paragraph width.

bool add_object(key: Variant, size: Vector2, inline_align: InlineAlignment = 5, length: int = 1, baseline: float = 0.0)

Adds inline object to the text buffer, key must be unique. In the text, object is represented as length object replacement characters.

bool add_string(text: String, font: Font, font_size: int, language: String = "", meta: Variant = null)

Adds text span and font to draw it.

void clear()

Clears text paragraph (removes text and inline objects).

void clear_dropcap()

Removes dropcap.

void draw(canvas: RID, pos: Vector2, color: Color = Color(1, 1, 1, 1), dc_color: Color = Color(1, 1, 1, 1), oversampling: float = 0.0) const

Draw all lines of the text and drop cap into a canvas item at a given position, with color. pos specifies the top left corner of the bounding box. If oversampling is greater than zero, it is used as font oversampling factor, otherwise viewport oversampling settings are used.

void draw_dropcap(canvas: RID, pos: Vector2, color: Color = Color(1, 1, 1, 1), oversampling: float = 0.0) const

Draw drop cap into a canvas item at a given position, with color. pos specifies the top left corner of the bounding box. If oversampling is greater than zero, it is used as font oversampling factor, otherwise viewport oversampling settings are used.

void draw_dropcap_outline(canvas: RID, pos: Vector2, outline_size: int = 1, color: Color = Color(1, 1, 1, 1), oversampling: float = 0.0) const

Draw drop cap outline into a canvas item at a given position, with color. pos specifies the top left corner of the bounding box. If oversampling is greater than zero, it is used as font oversampling factor, otherwise viewport oversampling settings are used.

void draw_line(canvas: RID, pos: Vector2, line: int, color: Color = Color(1, 1, 1, 1), oversampling: float = 0.0) const

Draw single line of text into a canvas item at a given position, with color. pos specifies the top left corner of the bounding box. If oversampling is greater than zero, it is used as font oversampling factor, otherwise viewport oversampling settings are used.

void draw_line_outline(canvas: RID, pos: Vector2, line: int, outline_size: int = 1, color: Color = Color(1, 1, 1, 1), oversampling: float = 0.0) const

Draw outline of the single line of text into a canvas item at a given position, with color. pos specifies the top left corner of the bounding box. If oversampling is greater than zero, it is used as font oversampling factor, otherwise viewport oversampling settings are used.

void draw_outline(canvas: RID, pos: Vector2, outline_size: int = 1, color: Color = Color(1, 1, 1, 1), dc_color: Color = Color(1, 1, 1, 1), oversampling: float = 0.0) const

Draw outlines of all lines of the text and drop cap into a canvas item at a given position, with color. pos specifies the top left corner of the bounding box. If oversampling is greater than zero, it is used as font oversampling factor, otherwise viewport oversampling settings are used.

TextParagraph duplicate() const

Duplicates this TextParagraph.

int get_dropcap_lines() const

Returns number of lines used by dropcap.

RID get_dropcap_rid() const

Returns drop cap text buffer RID.

Vector2 get_dropcap_size() const

Returns drop cap bounding box size.

TextShaping.Direction get_inferred_direction() const

Returns the text writing direction inferred by the BiDi algorithm.

float get_line_ascent(line: int) const

Returns the text line ascent (number of pixels above the baseline for horizontal layout or to the left of baseline for vertical).

int get_line_count() const

Returns number of lines in the paragraph.

float get_line_descent(line: int) const

Returns the text line descent (number of pixels below the baseline for horizontal layout or to the right of baseline for vertical).

Rect2 get_line_object_rect(line: int, key: Variant) const

Returns bounding rectangle of the inline object.

Array get_line_objects(line: int) const

Returns array of inline objects in the line.

Vector2i get_line_range(line: int) const

Returns character range of the line.

RID get_line_rid(line: int) const

Returns TextShaping line buffer RID.

Vector2 get_line_size(line: int) const

Returns size of the bounding box of the line of text. Returned size is rounded up.

float get_line_underline_position(line: int) const

Returns pixel offset of the underline below the baseline.

float get_line_underline_thickness(line: int) const

Returns thickness of the underline.

float get_line_width(line: int) const

Returns width (for horizontal layout) or height (for vertical) of the line of text.

Vector2 get_non_wrapped_size() const

Returns the size of the bounding box of the paragraph, without line breaks.

Vector2i get_range() const

Returns the character range of the paragraph.

RID get_rid() const

Returns TextShaping full string buffer RID.

Vector2 get_size() const

Returns the size of the bounding box of the paragraph.

bool has_object(key: Variant) const

Returns true if an object with key is embedded in this shaped text buffer.

int hit_test(coords: Vector2) const

Returns caret character offset at the specified coordinates. This function always returns a valid position.

bool resize_object(key: Variant, size: Vector2, inline_align: InlineAlignment = 5, baseline: float = 0.0)

Sets new size and alignment of embedded object.

void set_bidi_override(override: Array)

Overrides BiDi for the structured text.

Override ranges should cover full source text without overlaps. BiDi algorithm will be used on each range separately.

bool set_dropcap(text: String, font: Font, font_size: int, dropcap_margins: Rect2 = Rect2(0, 0, 0, 0), language: String = "")

Sets drop cap, overrides previously set drop cap. Drop cap (dropped capital) is a decorative element at the beginning of a paragraph that is larger than the rest of the text.

void tab_align(tab_stops: []f32)

Aligns paragraph to the given tab-stops.