Class Font

Abstract base class for fonts and font variations.

Inheritance: Resource

RefCounted

Object

Font

Derived: FontFile

FontVariation

SystemFont

Remarks

Abstract base class for different font types. It has methods for drawing text and font character introspection.

Properties

fallbacks

Array of fallback Fonts to use as a substitute if a glyph is not found in this current Font.

If this array is empty in a FontVariation, the base_font's fallbacks are used instead.

var fallbacks : Font[] = []

Property Value

Font[]

Remarks

void set_fallbacks(Font[] value)
Font[] get_fallbacks

Methods

draw_char(RID, Vector2, int, int, Color)

Qualifiers: const

Draw a single Unicode character char into a canvas item using the font, at a given position, with modulate color. pos specifies the baseline, not the top. To draw from the top, ascent must be added to the Y axis.

Note: Do not use this function to draw strings character by character, use Font.draw_string or TextLine instead.

float draw_char(RID canvas_item, Vector2 pos, int char, int font_size, Color modulate)

Parameters

canvas_item RID
pos Vector2
char int
font_size int
modulate Color

draw_char_outline(RID, Vector2, int, int, int, Color)

Qualifiers: const

Draw a single Unicode character char outline into a canvas item using the font, at a given position, with modulate color and size outline size. pos specifies the baseline, not the top. To draw from the top, ascent must be added to the Y axis.

Note: Do not use this function to draw strings character by character, use Font.draw_string or TextLine instead.

float draw_char_outline(RID canvas_item, Vector2 pos, int char, int font_size, int size, Color modulate)

Parameters

canvas_item RID
pos Vector2
char int
font_size int
size int
modulate Color

draw_multiline_string(RID, Vector2, String, int, float, int, int, Color, int, int, int, int)

Qualifiers: const

Breaks text into lines using rules specified by brk_flags and draws it into a canvas item using the font, at a given position, with modulate color, optionally clipping the width and aligning horizontally. pos specifies the baseline of the first line, not the top. To draw from the top, ascent must be added to the Y axis.

See also CanvasItem.draw_multiline_string.

void draw_multiline_string(RID canvas_item, Vector2 pos, String text, int alignment, float width, int font_size, int max_lines, Color modulate, int brk_flags, int justification_flags, int direction, int orientation)

Parameters

canvas_item RID
pos Vector2
text String
alignment int
width float
font_size int
max_lines int
modulate Color
brk_flags int
justification_flags int
direction int
orientation int

draw_multiline_string_outline(RID, Vector2, String, int, float, int, int, int, Color, int, int, int, int)

Qualifiers: const

Breaks text to the lines using rules specified by brk_flags and draws text outline into a canvas item using the font, at a given position, with modulate color and size outline size, optionally clipping the width and aligning horizontally. pos specifies the baseline of the first line, not the top. To draw from the top, ascent must be added to the Y axis.

See also CanvasItem.draw_multiline_string_outline.

void draw_multiline_string_outline(RID canvas_item, Vector2 pos, String text, int alignment, float width, int font_size, int max_lines, int size, Color modulate, int brk_flags, int justification_flags, int direction, int orientation)

Parameters

canvas_item RID
pos Vector2
text String
alignment int
width float
font_size int
max_lines int
size int
modulate Color
brk_flags int
justification_flags int
direction int
orientation int

draw_string(RID, Vector2, String, int, float, int, Color, int, int, int)

Qualifiers: const

Draw text into a canvas item using the font, at a given position, with modulate color, optionally clipping the width and aligning horizontally. pos specifies the baseline, not the top. To draw from the top, ascent must be added to the Y axis.

Parameters

canvas_item RID
pos Vector2
text String
alignment int
width float
font_size int
modulate Color
justification_flags int
direction int
orientation int

draw_string_outline(RID, Vector2, String, int, float, int, int, Color, int, int, int)

Qualifiers: const

Draw text outline into a canvas item using the font, at a given position, with modulate color and size outline size, optionally clipping the width and aligning horizontally. pos specifies the baseline, not the top. To draw from the top, ascent must be added to the Y axis.

See also CanvasItem.draw_string_outline.

void draw_string_outline(RID canvas_item, Vector2 pos, String text, int alignment, float width, int font_size, int size, Color modulate, int justification_flags, int direction, int orientation)

