<?xml version="1.0" encoding="UTF-8" ?>
<class name="TLShapedString" inherits="Resource" category="Core" version="3.2">
	<brief_description>
		Holds shaped line of plain text.
	</brief_description>
	<description>
		Note 1: Code points, Characters, Clusters and Glyphs

		- A code point is a single encoding UTF-16 unit (Unicode character or half of the surrogate pair).
		- A character is a full Unicode character.
		- A grapheme cluster is the abstract unit of a writing system (a letter, a digit, or punctuation).
		- A glyph is a shape used to render a character or a sequence of characters.

		In general, code point, characters, clusters and glyphs do not have one-to-one correspondence.

		Note 2: Encoding
	
		TLShapedString uses UTF-16 encoding, all positions accepted and returned by TLShapedString function are measured in UTF-16 code points.
	</description>
	<tutorials>
	</tutorials>
	<methods>
		<method name="add_sstring">
			<return type="void">
			</return>
			<argument index="0" name="text" type="TLShapedString">
			</argument>
			<description>
				Appends shaped string.
			</description>
		</method>
		<method name="add_text">
			<return type="void">
			</return>
			<argument index="0" name="text" type="String">
			</argument>
			<description>
				Appends plain text string.
			</description>
		</method>
		<method name="add_utf16">
			<return type="void">
			</return>
			<argument index="0" name="text" type="PoolByteArray">
			</argument>
			<description>
			</description>
		</method>
		<method name="add_utf32">
			<return type="void">
			</return>
			<argument index="0" name="text" type="PoolByteArray">
			</argument>
			<description>
			</description>
		</method>
		<method name="add_utf8">
			<return type="void">
			</return>
			<argument index="0" name="text" type="PoolByteArray">
			</argument>
			<description>
			</description>
		</method>
		<method name="break_jst" qualifiers="const">
			<return type="Array">
			</return>
			<description>
			</description>
		</method>
		<method name="break_lines" qualifiers="const">
			<return type="Array">
			</return>
			<argument index="0" name="width" type="float">
			</argument>
			<argument index="1" name="flags" type="int">
			</argument>
			<description>
				Breaks text into lines that fit within a specified width.
				Returns [Array] of line boundaries.
			</description>
		</method>
		<method name="break_words" qualifiers="const">
			<return type="Array">
			</return>
			<description>
				Breaks text into words.
				Returns [Array] of word boundaries.
			</description>
		</method>
		<method name="char_count" qualifiers="const">
			<return type="int">
			</return>
			<description>
				Returns number of characters in the string.
			</description>
		</method>
		<method name="clusters" qualifiers="const">
			<return type="int">
			</return>
			<description>
				Returns number of grapheme clusters, clusters are indexed in visual order.
			</description>
		</method>
		<method name="copy_properties">
			<return type="void">
			</return>
			<argument index="0" name="source" type="TLShapedString">
			</argument>
			<description>
			</description>
		</method>
		<method name="draw">
			<return type="void">
			</return>
			<argument index="0" name="canvas_item" type="RID">
			</argument>
			<argument index="1" name="position" type="Vector2">
			</argument>
			<argument index="2" name="modulate" type="Color">
			</argument>
			<description>
				Draws a string.
			</description>
		</method>
		<method name="draw_as_hex">
			<return type="void">
			</return>
			<argument index="0" name="canvas_item" type="RID">
			</argument>
			<argument index="1" name="position" type="Vector2">
			</argument>
			<argument index="2" name="modulate" type="Color">
			</argument>
			<argument index="3" name="draw_brk_ops" type="bool">
			</argument>
			<argument index="4" name="draw_jst_ops" type="bool">
			</argument>
			<description>
				[code]DEBUG:[/code] Draws a string using "hexbox" fallback font.
			</description>
		</method>
		<method name="draw_cluster">
			<return type="Vector2">
			</return>
			<argument index="0" name="canvas_item" type="RID">
			</argument>
			<argument index="1" name="position" type="Vector2">
			</argument>
			<argument index="2" name="index" type="int">
			</argument>
			<argument index="3" name="modulate" type="Color">
			</argument>
			<description>
				Draws single grapheme cluster. Returns advance.
			</description>
		</method>
		<method name="draw_dbg">
			<return type="void">
			</return>
			<argument index="0" name="canvas_item" type="RID">
			</argument>
			<argument index="1" name="position" type="Vector2">
			</argument>
			<argument index="2" name="modulate" type="Color">
			</argument>
			<argument index="3" name="draw_brk_ops" type="bool">
			</argument>
			<argument index="4" name="draw_jst_ops" type="bool">
			</argument>
			<description>
				[code]DEBUG:[/code] Draws a string with additional debug information.
			</description>
		</method>
		<method name="draw_logical_as_hex">
			<return type="void">
			</return>
			<argument index="0" name="canvas_item" type="RID">
			</argument>
			<argument index="1" name="position" type="Vector2">
			</argument>
			<argument index="2" name="modulate" type="Color">
			</argument>
			<argument index="3" name="draw_brk_ops" type="bool">
			</argument>
			<argument index="4" name="draw_jst_ops" type="bool">
			</argument>
			<description>
				[code]DEBUG:[/code] Draws logical character codes of the string with additional debug information.
			</description>
		</method>
		<method name="empty" qualifiers="const">
			<return type="bool">
			</return>
			<description>
				Returns [code]true[/code] if the string is empty.
			</description>
		</method>
		<method name="extend_to_width">
			<return type="float">
			</return>
			<argument index="0" name="width" type="float">
			</argument>
			<argument index="1" name="flags" type="int">
			</argument>
			<description>
				Increase text width to the specified. Returns new line width.
			</description>
		</method>
		<method name="get_ascent" qualifiers="const">
			<return type="float">
			</return>
			<description>
				Returns ascent of the line.
			</description>
		</method>
		<method name="get_char_direction" qualifiers="const">
			<return type="int" enum="TextDirection">
			</return>
			<argument index="0" name="position" type="int">
			</argument>
			<description>
				Return writing direction of a character writing direction.
			</description>
		</method>
		<method name="get_cluster_ascent" qualifiers="const">
			<return type="float">
			</return>
			<argument index="0" name="index" type="int">
			</argument>
			<description>
				Returns cluster ascent.
			</description>
		</method>
		<method name="get_cluster_debug_info" qualifiers="const">
			<return type="String">
			</return>
			<argument index="0" name="index" type="int">
			</argument>
			<description>
			</description>
		</method>
		<method name="get_cluster_descent" qualifiers="const">
			<return type="float">
			</return>
			<argument index="0" name="index" type="int">
			</argument>
			<description>
				Returns cluster descent.
			</description>
		</method>
		<method name="get_cluster_end" qualifiers="const">
			<return type="int">
			</return>
			<argument index="0" name="index" type="int">
			</argument>
			<description>
				Returns last character position corresponding cluster.
			</description>
		</method>
		<method name="get_cluster_face" qualifiers="const">
			<return type="TLFontFace">
			</return>
			<argument index="0" name="position" type="int">
			</argument>
			<description>
				Returns font face of the cluster.
			</description>
		</method>
		<method name="get_cluster_face_size" qualifiers="const">
			<return type="float">
			</return>
			<argument index="0" name="position" type="int">
			</argument>
			<description>
				Returns font size of the cluster. For non-attributed string it's always equal to base size.
			</description>
		</method>
		<method name="get_cluster_glyph" qualifiers="const">
			<return type="int">
			</return>
			<argument index="0" name="index" type="int">
			</argument>
			<argument index="1" name="glyph" type="int">
			</argument>
			<description>
				Returns glyph ID.
			</description>
		</method>
		<method name="get_cluster_glyph_advance" qualifiers="const">
			<return type="Vector2">
			</return>
			<argument index="0" name="index" type="int">
			</argument>
			<argument index="1" name="glyph" type="int">
			</argument>
			<description>
				Returns glyph advance.
			</description>
		</method>
		<method name="get_cluster_glyph_offset" qualifiers="const">
			<return type="Vector2">
			</return>
			<argument index="0" name="index" type="int">
			</argument>
			<argument index="1" name="glyph" type="int">
			</argument>
			<description>
				Returns glyph offset.
			</description>
		</method>
		<method name="get_cluster_glyphs" qualifiers="const">
			<return type="int">
			</return>
			<argument index="0" name="index" type="int">
			</argument>
			<description>
				Returns number of glyphs in cluster.
			</description>
		</method>
		<method name="get_cluster_height" qualifiers="const">
			<return type="float">
			</return>
			<argument index="0" name="index" type="int">
			</argument>
			<description>
				Returns cluster height.
			</description>
		</method>
		<method name="get_cluster_index" qualifiers="const">
			<return type="int">
			</return>
			<argument index="0" name="position" type="int">
			</argument>
			<description>
				Returns cluster index corresponding to a specific character position in string.
			</description>
		</method>
		<method name="get_cluster_leading_edge" qualifiers="const">
			<return type="float">
			</return>
			<argument index="0" name="index" type="int">
			</argument>
			<description>
				Returns cluster leading edge offset in pixels.
			</description>
		</method>
		<method name="get_cluster_rect" qualifiers="const">
			<return type="Rect2">
			</return>
			<argument index="0" name="index" type="int">
			</argument>
			<description>
				Returns cluster bounding rectangle.
			</description>
		</method>
		<method name="get_cluster_start" qualifiers="const">
			<return type="int">
			</return>
			<argument index="0" name="index" type="int">
			</argument>
			<description>
				Returns first character position corresponding cluster.
			</description>
		</method>
		<method name="get_cluster_trailing_edge" qualifiers="const">
			<return type="float">
			</return>
			<argument index="0" name="index" type="int">
			</argument>
			<description>
				Returns cluster trailing edge offset in pixels.
			</description>
		</method>
		<method name="get_cluster_width" qualifiers="const">
			<return type="float">
			</return>
			<argument index="0" name="index" type="int">
			</argument>
			<description>
				Returns cluster width.
			</description>
		</method>
		<method name="get_cursor_positions" qualifiers="const">
			<return type="Array">
			</return>
			<argument index="0" name="position" type="int">
			</argument>
			<argument index="1" name="primary_dir" type="int">
			</argument>
			<description>
				Returns an [Array] of [code]float[/code] (up to two elements) offsets corresponding to the strong and weak cursor, at the specified character position.
			</description>
		</method>
		<method name="get_descent" qualifiers="const">
			<return type="float">
			</return>
			<description>
				Returns descent of the line.
			</description>
		</method>
		<method name="get_height" qualifiers="const">
			<return type="float">
			</return>
			<description>
				Returns height of the line.
			</description>
		</method>
		<method name="get_highlight_shapes" qualifiers="const">
			<return type="Array">
			</return>
			<argument index="0" name="start" type="int">
			</argument>
			<argument index="1" name="end" type="int">
			</argument>
			<description>
				Returns an [Array] of [Rect2] enclosing the selection/highlight in the specified range.
			</description>
		</method>
		<method name="get_para_direction" qualifiers="const">
			<return type="int">
			</return>
			<description>
				Returns shaped string paragraph direction.
			</description>
		</method>
		<method name="get_utf16" qualifiers="const">
			<return type="PoolByteArray">
			</return>
			<description>
				Returns raw text string in UTF-16 encoding.
			</description>
		</method>
		<method name="get_utf32" qualifiers="const">
			<return type="PoolByteArray">
			</return>
			<description>
				Returns raw text string in UTF-32 encoding.
			</description>
		</method>
		<method name="get_utf8" qualifiers="const">
			<return type="PoolByteArray">
			</return>
			<description>
				Returns raw text string in UTF-8 encoding.
			</description>
		</method>
		<method name="get_width" qualifiers="const">
			<return type="float">
			</return>
			<description>
				Returns width of the line.
			</description>
		</method>
		<method name="hit_test" qualifiers="const">
			<return type="int">
			</return>
			<argument index="0" name="position" type="float">
			</argument>
			<description>
				Returns a cursor position corresponding to the specified pixel offset.
			</description>
		</method>
		<method name="hit_test_cluster" qualifiers="const">
			<return type="int">
			</return>
			<argument index="0" name="position" type="float">
			</argument>
			<description>
				Returns a cluster index corresponding to the specified pixel offset.
			</description>
		</method>
		<method name="is_valid" qualifiers="const">
			<return type="bool">
			</return>
			<description>
				Returns [code]true[/code] if the string is shaped successfully.
			</description>
		</method>
		<method name="length" qualifiers="const">
			<return type="int">
			</return>
			<description>
				Returns number of UTF-16 codepoints in the string.
			</description>
		</method>
		<method name="next_safe_bound" qualifiers="const">
			<return type="int">
			</return>
			<argument index="0" name="position" type="int">
			</argument>
			<description>
				Returns next whole character position in the string.
			</description>
		</method>
		<method name="pos_u16_to_wcs" qualifiers="const">
			<return type="int">
			</return>
			<argument index="0" name="position" type="int">
			</argument>
			<description>
				Returns character position (Characters)
			</description>
		</method>
		<method name="pos_wcs_to_u16" qualifiers="const">
			<return type="int">
			</return>
			<argument index="0" name="position" type="int">
			</argument>
			<description>
				Retruns character position (UTF-16 codepoints)
			</description>
		</method>
		<method name="prev_safe_bound" qualifiers="const">
			<return type="int">
			</return>
			<argument index="0" name="position" type="int">
			</argument>
			<description>
				Returns previous whole character position in the string.
			</description>
		</method>
		<method name="replace_sstring">
			<return type="void">
			</return>
			<argument index="0" name="start" type="int">
			</argument>
			<argument index="1" name="end" type="int">
			</argument>
			<argument index="2" name="text" type="TLShapedString">
			</argument>
			<description>
				Replaces substring with contents of another shaped string.
			</description>
		</method>
		<method name="replace_text">
			<return type="void">
			</return>
			<argument index="0" name="start" type="int">
			</argument>
			<argument index="1" name="end" type="int">
			</argument>
			<argument index="2" name="text" type="String">
			</argument>
			<description>
				Replaces substring with text.
			</description>
		</method>
		<method name="replace_utf16">
			<return type="void">
			</return>
			<argument index="0" name="start" type="int">
			</argument>
			<argument index="1" name="end" type="int">
			</argument>
			<argument index="2" name="text" type="PoolByteArray">
			</argument>
			<description>
				Replaces substring with contents of the raw UTF-16 encoded string.
			</description>
		</method>
		<method name="replace_utf32">
			<return type="void">
			</return>
			<argument index="0" name="start" type="int">
			</argument>
			<argument index="1" name="end" type="int">
			</argument>
			<argument index="2" name="text" type="PoolByteArray">
			</argument>
			<description>
				Replaces substring with contents of the raw UTF-32 encoded string.
			</description>
		</method>
		<method name="replace_utf8">
			<return type="void">
			</return>
			<argument index="0" name="start" type="int">
			</argument>
			<argument index="1" name="end" type="int">
			</argument>
			<argument index="2" name="text" type="PoolByteArray">
			</argument>
			<description>
				Replaces substring with contents of the raw UTF-8 encoded string.
			</description>
		</method>
		<method name="set_utf16">
			<return type="void">
			</return>
			<argument index="0" name="data" type="PoolByteArray">
			</argument>
			<description>
				Sets text to the contents of the raw UTF-16 encoded string.
			</description>
		</method>
		<method name="set_utf32">
			<return type="void">
			</return>
			<argument index="0" name="data" type="PoolByteArray">
			</argument>
			<description>
				Sets text to the contents of the raw UTF-32 encoded string.
			</description>
		</method>
		<method name="set_utf8">
			<return type="void">
			</return>
			<argument index="0" name="data" type="PoolByteArray">
			</argument>
			<description>
				Sets text to the contents of the raw UTF-8 encoded string.
			</description>
		</method>
		<method name="shape">
			<return type="bool">
			</return>
			<description>
				Shapes string and returns [code]true[/code] if the string is shaped successfully.
			</description>
		</method>
		<method name="substr" qualifiers="const">
			<return type="TLShapedString">
			</return>
			<argument index="0" name="start" type="int">
			</argument>
			<argument index="1" name="end" type="int">
			</argument>
			<argument index="2" name="trim" type="int">
			</argument>
			<description>
				Returns part of the shaped string from the position [code]start[/code] to [code]end[/code], trims it according to [code]trim[/code] parameter.
			</description>
		</method>
	</methods>
	<members>
		<member name="base_direction" type="int" setter="set_base_direction" getter="get_base_direction" default="3">
			Base text writing direction.
		</member>
		<member name="base_font" type="TLFontFamily" setter="set_base_font" getter="get_base_font">
			Base font family reference.
		</member>
		<member name="base_font_size" type="int" setter="set_base_font_size" getter="get_base_font_size" default="12">
			Font size.
		</member>
		<member name="base_font_style" type="String" setter="set_base_font_style" getter="get_base_font_style" default="&quot;Regular&quot;">
			Style name (Regular, Bold, Italic, Oblique etc.).
		</member>
		<member name="features" type="String" setter="set_features" getter="get_features" default="&quot;&quot;">
			Comma separated list of OpenType feature tags. More info: https://docs.microsoft.com/en-us/typography/opentype/spec/featuretags.
		</member>
		<member name="language" type="String" setter="set_language" getter="get_language" default="&quot;en&quot;">
			Language code for line-breaking and text shaping algorithms.
		</member>
		<member name="preserve_control" type="bool" setter="set_preserve_control" getter="get_preserve_control" default="false">
			If [code]true[/code], displays control character.
		</member>
		<member name="text" type="String" setter="set_text" getter="get_text" default="&quot;&quot;">
			Text string.
		</member>
	</members>
	<signals>
		<signal name="string_changed">
			<description>
				Emitted when the text or/and other property of the string changes.
			</description>
		</signal>
		<signal name="string_shaped">
			<description>
				Emitted when the text shaping process is completed.
			</description>
		</signal>
	</signals>
	<constants>
		<constant name="TEXT_DIRECTION_LTR" value="0" enum="TextDirection">
			Left-to-right text writing direction.
		</constant>
		<constant name="TEXT_DIRECTION_RTL" value="1" enum="TextDirection">
			Right-to-left text writing direction.
		</constant>
		<constant name="TEXT_DIRECTION_LOCALE" value="2" enum="TextDirection">
			Text writing direction is derived from the locale's script according to the CLDR metadata.
		</constant>
		<constant name="TEXT_DIRECTION_AUTO" value="3" enum="TextDirection">
			Text writing direction is derived from the first character in the string with BiDi class L, R, or AL or locale's script if text is not strongly directional.
		</constant>
		<constant name="TEXT_DIRECTION_INVALID" value="4" enum="TextDirection">
			Invalid text direction (Used as return value only).
		</constant>
		<constant name="TEXT_JUSTIFICATION_NONE" value="0" enum="TextJustification">
			No text justification.
		</constant>
		<constant name="TEXT_JUSTIFICATION_KASHIDA_AND_WHITESPACE" value="1" enum="TextJustification">
			Use kashida and white space elongation to justify text.
		</constant>
		<constant name="TEXT_JUSTIFICATION_KASHIDA_ONLY" value="2" enum="TextJustification">
			Use kashida elongation to justify text.
		</constant>
		<constant name="TEXT_JUSTIFICATION_WHITESPACE_ONLY" value="3" enum="TextJustification">
			Use white space elongation to justify text.
		</constant>
		<constant name="TEXT_JUSTIFICATION_KASHIDA_AND_WHITESPACE_AND_INTERCHAR" value="4" enum="TextJustification">
			Use kashida, white space and inter character elongation to justify text.
		</constant>
		<constant name="TEXT_JUSTIFICATION_KASHIDA_AND_INTERCHAR" value="5" enum="TextJustification">
			Use kashida and inter character elongation to justify text.
		</constant>
		<constant name="TEXT_JUSTIFICATION_WHITESPACE_AND_INTERCHAR" value="6" enum="TextJustification">
			Use white space and inter character elongation to justify text.
		</constant>
		<constant name="TEXT_JUSTIFICATION_INTERCHAR_ONLY" value="7" enum="TextJustification">
			Use inter character elongation to justify text.
		</constant>
		<constant name="TEXT_BREAK_NONE" value="0" enum="TextBreak">
			No line breaking.
		</constant>
		<constant name="TEXT_BREAK_MANDATORY" value="1" enum="TextBreak">
			Break lines only at mandatory break points.
		</constant>
		<constant name="TEXT_BREAK_MANDATORY_AND_WORD_BOUND" value="2" enum="TextBreak">
			Break lines at mandatory break points and word boundaries.
		</constant>
		<constant name="TEXT_BREAK_MANDATORY_AND_ANYWHERE" value="3" enum="TextBreak">
			Break lines at mandatory break points and grapheme cluster boundaries.
		</constant>
		<constant name="TEXT_TRIM_NONE" value="0" enum="TextTrimMode">
			No substring trimming.
		</constant>
		<constant name="TEXT_TRIM_BREAK" value="1" enum="TextTrimMode">
			Trim line break characters for substring ends.
		</constant>
		<constant name="TEXT_TRIM_BREAK_AND_WHITESPACE" value="2" enum="TextTrimMode">
			Trim line break and white space characters for substring ends.
		</constant>
	</constants>
</class>
