7adf4cc9b5
For the time being we don't support writing a description for those, preferring having all details in the method's description. Using self-closing tags saves half the lines, and prevents contributors from thinking that they should write the argument or return documentation there.
274 lines
14 KiB
XML
274 lines
14 KiB
XML
<?xml version="1.0" encoding="UTF-8" ?>
|
||
<class name="Font" inherits="Resource" version="4.0">
|
||
<brief_description>
|
||
Font class is set of font data sources used to draw text.
|
||
</brief_description>
|
||
<description>
|
||
Font contains a set of glyphs to represent Unicode characters, as well as the ability to draw it with variable width, ascent, descent and kerning.
|
||
[b]Note:[/b] A character is a symbol that represents an item (letter, digit etc.) in an abstract way.
|
||
[b]Note:[/b] A glyph is a bitmap or shape used to draw a one or more characters in a context-dependent manner. Glyph indices are bound to the specific font data source.
|
||
[b]Note:[/b] If a non of the font data sources contain glyphs for a character used in a string, the character in question will be replaced with a box displaying its hexadecimal code.
|
||
[codeblocks]
|
||
[gdscript]
|
||
var font = Font.new()
|
||
font.add_data(load("res://BarlowCondensed-Bold.ttf"))
|
||
$"Label".set("custom_fonts/font", font)
|
||
$"Label".set("custom_fonts/font_size", 64)
|
||
[/gdscript]
|
||
[csharp]
|
||
var font = new Font();
|
||
font.AddData(ResourceLoader.Load<FontData>("res://BarlowCondensed-Bold.ttf"));
|
||
GetNode("Label").Set("custom_fonts/font", font);
|
||
GetNode("Label").Set("custom_font_sizes/font_size", 64);
|
||
[/csharp]
|
||
[/codeblocks]
|
||
To control font substitution priority use [FontData] language and script support.
|
||
Use language overrides to use same [Font] stack for multiple languages:
|
||
[codeblocks]
|
||
[gdscript]
|
||
# Use Naskh font for Persian and Nastaʼlīq font for Urdu text.
|
||
var font_data_fa = load("res://NotoNaskhArabicUI_Regular.ttf");
|
||
font_data_fa.set_language_support_override("fa", true);
|
||
font_data_fa.set_language_support_override("ur", false);
|
||
|
||
var font_data_ur = load("res://NotoNastaliqUrdu_Regular.ttf");
|
||
font_data_ur.set_language_support_override("fa", false);
|
||
font_data_ur.set_language_support_override("ur", true);
|
||
[/gdscript]
|
||
[csharp]
|
||
// Use Naskh font for Persian and Nastaʼlīq font for Urdu text.
|
||
var fontDataFA = ResourceLoader.Load<FontData>("res://NotoNaskhArabicUI_Regular.ttf");
|
||
fontDataFA.SetLanguageSupportOverride("fa", true);
|
||
fontDataFA.SetLanguageSupportOverride("ur", false);
|
||
|
||
var fontDataUR = ResourceLoader.Load<FontData>("res://NotoNastaliqUrdu_Regular.ttf");
|
||
fontDataUR.SetLanguageSupportOverride("fa", false);
|
||
fontDataUR.SetLanguageSupportOverride("ur", true);
|
||
[/csharp]
|
||
[/codeblocks]
|
||
Use script overrides to specify supported scripts for bitmap font or for less common scripts not directly supported by TrueType format:
|
||
[codeblocks]
|
||
[gdscript]
|
||
# Use specified font for Egyptian hieroglyphs.
|
||
var font_data = load("res://unifont.ttf");
|
||
font_data.set_script_support_override("Egyp", true);
|
||
[/gdscript]
|
||
[csharp]
|
||
// Use specified font for Egyptian hieroglyphs.
|
||
var fontData = ResourceLoader.Load<FontData>("res://unifont.ttf");
|
||
fontData.SetScriptSupportOverride("Egyp", true);
|
||
[/csharp]
|
||
[/codeblocks]
|
||
</description>
|
||
<tutorials>
|
||
</tutorials>
|
||
<methods>
|
||
<method name="add_data">
|
||
<return type="void" />
|
||
<argument index="0" name="data" type="FontData" />
|
||
<description>
|
||
Add font data source to the set.
|
||
</description>
|
||
</method>
|
||
<method name="draw_char" qualifiers="const">
|
||
<return type="float" />
|
||
<argument index="0" name="canvas_item" type="RID" />
|
||
<argument index="1" name="pos" type="Vector2" />
|
||
<argument index="2" name="char" type="int" />
|
||
<argument index="3" name="next" type="int" default="0" />
|
||
<argument index="4" name="size" type="int" default="-1" />
|
||
<argument index="5" name="modulate" type="Color" default="Color(1, 1, 1, 1)" />
|
||
<argument index="6" name="outline_size" type="int" default="0" />
|
||
<argument index="7" name="outline_modulate" type="Color" default="Color(1, 1, 1, 0)" />
|
||
<description>
|
||
Draw a single Unicode character [code]char[/code] into a canvas item using the font, at a given position, with [code]modulate[/code] color, and optionally kerning if [code]next[/code] is passed. [code]position[/code] specifies the baseline, not the top. To draw from the top, [i]ascent[/i] must be added to the Y axis.
|
||
[b]Note:[/b] Do not use this function to draw strings character by character, use [method draw_string] or [TextLine] instead.
|
||
</description>
|
||
</method>
|
||
<method name="draw_multiline_string" qualifiers="const">
|
||
<return type="void" />
|
||
<argument index="0" name="canvas_item" type="RID" />
|
||
<argument index="1" name="pos" type="Vector2" />
|
||
<argument index="2" name="text" type="String" />
|
||
<argument index="3" name="align" type="int" enum="HAlign" default="0" />
|
||
<argument index="4" name="width" type="float" default="-1" />
|
||
<argument index="5" name="max_lines" type="int" default="-1" />
|
||
<argument index="6" name="size" type="int" default="-1" />
|
||
<argument index="7" name="modulate" type="Color" default="Color(1, 1, 1, 1)" />
|
||
<argument index="8" name="outline_size" type="int" default="0" />
|
||
<argument index="9" name="outline_modulate" type="Color" default="Color(1, 1, 1, 0)" />
|
||
<argument index="10" name="flags" type="int" default="51" />
|
||
<description>
|
||
Breaks [code]text[/code] to the lines using rules specified by [code]flags[/code] and draws it into a canvas item using the font, at a given position, with [code]modulate[/code] color, optionally clipping the width and aligning horizontally. [code]position[/code] specifies the baseline of the first line, not the top. To draw from the top, [i]ascent[/i] must be added to the Y axis.
|
||
See also [method CanvasItem.draw_multiline_string].
|
||
</description>
|
||
</method>
|
||
<method name="draw_string" qualifiers="const">
|
||
<return type="void" />
|
||
<argument index="0" name="canvas_item" type="RID" />
|
||
<argument index="1" name="pos" type="Vector2" />
|
||
<argument index="2" name="text" type="String" />
|
||
<argument index="3" name="align" type="int" enum="HAlign" default="0" />
|
||
<argument index="4" name="width" type="float" default="-1" />
|
||
<argument index="5" name="size" type="int" default="-1" />
|
||
<argument index="6" name="modulate" type="Color" default="Color(1, 1, 1, 1)" />
|
||
<argument index="7" name="outline_size" type="int" default="0" />
|
||
<argument index="8" name="outline_modulate" type="Color" default="Color(1, 1, 1, 0)" />
|
||
<argument index="9" name="flags" type="int" default="3" />
|
||
<description>
|
||
Draw [code]text[/code] into a canvas item using the font, at a given position, with [code]modulate[/code] color, optionally clipping the width and aligning horizontally. [code]position[/code] specifies the baseline, not the top. To draw from the top, [i]ascent[/i] must be added to the Y axis.
|
||
See also [method CanvasItem.draw_string].
|
||
</description>
|
||
</method>
|
||
<method name="get_ascent" qualifiers="const">
|
||
<return type="float" />
|
||
<argument index="0" name="size" type="int" default="-1" />
|
||
<description>
|
||
Returns the average font ascent (number of pixels above the baseline).
|
||
[b]Note:[/b] 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).
|
||
</description>
|
||
</method>
|
||
<method name="get_char_size" qualifiers="const">
|
||
<return type="Vector2" />
|
||
<argument index="0" name="char" type="int" />
|
||
<argument index="1" name="next" type="int" default="0" />
|
||
<argument index="2" name="size" type="int" default="-1" />
|
||
<description>
|
||
Returns the size of a character, optionally taking kerning into account if the next character is provided.
|
||
[b]Note:[/b] Do not use this function to calculate width of the string character by character, use [method get_string_size] or [TextLine] instead. The height returned is the font height (see also [method get_height]) and has no relation to the glyph height.
|
||
</description>
|
||
</method>
|
||
<method name="get_data" qualifiers="const">
|
||
<return type="FontData" />
|
||
<argument index="0" name="idx" type="int" />
|
||
<description>
|
||
Returns the font data source at index [code]idx[/code]. If the index does not exist, returns [code]null[/code].
|
||
</description>
|
||
</method>
|
||
<method name="get_data_count" qualifiers="const">
|
||
<return type="int" />
|
||
<description>
|
||
Returns the number of font data sources.
|
||
</description>
|
||
</method>
|
||
<method name="get_descent" qualifiers="const">
|
||
<return type="float" />
|
||
<argument index="0" name="size" type="int" default="-1" />
|
||
<description>
|
||
Returns the average font descent (number of pixels below the baseline).
|
||
[b]Note:[/b] 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).
|
||
</description>
|
||
</method>
|
||
<method name="get_height" qualifiers="const">
|
||
<return type="float" />
|
||
<argument index="0" name="size" type="int" default="-1" />
|
||
<description>
|
||
Returns the total average font height (ascent plus descent) in pixels.
|
||
[b]Note:[/b] 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).
|
||
</description>
|
||
</method>
|
||
<method name="get_multiline_string_size" qualifiers="const">
|
||
<return type="Vector2" />
|
||
<argument index="0" name="text" type="String" />
|
||
<argument index="1" name="width" type="float" default="-1" />
|
||
<argument index="2" name="size" type="int" default="-1" />
|
||
<argument index="3" name="flags" type="int" default="48" />
|
||
<description>
|
||
Returns the size of a bounding box of a string broken into the lines, taking kerning and advance into account.
|
||
See also [method draw_multiline_string].
|
||
</description>
|
||
</method>
|
||
<method name="get_spacing" qualifiers="const">
|
||
<return type="int" />
|
||
<argument index="0" name="type" type="int" />
|
||
<description>
|
||
Returns the spacing for the given [code]type[/code] (see [enum SpacingType]).
|
||
</description>
|
||
</method>
|
||
<method name="get_string_size" qualifiers="const">
|
||
<return type="Vector2" />
|
||
<argument index="0" name="text" type="String" />
|
||
<argument index="1" name="size" type="int" default="-1" />
|
||
<description>
|
||
Returns the size of a bounding box of a string, taking kerning and advance into account.
|
||
[b]Note:[/b] Real height of the string is context-dependent and can be significantly different from the value returned by [method get_height].
|
||
See also [method draw_string].
|
||
</description>
|
||
</method>
|
||
<method name="get_supported_chars" qualifiers="const">
|
||
<return type="String" />
|
||
<description>
|
||
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.
|
||
</description>
|
||
</method>
|
||
<method name="get_underline_position" qualifiers="const">
|
||
<return type="float" />
|
||
<argument index="0" name="size" type="int" default="-1" />
|
||
<description>
|
||
Return average pixel offset of the underline below the baseline.
|
||
[b]Note:[/b] 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.
|
||
</description>
|
||
</method>
|
||
<method name="get_underline_thickness" qualifiers="const">
|
||
<return type="float" />
|
||
<argument index="0" name="size" type="int" default="-1" />
|
||
<description>
|
||
Return average thickness of the underline.
|
||
[b]Note:[/b] 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.
|
||
</description>
|
||
</method>
|
||
<method name="has_char" qualifiers="const">
|
||
<return type="bool" />
|
||
<argument index="0" name="char" type="int" />
|
||
<description>
|
||
Return [code]true[/code] if a Unicode [code]char[/code] is available in the font.
|
||
</description>
|
||
</method>
|
||
<method name="remove_data">
|
||
<return type="void" />
|
||
<argument index="0" name="idx" type="int" />
|
||
<description>
|
||
Removes the font data source at index [code]idx[/code]. If the index does not exist, nothing happens.
|
||
</description>
|
||
</method>
|
||
<method name="set_data">
|
||
<return type="void" />
|
||
<argument index="0" name="idx" type="int" />
|
||
<argument index="1" name="data" type="FontData" />
|
||
<description>
|
||
Sets the font data source at index [code]idx[/code]. If the index does not exist, nothing happens.
|
||
</description>
|
||
</method>
|
||
<method name="set_spacing">
|
||
<return type="void" />
|
||
<argument index="0" name="type" type="int" />
|
||
<argument index="1" name="value" type="int" />
|
||
<description>
|
||
Sets the spacing for [code]type[/code] (see [enum SpacingType]) to [code]value[/code] in pixels (not relative to the font size).
|
||
</description>
|
||
</method>
|
||
<method name="update_changes">
|
||
<return type="void" />
|
||
<description>
|
||
After editing a font (changing data sources, etc.). Call this function to propagate changes to controls that might use it.
|
||
</description>
|
||
</method>
|
||
</methods>
|
||
<members>
|
||
<member name="extra_spacing_bottom" type="int" setter="set_spacing" getter="get_spacing" default="0">
|
||
Extra spacing at the bottom of the line in pixels.
|
||
</member>
|
||
<member name="extra_spacing_top" type="int" setter="set_spacing" getter="get_spacing" default="0">
|
||
Extra spacing at the top of the line in pixels.
|
||
</member>
|
||
</members>
|
||
<constants>
|
||
<constant name="SPACING_TOP" value="0" enum="SpacingType">
|
||
Spacing at the top of the line.
|
||
</constant>
|
||
<constant name="SPACING_BOTTOM" value="1" enum="SpacingType">
|
||
Spacing at the bottom of the line.
|
||
</constant>
|
||
</constants>
|
||
</class>
|