Parameters

canvas_item RID
pos Vector2
text String
alignment int
width float
font_size int
size int
modulate Color
justification_flags int
direction int
orientation int

find_variation(Dictionary, int, float, Transform2D, int, int, int, int, float)

Qualifiers: const

Returns TextServer RID of the font cache for specific variation.

RID find_variation(Dictionary variation_coordinates, int face_index, float strength, Transform2D transform, int spacing_top, int spacing_bottom, int spacing_space, int spacing_glyph, float baseline_offset)

Parameters

variation_coordinates Dictionary
face_index int
strength float
transform Transform2D
spacing_top int
spacing_bottom int
spacing_space int
spacing_glyph int
baseline_offset float

get_ascent(int)

Qualifiers: const

Returns the average font ascent (number of pixels above the baseline).

Note: Real ascent of the string is context-dependent and can be significantly different from the value returned by this function. Use it only as rough estimate (e.g. as the ascent of empty line).

float get_ascent(int font_size)

Parameters

font_size int

get_char_size(int, int)

Qualifiers: const

Returns the size of a character. Does not take kerning into account.

Note: Do not use this function to calculate width of the string character by character, use Font.get_string_size or TextLine instead. The height returned is the font height (see also Font.get_height) and has no relation to the glyph height.

Vector2 get_char_size(int char, int font_size)

Parameters

char int
font_size int

get_descent(int)

Qualifiers: const

Returns the average font descent (number of pixels below the baseline).

Note: Real descent of the string is context-dependent and can be significantly different from the value returned by this function. Use it only as rough estimate (e.g. as the descent of empty line).

float get_descent(int font_size)

Parameters

font_size int

get_face_count

Qualifiers: const

Returns number of faces in the TrueType / OpenType collection.

int get_face_count

get_font_name

Qualifiers: const

Returns font family name.

String get_font_name

get_font_stretch

Qualifiers: const

Returns font stretch amount, compared to a normal width. A percentage value between 50% and 200%.

int get_font_stretch

get_font_style

Qualifiers: const

Returns font style flags, see FontStyle.

int get_font_style

get_font_style_name

Qualifiers: const

Returns font style name.

String get_font_style_name

get_font_weight

Qualifiers: const

Returns weight (boldness) of the font. A value in the 100...999 range, normal font weight is 400, bold font weight is 700.

int get_font_weight

get_height(int)

Qualifiers: const

Returns the total average font height (ascent plus descent) in pixels.

Note: Real height of the string is context-dependent and can be significantly different from the value returned by this function. Use it only as rough estimate (e.g. as the height of empty line).

float get_height(int font_size)

Parameters

font_size int

get_multiline_string_size(String, int, float, int, int, int, int, int, int)

Qualifiers: const

Returns the size of a bounding box of a string broken into the lines, taking kerning and advance into account.

Parameters

text String
alignment int
width float
font_size int
max_lines int
brk_flags int
justification_flags int
direction int
orientation int

get_opentype_features

Qualifiers: const

Returns a set of OpenType feature tags. More info: OpenType feature tags.

Dictionary get_opentype_features

get_ot_name_strings

Qualifiers: const

Returns Dictionary with OpenType font name strings (localized font names, version, description, license information, sample text, etc.).

Dictionary get_ot_name_strings

get_rids

Qualifiers: const

Returns Array of valid Font RIDs, which can be passed to the TextServer methods.

RID[] get_rids

get_spacing(int)

Qualifiers: const

Returns the spacing for the given type (see SpacingType).

int get_spacing(int spacing)

Parameters

spacing int

get_string_size(String, int, float, int, int, int, int)

Qualifiers: const

Returns the size of a bounding box of a single-line string, taking kerning, advance and subpixel positioning into account. See also Font.get_multiline_string_size and Font.draw_string.

For example, to get the string size as displayed by a single-line Label, use:

gdscript
C#

var string_size = $Label.get_theme_font("font").get_string_size($Label.text, HORIZONTAL_ALIGNMENT_LEFT, -1, $Label.get_theme_font_size("font_size"))

Label label = GetNode<Label>("Label");
Vector2 stringSize = label.GetThemeFont("font").GetStringSize(label.Text, HorizontalAlignment.Left, -1, label.GetThemeFontSize("font_size"));

Note: Since kerning, advance and subpixel positioning are taken into account by Font.get_string_size, using separate Font.get_string_size calls on substrings of a string then adding the results together will return a different result compared to using a single Font.get_string_size call on the full string.

Note: Real height of the string is context-dependent and can be significantly different from the value returned by Font.get_height.

Vector2 get_string_size(String text, int alignment, float width, int font_size, int justification_flags, int direction, int orientation)

Parameters

text String
alignment int
width float
font_size int
justification_flags int
direction int
orientation int

get_supported_chars

Qualifiers: const

Returns a string containing all the characters available in the font.

If a given character is included in more than one font data source, it appears only once in the returned string.

String get_supported_chars

get_supported_feature_list

Qualifiers: const

Returns list of OpenType features supported by font.

Dictionary get_supported_feature_list

get_supported_variation_list

Qualifiers: const

Returns list of supported variation coordinates, each coordinate is returned as tag: Vector3i(min_value,max_value,default_value).

Font variations allow for continuous change of glyph characteristics along some given design axis, such as weight, width or slant.

To print available variation axes of a variable font:

var fv = FontVariation.new()
fv.base_font = load("res://RobotoFlex.ttf")
var variation_list = fv.get_supported_variation_list()
for tag in variation_list:
    var name = TextServerManager.get_primary_interface().tag_to_name(tag)
    var values = variation_list[tag]
    print("variation axis: %s (%d)\n\tmin, max, default: %s" % [name, tag, values])

Note: To set and get variation coordinates of a FontVariation, use variation_opentype.

Dictionary get_supported_variation_list

get_underline_position(int)

Qualifiers: const

Returns average pixel offset of the underline below the baseline.

Note: Real underline position of the string is context-dependent and can be significantly different from the value returned by this function. Use it only as rough estimate.

float get_underline_position(int font_size)

Parameters

font_size int

get_underline_thickness(int)

Qualifiers: const

Returns average thickness of the underline.

Note: Real underline thickness of the string is context-dependent and can be significantly different from the value returned by this function. Use it only as rough estimate.

float get_underline_thickness(int font_size)

Parameters

font_size int

has_char(int)

Qualifiers: const

Returns true if a Unicode char is available in the font.

bool has_char(int char)

Parameters

char int

is_language_supported(String)

Qualifiers: const

Returns true, if font supports given language (ISO 639 code).

bool is_language_supported(String language)

Parameters

language String

is_script_supported(String)

Qualifiers: const

Returns true, if font supports given script (ISO 15924 code).

bool is_script_supported(String script)

Parameters

script String

set_cache_capacity(int, int)

Sets LRU cache capacity for draw_* methods.

void set_cache_capacity(int single_line, int multi_line)

Parameters

single_line int
multi_line int

Table of Contents

Class Font

Remarks

Properties

fallbacks

Property Value

Remarks

Methods

draw_char(RID, Vector2, int, int, Color)

Parameters

draw_char_outline(RID, Vector2, int, int, int, Color)

Parameters

draw_multiline_string(RID, Vector2, String, int, float, int, int, Color, int, int, int, int)

Parameters

draw_multiline_string_outline(RID, Vector2, String, int, float, int, int, int, Color, int, int, int, int)

Parameters

draw_string(RID, Vector2, String, int, float, int, Color, int, int, int)

Parameters

draw_string_outline(RID, Vector2, String, int, float, int, int, Color, int, int, int)

Parameters

find_variation(Dictionary, int, float, Transform2D, int, int, int, int, float)

Parameters

get_ascent(int)

Parameters

get_char_size(int, int)

Parameters

get_descent(int)

Parameters

get_face_count

get_font_name

get_font_stretch

get_font_style

get_font_style_name

get_font_weight

get_height(int)

Parameters

get_multiline_string_size(String, int, float, int, int, int, int, int, int)

Parameters

get_opentype_features

get_ot_name_strings

get_rids

get_spacing(int)

Parameters

get_string_size(String, int, float, int, int, int, int)

Parameters

get_supported_chars

get_supported_feature_list

get_supported_variation_list

get_underline_position(int)

Parameters

get_underline_thickness(int)

Parameters

has_char(int)

Parameters

is_language_supported(String)

Parameters

is_script_supported(String)

Parameters

set_cache_capacity(int, int)

Parameters