diff options
Diffstat (limited to 'doc')
39 files changed, 2104 insertions, 571 deletions
diff --git a/doc/classes/@GlobalScope.xml b/doc/classes/@GlobalScope.xml index 33afe38446..4a6b85f229 100644 --- a/doc/classes/@GlobalScope.xml +++ b/doc/classes/@GlobalScope.xml @@ -115,7 +115,7 @@ <param index="3" name="end" type="float" /> <param index="4" name="t" type="float" /> <description> - Returns the derivative at the given [param t] on a one-dimensional [url=https://en.wikipedia.org/wiki/B%C3%A9zier_curve]Bezier curve[/url] defined by the given [param control_1], [param control_2], and [param end] points. + Returns the derivative at the given [param t] on a one-dimensional [url=https://en.wikipedia.org/wiki/B%C3%A9zier_curve]Bézier curve[/url] defined by the given [param control_1], [param control_2], and [param end] points. </description> </method> <method name="bezier_interpolate"> @@ -126,7 +126,7 @@ <param index="3" name="end" type="float" /> <param index="4" name="t" type="float" /> <description> - Returns the point at the given [param t] on a one-dimensional [url=https://en.wikipedia.org/wiki/B%C3%A9zier_curve]Bezier curve[/url] defined by the given [param control_1], [param control_2], and [param end] points. + Returns the point at the given [param t] on a one-dimensional [url=https://en.wikipedia.org/wiki/B%C3%A9zier_curve]Bézier curve[/url] defined by the given [param control_1], [param control_2], and [param end] points. </description> </method> <method name="bytes_to_var"> @@ -2877,40 +2877,38 @@ </constant> <constant name="PROPERTY_USAGE_STORE_IF_NULL" value="8192" enum="PropertyUsageFlags"> </constant> - <constant name="PROPERTY_USAGE_ANIMATE_AS_TRIGGER" value="16384" enum="PropertyUsageFlags"> + <constant name="PROPERTY_USAGE_UPDATE_ALL_IF_MODIFIED" value="16384" enum="PropertyUsageFlags"> </constant> - <constant name="PROPERTY_USAGE_UPDATE_ALL_IF_MODIFIED" value="32768" enum="PropertyUsageFlags"> + <constant name="PROPERTY_USAGE_SCRIPT_DEFAULT_VALUE" value="32768" enum="PropertyUsageFlags"> </constant> - <constant name="PROPERTY_USAGE_SCRIPT_DEFAULT_VALUE" value="65536" enum="PropertyUsageFlags"> + <constant name="PROPERTY_USAGE_CLASS_IS_ENUM" value="65536" enum="PropertyUsageFlags"> </constant> - <constant name="PROPERTY_USAGE_CLASS_IS_ENUM" value="131072" enum="PropertyUsageFlags"> + <constant name="PROPERTY_USAGE_NIL_IS_VARIANT" value="131072" enum="PropertyUsageFlags"> </constant> - <constant name="PROPERTY_USAGE_NIL_IS_VARIANT" value="262144" enum="PropertyUsageFlags"> + <constant name="PROPERTY_USAGE_INTERNAL" value="262144" enum="PropertyUsageFlags"> </constant> - <constant name="PROPERTY_USAGE_INTERNAL" value="524288" enum="PropertyUsageFlags"> - </constant> - <constant name="PROPERTY_USAGE_DO_NOT_SHARE_ON_DUPLICATE" value="1048576" enum="PropertyUsageFlags"> + <constant name="PROPERTY_USAGE_DO_NOT_SHARE_ON_DUPLICATE" value="524288" enum="PropertyUsageFlags"> If the property is a [Resource], a new copy of it is always created when calling [method Node.duplicate] or [method Resource.duplicate]. </constant> - <constant name="PROPERTY_USAGE_HIGH_END_GFX" value="2097152" enum="PropertyUsageFlags"> + <constant name="PROPERTY_USAGE_HIGH_END_GFX" value="1048576" enum="PropertyUsageFlags"> The property is only shown in the editor if modern renderers are supported (GLES3 is excluded). </constant> - <constant name="PROPERTY_USAGE_NODE_PATH_FROM_SCENE_ROOT" value="4194304" enum="PropertyUsageFlags"> + <constant name="PROPERTY_USAGE_NODE_PATH_FROM_SCENE_ROOT" value="2097152" enum="PropertyUsageFlags"> </constant> - <constant name="PROPERTY_USAGE_RESOURCE_NOT_PERSISTENT" value="8388608" enum="PropertyUsageFlags"> + <constant name="PROPERTY_USAGE_RESOURCE_NOT_PERSISTENT" value="4194304" enum="PropertyUsageFlags"> </constant> - <constant name="PROPERTY_USAGE_KEYING_INCREMENTS" value="16777216" enum="PropertyUsageFlags"> + <constant name="PROPERTY_USAGE_KEYING_INCREMENTS" value="8388608" enum="PropertyUsageFlags"> </constant> - <constant name="PROPERTY_USAGE_DEFERRED_SET_RESOURCE" value="33554432" enum="PropertyUsageFlags"> + <constant name="PROPERTY_USAGE_DEFERRED_SET_RESOURCE" value="16777216" enum="PropertyUsageFlags"> </constant> - <constant name="PROPERTY_USAGE_EDITOR_INSTANTIATE_OBJECT" value="67108864" enum="PropertyUsageFlags"> + <constant name="PROPERTY_USAGE_EDITOR_INSTANTIATE_OBJECT" value="33554432" enum="PropertyUsageFlags"> </constant> - <constant name="PROPERTY_USAGE_EDITOR_BASIC_SETTING" value="134217728" enum="PropertyUsageFlags"> + <constant name="PROPERTY_USAGE_EDITOR_BASIC_SETTING" value="67108864" enum="PropertyUsageFlags"> </constant> - <constant name="PROPERTY_USAGE_READ_ONLY" value="268435456" enum="PropertyUsageFlags"> + <constant name="PROPERTY_USAGE_READ_ONLY" value="134217728" enum="PropertyUsageFlags"> The property is read-only in the [EditorInspector]. </constant> - <constant name="PROPERTY_USAGE_ARRAY" value="536870912" enum="PropertyUsageFlags"> + <constant name="PROPERTY_USAGE_ARRAY" value="268435456" enum="PropertyUsageFlags"> The property is an array. </constant> <constant name="PROPERTY_USAGE_DEFAULT" value="6" enum="PropertyUsageFlags"> diff --git a/doc/classes/Animation.xml b/doc/classes/Animation.xml index 58681090b4..d9a1f896f1 100644 --- a/doc/classes/Animation.xml +++ b/doc/classes/Animation.xml @@ -596,15 +596,12 @@ [b]Note:[/b] The result value is always normalized and may not match the key value. </constant> <constant name="UPDATE_CONTINUOUS" value="0" enum="UpdateMode"> - Update between keyframes. + Update between keyframes and hold the value. </constant> <constant name="UPDATE_DISCRETE" value="1" enum="UpdateMode"> - Update at the keyframes and hold the value. - </constant> - <constant name="UPDATE_TRIGGER" value="2" enum="UpdateMode"> Update at the keyframes. </constant> - <constant name="UPDATE_CAPTURE" value="3" enum="UpdateMode"> + <constant name="UPDATE_CAPTURE" value="2" enum="UpdateMode"> Same as linear interpolation, but also interpolates from the current value (i.e. dynamically at runtime) if the first key isn't at 0 seconds. </constant> <constant name="LOOP_NONE" value="0" enum="LoopMode"> diff --git a/doc/classes/AudioStreamRandomizer.xml b/doc/classes/AudioStreamRandomizer.xml index 5490770b7d..9b58d78af5 100644 --- a/doc/classes/AudioStreamRandomizer.xml +++ b/doc/classes/AudioStreamRandomizer.xml @@ -78,13 +78,13 @@ </members> <constants> <constant name="PLAYBACK_RANDOM_NO_REPEATS" value="0" enum="PlaybackMode"> - Pick a stream at random according to the probability weights chosen for each stream, but avoid playing the same stream twice in a row whenever possible. + Pick a stream at random according to the probability weights chosen for each stream, but avoid playing the same stream twice in a row whenever possible. If only 1 sound is present in the pool, the same sound will always play, effectively allowing repeats to occur. </constant> <constant name="PLAYBACK_RANDOM" value="1" enum="PlaybackMode"> - Pick a stream at random according to the probability weights chosen for each stream. + Pick a stream at random according to the probability weights chosen for each stream. If only 1 sound is present in the pool, the same sound will always play. </constant> <constant name="PLAYBACK_SEQUENTIAL" value="2" enum="PlaybackMode"> - Play streams in the order they appear in the stream pool. + Play streams in the order they appear in the stream pool. If only 1 sound is present in the pool, the same sound will always play. </constant> </constants> </class> diff --git a/doc/classes/BackBufferCopy.xml b/doc/classes/BackBufferCopy.xml index 3c811e6226..b2c5a1756f 100644 --- a/doc/classes/BackBufferCopy.xml +++ b/doc/classes/BackBufferCopy.xml @@ -4,8 +4,8 @@ Copies a region of the screen (or the whole screen) to a buffer so it can be accessed in your shader scripts through the [code]texture(SCREEN_TEXTURE, ...)[/code] function. </brief_description> <description> - Node for back-buffering the currently-displayed screen. The region defined in the BackBufferCopy node is buffered with the content of the screen it covers, or the entire screen according to the copy mode set. Use the [code]texture(SCREEN_TEXTURE, ...)[/code] function in your shader scripts to access the buffer. - [b]Note:[/b] Since this node inherits from [Node2D] (and not [Control]), anchors and margins won't apply to child [Control]-derived nodes. This can be problematic when resizing the window. To avoid this, add [Control]-derived nodes as [i]siblings[/i] to the BackBufferCopy node instead of adding them as children. + Node for back-buffering the currently-displayed screen. The region defined in the [BackBufferCopy] node is buffered with the content of the screen it covers, or the entire screen according to the copy mode set. Use the [code]texture(SCREEN_TEXTURE, ...)[/code] function in your shader scripts to access the buffer. + [b]Note:[/b] Since this node inherits from [Node2D] (and not [Control]), anchors and margins won't apply to child [Control]-derived nodes. This can be problematic when resizing the window. To avoid this, add [Control]-derived nodes as [i]siblings[/i] to the [BackBufferCopy] node instead of adding them as children. </description> <tutorials> </tutorials> @@ -14,18 +14,18 @@ Buffer mode. See [enum CopyMode] constants. </member> <member name="rect" type="Rect2" setter="set_rect" getter="get_rect" default="Rect2(-100, -100, 200, 200)"> - The area covered by the BackBufferCopy. Only used if [member copy_mode] is [constant COPY_MODE_RECT]. + The area covered by the [BackBufferCopy]. Only used if [member copy_mode] is [constant COPY_MODE_RECT]. </member> </members> <constants> <constant name="COPY_MODE_DISABLED" value="0" enum="CopyMode"> - Disables the buffering mode. This means the BackBufferCopy node will directly use the portion of screen it covers. + Disables the buffering mode. This means the [BackBufferCopy] node will directly use the portion of screen it covers. </constant> <constant name="COPY_MODE_RECT" value="1" enum="CopyMode"> - BackBufferCopy buffers a rectangular region. + [BackBufferCopy] buffers a rectangular region. </constant> <constant name="COPY_MODE_VIEWPORT" value="2" enum="CopyMode"> - BackBufferCopy buffers the entire screen. + [BackBufferCopy] buffers the entire screen. </constant> </constants> </class> diff --git a/doc/classes/CollisionObject2D.xml b/doc/classes/CollisionObject2D.xml index ee69015ae1..3ed2c9d3de 100644 --- a/doc/classes/CollisionObject2D.xml +++ b/doc/classes/CollisionObject2D.xml @@ -157,7 +157,7 @@ <param index="0" name="owner_id" type="int" /> <param index="1" name="shape_id" type="int" /> <description> - Returns the [Shape2D] with the given id from the given shape owner. + Returns the [Shape2D] with the given ID from the given shape owner. </description> </method> <method name="shape_owner_get_shape_count" qualifiers="const"> @@ -172,7 +172,7 @@ <param index="0" name="owner_id" type="int" /> <param index="1" name="shape_id" type="int" /> <description> - Returns the child index of the [Shape2D] with the given id from the given shape owner. + Returns the child index of the [Shape2D] with the given ID from the given shape owner. </description> </method> <method name="shape_owner_get_transform" qualifiers="const"> diff --git a/doc/classes/CollisionObject3D.xml b/doc/classes/CollisionObject3D.xml index f10136521a..c302963b92 100644 --- a/doc/classes/CollisionObject3D.xml +++ b/doc/classes/CollisionObject3D.xml @@ -130,7 +130,7 @@ <param index="0" name="owner_id" type="int" /> <param index="1" name="shape_id" type="int" /> <description> - Returns the [Shape3D] with the given id from the given shape owner. + Returns the [Shape3D] with the given ID from the given shape owner. </description> </method> <method name="shape_owner_get_shape_count" qualifiers="const"> @@ -145,7 +145,7 @@ <param index="0" name="owner_id" type="int" /> <param index="1" name="shape_id" type="int" /> <description> - Returns the child index of the [Shape3D] with the given id from the given shape owner. + Returns the child index of the [Shape3D] with the given ID from the given shape owner. </description> </method> <method name="shape_owner_get_transform" qualifiers="const"> diff --git a/doc/classes/Color.xml b/doc/classes/Color.xml index 90fbdcc622..4d78433915 100644 --- a/doc/classes/Color.xml +++ b/doc/classes/Color.xml @@ -1,12 +1,11 @@ <?xml version="1.0" encoding="UTF-8" ?> <class name="Color" version="4.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> <brief_description> - Color in RGBA format using floats on the range of 0 to 1. + Color built-in type, in RGBA format. </brief_description> <description> - A color represented by red, green, blue, and alpha (RGBA) components. The alpha component is often used for opacity. Values are in floating-point and usually range from 0 to 1. Some properties (such as CanvasItem.modulate) may accept values greater than 1 (overbright or HDR colors). - You can also create a color from standardized color names by using the string constructor or directly using the color constants defined here. The standardized color set is based on the [url=https://en.wikipedia.org/wiki/X11_color_names]X11 color names[/url]. - If you want to supply values in a range of 0 to 255, you should use [method @GDScript.Color8]. + A color represented in RGBA format by red ([member r]), green ([member g]), blue ([member b]), and alpha ([member a]) components. Each component is a 16-bit floating-point value, usually ranging from 0 to 1. Some properties (such as [member CanvasItem.modulate]) may support values greater than 1, for overbright or High Dynamic Range colors. If you want to supply values in a range of 0 to 255, you should use [method @GDScript.Color8]. + Colors can also be created by name from a set of standardized colors, through the [String] constructor, [method from_string], or by directly fetching the color constants documented here. The standardized color set is based on the [url=https://en.wikipedia.org/wiki/X11_color_names]X11 color names[/url], with the addition of [constant TRANSPARENT]. [b]Note:[/b] In a boolean context, a Color will evaluate to [code]false[/code] if it's equal to [code]Color(0, 0, 0, 1)[/code] (opaque black). Otherwise, a Color will always evaluate to [code]true[/code]. [url=https://raw.githubusercontent.com/godotengine/godot-docs/master/img/color_constants.png]Color constants cheatsheet[/url] </description> @@ -19,7 +18,8 @@ <constructor name="Color"> <return type="Color" /> <description> - Constructs a default-initialized [Color] with all components set to [code]0[/code]. + Constructs a default [Color] from opaque black. This is the same as [constant BLACK]. + [b]Note:[/b] in C#, constructs an empty color with all of its components set to [code]0.0[/code] (transparent black). </description> </constructor> <constructor name="Color"> @@ -27,10 +27,10 @@ <param index="0" name="from" type="Color" /> <param index="1" name="alpha" type="float" /> <description> - Constructs a [Color] from an existing color, but with a custom alpha value. + Constructs a [Color] from the existing color, with [member a] set to the given [param alpha] value. [codeblocks] [gdscript] - var red = Color(Color.red, 0.2) # 20% opaque red. + var red = Color(Color.RED, 0.2) # 20% opaque red. [/gdscript] [csharp] var red = new Color(Colors.Red, 0.2f); // 20% opaque red. @@ -49,7 +49,7 @@ <return type="Color" /> <param index="0" name="code" type="String" /> <description> - Constructs a [Color] either from an HTML color code or from a standardized color name. Supported color names are the same as the constants. + Constructs a [Color] either from an HTML color code or from a standardized color name. The supported color names are the same as the constants. </description> </constructor> <constructor name="Color"> @@ -57,7 +57,7 @@ <param index="0" name="code" type="String" /> <param index="1" name="alpha" type="float" /> <description> - Constructs a [Color] either from an HTML color code or from a standardized color name, with [param alpha] on the range of 0 to 1. Supported color names are the same as the constants. + Constructs a [Color] either from an HTML color code or from a standardized color name, with [param alpha] on the range of 0.0 to 1.0. The supported color names are the same as the constants. </description> </constructor> <constructor name="Color"> @@ -66,7 +66,7 @@ <param index="1" name="g" type="float" /> <param index="2" name="b" type="float" /> <description> - Constructs a [Color] from RGB values, typically between 0 and 1. Alpha will be 1. + Constructs a [Color] from RGB values, typically between 0.0 and 1.0. [member a] is set to 1.0. [codeblocks] [gdscript] var color = Color(0.2, 1.0, 0.7) # Similar to `Color8(51, 255, 178, 255)` @@ -84,7 +84,7 @@ <param index="2" name="b" type="float" /> <param index="3" name="a" type="float" /> <description> - Constructs a [Color] from RGBA values, typically between 0 and 1. + Constructs a [Color] from RGBA values, typically between 0.0 and 1.0. [codeblocks] [gdscript] var color = Color(0.2, 1.0, 0.7, 0.8) # Similar to `Color8(51, 255, 178, 204)` @@ -101,7 +101,7 @@ <return type="Color" /> <param index="0" name="over" type="Color" /> <description> - Returns a new color resulting from blending this color over another. If the color is opaque, the result is also opaque. The second color may have a range of alpha values. + Returns a new color resulting from overlaying this color over the given color. In a painting program, you can imagine it as the [param over] color painted over this colour (including alpha). [codeblocks] [gdscript] var bg = Color(0.0, 1.0, 0.0, 0.5) # Green with alpha of 50% @@ -128,7 +128,7 @@ <return type="Color" /> <param index="0" name="amount" type="float" /> <description> - Returns a new color resulting from making this color darker by the specified percentage (ratio from 0 to 1). + Returns a new color resulting from making this color darker by the specified [param amount] (ratio from 0.0 to 1.0). See also [method lightened]. [codeblocks] [gdscript] var green = Color(0.0, 1.0, 0.0) @@ -148,7 +148,7 @@ <param index="2" name="v" type="float" /> <param index="3" name="alpha" type="float" default="1.0" /> <description> - Constructs a color from an [url=https://en.wikipedia.org/wiki/HSL_and_HSV]HSV profile[/url]. [param h] (hue), [param s] (saturation), and [param v] (value) are typically between 0 and 1. + Constructs a color from an [url=https://en.wikipedia.org/wiki/HSL_and_HSV]HSV profile[/url]. The hue ([param h]), saturation ([param s]), and value ([param v]) are typically between 0.0 and 1.0. [codeblocks] [gdscript] var color = Color.from_hsv(0.58, 0.5, 0.79, 0.8) @@ -166,7 +166,7 @@ <param index="2" name="l" type="float" /> <param index="3" name="alpha" type="float" default="1.0" /> <description> - Constructs a color from an [url=https://bottosson.github.io/posts/colorpicker/]OK HSL profile[/url]. [param h] (hue), [param s] (saturation), and [param l] (lightness) are typically between 0 and 1. + Constructs a color from an [url=https://bottosson.github.io/posts/colorpicker/]OK HSL profile[/url]. The hue ([param h]), saturation ([param s]), and lightness ([param l]) are typically between 0.0 and 1.0. [codeblocks] [gdscript] var color = Color.from_ok_hsl(0.58, 0.5, 0.79, 0.8) @@ -189,14 +189,13 @@ <param index="0" name="str" type="String" /> <param index="1" name="default" type="Color" /> <description> - Creates a [Color] from string, which can be either a HTML color code or a named color. Fallbacks to [param default] if the string does not denote any valid color. + Creates a [Color] from the given string, which can be either an HTML color code or a named color (case-insensitive). Returns [param default] if the color cannot be inferred from the string. </description> </method> <method name="get_luminance" qualifiers="const"> <return type="float" /> <description> - Returns the luminance of the color in the [code][0.0, 1.0][/code] range. - This is useful when determining light or dark color. Colors with a luminance smaller than 0.5 can be generally considered dark. + Returns the light intensity of the color, as a value between 0.0 and 1.0 (inclusive). This is useful when determining light or dark color. Colors with a luminance smaller than 0.5 can be generally considered dark. [b]Note:[/b] [method get_luminance] relies on the color being in the linear color space to return an accurate relative luminance value. If the color is in the sRGB color space, use [method srgb_to_linear] to convert it to the linear color space first. </description> </method> @@ -204,9 +203,12 @@ <return type="Color" /> <param index="0" name="hex" type="int" /> <description> - Returns the [Color] associated with the provided integer number, with 8 bits per channel in ARGB order. The integer should be 32-bit. Best used with hexadecimal notation. + Returns the [Color] associated with the provided [param hex] integer in 32-bit ARGB format (8 bits per channel, alpha channel first). + In GDScript and C#, the [int] is best visualized with hexadecimal notation ([code]"0x"[/code] prefix). [codeblock] - modulate = Color.hex(0xffff0000) # red + var red = Color.hex(0xffff0000) + var dark_cyan = Color.hex(0xff008b8b) + var my_color = Color.hex(0xa4bbefd2) [/codeblock] </description> </method> @@ -214,25 +216,27 @@ <return type="Color" /> <param index="0" name="hex" type="int" /> <description> - Same as [method hex], but takes 64-bit integer and the color uses 16 bits per channel. + Returns the [Color] associated with the provided [param hex] integer in 64-bit ARGB format (16 bits per channel, alpha channel first). + In GDScript and C#, the [int] is best visualized with hexadecimal notation ([code]"0x"[/code] prefix). </description> </method> <method name="html" qualifiers="static"> <return type="Color" /> <param index="0" name="rgba" type="String" /> <description> - Returns a new color from [param rgba], an HTML hexadecimal color string. [param rgba] is not case sensitive, and may be prefixed with a '#' character. - [param rgba] must be a valid three-digit or six-digit hexadecimal color string, and may contain an alpha channel value. If [param rgba] does not contain an alpha channel value, an alpha channel value of 1.0 is applied. - If [param rgba] is invalid a Color(0.0, 0.0, 0.0, 1.0) is returned. - [b]Note:[/b] This method is not implemented in C#, but the same functionality is provided in the class constructor. + Returns a new color from [param rgba], an HTML hexadecimal color string. [param rgba] is not case-sensitive, and may be prefixed by a hash sign ([code]#[/code]). + [param rgba] must be a valid three-digit or six-digit hexadecimal color string, and may contain an alpha channel value. If [param rgba] does not contain an alpha channel value, an alpha channel value of 1.0 is applied. If [param rgba] is invalid, returns an empty color. + [b]Note:[/b] In C#, this method is not implemented. The same functionality is provided by the Color constructor. [codeblocks] [gdscript] - var green = Color.html("#00FF00FF") # set green to Color(0.0, 1.0, 0.0, 1.0) - var blue = Color.html("#0000FF") # set blue to Color(0.0, 0.0, 1.0, 1.0) + var blue = Color.html("#0000ff") # blue is Color(0.0, 0.0, 1.0, 1.0) + var green = Color.html("#0F0") # green is Color(0.0, 1.0, 0.0, 1.0) + var col = Color.html("663399cc") # col is Color(0.4, 0.2, 0.6, 0.8) [/gdscript] [csharp] - var green = new Color("#00FF00FF"); // set green to Color(0.0, 1.0, 0.0, 1.0) - var blue = new Color("#0000FF"); // set blue to Color(0.0, 0.0, 1.0, 1.0) + var blue = new Color("#0000ff"); // blue is Color(0.0, 0.0, 1.0, 1.0) + var green = new Color("#0F0"); // green is Color(0.0, 1.0, 0.0, 1.0) + var col = new Color("663399cc"); // col is Color(0.4, 0.2, 0.6, 0.8) [/csharp] [/codeblocks] </description> @@ -241,24 +245,26 @@ <return type="bool" /> <param index="0" name="color" type="String" /> <description> - Returns [code]true[/code] if [param color] is a valid HTML hexadecimal color string. [param color] is not case sensitive, and may be prefixed with a '#' character. - For a string to be valid it must be three-digit or six-digit hexadecimal, and may contain an alpha channel value. + Returns [code]true[/code] if [param color] is a valid HTML hexadecimal color string. The string must be a hexadecimal value (case-insensitive) of either 3, 4, 6 or 8 digits, and may be prefixed by a hash sign ([code]#[/code]). This method is identical to [method String.is_valid_html_color]. [codeblocks] [gdscript] - var result = Color.html_is_valid("#55aaFF") # result is true - result = Color.html_is_valid("#55AAFF20") # result is true - result = Color.html_is_valid("55AAFF") # result is true - result = Color.html_is_valid("#F2C") # result is true - result = Color.html_is_valid("#AABBC) # result is false - result = Color.html_is_valid("#55aaFF5") # result is false + Color.html_is_valid("#55aaFF") # Returns true + Color.html_is_valid("#55AAFF20") # Returns true + Color.html_is_valid("55AAFF") # Returns true + Color.html_is_valid("#F2C") # Returns true + + Color.html_is_valid("#AABBC) # Returns false + Color.html_is_valid("#55aaFF5") # Returns false [/gdscript] [csharp] - var result = Color.HtmlIsValid("#55AAFF"); // result is true - result = Color.HtmlIsValid("#55AAFF20"); // result is true - result = Color.HtmlIsValid("55AAFF); // result is true - result = Color.HtmlIsValid("#F2C"); // result is true - result = Color.HtmlIsValid("#AABBC"); // result is false - result = Color.HtmlIsValid("#55aaFF5"); // result is false + // This method is not available in C#. Use `StringExtensions.IsValidHtmlColor()`, instead. + "#55AAFF".IsValidHtmlColor(); // Returns true + "#55AAFF20".IsValidHtmlColor(); // Returns true + "55AAFF".IsValidHtmlColor(); // Returns true + "#F2C".IsValidHtmlColor(); // Returns true + + "#AABBC".IsValidHtmlColor(); // Returns false + "#55aaFF5".IsValidHtmlColor(); // Returns false [/csharp] [/codeblocks] </description> @@ -266,13 +272,15 @@ <method name="inverted" qualifiers="const"> <return type="Color" /> <description> - Returns the inverted color [code](1 - r, 1 - g, 1 - b, a)[/code]. + Returns the color with its [member r], [member g], and [member b] components inverted ([code](1 - r, 1 - g, 1 - b, a)[/code]). [codeblocks] [gdscript] + var black = Color.WHITE.inverted() var color = Color(0.3, 0.4, 0.9) var inverted_color = color.inverted() # Equivalent to `Color(0.7, 0.6, 0.1)` [/gdscript] [csharp] + var black = Colors.White.Inverted(); var color = new Color(0.3f, 0.4f, 0.9f); Color invertedColor = color.Inverted(); // Equivalent to `new Color(0.7f, 0.6f, 0.1f)` [/csharp] @@ -291,17 +299,23 @@ <param index="0" name="to" type="Color" /> <param index="1" name="weight" type="float" /> <description> - Returns the linear interpolation with another color. The interpolation factor [param weight] is between 0 and 1. + Returns the linear interpolation between this color's components and [param to]'s components. The interpolation factor [param weight] should be between 0.0 and 1.0 (inclusive). See also [method @GlobalScope.lerp]. [codeblocks] [gdscript] - var c1 = Color(1.0, 0.0, 0.0) - var c2 = Color(0.0, 1.0, 0.0) - var lerp_color = c1.lerp(c2, 0.5) # Equivalent to `Color(0.5, 0.5, 0.0)` + var red = Color(1.0, 0.0, 0.0) + var aqua = Color(0.0, 1.0, 0.8) + + red.lerp(aqua, 0.2) # Returns Color(0.8, 0.2, 0.16) + red.lerp(aqua, 0.5) # Returns Color(0.5, 0.5, 0.4) + red.lerp(aqua, 1.0) # Returns Color(0.0, 1.0, 0.8) [/gdscript] [csharp] - var c1 = new Color(1.0f, 0.0f, 0.0f); - var c2 = new Color(0.0f, 1.0f, 0.0f); - Color lerpColor = c1.Lerp(c2, 0.5f); // Equivalent to `new Color(0.5f, 0.5f, 0.0f)` + var red = new Color(1.0f, 0.0f, 0.0f); + var aqua = new Color(0.0f, 1.0f, 0.8f); + + red.Lerp(aqua, 0.2f); // Returns Color(0.8f, 0.2f, 0.16f) + red.Lerp(aqua, 0.5f); // Returns Color(0.5f, 0.5f, 0.4f) + red.Lerp(aqua, 1.0f); // Returns Color(0.0f, 1.0f, 0.8f) [/csharp] [/codeblocks] </description> @@ -310,15 +324,15 @@ <return type="Color" /> <param index="0" name="amount" type="float" /> <description> - Returns a new color resulting from making this color lighter by the specified percentage (ratio from 0 to 1). + Returns a new color resulting from making this color lighter by the specified [param amount], which should be a ratio from 0.0 to 1.0. See also [method darkened]. [codeblocks] [gdscript] var green = Color(0.0, 1.0, 0.0) - var lightgreen = green.lightened(0.2) # 20% lighter than regular green + var light_green = green.lightened(0.2) # 20% lighter than regular green [/gdscript] [csharp] var green = new Color(0.0f, 1.0f, 0.0f); - Color lightgreen = green.Lightened(0.2f); // 20% lighter than regular green + Color lightGreen = green.Lightened(0.2f); // 20% lighter than regular green [/csharp] [/codeblocks] </description> @@ -326,19 +340,19 @@ <method name="linear_to_srgb" qualifiers="const"> <return type="Color" /> <description> - Returns the color converted to the [url=https://en.wikipedia.org/wiki/SRGB]sRGB[/url] color space. This assumes the original color is in the linear color space. See also [method srgb_to_linear] which performs the opposite operation. + Returns the color converted to the [url=https://en.wikipedia.org/wiki/SRGB]sRGB[/url] color space. This method assumes the original color is in the linear color space. See also [method srgb_to_linear] which performs the opposite operation. </description> </method> <method name="srgb_to_linear" qualifiers="const"> <return type="Color" /> <description> - Returns the color converted to the linear color space. This assumes the original color is in the sRGB color space. See also [method linear_to_srgb] which performs the opposite operation. + Returns the color converted to the linear color space. This method assumes the original color already is in the sRGB color space. See also [method linear_to_srgb] which performs the opposite operation. </description> </method> <method name="to_abgr32" qualifiers="const"> <return type="int" /> <description> - Returns the color converted to a 32-bit integer in ABGR format (each byte represents a color channel). ABGR is the reversed version of the default format. + Returns the color converted to a 32-bit integer in ABGR format (each component is 8 bits). ABGR is the reversed version of the default RGBA format. [codeblocks] [gdscript] var color = Color(1, 0.5, 0.2) @@ -354,7 +368,7 @@ <method name="to_abgr64" qualifiers="const"> <return type="int" /> <description> - Returns the color converted to a 64-bit integer in ABGR format (each word represents a color channel). ABGR is the reversed version of the default format. + Returns the color converted to a 64-bit integer in ABGR format (each component is 16 bits). ABGR is the reversed version of the default RGBA format. [codeblocks] [gdscript] var color = Color(1, 0.5, 0.2) @@ -370,7 +384,7 @@ <method name="to_argb32" qualifiers="const"> <return type="int" /> <description> - Returns the color converted to a 32-bit integer in ARGB format (each byte represents a color channel). ARGB is more compatible with DirectX. + Returns the color converted to a 32-bit integer in ARGB format (each component is 8 bits). ARGB is more compatible with DirectX. [codeblocks] [gdscript] var color = Color(1, 0.5, 0.2) @@ -386,7 +400,7 @@ <method name="to_argb64" qualifiers="const"> <return type="int" /> <description> - Returns the color converted to a 64-bit integer in ARGB format (each word represents a color channel). ARGB is more compatible with DirectX. + Returns the color converted to a 64-bit integer in ARGB format (each component is 16 bits). ARGB is more compatible with DirectX. [codeblocks] [gdscript] var color = Color(1, 0.5, 0.2) @@ -403,18 +417,18 @@ <return type="String" /> <param index="0" name="with_alpha" type="bool" default="true" /> <description> - Returns the color converted to an HTML hexadecimal color string in RGBA format (ex: [code]ff34f822[/code]). - Setting [param with_alpha] to [code]false[/code] excludes alpha from the hexadecimal string (and uses RGB instead of RGBA format). + Returns the color converted to an HTML hexadecimal color [String] in RGBA format, without the hash ([code]#[/code]) prefix. + Setting [param with_alpha] to [code]false[/code], excludes alpha from the hexadecimal string, using RGB format instead of RGBA format. [codeblocks] [gdscript] - var color = Color(1, 1, 1, 0.5) - var with_alpha = color.to_html() # Returns "ffffff7f" - var without_alpha = color.to_html(false) # Returns "ffffff" + var white = Color(1, 1, 1, 0.5) + var with_alpha = white.to_html() # Returns "ffffff7f" + var without_alpha = white.to_html(false) # Returns "ffffff" [/gdscript] [csharp] - var color = new Color(1, 1, 1, 0.5f); - String withAlpha = color.ToHtml(); // Returns "ffffff7f" - String withoutAlpha = color.ToHtml(false); // Returns "ffffff" + var white = new Color(1, 1, 1, 0.5f); + string withAlpha = white.ToHtml(); // Returns "ffffff7f" + string withoutAlpha = white.ToHtml(false); // Returns "ffffff" [/csharp] [/codeblocks] </description> @@ -422,7 +436,7 @@ <method name="to_rgba32" qualifiers="const"> <return type="int" /> <description> - Returns the color converted to a 32-bit integer in RGBA format (each byte represents a color channel). RGBA is Godot's default format. + Returns the color converted to a 32-bit integer in RGBA format (each component is 8 bits). RGBA is Godot's default format. [codeblocks] [gdscript] var color = Color(1, 0.5, 0.2) @@ -438,7 +452,7 @@ <method name="to_rgba64" qualifiers="const"> <return type="int" /> <description> - Returns the color converted to a 64-bit integer in RGBA format (each word represents a color channel). RGBA is Godot's default format. + Returns the color converted to a 64-bit integer in RGBA format (each component is 16 bits). RGBA is Godot's default format. [codeblocks] [gdscript] var color = Color(1, 0.5, 0.2) @@ -457,19 +471,19 @@ The color's alpha component, typically on the range of 0 to 1. A value of 0 means that the color is fully transparent. A value of 1 means that the color is fully opaque. </member> <member name="a8" type="int" setter="" getter="" default="255"> - Wrapper for [member a] that uses the range 0 to 255 instead of 0 to 1. + Wrapper for [member a] that uses the range 0 to 255, instead of 0 to 1. </member> <member name="b" type="float" setter="" getter="" default="0.0"> The color's blue component, typically on the range of 0 to 1. </member> <member name="b8" type="int" setter="" getter="" default="0"> - Wrapper for [member b] that uses the range 0 to 255 instead of 0 to 1. + Wrapper for [member b] that uses the range 0 to 255, instead of 0 to 1. </member> <member name="g" type="float" setter="" getter="" default="0.0"> The color's green component, typically on the range of 0 to 1. </member> <member name="g8" type="int" setter="" getter="" default="0"> - Wrapper for [member g] that uses the range 0 to 255 instead of 0 to 1. + Wrapper for [member g] that uses the range 0 to 255, instead of 0 to 1. </member> <member name="h" type="float" setter="" getter="" default="0.0"> The HSV hue of this color, on the range 0 to 1. @@ -478,7 +492,7 @@ The color's red component, typically on the range of 0 to 1. </member> <member name="r8" type="int" setter="" getter="" default="0"> - Wrapper for [member r] that uses the range 0 to 255 instead of 0 to 1. + Wrapper for [member r] that uses the range 0 to 255, instead of 0 to 1. </member> <member name="s" type="float" setter="" getter="" default="0.0"> The HSV saturation of this color, on the range 0 to 1. @@ -510,7 +524,7 @@ Bisque color. </constant> <constant name="BLACK" value="Color(0, 0, 0, 1)"> - Black color. + Black color. In GDScript, this is the default value of any color. </constant> <constant name="BLANCHED_ALMOND" value="Color(1, 0.921569, 0.803922, 1)"> Blanched almond color. @@ -932,7 +946,7 @@ <return type="bool" /> <param index="0" name="right" type="Color" /> <description> - Returns [code]true[/code] if the colors are not equal. + Returns [code]true[/code] if the colors are not exactly equal. [b]Note:[/b] Due to floating-point precision errors, consider using [method is_equal_approx] instead, which is more reliable. </description> </operator> @@ -1004,7 +1018,7 @@ <return type="float" /> <param index="0" name="index" type="int" /> <description> - Access color components using their index. [code]c[0][/code] is equivalent to [code]c.r[/code], [code]c[1][/code] is equivalent to [code]c.g[/code], [code]c[2][/code] is equivalent to [code]c.b[/code], and [code]c[3][/code] is equivalent to [code]c.a[/code]. + Access color components using their index. [code][0][/code] is equivalent to [member r], [code][1][/code] is equivalent to [member g], [code][2][/code] is equivalent to [member b], and [code][3][/code] is equivalent to [member a]. </description> </operator> <operator name="operator unary+"> @@ -1016,7 +1030,7 @@ <operator name="operator unary-"> <return type="Color" /> <description> - Inverts the given color. This is equivalent to [code]Color.WHITE - c[/code] or [code]Color(1 - c.r, 1 - c.g, 1 - c.b, 1 - c.a)[/code]. + Inverts the given color. This is equivalent to [code]Color.WHITE - c[/code] or [code]Color(1 - c.r, 1 - c.g, 1 - c.b, 1 - c.a)[/code]. Unlike with [method inverted], the [member a] component is inverted, too. </description> </operator> </operators> diff --git a/doc/classes/Control.xml b/doc/classes/Control.xml index 8a38deeebe..fd6aab6a49 100644 --- a/doc/classes/Control.xml +++ b/doc/classes/Control.xml @@ -1071,7 +1071,8 @@ Tells the parent [Container] nodes how they should resize and place the node on the Y axis. Use one of the [enum SizeFlags] constants to change the flags. See the constants to learn what each does. </member> <member name="theme" type="Theme" setter="set_theme" getter="get_theme"> - The [Theme] resource this node and all its [Control] children use. If a child node has its own [Theme] resource set, theme items are merged with child's definitions having higher priority. + The [Theme] resource this node and all its [Control] and [Window] children use. If a child node has its own [Theme] resource set, theme items are merged with child's definitions having higher priority. + [b]Note:[/b] [Window] styles will have no effect unless the window is embedded. </member> <member name="theme_type_variation" type="StringName" setter="set_theme_type_variation" getter="get_theme_type_variation" default="&"""> The name of a theme type variation used by this [Control] to look up its own theme items. When empty, the class name of the node is used (e.g. [code]Button[/code] for the [Button] control), as well as the class names of all parent classes (in order of inheritance). diff --git a/doc/classes/Curve2D.xml b/doc/classes/Curve2D.xml index ccdf085319..b5e75dff68 100644 --- a/doc/classes/Curve2D.xml +++ b/doc/classes/Curve2D.xml @@ -51,7 +51,7 @@ <return type="Vector2" /> <param index="0" name="to_point" type="Vector2" /> <description> - Returns the closest baked point (in curve's local space) to [param to_point]. + Returns the closest point on baked segments (in curve's local space) to [param to_point]. [param to_point] must be in this curve's local space. </description> </method> @@ -94,7 +94,7 @@ </method> <method name="sample_baked" qualifiers="const"> <return type="Vector2" /> - <param index="0" name="offset" type="float" /> + <param index="0" name="offset" type="float" default="0.0" /> <param index="1" name="cubic" type="bool" default="false" /> <description> Returns a point within the curve at position [param offset], where [param offset] is measured as a pixel distance along the curve. @@ -104,13 +104,10 @@ </method> <method name="sample_baked_with_rotation" qualifiers="const"> <return type="Transform2D" /> - <param index="0" name="offset" type="float" /> + <param index="0" name="offset" type="float" default="0.0" /> <param index="1" name="cubic" type="bool" default="false" /> - <param index="2" name="loop" type="bool" default="true" /> - <param index="3" name="lookahead" type="float" default="4.0" /> <description> Similar to [method sample_baked], but returns [Transform2D] that includes a rotation along the curve. Returns empty transform if length of the curve is [code]0[/code]. - Use [param loop] to smooth the tangent at the end of the curve. [param lookahead] defines the distance to a nearby point for calculating the tangent vector. [codeblock] var transform = curve.sample_baked_with_rotation(offset) position = transform.get_origin() @@ -160,6 +157,13 @@ [param tolerance_degrees] controls how many degrees the midpoint of a segment may deviate from the real curve, before the segment has to be subdivided. </description> </method> + <method name="tessellate_even_length" qualifiers="const"> + <return type="PackedVector2Array" /> + <param index="0" name="max_stages" type="int" default="5" /> + <param index="1" name="tolerance_length" type="float" default="20.0" /> + <description> + </description> + </method> </methods> <members> <member name="bake_interval" type="float" setter="set_bake_interval" getter="get_bake_interval" default="5.0"> diff --git a/doc/classes/Curve3D.xml b/doc/classes/Curve3D.xml index 851996131f..cfe2036499 100644 --- a/doc/classes/Curve3D.xml +++ b/doc/classes/Curve3D.xml @@ -114,7 +114,7 @@ </method> <method name="sample_baked" qualifiers="const"> <return type="Vector3" /> - <param index="0" name="offset" type="float" /> + <param index="0" name="offset" type="float" default="0.0" /> <param index="1" name="cubic" type="bool" default="false" /> <description> Returns a point within the curve at position [param offset], where [param offset] is measured as a distance in 3D units along the curve. @@ -134,7 +134,7 @@ </method> <method name="sample_baked_with_rotation" qualifiers="const"> <return type="Transform3D" /> - <param index="0" name="offset" type="float" /> + <param index="0" name="offset" type="float" default="0.0" /> <param index="1" name="cubic" type="bool" default="false" /> <param index="2" name="apply_tilt" type="bool" default="false" /> <description> diff --git a/doc/classes/Dictionary.xml b/doc/classes/Dictionary.xml index 9842288d35..92225b816f 100644 --- a/doc/classes/Dictionary.xml +++ b/doc/classes/Dictionary.xml @@ -4,9 +4,8 @@ Dictionary type. </brief_description> <description> - Dictionary type. Associative container, which contains values referenced by unique keys. Dictionaries are composed of pairs of keys (which must be unique) and values. Dictionaries will preserve the insertion order when adding elements. In other programming languages, this data structure is sometimes referred to as a hash map or associative array. + Dictionary type. Associative container, which contains values referenced by unique keys. Dictionaries are composed of pairs of keys (which must be unique) and values. Dictionaries will preserve the insertion order when adding new entries. In other programming languages, this data structure is sometimes referred to as a hash map or associative array. You can define a dictionary by placing a comma-separated list of [code]key: value[/code] pairs in curly braces [code]{}[/code]. - Erasing elements while iterating over them [b]is not supported[/b] and will result in undefined behavior. [b]Note:[/b] Dictionaries are always passed by reference. To get a copy of a dictionary which can be modified independently of the original dictionary, use [method duplicate]. Creating a dictionary: [codeblocks] @@ -40,10 +39,10 @@ }; [/csharp] [/codeblocks] - You can access a dictionary's values by referencing the appropriate key. In the above example, [code]points_dict["White"][/code] will return [code]50[/code]. You can also write [code]points_dict.White[/code], which is equivalent. However, you'll have to use the bracket syntax if the key you're accessing the dictionary with isn't a fixed string (such as a number or variable). + You can access a dictionary's value by referencing its corresponding key. In the above example, [code]points_dict["White"][/code] will return [code]50[/code]. You can also write [code]points_dict.White[/code], which is equivalent. However, you'll have to use the bracket syntax if the key you're accessing the dictionary with isn't a fixed string (such as a number or variable). [codeblocks] [gdscript] - export(String, "White", "Yellow", "Orange") var my_color + @export(String, "White", "Yellow", "Orange") var my_color var points_dict = {"White": 50, "Yellow": 75, "Orange": 100} func _ready(): # We can't use dot syntax here as `my_color` is a variable. @@ -69,7 +68,9 @@ Dictionaries can contain more complex data: [codeblocks] [gdscript] - my_dict = {"First Array": [1, 2, 3, 4]} # Assigns an Array to a String key. + var my_dict = { + "First Array": [1, 2, 3, 4] # Assigns an Array to a String key. + } [/gdscript] [csharp] var myDict = new Godot.Collections.Dictionary @@ -91,7 +92,7 @@ {"Yellow", 75}, {"Orange", 100} }; - pointsDict["blue"] = 150; // Add "Blue" as a key and assign 150 as its value. + pointsDict["Blue"] = 150; // Add "Blue" as a key and assign 150 as its value. [/csharp] [/codeblocks] Finally, dictionaries can contain different types of keys and values in the same dictionary: @@ -118,63 +119,23 @@ }; [/csharp] [/codeblocks] - [b]Note:[/b] Unlike [Array]s, you can't compare dictionaries directly: + The keys of a dictionary can be iterated with the [code]for[/code] keyword: [codeblocks] [gdscript] - var array1 = [1, 2, 3] - var array2 = [1, 2, 3] - - func compare_arrays(): - print(array1 == array2) # Will print true. - - var dict1 = {"a": 1, "b": 2, "c": 3} - var dict2 = {"a": 1, "b": 2, "c": 3} - - func compare_dictionaries(): - print(dict1 == dict2) # Will NOT print true. + var groceries = {"Orange": 20, "Apple": 2, "Banana": 4} + for fruit in groceries: + var amount = groceries[fruit] [/gdscript] [csharp] - // You have to use GD.Hash(). - - public Godot.Collections.Array array1 = new Godot.Collections.Array{1, 2, 3}; - public Godot.Collections.Array array2 = new Godot.Collections.Array{1, 2, 3}; - - public void CompareArrays() + var groceries = new Godot.Collections.Dictionary{{"Orange", 20}, {"Apple", 2}, {"Banana", 4}}; + foreach (var (fruit, amount) in groceries) { - GD.Print(array1 == array2); // Will print FALSE!! - GD.Print(GD.Hash(array1) == GD.Hash(array2)); // Will print true. - } - - public Godot.Collections.Dictionary dict1 = new Godot.Collections.Dictionary{{"a", 1}, {"b", 2}, {"c", 3}}; - public Godot.Collections.Dictionary dict2 = new Godot.Collections.Dictionary{{"a", 1}, {"b", 2}, {"c", 3}}; - - public void CompareDictionaries() - { - GD.Print(dict1 == dict2); // Will NOT print true. + // `fruit` is the key, `amount` is the value. } [/csharp] [/codeblocks] - You need to first calculate the dictionary's hash with [method hash] before you can compare them: - [codeblocks] - [gdscript] - var dict1 = {"a": 1, "b": 2, "c": 3} - var dict2 = {"a": 1, "b": 2, "c": 3} - - func compare_dictionaries(): - print(dict1.hash() == dict2.hash()) # Will print true. - [/gdscript] - [csharp] - // You have to use GD.Hash(). - public Godot.Collections.Dictionary dict1 = new Godot.Collections.Dictionary{{"a", 1}, {"b", 2}, {"c", 3}}; - public Godot.Collections.Dictionary dict2 = new Godot.Collections.Dictionary{{"a", 1}, {"b", 2}, {"c", 3}}; - - public void CompareDictionaries() - { - GD.Print(GD.Hash(dict1) == GD.Hash(dict2)); // Will print true. - } - [/csharp] - [/codeblocks] - [b]Note:[/b] When declaring a dictionary with [code]const[/code], the dictionary itself can still be mutated by defining the values of individual keys. Using [code]const[/code] will only prevent assigning the constant with another value after it was initialized. + [b]Note:[/b] Erasing elements while iterating over dictionaries is [b]not[/b] supported and will result in unpredictable behavior. + [b]Note:[/b] When declaring a dictionary with [code]const[/code], the dictionary becomes read-only. A read-only Dictionary's entries cannot be overriden at run-time. This does [i]not[/i] affect nested [Array] and [Dictionary] values. </description> <tutorials> <link title="GDScript basics: Dictionary">$DOCS_URL/tutorials/scripting/gdscript/gdscript_basics.html#dictionary</link> @@ -192,7 +153,7 @@ <return type="Dictionary" /> <param index="0" name="from" type="Dictionary" /> <description> - Constructs a [Dictionary] as a copy of the given [Dictionary]. + Returns the same array as [param from]. If you need a copy of the array, use [method duplicate]. </description> </constructor> </constructors> @@ -200,30 +161,30 @@ <method name="clear"> <return type="void" /> <description> - Clear the dictionary, removing all key/value pairs. + Clears the dictionary, removing all entries from it. </description> </method> <method name="duplicate" qualifiers="const"> <return type="Dictionary" /> <param index="0" name="deep" type="bool" default="false" /> <description> - Creates a copy of the dictionary, and returns it. The [param deep] parameter causes inner dictionaries and arrays to be copied recursively, but does not apply to objects. + Creates and returns a new copy of the dictionary. If [param deep] is [code]true[/code], inner [Dictionary] and [Array] keys and values are also copied, recursively. </description> </method> <method name="erase"> <return type="bool" /> <param index="0" name="key" type="Variant" /> <description> - Erase a dictionary key/value pair by key. Returns [code]true[/code] if the given key was present in the dictionary, [code]false[/code] otherwise. - [b]Note:[/b] Don't erase elements while iterating over the dictionary. You can iterate over the [method keys] array instead. + Removes the dictionary entry by key, if it exists. Returns [code]true[/code] if the given [param key] existed in the dictionary, otherwise [code]false[/code]. + [b]Note:[/b] Do not erase entries while iterating over the dictionary. You can iterate over the [method keys] array instead. </description> </method> <method name="find_key" qualifiers="const"> <return type="Variant" /> <param index="0" name="value" type="Variant" /> <description> - Returns the first key whose associated value is equal to [param value], or [code]null[/code] if no such value is found. - [b]Note:[/b] [code]null[/code] is also a valid key. If you have it in your [Dictionary], the [method find_key] method can give misleading results. + Finds and returns the first key whose associated value is equal to [param value], or [code]null[/code] if it is not found. + [b]Note:[/b] [code]null[/code] is also a valid key. If inside the dictionary, [method find_key] may give misleading results. </description> </method> <method name="get" qualifiers="const"> @@ -231,72 +192,89 @@ <param index="0" name="key" type="Variant" /> <param index="1" name="default" type="Variant" default="null" /> <description> - Returns the current value for the specified key in the [Dictionary]. If the key does not exist, the method returns the value of the optional default argument, or [code]null[/code] if it is omitted. + Returns the corresponding value for the given [param key] in the dictionary. If the [param key] does not exist, returns [param default], or [code]null[/code] if the parameter is omitted. </description> </method> <method name="has" qualifiers="const"> <return type="bool" /> <param index="0" name="key" type="Variant" /> <description> - Returns [code]true[/code] if the dictionary has a given key. - [b]Note:[/b] This is equivalent to using the [code]in[/code] operator as follows: + Returns [code]true[/code] if the dictionary contains an entry with the given [param key]. [codeblocks] [gdscript] - # Will evaluate to `true`. - if "godot" in {"godot": "engine"}: - pass + var my_dict = { + "Godot" : 4, + 210 : null, + } + + print(my_dict.has("Godot")) # Prints true + print(my_dict.has(210)) # Prints true + print(my_dict.has(4)) # Prints false [/gdscript] [csharp] - // You have to use Contains() here as an alternative to GDScript's `in` operator. - if (new Godot.Collections.Dictionary{{"godot", "engine"}}.Contains("godot")) + var myDict = new Godot.Collections.Dictionary { - // I am executed. - } + { "Godot", 4 }, + { 210, default }, + }; + + GD.Print(myDict.Contains("Godot")); // Prints true + GD.Print(myDict.Contains(210)); // Prints true + GD.Print(myDict.Contains(4)); // Prints false [/csharp] [/codeblocks] - This method (like the [code]in[/code] operator) will evaluate to [code]true[/code] as long as the key exists, even if the associated value is [code]null[/code]. + In GDScript, this is equivalent to the [code]in[/code] operator: + [codeblock] + if "Godot" in {"Godot": 4}: + print("The key is here!") # Will be printed. + [/codeblock] + [b]Note:[/b] This method returns [code]true[/code] as long as the [param key] exists, even if its corresponding value is [code]null[/code]. </description> </method> <method name="has_all" qualifiers="const"> <return type="bool" /> <param index="0" name="keys" type="Array" /> <description> - Returns [code]true[/code] if the dictionary has all the keys in the given array. + Returns [code]true[/code] if the dictionary contains all keys in the given [param keys] array. + [codeblock] + var data = {"width" : 10, "height" : 20} + data.has_all(["height", "width"]) # Returns true + [/codeblock] </description> </method> <method name="hash" qualifiers="const"> <return type="int" /> <description> - Returns a hashed 32-bit integer value representing the dictionary contents. This can be used to compare dictionaries by value: + Returns a hashed 32-bit integer value representing the dictionary contents. [codeblocks] [gdscript] - var dict1 = {0: 10} - var dict2 = {0: 10} - # The line below prints `true`, whereas it would have printed `false` if both variables were compared directly. - print(dict1.hash() == dict2.hash()) + var dict1 = {"A": 10, "B": 2} + var dict2 = {"A": 10, "B": 2} + + print(dict1.hash() == dict2.hash()) # Prints true [/gdscript] [csharp] - var dict1 = new Godot.Collections.Dictionary{{0, 10}}; - var dict2 = new Godot.Collections.Dictionary{{0, 10}}; - // The line below prints `true`, whereas it would have printed `false` if both variables were compared directly. - // Dictionary has no Hash() method. Use GD.Hash() instead. - GD.Print(GD.Hash(dict1) == GD.Hash(dict2)); + var dict1 = new Godot.Collections.Dictionary{{"A", 10}, {"B", 2}}; + var dict2 = new Godot.Collections.Dictionary{{"A", 10}, {"B", 2}}; + + // Godot.Collections.Dictionary has no Hash() method. Use GD.Hash() instead. + GD.Print(GD.Hash(dict1) == GD.Hash(dict2)); // Prints true [/csharp] [/codeblocks] - [b]Note:[/b] Dictionaries with the same keys/values but in a different order will have a different hash. - [b]Note:[/b] Dictionaries with equal content will always produce identical hash values. However, the reverse is not true. Returning identical hash values does [i]not[/i] imply the dictionaries are equal, because different dictionaries can have identical hash values due to hash collisions. + [b]Note:[/b] Dictionaries with the same entries but in a different order will not have the same hash. + [b]Note:[/b] Dictionaries with equal hash values are [i]not[/i] guaranteed to be the same, because of hash collisions. On the countrary, dictionaries with different hash values are guaranteed to be different. </description> </method> <method name="is_empty" qualifiers="const"> <return type="bool" /> <description> - Returns [code]true[/code] if the dictionary is empty. + Returns [code]true[/code] if the dictionary is empty (its size is [code]0[/code]). See also [method size]. </description> </method> <method name="keys" qualifiers="const"> <return type="Array" /> <description> - Returns the list of keys in the [Dictionary]. + Returns the list of keys in the dictionary. </description> </method> <method name="merge"> @@ -304,19 +282,19 @@ <param index="0" name="dictionary" type="Dictionary" /> <param index="1" name="overwrite" type="bool" default="false" /> <description> - Adds elements from [param dictionary] to this [Dictionary]. By default, duplicate keys will not be copied over, unless [param overwrite] is [code]true[/code]. + Adds entries from [param dictionary] to this dictionary. By default, duplicate keys are not copied over, unless [param overwrite] is [code]true[/code]. </description> </method> <method name="size" qualifiers="const"> <return type="int" /> <description> - Returns the number of keys in the dictionary. + Returns the number of entries in the dictionary. Empty dictionaries ([code]{ }[/code]) always return [code]0[/code]. See also [method is_empty]. </description> </method> <method name="values" qualifiers="const"> <return type="Array" /> <description> - Returns the list of values in the [Dictionary]. + Returns the list of values in this dictionary. </description> </method> </methods> @@ -325,21 +303,22 @@ <return type="bool" /> <param index="0" name="right" type="Dictionary" /> <description> - Returns [code]true[/code] if the dictionaries differ, i.e. their key or value lists are different (including the order). + Returns [code]true[/code] if the two dictionaries do not contain the same keys and values. </description> </operator> <operator name="operator =="> <return type="bool" /> <param index="0" name="right" type="Dictionary" /> <description> - Returns [code]true[/code] if both dictionaries have the same contents, i.e. their keys list and value list are equal. + Returns [code]true[/code] if the two dictionaries contain the same keys and values. The order of the entries does not matter. + [b]Note:[/b] In C#, by convention, this operator compares by [b]reference[/b]. If you need to compare by value, iterate over both dictionaries. </description> </operator> <operator name="operator []"> <return type="Variant" /> <param index="0" name="key" type="Variant" /> <description> - Returns a value at the given [param key] or [code]null[/code] and error if the key does not exist. For safe access, use [method get] or [method has]. + Returns the corresponding value for the given [param key] in the dictionary. If the entry does not exist, fails and returns [code]null[/code]. For safe access, use [method get] or [method has]. </description> </operator> </operators> diff --git a/doc/classes/DisplayServer.xml b/doc/classes/DisplayServer.xml index 0039301bf6..29135376c5 100644 --- a/doc/classes/DisplayServer.xml +++ b/doc/classes/DisplayServer.xml @@ -719,6 +719,12 @@ [b]Note:[/b] This method is implemented on macOS, Windows and Linux (X11). </description> </method> + <method name="is_touchscreen_available" qualifiers="const"> + <return type="bool" /> + <description> + Returns [code]true[/code] if touch events are available (Android or iOS), the capability is detected on the Webplatform or if [member ProjectSettings.input_devices/pointing/emulate_touch_from_mouse] is [code]true[/code]. + </description> + </method> <method name="keyboard_get_current_layout" qualifiers="const"> <return type="int" /> <description> @@ -889,13 +895,6 @@ Returns [code]true[/code] if the screen should never be turned off by the operating system's power-saving measures. See also [method screen_set_keep_on]. </description> </method> - <method name="screen_is_touchscreen" qualifiers="const"> - <return type="bool" /> - <param index="0" name="screen" type="int" default="-1" /> - <description> - Returns [code]true[/code] if the screen can send touch events or if [member ProjectSettings.input_devices/pointing/emulate_touch_from_mouse] is [code]true[/code]. - </description> - </method> <method name="screen_set_keep_on"> <return type="void" /> <param index="0" name="enable" type="bool" /> @@ -1156,14 +1155,14 @@ <return type="Vector2i" /> <param index="0" name="window_id" type="int" default="0" /> <description> - Returns the position of the given window to on the screen. + Returns the position of the client area of the given window on the screen. </description> </method> - <method name="window_get_real_size" qualifiers="const"> + <method name="window_get_position_with_decorations" qualifiers="const"> <return type="Vector2i" /> <param index="0" name="window_id" type="int" default="0" /> <description> - Returns the size of the window specified by [param window_id] (in pixels), including the borders drawn by the operating system. See also [method window_get_size]. + Returns the position of the given window on the screen including the borders drawn by the operating system. See also [method window_get_position]. </description> </method> <method name="window_get_safe_title_margins" qualifiers="const"> @@ -1177,7 +1176,14 @@ <return type="Vector2i" /> <param index="0" name="window_id" type="int" default="0" /> <description> - Returns the size of the window specified by [param window_id] (in pixels), excluding the borders drawn by the operating system. This is also called the "client area". See also [method window_get_real_size], [method window_set_size] and [method window_get_position]. + Returns the size of the window specified by [param window_id] (in pixels), excluding the borders drawn by the operating system. This is also called the "client area". See also [method window_get_size_with_decorations], [method window_set_size] and [method window_get_position]. + </description> + </method> + <method name="window_get_size_with_decorations" qualifiers="const"> + <return type="Vector2i" /> + <param index="0" name="window_id" type="int" default="0" /> + <description> + Returns the size of the window specified by [param window_id] (in pixels), including the borders drawn by the operating system. See also [method window_get_size]. </description> </method> <method name="window_get_vsync_mode" qualifiers="const"> @@ -1634,14 +1640,17 @@ Maximized window mode, i.e. [Window] will occupy whole screen area except task bar and still display its borders. Normally happens when the minimize button is pressed. </constant> <constant name="WINDOW_MODE_FULLSCREEN" value="3" enum="WindowMode"> - Full screen window mode. Note that this is not [i]exclusive[/i] full screen. On Windows and Linux (X11), a borderless window is used to emulate full screen. On macOS, a new desktop is used to display the running project. - Regardless of the platform, enabling full screen will change the window size to match the monitor's size. Therefore, make sure your project supports [url=$DOCS_URL/tutorials/rendering/multiple_resolutions.html]multiple resolutions[/url] when enabling full screen mode. + Full screen mode with full multi-window support. + Full screen window cover the entire display area of a screen, have no border or decorations. Display video mode is not changed. + [b]Note:[/b] Regardless of the platform, enabling full screen will change the window size to match the monitor's size. Therefore, make sure your project supports [url=$DOCS_URL/tutorials/rendering/multiple_resolutions.html]multiple resolutions[/url] when enabling full screen mode. </constant> <constant name="WINDOW_MODE_EXCLUSIVE_FULLSCREEN" value="4" enum="WindowMode"> - Exclusive full screen window mode. This mode is implemented on Windows and macOS only. On other platforms, it is equivalent to [constant WINDOW_MODE_FULLSCREEN]. - [b]On Windows:[/b] Only one window in exclusive full screen mode can be visible on a given screen at a time. If multiple windows are in exclusive full screen mode for the same screen, the last one being set to this mode takes precedence. - [b]On macOS:[/b] Exclusive full-screen mode prevents Dock and Menu from showing up when the mouse pointer is hovering the edge of the screen. - Regardless of the platform, enabling full screen will change the window size to match the monitor's size. Therefore, make sure your project supports [url=$DOCS_URL/tutorials/rendering/multiple_resolutions.html]multiple resolutions[/url] when enabling full screen mode. + A single window full screen mode. This mode has less overhead, but only one window can be open on a given screen at a time (opening a child window or application switching will trigger a full screen transition). + Full screen window cover the entire display area of a screen, have no border or decorations. Display video mode is not changed. + [b]On Windows:[/b] Depending on video driver, full screen transition might cause screens to go black for a moment. + [b]On macOS:[/b] Exclusive full screen mode prevents Dock and Menu from showing up when the mouse pointer is hovering the edge of the screen. + [b]On Linux (X11):[/b] Exclusive full screen mode bypasses compositor. + [b]Note:[/b] Regardless of the platform, enabling full screen will change the window size to match the monitor's size. Therefore, make sure your project supports [url=$DOCS_URL/tutorials/rendering/multiple_resolutions.html]multiple resolutions[/url] when enabling full screen mode. </constant> <constant name="WINDOW_FLAG_RESIZE_DISABLED" value="0" enum="WindowFlags"> The window can't be resizing by dragging its resize grip. It's still possible to resize the window using [method window_set_size]. This flag is ignored for full screen windows. @@ -1715,6 +1724,7 @@ <constant name="DISPLAY_HANDLE" value="0" enum="HandleType"> Display handle: - Linux (X11): [code]X11::Display*[/code] for the display. + - Android: [code]EGLDisplay[/code] for the display. </constant> <constant name="WINDOW_HANDLE" value="1" enum="HandleType"> Window handle: diff --git a/doc/classes/FileAccess.xml b/doc/classes/FileAccess.xml index e52f897164..be0c8fd6ca 100644 --- a/doc/classes/FileAccess.xml +++ b/doc/classes/FileAccess.xml @@ -153,6 +153,20 @@ Returns the last error that happened when trying to perform operations. Compare with the [code]ERR_FILE_*[/code] constants from [enum Error]. </description> </method> + <method name="get_file_as_bytes" qualifiers="static"> + <return type="PackedByteArray" /> + <param index="0" name="path" type="String" /> + <description> + Returns the whole [param path] file contents as a [PackedByteArray] without any decoding. + </description> + </method> + <method name="get_file_as_string" qualifiers="static"> + <return type="String" /> + <param index="0" name="path" type="String" /> + <description> + Returns the whole [param path] file contents as a [String]. Text is interpreted as being UTF-8 encoded. + </description> + </method> <method name="get_float" qualifiers="const"> <return type="float" /> <description> diff --git a/doc/classes/Font.xml b/doc/classes/Font.xml index 6a42b62bcf..761e75339a 100644 --- a/doc/classes/Font.xml +++ b/doc/classes/Font.xml @@ -161,6 +161,12 @@ Returns font family name. </description> </method> + <method name="get_font_stretch" qualifiers="const"> + <return type="int" /> + <description> + Returns font stretch amount, compared to a normal width. A percentage value between [code]50%[/code] and [code]200%[/code]. + </description> + </method> <method name="get_font_style" qualifiers="const"> <return type="int" enum="TextServer.FontStyle" /> <description> @@ -173,6 +179,12 @@ Returns font style name. </description> </method> + <method name="get_font_weight" qualifiers="const"> + <return type="int" /> + <description> + Returns weight (boldness) of the font. A value in the [code]100...999[/code] range, normal font weight is [code]400[/code], bold font weight is [code]700[/code]. + </description> + </method> <method name="get_height" qualifiers="const"> <return type="float" /> <param index="0" name="font_size" type="int" default="16" /> diff --git a/doc/classes/FontFile.xml b/doc/classes/FontFile.xml index 271f6a13e0..1019c271dc 100644 --- a/doc/classes/FontFile.xml +++ b/doc/classes/FontFile.xml @@ -542,6 +542,9 @@ </method> </methods> <members> + <member name="allow_system_fallback" type="bool" setter="set_allow_system_fallback" getter="is_allow_system_fallback" default="true"> + If set to [code]true[/code], system fonts can be automatically used as fallbacks. + </member> <member name="antialiasing" type="int" setter="set_antialiasing" getter="get_antialiasing" enum="TextServer.FontAntialiasing" default="1"> Font anti-aliasing mode. </member> @@ -557,9 +560,15 @@ <member name="font_name" type="String" setter="set_font_name" getter="get_font_name" default=""""> Font family name. </member> + <member name="font_stretch" type="int" setter="set_font_stretch" getter="get_font_stretch" default="100"> + Font stretch amount, compared to a normal width. A percentage value between [code]50%[/code] and [code]200%[/code]. + </member> <member name="font_style" type="int" setter="set_font_style" getter="get_font_style" enum="TextServer.FontStyle" default="0"> Font style flags, see [enum TextServer.FontStyle]. </member> + <member name="font_weight" type="int" setter="set_font_weight" getter="get_font_weight" default="400"> + Weight (boldness) of the font. A value in the [code]100...999[/code] range, normal font weight is [code]400[/code], bold font weight is [code]700[/code]. + </member> <member name="force_autohinter" type="bool" setter="set_force_autohinter" getter="is_force_autohinter" default="false"> If set to [code]true[/code], auto-hinting is supported and preferred over font built-in hinting. Used by dynamic fonts only. </member> diff --git a/doc/classes/Light3D.xml b/doc/classes/Light3D.xml index 60e20cd97d..fe7756faaf 100644 --- a/doc/classes/Light3D.xml +++ b/doc/classes/Light3D.xml @@ -114,7 +114,7 @@ <member name="shadow_enabled" type="bool" setter="set_shadow" getter="has_shadow" default="false"> If [code]true[/code], the light will cast real-time shadows. This has a significant performance cost. Only enable shadow rendering when it makes a noticeable difference in the scene's appearance, and consider using [member distance_fade_enabled] to hide the light when far away from the [Camera3D]. </member> - <member name="shadow_normal_bias" type="float" setter="set_param" getter="get_param" default="1.0"> + <member name="shadow_normal_bias" type="float" setter="set_param" getter="get_param" default="2.0"> Offsets the lookup into the shadow map by the object's normal. This can be used to reduce self-shadowing artifacts without using [member shadow_bias]. In practice, this value should be tweaked along with [member shadow_bias] to reduce artifacts as much as possible. </member> <member name="shadow_opacity" type="float" setter="set_param" getter="get_param" default="1.0"> diff --git a/doc/classes/OS.xml b/doc/classes/OS.xml index 610f77e3d8..0efc6ab399 100644 --- a/doc/classes/OS.xml +++ b/doc/classes/OS.xml @@ -394,18 +394,38 @@ <method name="get_system_font_path" qualifiers="const"> <return type="String" /> <param index="0" name="font_name" type="String" /> - <param index="1" name="bold" type="bool" default="false" /> - <param index="2" name="italic" type="bool" default="false" /> + <param index="1" name="weight" type="int" default="400" /> + <param index="2" name="stretch" type="int" default="100" /> + <param index="3" name="italic" type="bool" default="false" /> <description> - Returns path to the system font file with [param font_name] and style. Return empty string if no matching fonts found. - [b]Note:[/b] This method is implemented on iOS, Linux, macOS and Windows. + Returns path to the system font file with [param font_name] and style. Returns empty string if no matching fonts found. + The following aliases can be used to request default fonts: "sans-serif", "serif", "monospace", "cursive", and "fantasy". + [b]Note:[/b] Returned font might have different style if the requested style is not available. + [b]Note:[/b] This method is implemented on Android, iOS, Linux, macOS and Windows. + </description> + </method> + <method name="get_system_font_path_for_text" qualifiers="const"> + <return type="PackedStringArray" /> + <param index="0" name="font_name" type="String" /> + <param index="1" name="text" type="String" /> + <param index="2" name="locale" type="String" default="""" /> + <param index="3" name="script" type="String" default="""" /> + <param index="4" name="weight" type="int" default="400" /> + <param index="5" name="stretch" type="int" default="100" /> + <param index="6" name="italic" type="bool" default="false" /> + <description> + Returns an array of the system substitute font file paths, which are similar to the font with [param font_name] and style for the specified text, locale and script. Returns empty array if no matching fonts found. + The following aliases can be used to request default fonts: "sans-serif", "serif", "monospace", "cursive", and "fantasy". + [b]Note:[/b] Depending on OS, it's not guaranteed that any of the returned fonts is suitable for rendering specified text. Fonts should be loaded and checked in the order they are returned, and the first suitable one used. + [b]Note:[/b] Returned fonts might have different style if the requested style is not available or belong to a different font family. + [b]Note:[/b] This method is implemented on Android, iOS, Linux, macOS and Windows. </description> </method> <method name="get_system_fonts" qualifiers="const"> <return type="PackedStringArray" /> <description> Returns list of font family names available. - [b]Note:[/b] This method is implemented on iOS, Linux, macOS and Windows. + [b]Note:[/b] This method is implemented on Android, iOS, Linux, macOS and Windows. </description> </method> <method name="get_thread_caller_id" qualifiers="const"> diff --git a/doc/classes/Object.xml b/doc/classes/Object.xml index bf15f96291..5e834b3d91 100644 --- a/doc/classes/Object.xml +++ b/doc/classes/Object.xml @@ -764,6 +764,22 @@ Emits the [signal property_list_changed] signal. This is mainly used to refresh the editor, so that the Inspector and editor plugins are properly updated. </description> </method> + <method name="property_can_revert" qualifiers="const"> + <return type="bool" /> + <param index="0" name="property" type="StringName" /> + <description> + Returns [code]true[/code] if the given [param property] has a custom default value. Use [method property_get_revert] to get the [param property]'s default value. + [b]Note:[/b] This method is used by the Inspector dock to display a revert icon. The object must implement [method _property_can_revert] to customize the default value. If [method _property_can_revert] is not implemented, this method returns [code]false[/code]. + </description> + </method> + <method name="property_get_revert" qualifiers="const"> + <return type="Variant" /> + <param index="0" name="property" type="StringName" /> + <description> + Returns the custom default value of the given [param property]. Use [method property_can_revert] to check if the [param property] has a custom default value. + [b]Note:[/b] This method is used by the Inspector dock to display a revert icon. The object must implement [method _property_get_revert] to customize the default value. If [method _property_get_revert] is not implemented, this method returns [code]null[/code]. + </description> + </method> <method name="remove_meta"> <return type="void" /> <param index="0" name="name" type="StringName" /> diff --git a/doc/classes/OmniLight3D.xml b/doc/classes/OmniLight3D.xml index 193ae8deeb..f71c81e713 100644 --- a/doc/classes/OmniLight3D.xml +++ b/doc/classes/OmniLight3D.xml @@ -20,7 +20,7 @@ <member name="omni_shadow_mode" type="int" setter="set_shadow_mode" getter="get_shadow_mode" enum="OmniLight3D.ShadowMode" default="1"> See [enum ShadowMode]. </member> - <member name="shadow_bias" type="float" setter="set_param" getter="get_param" overrides="Light3D" default="0.2" /> + <member name="shadow_normal_bias" type="float" setter="set_param" getter="get_param" overrides="Light3D" default="1.0" /> </members> <constants> <constant name="SHADOW_DUAL_PARABOLOID" value="0" enum="ShadowMode"> diff --git a/doc/classes/PhysicsPointQueryParameters2D.xml b/doc/classes/PhysicsPointQueryParameters2D.xml index e49d2a9f5f..76dc816dab 100644 --- a/doc/classes/PhysicsPointQueryParameters2D.xml +++ b/doc/classes/PhysicsPointQueryParameters2D.xml @@ -10,7 +10,7 @@ </tutorials> <members> <member name="canvas_instance_id" type="int" setter="set_canvas_instance_id" getter="get_canvas_instance_id" default="0"> - If different from [code]0[/code], restricts the query to a specific canvas layer specified by its instance id. See [method Object.get_instance_id]. + If different from [code]0[/code], restricts the query to a specific canvas layer specified by its instance ID. See [method Object.get_instance_id]. </member> <member name="collide_with_areas" type="bool" setter="set_collide_with_areas" getter="is_collide_with_areas_enabled" default="false"> If [code]true[/code], the query will take [Area2D]s into account. diff --git a/doc/classes/PopupMenu.xml b/doc/classes/PopupMenu.xml index a69163f429..6810b0e8e4 100644 --- a/doc/classes/PopupMenu.xml +++ b/doc/classes/PopupMenu.xml @@ -206,7 +206,7 @@ <return type="int" /> <param index="0" name="index" type="int" /> <description> - Returns the id of the item at the given [param index]. [code]id[/code] can be manually assigned, while index can not. + Returns the ID of the item at the given [param index]. [code]id[/code] can be manually assigned, while index can not. </description> </method> <method name="get_item_indent" qualifiers="const"> diff --git a/doc/classes/ProjectSettings.xml b/doc/classes/ProjectSettings.xml index 1f0a8d91fa..dce9d5a55c 100644 --- a/doc/classes/ProjectSettings.xml +++ b/doc/classes/ProjectSettings.xml @@ -2299,6 +2299,9 @@ <member name="xr/openxr/reference_space" type="int" setter="" getter="" default=""1""> Specify the default reference space. </member> + <member name="xr/openxr/submit_depth_buffer" type="bool" setter="" getter="" default="false"> + If [code]true[/code], OpenXR will manage the depth buffer and use the depth buffer for advanced reprojection provided this is supported by the XR runtime. Note that some rendering features in Godot can't be used with this feature. + </member> <member name="xr/openxr/view_configuration" type="int" setter="" getter="" default=""1""> Specify the view configuration with which to configure OpenXR setting up either Mono or Stereo rendering. </member> diff --git a/doc/classes/RID.xml b/doc/classes/RID.xml index a6523e4c8b..2d40a7be57 100644 --- a/doc/classes/RID.xml +++ b/doc/classes/RID.xml @@ -4,7 +4,8 @@ Handle for a [Resource]'s unique ID. </brief_description> <description> - The RID type is used to access the unique integer ID of a resource. They are opaque, which means they do not grant access to the associated resource by themselves. They are used by and with the low-level Server classes such as [RenderingServer]. + The RID [Variant] type is used to access a low-level resource by its unique ID. RIDs are opaque, which means they do not grant access to the resource by themselves. They are used by the low-level server classes, such as [DisplayServer], [RenderingServer], [TextServer], etc. + A low-level resource may correspond to a high-level [Resource], such as [Texture] or [Mesh]. </description> <tutorials> </tutorials> @@ -27,13 +28,13 @@ <method name="get_id" qualifiers="const"> <return type="int" /> <description> - Returns the ID of the referenced resource. + Returns the ID of the referenced low-level resource. </description> </method> <method name="is_valid" qualifiers="const"> <return type="bool" /> <description> - Returns [code]true[/code] if [RID] is valid. + Returns [code]true[/code] if the [RID] is not [code]0[/code]. </description> </method> </methods> @@ -42,36 +43,42 @@ <return type="bool" /> <param index="0" name="right" type="RID" /> <description> + Returns [code]true[/code] if the [RID]s are not equal. </description> </operator> <operator name="operator <"> <return type="bool" /> <param index="0" name="right" type="RID" /> <description> + Returns [code]true[/code] if the [RID]'s ID is less than [param right]'s ID. </description> </operator> <operator name="operator <="> <return type="bool" /> <param index="0" name="right" type="RID" /> <description> + Returns [code]true[/code] if the [RID]'s ID is less than or equal to [param right]'s ID. </description> </operator> <operator name="operator =="> <return type="bool" /> <param index="0" name="right" type="RID" /> <description> + Returns [code]true[/code] if both [RID]s are equal, which means they both refer to the same low-level resource. </description> </operator> <operator name="operator >"> <return type="bool" /> <param index="0" name="right" type="RID" /> <description> + Returns [code]true[/code] if the [RID]'s ID is greater than [param right]'s ID. </description> </operator> <operator name="operator >="> <return type="bool" /> <param index="0" name="right" type="RID" /> <description> + Returns [code]true[/code] if the [RID]'s ID is greater than or equal to [param right]'s ID. </description> </operator> </operators> diff --git a/doc/classes/RenderingServer.xml b/doc/classes/RenderingServer.xml index 2ffa4dc50b..fc05f67416 100644 --- a/doc/classes/RenderingServer.xml +++ b/doc/classes/RenderingServer.xml @@ -1295,13 +1295,13 @@ <method name="get_test_cube"> <return type="RID" /> <description> - Returns the id of the test cube. Creates one if none exists. + Returns the ID of the test cube. Creates one if none exists. </description> </method> <method name="get_test_texture"> <return type="RID" /> <description> - Returns the id of the test texture. Creates one if none exists. + Returns the ID of the test texture. Creates one if none exists. </description> </method> <method name="get_video_adapter_api_version" qualifiers="const"> @@ -1335,7 +1335,7 @@ <method name="get_white_texture"> <return type="RID" /> <description> - Returns the id of a white texture. Creates one if none exists. + Returns the ID of a white texture. Creates one if none exists. </description> </method> <method name="gi_set_use_half_resolution"> diff --git a/doc/classes/RichTextLabel.xml b/doc/classes/RichTextLabel.xml index cb2481f705..e222894647 100644 --- a/doc/classes/RichTextLabel.xml +++ b/doc/classes/RichTextLabel.xml @@ -399,6 +399,12 @@ Scrolls the window's top line to match first line of the [param paragraph]. </description> </method> + <method name="scroll_to_selection"> + <return type="void" /> + <description> + Scrolls to the beginning of the current selection. + </description> + </method> <method name="select_all"> <return type="void" /> <description> diff --git a/doc/classes/SpotLight3D.xml b/doc/classes/SpotLight3D.xml index 28e2ef0d95..59d36aefab 100644 --- a/doc/classes/SpotLight3D.xml +++ b/doc/classes/SpotLight3D.xml @@ -12,6 +12,7 @@ </tutorials> <members> <member name="shadow_bias" type="float" setter="set_param" getter="get_param" overrides="Light3D" default="0.03" /> + <member name="shadow_normal_bias" type="float" setter="set_param" getter="get_param" overrides="Light3D" default="1.0" /> <member name="spot_angle" type="float" setter="set_param" getter="get_param" default="45.0"> The spotlight's angle in degrees. [b]Note:[/b] [member spot_angle] is not affected by [member Node3D.scale] (the light's scale or its parent's scale). diff --git a/doc/classes/String.xml b/doc/classes/String.xml index c186952c74..d5624aeaa2 100644 --- a/doc/classes/String.xml +++ b/doc/classes/String.xml @@ -1,10 +1,12 @@ <?xml version="1.0" encoding="UTF-8" ?> <class name="String" version="4.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> <brief_description> - Built-in string class. + Built-in string Variant type. </brief_description> <description> - This is the built-in string class (and the one used by GDScript). It supports Unicode and provides all necessary means for string handling. Strings are reference-counted and use a copy-on-write approach, so passing them around is cheap in resources. + This is the built-in string Variant type (and the one used by GDScript). Strings may contain any number of Unicode characters, and expose methods useful for manipulating and generating strings. Strings are reference-counted and use a copy-on-write approach (every modification to a string returns a new [String]), so passing them around is cheap in resources. + Some string methods have corresponding variations. Variations suffixed with [code]n[/code] ([method countn], [method findn], [method replacen], etc.) are [b]case-insensitive[/b] (they make no distinction between uppercase and lowercase letters). Method variations prefixed with [code]r[/code] ([method rfind], [method rsplit], etc.) are reversed, and start from the end of the string, instead of the beginning. + [b]Note:[/b] In a boolean context, a string will evaluate to [code]false[/code] if it is empty ([code]""[/code]). Otherwise, a string will always evaluate to [code]true[/code]. </description> <tutorials> <link title="GDScript format strings">$DOCS_URL/tutorials/scripting/gdscript/gdscript_format_string.html</link> @@ -43,30 +45,32 @@ <return type="bool" /> <param index="0" name="text" type="String" /> <description> - Returns [code]true[/code] if the string begins with the given string. + Returns [code]true[/code] if the string begins with the given [param text]. See also [method ends_with]. </description> </method> <method name="bigrams" qualifiers="const"> <return type="PackedStringArray" /> <description> - Returns an array containing the bigrams (pairs of consecutive letters) of this string. + Returns an array containing the bigrams (pairs of consecutive characters) of this string. [codeblock] - print("Bigrams".bigrams()) # Prints ["Bi", "ig", "gr", "ra", "am", "ms"] + print("Get up!".bigrams()) # Prints ["Ge", "et", "t ", " u", "up", "p!"] [/codeblock] </description> </method> <method name="bin_to_int" qualifiers="const"> <return type="int" /> <description> - Converts a string containing a binary number into an integer. Binary strings can either be prefixed with [code]0b[/code] or not, and they can also start with a [code]-[/code] before the optional prefix. + Converts the string representing a binary number into an [int]. The string may optionally be prefixed with [code]"0b"[/code], and an additional [code]-[/code] prefix for negative numbers. [codeblocks] [gdscript] - print("0b101".bin_to_int()) # Prints "5". - print("101".bin_to_int()) # Prints "5". + print("101".bin_to_int()) # Prints 5 + print("0b101".bin_to_int()) # Prints 5 + print("-0b10".bin_to_int()) # Prints -2 [/gdscript] [csharp] - GD.Print("0b101".BinToInt()); // Prints "5". - GD.Print("101".BinToInt()); // Prints "5". + GD.Print("101".BinToInt()); // Prints 5 + GD.Print("0b101".BinToInt()); // Prints 5 + GD.Print("-0b10".BinToInt()); // Prints -2 [/csharp] [/codeblocks] </description> @@ -87,26 +91,36 @@ <method name="capitalize" qualifiers="const"> <return type="String" /> <description> - Changes the case of some letters. Replaces underscores with spaces, adds spaces before in-word uppercase characters, converts all letters to lowercase, then capitalizes the first letter and every letter following a space character. For [code]capitalize camelCase mixed_with_underscores[/code], it will return [code]Capitalize Camel Case Mixed With Underscores[/code]. + Changes the appearance of the string: replaces underscores ([code]_[/code]) with spaces, adds spaces before uppercase letters in the middle of a word, converts all letters to lowercase, then converts the first one and each one following a space to uppercase. + [codeblocks] + [gdscript] + "move_local_x".capitalize() # Returns "Move Local X" + "sceneFile_path".capitalize() # Returns "Scene File Path" + [/gdscript] + [csharp] + "move_local_x".Capitalize(); // Returns "Move Local X" + "sceneFile_path".Capitalize(); // Returns "Scene File Path" + [/csharp] + [/codeblocks] + [b]Note:[/b] This method not the same as the default appearance of properties in the Inspector dock, as it does not capitalize acronyms ([code]"2D"[/code], [code]"FPS"[/code], [code]"PNG"[/code], etc.) as you may expect. </description> </method> <method name="casecmp_to" qualifiers="const"> <return type="int" /> <param index="0" name="to" type="String" /> <description> - Performs a case-sensitive comparison to another string. Returns [code]-1[/code] if less than, [code]1[/code] if greater than, or [code]0[/code] if equal. "less than" or "greater than" are determined by the [url=https://en.wikipedia.org/wiki/List_of_Unicode_characters]Unicode code points[/url] of each string, which roughly matches the alphabetical order. - [b]Behavior with different string lengths:[/b] Returns [code]1[/code] if the "base" string is longer than the [param to] string or [code]-1[/code] if the "base" string is shorter than the [param to] string. Keep in mind this length is determined by the number of Unicode codepoints, [i]not[/i] the actual visible characters. - [b]Behavior with empty strings:[/b] Returns [code]-1[/code] if the "base" string is empty, [code]1[/code] if the [param to] string is empty or [code]0[/code] if both strings are empty. - To get a boolean result from a string comparison, use the [code]==[/code] operator instead. See also [method nocasecmp_to] and [method naturalnocasecmp_to]. + Performs a case-sensitive comparison to another string. Returns [code]-1[/code] if less than, [code]1[/code] if greater than, or [code]0[/code] if equal. "Less than" and "greater than" are determined by the [url=https://en.wikipedia.org/wiki/List_of_Unicode_characters]Unicode code points[/url] of each string, which roughly matches the alphabetical order. + With different string lengths, returns [code]1[/code] if this string is longer than the [param to] string, or [code]-1[/code] if shorter. Note that the length of empty strings is [i]always[/i] [code]0[/code]. + To get a [bool] result from a string comparison, use the [code]==[/code] operator instead. See also [method nocasecmp_to] and [method naturalnocasecmp_to]. </description> </method> <method name="chr" qualifiers="static"> <return type="String" /> <param index="0" name="char" type="int" /> <description> - Directly converts an decimal integer to a unicode character. Tables of these characters can be found in various locations, for example [url=https://unicodelookup.com/]here.[/url] + Returns a single Unicode character from the decimal [param char]. You may use [url=https://unicodelookup.com/]unicodelookup.com[/url] or [url=https://www.unicode.org/charts/]unicode.org[/url] as points of reference. [codeblock] - print(String.chr(65)) # Prints "A" + print(String.chr(65)) # Prints "A" print(String.chr(129302)) # Prints "🤖" (robot face emoji) [/codeblock] </description> @@ -115,7 +129,19 @@ <return type="bool" /> <param index="0" name="what" type="String" /> <description> - Returns [code]true[/code] if the string contains the given string. + Returns [code]true[/code] if the string contains [param what]. In GDScript, this corresponds to the [code]in[/code] operator. + [codeblocks] + [gdscript] + print("Node".contains("de")) # Prints true + print("team".contains("I")) # Prints false + print("I" in "team") # Prints false + [/gdscript] + [csharp] + GD.Print("Node".Contains("de")); // Prints true + GD.Print("team".Contains("I")); // Prints false + [/csharp] + [/codeblocks] + If you need to know where [param what] is within the string, use [method find]. </description> </method> <method name="count" qualifiers="const"> @@ -124,7 +150,7 @@ <param index="1" name="from" type="int" default="0" /> <param index="2" name="to" type="int" default="0" /> <description> - Returns the number of occurrences of substring [param what] between [param from] and [param to] positions. If [param from] and [param to] equals 0 the whole string will be used. If only [param to] equals 0 the remained substring will be used. + Returns the number of occurrences of the substring [param what] between [param from] and [param to] positions. If [param to] is 0, the search continues until the end of the string. </description> </method> <method name="countn" qualifiers="const"> @@ -133,7 +159,7 @@ <param index="1" name="from" type="int" default="0" /> <param index="2" name="to" type="int" default="0" /> <description> - Returns the number of occurrences of substring [param what] (ignoring case) between [param from] and [param to] positions. If [param from] and [param to] equals 0 the whole string will be used. If only [param to] equals 0 the remained substring will be used. + Returns the number of occurrences of the substring [param what] between [param from] and [param to] positions, [b]ignoring case[/b]. If [param to] is 0, the search continues until the end of the string. </description> </method> <method name="dedent" qualifiers="const"> @@ -146,7 +172,7 @@ <return type="bool" /> <param index="0" name="text" type="String" /> <description> - Returns [code]true[/code] if the string ends with the given string. + Returns [code]true[/code] if the string ends with the given [param text]. See also [method begins_with]. </description> </method> <method name="find" qualifiers="const"> @@ -154,17 +180,24 @@ <param index="0" name="what" type="String" /> <param index="1" name="from" type="int" default="0" /> <description> - Returns the index of the [b]first[/b] case-sensitive occurrence of the specified string in this instance, or [code]-1[/code]. Optionally, the starting search index can be specified, continuing to the end of the string. - [b]Note:[/b] If you just want to know whether a string contains a substring, use the [code]in[/code] operator as follows: + Returns the index of the [b]first[/b] occurrence of [param what] in this string, or [code]-1[/code] if there are none. The search's start can be specified with [param from], continuing to the end of the string. [codeblocks] [gdscript] - print("i" in "team") # Will print `false`. + print("Team".find("I")) # Prints -1 + + print("Potato".find("t")) # Prints 2 + print("Potato".find("t", 3)) # Prints 4 + print("Potato".find("t", 5)) # Prints -1 [/gdscript] [csharp] - // C# has no in operator, but we can use `Contains()`. - GD.Print("team".Contains("i")); // Will print `false`. + GD.Print("Team".Find("I")); // Prints -1 + + GD.Print("Potato".Find("t")); // Prints 2 + GD.print("Potato".Find("t", 3)); // Prints 4 + GD.print("Potato".Find("t", 5)); // Prints -1 [/csharp] [/codeblocks] + [b]Note:[/b] If you just want to know whether the string contains [param what], use [method contains]. In GDScript, you may also use the [code]in[/code] operator. </description> </method> <method name="findn" qualifiers="const"> @@ -172,7 +205,7 @@ <param index="0" name="what" type="String" /> <param index="1" name="from" type="int" default="0" /> <description> - Returns the index of the [b]first[/b] case-insensitive occurrence of the specified string in this instance, or [code]-1[/code]. Optionally, the starting search index can be specified, continuing to the end of the string. + Returns the index of the [b]first[/b] [b]case-insensitive[/b] occurrence of [param what] in this string, or [code]-1[/code] if there are none. The starting search index can be specified with [param from], continuing to the end of the string. </description> </method> <method name="format" qualifiers="const"> @@ -183,53 +216,64 @@ Formats the string by replacing all occurrences of [param placeholder] with the elements of [param values]. [param values] can be a [Dictionary] or an [Array]. Any underscores in [param placeholder] will be replaced with the corresponding keys in advance. Array elements use their index as keys. [codeblock] - # Prints: Waiting for Godot is a play by Samuel Beckett, and Godot Engine is named after it. + # Prints "Waiting for Godot is a play by Samuel Beckett, and Godot Engine is named after it." var use_array_values = "Waiting for {0} is a play by {1}, and {0} Engine is named after it." print(use_array_values.format(["Godot", "Samuel Beckett"])) - # Prints: User 42 is Godot. + # Prints "User 42 is Godot." print("User {id} is {name}.".format({"id": 42, "name": "Godot"})) [/codeblock] - Some additional handling is performed when [param values] is an array. If [param placeholder] does not contain an underscore, the elements of the array will be used to replace one occurrence of the placeholder in turn; If an array element is another 2-element array, it'll be interpreted as a key-value pair. + Some additional handling is performed when [param values] is an [Array]. If [param placeholder] does not contain an underscore, the elements of the [param values] array will be used to replace one occurrence of the placeholder in order; If an element of [param values] is another 2-element array, it'll be interpreted as a key-value pair. [codeblock] - # Prints: User 42 is Godot. + # Prints "User 42 is Godot." print("User {} is {}.".format([42, "Godot"], "{}")) print("User {id} is {name}.".format([["id", 42], ["name", "Godot"]])) [/codeblock] + See also the [url=$DOCS_URL/tutorials/scripting/gdscript/gdscript_format_string.html]GDScript format string[/url] tutorial. </description> </method> <method name="get_base_dir" qualifiers="const"> <return type="String" /> <description> If the string is a valid file path, returns the base directory name. + [codeblock] + var dir_path = "/path/to/file.txt".get_basename() # dir_path is "/path/to" + [/codeblock] </description> </method> <method name="get_basename" qualifiers="const"> <return type="String" /> <description> - If the string is a valid file path, returns the full file path without the extension. + If the string is a valid file path, returns the full file path, without the extension. + [codeblock] + var base = "/path/to/file.txt".get_basename() # base is "/path/to/file" + [/codeblock] </description> </method> <method name="get_extension" qualifiers="const"> <return type="String" /> <description> - Returns the extension without the leading period character ([code].[/code]) if the string is a valid file name or path. If the string does not contain an extension, returns an empty string instead. + If the string is a valid file name or path, returns the file extension without the leading period ([code].[/code]). Otherwise, returns an empty string. [codeblock] - print("/path/to/file.txt".get_extension()) # "txt" - print("file.txt".get_extension()) # "txt" - print("file.sample.txt".get_extension()) # "txt" - print(".txt".get_extension()) # "txt" - print("file.txt.".get_extension()) # "" (empty string) - print("file.txt..".get_extension()) # "" (empty string) - print("txt".get_extension()) # "" (empty string) - print("".get_extension()) # "" (empty string) + var a = "/path/to/file.txt".get_extension() # a is "txt" + var b = "cool.txt".get_extension() # b is "txt" + var c = "cool.font.tres".get_extension() # c is "tres" + var d = ".pack1".get_extension() # d is "pack1" + + var e = "file.txt.".get_extension() # e is "" + var f = "file.txt..".get_extension() # f is "" + var g = "txt".get_extension() # g is "" + var h = "".get_extension() # h is "" [/codeblock] </description> </method> <method name="get_file" qualifiers="const"> <return type="String" /> <description> - If the string is a valid file path, returns the filename. + If the string is a valid file path, returns the file name, including the extension. + [codeblock] + var file = "/path/to/icon.png".get_file() # file is "icon.png" + [/codeblock] </description> </method> <method name="get_slice" qualifiers="const"> @@ -237,11 +281,11 @@ <param index="0" name="delimiter" type="String" /> <param index="1" name="slice" type="int" /> <description> - Splits a string using a [param delimiter] and returns a substring at index [param slice]. Returns an empty string if the index doesn't exist. - This is a more performant alternative to [method split] for cases when you need only one element from the array at a fixed index. + Splits the string using a [param delimiter] and returns the substring at index [param slice]. Returns an empty string if the [param slice] does not exist. + This is faster than [method split], if you only need one substring. [b]Example:[/b] [codeblock] - print("i/am/example/string".get_slice("/", 2)) # Prints 'example'. + print("i/am/example/hi".get_slice("/", 2)) # Prints "example" [/codeblock] </description> </method> @@ -249,7 +293,7 @@ <return type="int" /> <param index="0" name="delimiter" type="String" /> <description> - Splits a string using a [param delimiter] and returns a number of slices. + Returns the total number of slices when the string is split with the given [param delimiter] (see [method split]). </description> </method> <method name="get_slicec" qualifiers="const"> @@ -257,29 +301,29 @@ <param index="0" name="delimiter" type="int" /> <param index="1" name="slice" type="int" /> <description> - Splits a string using a Unicode character with code [param delimiter] and returns a substring at index [param slice]. Returns an empty string if the index doesn't exist. - This is a more performant alternative to [method split] for cases when you need only one element from the array at a fixed index. + Splits the string using a Unicode character with code [param delimiter] and returns the substring at index [param slice]. Returns an empty string if the [param slice] does not exist. + This is faster than [method split], if you only need one substring. </description> </method> <method name="hash" qualifiers="const"> <return type="int" /> <description> Returns the 32-bit hash value representing the string's contents. - [b]Note:[/b] [String]s with equal content will always produce identical hash values. However, the reverse is not true. Returning identical hash values does [i]not[/i] imply the strings are equal, because different strings can have identical hash values due to hash collisions. + [b]Note:[/b] Strings with equal hash values are [i]not[/i] guaranteed to be the same, as a result of hash collisions. On the countrary, strings with different hash values are guaranteed to be different. </description> </method> <method name="hex_to_int" qualifiers="const"> <return type="int" /> <description> - Converts a string containing a hexadecimal number into an integer. Hexadecimal strings can either be prefixed with [code]0x[/code] or not, and they can also start with a [code]-[/code] before the optional prefix. + Converts the string representing a hexadecimal number into an [int]. The string may be optionally prefixed with [code]"0x"[/code], and an additional [code]-[/code] prefix for negative numbers. [codeblocks] [gdscript] - print("0xff".hex_to_int()) # Prints "255". - print("ab".hex_to_int()) # Prints "171". + print("0xff".hex_to_int()) # Prints 255 + print("ab".hex_to_int()) # Prints 171 [/gdscript] [csharp] - GD.Print("0xff".HexToInt()); // Prints "255". - GD.Print("ab".HexToInt()); // Prints "171". + GD.Print("0xff".HexToInt()); // Prints 255 + GD.Print("ab".HexToInt()); // Prints 171 [/csharp] [/codeblocks] </description> @@ -288,17 +332,16 @@ <return type="String" /> <param index="0" name="size" type="int" /> <description> - Converts an integer representing a number of bytes into a human-readable form. - Note that this output is in [url=https://en.wikipedia.org/wiki/Binary_prefix#IEC_prefixes]IEC prefix format[/url], and includes [code]B[/code], [code]KiB[/code], [code]MiB[/code], [code]GiB[/code], [code]TiB[/code], [code]PiB[/code], and [code]EiB[/code]. + Converts [param size] which represents a number of bytes into a human-readable form. + The result is in [url=https://en.wikipedia.org/wiki/Binary_prefix#IEC_prefixes]IEC prefix format[/url], which may end in either [code]"B"[/code], [code]"KiB"[/code], [code]"MiB"[/code], [code]"GiB"[/code], [code]"TiB"[/code], [code]"PiB"[/code], or [code]"EiB"[/code]. </description> </method> <method name="indent" qualifiers="const"> <return type="String" /> <param index="0" name="prefix" type="String" /> <description> - Returns a copy of the string with lines indented with [param prefix]. - For example, the string can be indented with two tabs using [code]"\t\t"[/code], or four spaces using [code]" "[/code]. The prefix can be any string so it can also be used to comment out strings with e.g. [code]"# "[/code]. See also [method dedent] to remove indentation. - [b]Note:[/b] Empty lines are kept empty. + Indents every line of the string with the given [param prefix]. Empty lines are not indented. See also [method dedent] to remove indentation. + For example, the string can be indented with two tabulations using [code]"\t\t"[/code], or four spaces using [code]" "[/code]. </description> </method> <method name="insert" qualifiers="const"> @@ -306,57 +349,65 @@ <param index="0" name="position" type="int" /> <param index="1" name="what" type="String" /> <description> - Returns a copy of the string with the substring [param what] inserted at the given [param position]. + Inserts [param what] at the given [param position] in the string. </description> </method> <method name="is_absolute_path" qualifiers="const"> <return type="bool" /> <description> - Returns [code]true[/code] if the string is a path to a file or directory and its starting point is explicitly defined. This includes [code]res://[/code], [code]user://[/code], [code]C:\[/code], [code]/[/code], etc. + Returns [code]true[/code] if the string is a path to a file or directory, and its starting point is explicitly defined. This method is the opposite of [method is_relative_path]. + This includes all paths starting with [code]"res://"[/code], [code]"user://"[/code], [code]"C:\"[/code], [code]"/"[/code], etc. </description> </method> <method name="is_empty" qualifiers="const"> <return type="bool" /> <description> - Returns [code]true[/code] if the length of the string equals [code]0[/code]. + Returns [code]true[/code] if the string's length is [code]0[/code] ([code]""[/code]). See also [method length]. </description> </method> <method name="is_relative_path" qualifiers="const"> <return type="bool" /> <description> - Returns [code]true[/code] if the string is a path to a file or directory and its starting point is implicitly defined within the context it is being used. The starting point may refer to the current directory ([code]./[/code]), or the current [Node]. + Returns [code]true[/code] if the string is a path, and its starting point is dependent on context. The path could begin from the current directory, or the current [Node] (if the string is derived from a [NodePath]), and may sometimes be prefixed with [code]"./"[/code]. This method is the opposite of [method is_absolute_path]. </description> </method> <method name="is_subsequence_of" qualifiers="const"> <return type="bool" /> <param index="0" name="text" type="String" /> <description> - Returns [code]true[/code] if this string is a subsequence of the given string. + Returns [code]true[/code] if all characters of this string can be found in [param text] in their original order. + [codeblock] + var text = "Wow, incredible!" + + print("inedible".is_subsequence_of(text)) # Prints true + print("Word!".is_subsequence_of(text)) # Prints true + print("Window".is_subsequence_of(text)) # Prints false + print("".is_subsequence_of(text)) # Prints true + [/codeblock] </description> </method> <method name="is_subsequence_ofn" qualifiers="const"> <return type="bool" /> <param index="0" name="text" type="String" /> <description> - Returns [code]true[/code] if this string is a subsequence of the given string, without considering case. + Returns [code]true[/code] if all characters of this string can be found in [param text] in their original order, [b]ignoring case[/b]. </description> </method> <method name="is_valid_filename" qualifiers="const"> <return type="bool" /> <description> - Returns [code]true[/code] if this string is free from characters that aren't allowed in file names, those being: - [code]: / \ ? * " | % < >[/code] + Returns [code]true[/code] if this string does not contain characters that are not allowed in file names ([code]:[/code] [code]/[/code] [code]\[/code] [code]?[/code] [code]*[/code] [code]"[/code] [code]|[/code] [code]%[/code] [code]<[/code] [code]>[/code]). </description> </method> <method name="is_valid_float" qualifiers="const"> <return type="bool" /> <description> - Returns [code]true[/code] if this string contains a valid float. This is inclusive of integers, and also supports exponents: + Returns [code]true[/code] if this string represents a valid floating-point number. A valid float may contain only digits, one decimal point ([code].[/code]), and the exponent letter ([code]e[/code]). It may also be prefixed with a positive ([code]+[/code]) or negative ([code]-[/code]) sign. Any valid integer is also a valid float (see [method is_valid_int]). See also [method to_float]. [codeblock] - print("1.7".is_valid_float()) # Prints "true" - print("24".is_valid_float()) # Prints "true" - print("7e3".is_valid_float()) # Prints "true" - print("Hello".is_valid_float()) # Prints "false" + print("1.7".is_valid_float()) # Prints true + print("24".is_valid_float()) # Prints true + print("7e3".is_valid_float()) # Prints true + print("Hello".is_valid_float()) # Prints false [/codeblock] </description> </method> @@ -364,57 +415,73 @@ <return type="bool" /> <param index="0" name="with_prefix" type="bool" default="false" /> <description> - Returns [code]true[/code] if this string contains a valid hexadecimal number. If [param with_prefix] is [code]true[/code], then a validity of the hexadecimal number is determined by the [code]0x[/code] prefix, for example: [code]0xDEADC0DE[/code]. + Returns [code]true[/code] if this string is a valid hexadecimal number. A valid hexadecimal number only contains digits or letters [code]A[/code] to [code]F[/code] (either uppercase or lowercase), and may be prefixed with a positive ([code]+[/code]) or negative ([code]-[/code]) sign. + If [param with_prefix] is [code]true[/code], the hexadecimal number needs to prefixed by [code]"0x"[/code] to be considered valid. + [codeblock] + print("A08E".is_valid_hex_number()) # Prints true + print("-AbCdEf".is_valid_hex_number()) # Prints true + print("2.5".is_valid_hex_number()) # Prints false + + print("0xDEADC0DE".is_valid_hex_number(true)) # Prints true + [/codeblock] </description> </method> <method name="is_valid_html_color" qualifiers="const"> <return type="bool" /> <description> - Returns [code]true[/code] if this string contains a valid color in hexadecimal HTML notation. Other HTML notations such as named colors or [code]hsl()[/code] colors aren't considered valid by this method and will return [code]false[/code]. + Returns [code]true[/code] if this string is a valid color in hexadecimal HTML notation. The string must be a hexadecimal value (see [method is_valid_hex_number]) of either 3, 4, 6 or 8 digits, and may be prefixed by a hash sign ([code]#[/code]). Other HTML notations for colors, such as names or [code]hsl()[/code], are not considered valid. See also [method Color.html]. </description> </method> <method name="is_valid_identifier" qualifiers="const"> <return type="bool" /> <description> - Returns [code]true[/code] if this string is a valid identifier. A valid identifier may contain only letters, digits and underscores ([code]_[/code]) and the first character may not be a digit. + Returns [code]true[/code] if this string is a valid identifier. A valid identifier may contain only letters, digits and underscores ([code]_[/code]), and the first character may not be a digit. [codeblock] - print("good_ident_1".is_valid_identifier()) # Prints "true" - print("1st_bad_ident".is_valid_identifier()) # Prints "false" - print("bad_ident_#2".is_valid_identifier()) # Prints "false" + print("node_2d".is_valid_identifier()) # Prints true + print("TYPE_FLOAT".is_valid_identifier()) # Prints true + print("1st_method".is_valid_identifier()) # Prints false + print("MyMethod#2".is_valid_identifier()) # Prints false [/codeblock] </description> </method> <method name="is_valid_int" qualifiers="const"> <return type="bool" /> <description> - Returns [code]true[/code] if this string contains a valid integer. + Returns [code]true[/code] if this string represents a valid integer. A valid integer only contains digits, and may be prefixed with a positive ([code]+[/code]) or negative ([code]-[/code]) sign. See also [method to_int]. [codeblock] - print("7".is_valid_int()) # Prints "true" - print("14.6".is_valid_int()) # Prints "false" - print("L".is_valid_int()) # Prints "false" - print("+3".is_valid_int()) # Prints "true" - print("-12".is_valid_int()) # Prints "true" + print("7".is_valid_int()) # Prints true + print("1.65".is_valid_int()) # Prints false + print("Hi".is_valid_int()) # Prints false + print("+3".is_valid_int()) # Prints true + print("-12".is_valid_int()) # Prints true [/codeblock] </description> </method> <method name="is_valid_ip_address" qualifiers="const"> <return type="bool" /> <description> - Returns [code]true[/code] if this string contains only a well-formatted IPv4 or IPv6 address. This method considers [url=https://en.wikipedia.org/wiki/Reserved_IP_addresses]reserved IP addresses[/url] such as [code]0.0.0.0[/code] as valid. + Returns [code]true[/code] if this string represents a well-formatted IPv4 or IPv6 address. This method considers [url=https://en.wikipedia.org/wiki/Reserved_IP_addresses]reserved IP addresses[/url] such as [code]"0.0.0.0"[/code] and [code]"ffff:ffff:ffff:ffff:ffff:ffff:ffff:ffff"[/code] as valid. </description> </method> <method name="join" qualifiers="const"> <return type="String" /> <param index="0" name="parts" type="PackedStringArray" /> <description> - Returns a [String] which is the concatenation of the [param parts]. The separator between elements is the string providing this method. + Returns the concatenation of [param parts]' elements, with each element separated by the string calling this method. This method is the opposite of [method split]. [b]Example:[/b] [codeblocks] [gdscript] - print(", ".join(["One", "Two", "Three", "Four"])) + var fruits = ["Apple", "Orange", "Pear", "Kiwi"] + + print(", ".join(fruits)) # Prints "Apple, Orange, Pear, Kiwi" + print("---".join(fruits)) # Prints "Apple---Orange---Pear---Kiwi" [/gdscript] [csharp] - GD.Print(String.Join(",", new string[] {"One", "Two", "Three", "Four"})); + var fruits = new string[] {"Apple", "Orange", "Pear", "Kiwi"}; + + // In C#, this method is static. + GD.Print(string.Join(", ", fruits); // Prints "Apple, Orange, Pear, Kiwi" + GD.Print(string.Join("---", fruits)); // Prints "Apple---Orange---Pear---Kiwi" [/csharp] [/codeblocks] </description> @@ -422,25 +489,24 @@ <method name="json_escape" qualifiers="const"> <return type="String" /> <description> - Returns a copy of the string with special characters escaped using the JSON standard. + Returns a copy of the string with special characters escaped using the JSON standard. Because it closely matches the C standard, it is possible to use [method c_unescape] to unescape the string, if necessary. </description> </method> <method name="left" qualifiers="const"> <return type="String" /> <param index="0" name="length" type="int" /> <description> - Returns a number of characters from the left of the string. If negative [param length] is used, the characters are counted downwards from [String]'s length. - [b]Example:[/b] + Returns the first [param length] characters from the beginning of the string. If [param length] is negative, strips the last [param length] characters from the string's end. [codeblock] - print("sample text".left(3)) #prints "sam" - print("sample text".left(-3)) #prints "sample t" + print("Hello World!".left(3)) # Prints "Hel" + print("Hello World!".left(-4)) # Prints "Hello Wo" [/codeblock] </description> </method> <method name="length" qualifiers="const"> <return type="int" /> <description> - Returns the number of characters in the string. + Returns the number of characters in the string. Empty strings ([code]""[/code]) always return [code]0[/code]. See also [method is_empty]. </description> </method> <method name="lpad" qualifiers="const"> @@ -448,62 +514,60 @@ <param index="0" name="min_length" type="int" /> <param index="1" name="character" type="String" default="" "" /> <description> - Formats a string to be at least [param min_length] long by adding [param character]s to the left of the string. + Formats the string to be at least [param min_length] long by adding [param character]s to the left of the string, if necessary. See also [method rpad]. </description> </method> <method name="lstrip" qualifiers="const"> <return type="String" /> <param index="0" name="chars" type="String" /> <description> - Returns a copy of the string with characters removed from the left. The [param chars] argument is a string specifying the set of characters to be removed. - [b]Note:[/b] The [param chars] is not a prefix. See [method trim_prefix] method that will remove a single prefix string rather than a set of characters. + Removes a set of characters defined in [param chars] from the string's beginning. See also [method rstrip]. + [b]Note:[/b] [param chars] is not a prefix. Use [method trim_prefix] to remove a single prefix, rather than a set of characters. </description> </method> <method name="match" qualifiers="const"> <return type="bool" /> <param index="0" name="expr" type="String" /> <description> - Does a simple case-sensitive expression match, where [code]"*"[/code] matches zero or more arbitrary characters and [code]"?"[/code] matches any single character except a period ([code]"."[/code]). An empty string or empty expression always evaluates to [code]false[/code]. + Does a simple expression match, where [code]*[/code] matches zero or more arbitrary characters and [code]?[/code] matches any single character except a period ([code].[/code]). An empty string or empty expression always evaluates to [code]false[/code]. </description> </method> <method name="matchn" qualifiers="const"> <return type="bool" /> <param index="0" name="expr" type="String" /> <description> - Does a simple case-insensitive expression match, where [code]"*"[/code] matches zero or more arbitrary characters and [code]"?"[/code] matches any single character except a period ([code]"."[/code]). An empty string or empty expression always evaluates to [code]false[/code]. + Does a simple [b]case-insensitive[/b] expression match, where [code]*[/code] matches zero or more arbitrary characters and [code]?[/code] matches any single character except a period ([code].[/code]). An empty string or empty expression always evaluates to [code]false[/code]. </description> </method> <method name="md5_buffer" qualifiers="const"> <return type="PackedByteArray" /> <description> - Returns the MD5 hash of the string as an array of bytes. + Returns the [url=https://en.wikipedia.org/wiki/MD5]MD5 hash[/url] of the string as a [PackedByteArray]. </description> </method> <method name="md5_text" qualifiers="const"> <return type="String" /> <description> - Returns the MD5 hash of the string as a string. + Returns the [url=https://en.wikipedia.org/wiki/MD5]MD5 hash[/url] of the string as another [String]. </description> </method> <method name="naturalnocasecmp_to" qualifiers="const"> <return type="int" /> <param index="0" name="to" type="String" /> <description> - Performs a case-insensitive [i]natural order[/i] comparison to another string. Returns [code]-1[/code] if less than, [code]1[/code] if greater than, or [code]0[/code] if equal. "less than" or "greater than" are determined by the [url=https://en.wikipedia.org/wiki/List_of_Unicode_characters]Unicode code points[/url] of each string, which roughly matches the alphabetical order. Internally, lowercase characters will be converted to uppercase during the comparison. - When used for sorting, natural order comparison will order suites of numbers as expected by most people. If you sort the numbers from 1 to 10 using natural order, you will get [code][1, 2, 3, ...][/code] instead of [code][1, 10, 2, 3, ...][/code]. - [b]Behavior with different string lengths:[/b] Returns [code]1[/code] if the "base" string is longer than the [param to] string or [code]-1[/code] if the "base" string is shorter than the [param to] string. Keep in mind this length is determined by the number of Unicode codepoints, [i]not[/i] the actual visible characters. - [b]Behavior with empty strings:[/b] Returns [code]-1[/code] if the "base" string is empty, [code]1[/code] if the [param to] string is empty or [code]0[/code] if both strings are empty. - To get a boolean result from a string comparison, use the [code]==[/code] operator instead. See also [method nocasecmp_to] and [method casecmp_to]. + Performs a [b]case-insensitive[/b], [i]natural order[/i] comparison to another string. Returns [code]-1[/code] if less than, [code]1[/code] if greater than, or [code]0[/code] if equal. "Less than" or "greater than" are determined by the [url=https://en.wikipedia.org/wiki/List_of_Unicode_characters]Unicode code points[/url] of each string, which roughly matches the alphabetical order. Internally, lowercase characters are converted to uppercase for the comparison. + When used for sorting, natural order comparison orders sequences of numbers by the combined value of each digit as is often expected, instead of the single digit's value. A sorted sequence of numbered strings will be [code]["1", "2", "3", ...][/code], not [code]["1", "10", "2", "3", ...][/code]. + With different string lengths, returns [code]1[/code] if this string is longer than the [param to] string, or [code]-1[/code] if shorter. Note that the length of empty strings is [i]always[/i] [code]0[/code]. + To get a [bool] result from a string comparison, use the [code]==[/code] operator instead. See also [method nocasecmp_to] and [method casecmp_to]. </description> </method> <method name="nocasecmp_to" qualifiers="const"> <return type="int" /> <param index="0" name="to" type="String" /> <description> - Performs a case-insensitive comparison to another string. Returns [code]-1[/code] if less than, [code]1[/code] if greater than, or [code]0[/code] if equal. "less than" or "greater than" are determined by the [url=https://en.wikipedia.org/wiki/List_of_Unicode_characters]Unicode code points[/url] of each string, which roughly matches the alphabetical order. Internally, lowercase characters will be converted to uppercase during the comparison. - [b]Behavior with different string lengths:[/b] Returns [code]1[/code] if the "base" string is longer than the [param to] string or [code]-1[/code] if the "base" string is shorter than the [param to] string. Keep in mind this length is determined by the number of Unicode codepoints, [i]not[/i] the actual visible characters. - [b]Behavior with empty strings:[/b] Returns [code]-1[/code] if the "base" string is empty, [code]1[/code] if the [param to] string is empty or [code]0[/code] if both strings are empty. - To get a boolean result from a string comparison, use the [code]==[/code] operator instead. See also [method casecmp_to] and [method naturalnocasecmp_to]. + Performs a [b]case-insensitive[/b] comparison to another string. Returns [code]-1[/code] if less than, [code]1[/code] if greater than, or [code]0[/code] if equal. "Less than" or "greater than" are determined by the [url=https://en.wikipedia.org/wiki/List_of_Unicode_characters]Unicode code points[/url] of each string, which roughly matches the alphabetical order. Internally, lowercase characters are converted to uppercase for the comparison. + With different string lengths, returns [code]1[/code] if this string is longer than the [param to] string, or [code]-1[/code] if shorter. Note that the length of empty strings is [i]always[/i] [code]0[/code]. + To get a [bool] result from a string comparison, use the [code]==[/code] operator instead. See also [method casecmp_to] and [method naturalnocasecmp_to]. </description> </method> <method name="num" qualifiers="static"> @@ -511,20 +575,22 @@ <param index="0" name="number" type="float" /> <param index="1" name="decimals" type="int" default="-1" /> <description> - Converts a [float] to a string representation of a decimal number. - The number of decimal places can be specified with [param decimals]. If [param decimals] is [code]-1[/code] (default), decimal places will be automatically adjusted so that the string representation has 14 significant digits (counting both digits to the left and the right of the decimal point). - Trailing zeros are not included in the string. The last digit will be rounded and not truncated. + Converts a [float] to a string representation of a decimal number, with the number of decimal places specified in [param decimals]. + If [param decimals] is [code]-1[/code] as by default, the string representation may only have up to 14 significant digits, with digits before the decimal point having priority over digits after. + Trailing zeros are not included in the string. The last digit is rounded, not truncated. [b]Example:[/b] [codeblock] - String.num(3.141593) # "3.141593" - String.num(3.141593, 3) # "3.142" - String.num(3.14159300) # "3.141593", no trailing zeros. - # Last digit will be rounded up here, which reduces total digit count since - # trailing zeros are removed: - String.num(42.129999, 5) # "42.13" - # If `decimals` is not specified, the total number of significant digits is 14: - String.num(-0.0000012345432123454321) # "-0.00000123454321" - String.num(-10000.0000012345432123454321) # "-10000.0000012345" + String.num(3.141593) # Returns "3.141593" + String.num(3.141593, 3) # Returns "3.142" + String.num(3.14159300) # Returns "3.141593" + + # Here, the last digit will be rounded up, + # which reduces the total digit count, since trailing zeros are removed: + String.num(42.129999, 5) # Returns "42.13" + + # If `decimals` is not specified, the maximum number of significant digits is 14: + String.num(-0.0000012345432123454321) # Returns "-0.00000123454321" + String.num(-10000.0000012345432123454321) # Returns "-10000.0000012345" [/codeblock] </description> </method> @@ -534,13 +600,31 @@ <param index="1" name="base" type="int" default="10" /> <param index="2" name="capitalize_hex" type="bool" default="false" /> <description> - Converts a signed [int] to a string representation of a number. + Converts the given [param number] to a string representation, with the given [param base]. + By default, [param base] is set to decimal ([code]10[/code]). Other common bases in programming include binary ([code]2[/code]), [url=https://en.wikipedia.org/wiki/Octal]octal[/url] ([code]8[/code]), hexadecimal ([code]16[/code]). + If [param capitalize_hex] is [code]true[/code], digits higher than 9 are represented in uppercase. </description> </method> <method name="num_scientific" qualifiers="static"> <return type="String" /> <param index="0" name="number" type="float" /> <description> + Converts the given [param number] to a string representation, in scientific notation. + [codeblocks] + [gdscript] + var n = -5.2e8 + print(n) # Prints -520000000 + print(String.NumScientific(n)) # Prints -5.2e+08 + [/gdscript] + [csharp] + // This method is not implemented in C#. + // Use `string.ToString()` with "e" to achieve similar results. + var n = -5.2e8f; + GD.Print(n); // Prints -520000000 + GD.Print(n.ToString("e1")); // Prints -5.2e+008 + [/csharp] + [/codeblocks] + [b]Note:[/b] In C#, this method is not implemented. To achieve similar results, see C#'s [url=https://learn.microsoft.com/en-us/dotnet/standard/base-types/standard-numeric-format-strings]Standard numeric format strings[/url] </description> </method> <method name="num_uint64" qualifiers="static"> @@ -549,35 +633,38 @@ <param index="1" name="base" type="int" default="10" /> <param index="2" name="capitalize_hex" type="bool" default="false" /> <description> - Converts a unsigned [int] to a string representation of a number. + Converts the given unsigned [int] to a string representation, with the given [param base]. + By default, [param base] is set to decimal ([code]10[/code]). Other common bases in programming include binary ([code]2[/code]), [url=https://en.wikipedia.org/wiki/Octal]octal[/url] ([code]8[/code]), hexadecimal ([code]16[/code]). + If [param capitalize_hex] is [code]true[/code], digits higher than 9 are represented in uppercase. </description> </method> <method name="pad_decimals" qualifiers="const"> <return type="String" /> <param index="0" name="digits" type="int" /> <description> - Formats a number to have an exact number of [param digits] after the decimal point. + Formats the string representing a number to have an exact number of [param digits] [i]after[/i] the decimal point. </description> </method> <method name="pad_zeros" qualifiers="const"> <return type="String" /> <param index="0" name="digits" type="int" /> <description> - Formats a number to have an exact number of [param digits] before the decimal point. + Formats the string representing a number to have an exact number of [param digits] [i]before[/i] the decimal point. </description> </method> <method name="path_join" qualifiers="const"> <return type="String" /> <param index="0" name="file" type="String" /> <description> - If the string is a path, this concatenates [param file] at the end of the string as a subpath. E.g. [code]"this/is".path_join("path") == "this/is/path"[/code]. + Concatenates [param file] at the end of the string as a subpath, adding [code]/[/code] if necessary. + [b]Example:[/b] [code]"this/is".path_join("path") == "this/is/path"[/code]. </description> </method> <method name="repeat" qualifiers="const"> <return type="String" /> <param index="0" name="count" type="int" /> <description> - Returns original string repeated a number of times. The number of repetitions is given by the argument. + Repeats this string a number of times. [param count] needs to be greater than [code]0[/code]. Otherwise, returns an empty string. </description> </method> <method name="replace" qualifiers="const"> @@ -585,7 +672,7 @@ <param index="0" name="what" type="String" /> <param index="1" name="forwhat" type="String" /> <description> - Replaces occurrences of a case-sensitive substring with the given one inside the string. + Replaces all occurrences of [param what] inside the string with the given [param forwhat]. </description> </method> <method name="replacen" qualifiers="const"> @@ -593,7 +680,7 @@ <param index="0" name="what" type="String" /> <param index="1" name="forwhat" type="String" /> <description> - Replaces occurrences of a case-insensitive substring with the given one inside the string. + Replaces all [b]case-insensitive[/b] occurrences of [param what] inside the string with the given [param forwhat]. </description> </method> <method name="rfind" qualifiers="const"> @@ -601,7 +688,7 @@ <param index="0" name="what" type="String" /> <param index="1" name="from" type="int" default="-1" /> <description> - Returns the index of the [b]last[/b] case-sensitive occurrence of the specified string in this instance, or [code]-1[/code]. Optionally, the starting search index can be specified, continuing to the beginning of the string. + Returns the index of the [b]last[/b] occurrence of [param what] in this string, or [code]-1[/code] if there are none. The search's start can be specified with [param from], continuing to the beginning of the string. This method is the reverse of [method find]. </description> </method> <method name="rfindn" qualifiers="const"> @@ -609,18 +696,17 @@ <param index="0" name="what" type="String" /> <param index="1" name="from" type="int" default="-1" /> <description> - Returns the index of the [b]last[/b] case-insensitive occurrence of the specified string in this instance, or [code]-1[/code]. Optionally, the starting search index can be specified, continuing to the beginning of the string. + Returns the index of the [b]last[/b] [b]case-insensitive[/b] occurrence of [param what] in this string, or [code]-1[/code] if there are none. The starting search index can be specified with [param from], continuing to the beginning of the string. This method is the reverse of [method findn]. </description> </method> <method name="right" qualifiers="const"> <return type="String" /> <param index="0" name="length" type="int" /> <description> - Returns a number of characters from the right of the string. If negative [param length] is used, the characters are counted downwards from [String]'s length. - [b]Example:[/b] + Returns the last [param length] characters from the end of the string. If [param length] is negative, strips the first [param length] characters from the string's beginning. [codeblock] - print("sample text".right(3)) #prints "ext" - print("sample text".right(-3)) #prints "ple text" + print("Hello World!".right(3)) # Prints "ld!" + print("Hello World!".right(-4)) # Prints "o World!" [/codeblock] </description> </method> @@ -629,7 +715,7 @@ <param index="0" name="min_length" type="int" /> <param index="1" name="character" type="String" default="" "" /> <description> - Formats a string to be at least [param min_length] long by adding [param character]s to the right of the string. + Formats the string to be at least [param min_length] long, by adding [param character]s to the right of the string, if necessary. See also [method lpad]. </description> </method> <method name="rsplit" qualifiers="const"> @@ -638,21 +724,21 @@ <param index="1" name="allow_empty" type="bool" default="true" /> <param index="2" name="maxsplit" type="int" default="0" /> <description> - Splits the string by a [param delimiter] string and returns an array of the substrings, starting from right. If [param delimiter] is an empty string, each substring will be a single character. - The splits in the returned array are sorted in the same order as the original string, from left to right. - If [param allow_empty] is [code]true[/code], and there are two adjacent delimiters in the string, it will add an empty string to the array of substrings at this position. - If [param maxsplit] is specified, it defines the number of splits to do from the right up to [param maxsplit]. The default value of 0 means that all items are split, thus giving the same result as [method split]. + Splits the string using a [param delimiter] and returns an array of the substrings, starting from the end of the string. The splits in the returned array appear in the same order as the original string. If [param delimiter] is an empty string, each substring will be a single character. + If [param allow_empty] is [code]false[/code], empty strings between adjacent delimiters are excluded from the array. + If [param maxsplit] is greater than [code]0[/code], the number of splits may not exceed [param maxsplit]. By default, the entire string is split, which is mostly identical to [method split]. [b]Example:[/b] [codeblocks] [gdscript] var some_string = "One,Two,Three,Four" var some_array = some_string.rsplit(",", true, 1) + print(some_array.size()) # Prints 2 - print(some_array[0]) # Prints "One,Two,Three" - print(some_array[1]) # Prints "Four" + print(some_array[0]) # Prints "One,Two,Three" + print(some_array[1]) # Prints "Four" [/gdscript] [csharp] - // There is no Rsplit. + // In C#, there is no String.RSplit() method. [/csharp] [/codeblocks] </description> @@ -661,51 +747,55 @@ <return type="String" /> <param index="0" name="chars" type="String" /> <description> - Returns a copy of the string with characters removed from the right. The [param chars] argument is a string specifying the set of characters to be removed. - [b]Note:[/b] The [param chars] is not a suffix. See [method trim_suffix] method that will remove a single suffix string rather than a set of characters. + Removes a set of characters defined in [param chars] from the string's end. See also [method lstrip]. + [b]Note:[/b] [param chars] is not a suffix. Use [method trim_suffix] to remove a single suffix, rather than a set of characters. </description> </method> <method name="sha1_buffer" qualifiers="const"> <return type="PackedByteArray" /> <description> - Returns the SHA-1 hash of the string as an array of bytes. + Returns the [url=https://en.wikipedia.org/wiki/SHA-1]SHA-1[/url] hash of the string as a [PackedByteArray]. </description> </method> <method name="sha1_text" qualifiers="const"> <return type="String" /> <description> - Returns the SHA-1 hash of the string as a string. + Returns the [url=https://en.wikipedia.org/wiki/SHA-1]SHA-1[/url] hash of the string as another [String]. </description> </method> <method name="sha256_buffer" qualifiers="const"> <return type="PackedByteArray" /> <description> - Returns the SHA-256 hash of the string as an array of bytes. + Returns the [url=https://en.wikipedia.org/wiki/SHA-2]SHA-256[/url] hash of the string as a [PackedByteArray]. </description> </method> <method name="sha256_text" qualifiers="const"> <return type="String" /> <description> - Returns the SHA-256 hash of the string as a string. + Returns the [url=https://en.wikipedia.org/wiki/SHA-2]SHA-256[/url] hash of the string as another [String]. </description> </method> <method name="similarity" qualifiers="const"> <return type="float" /> <param index="0" name="text" type="String" /> <description> - Returns the similarity index ([url=https://en.wikipedia.org/wiki/S%C3%B8rensen%E2%80%93Dice_coefficient]Sorensen-Dice coefficient[/url]) of this string compared to another. A result of 1.0 means totally similar, while 0.0 means totally dissimilar. + Returns the similarity index ([url=https://en.wikipedia.org/wiki/S%C3%B8rensen%E2%80%93Dice_coefficient]Sorensen-Dice coefficient[/url]) of this string compared to another. A result of [code]1.0[/code] means totally similar, while [code]0.0[/code] means totally dissimilar. [codeblock] - print("ABC123".similarity("ABC123")) # Prints "1" - print("ABC123".similarity("XYZ456")) # Prints "0" - print("ABC123".similarity("123ABC")) # Prints "0.8" - print("ABC123".similarity("abc123")) # Prints "0.4" + print("ABC123".similarity("ABC123")) # Prints 1.0 + print("ABC123".similarity("XYZ456")) # Prints 0.0 + print("ABC123".similarity("123ABC")) # Prints 0.8 + print("ABC123".similarity("abc123")) # Prints 0.4 [/codeblock] </description> </method> <method name="simplify_path" qualifiers="const"> <return type="String" /> <description> - Returns a simplified canonical path. + If the string is a valid file path, converts the string into a canonical path. This is the shortest possible path, without [code]"./"[/code], and all the unnecessary [code]".."[/code] and [code]"/"[/code]. + [codeblock] + var simple_path = "./path/to///../file".simplify_path() + print(simple_path) # Prints "path/file" + [/codeblock] </description> </method> <method name="split" qualifiers="const"> @@ -714,27 +804,29 @@ <param index="1" name="allow_empty" type="bool" default="true" /> <param index="2" name="maxsplit" type="int" default="0" /> <description> - Splits the string by a [param delimiter] string and returns an array of the substrings. The [param delimiter] can be of any length. If [param delimiter] is an empty string, each substring will be a single character. - If [param allow_empty] is [code]true[/code], and there are two adjacent delimiters in the string, it will add an empty string to the array of substrings at this position. - If [param maxsplit] is specified, it defines the number of splits to do from the left up to [param maxsplit]. The default value of [code]0[/code] means that all items are split. - If you need only one element from the array at a specific index, [method get_slice] is a more performant option. + Splits the string using a [param delimiter] and returns an array of the substrings. If [param delimiter] is an empty string, each substring will be a single character. This method is the opposite of [method join]. + If [param allow_empty] is [code]false[/code], empty strings between adjacent delimiters are excluded from the array. + If [param maxsplit] is greater than [code]0[/code], the number of splits may not exceed [param maxsplit]. By default, the entire string is split. [b]Example:[/b] [codeblocks] [gdscript] - var some_string = "One,Two,Three,Four" - var some_array = some_string.split(",", true, 1) - print(some_array.size()) # Prints 2 - print(some_array[0]) # Prints "Four" - print(some_array[1]) # Prints "Three,Two,One" + var some_array = "One,Two,Three,Four".split(",", true, 2) + + print(some_array.size()) # Prints 3 + print(some_array[0]) # Prints "One" + print(some_array[1]) # Prints "Two" + print(some_array[2]) # Prints "Three,Four" [/gdscript] [csharp] - var someString = "One,Two,Three,Four"; - var someArray = someString.Split(",", true); // This is as close as it gets to Godots API. - GD.Print(someArray[0]); // Prints "Four" - GD.Print(someArray[1]); // Prints "Three,Two,One" + // C#'s `Split()` does not support the `maxsplit` parameter. + var someArray = "One,Two,Three".Split(","); + + GD.Print(someArray[0]); // Prints "One" + GD.Print(someArray[1]); // Prints "Two" + GD.Print(someArray[2]); // Prints "Three" [/csharp] [/codeblocks] - If you need to split strings with more complex rules, use the [RegEx] class instead. + [b]Note:[/b] If you only need one substring from the array, consider using [method get_slice] which is faster. If you need to split strings with more complex rules, use the [RegEx] class instead. </description> </method> <method name="split_floats" qualifiers="const"> @@ -742,9 +834,13 @@ <param index="0" name="delimiter" type="String" /> <param index="1" name="allow_empty" type="bool" default="true" /> <description> - Splits the string in floats by using a delimiter string and returns an array of the substrings. - For example, [code]"1,2.5,3"[/code] will return [code][1,2.5,3][/code] if split by [code]","[/code]. - If [param allow_empty] is [code]true[/code], and there are two adjacent delimiters in the string, it will add an empty string to the array of substrings at this position. + Splits the string into floats by using a [param delimiter] and returns a [PackedFloat64Array]. + If [param allow_empty] is [code]false[/code], empty or invalid [float] conversions between adjacent delimiters are excluded. + [codeblock] + var a = "1,2,4.5".split_floats(",") # a is [1.0, 2.0, 4.5] + var c = "1| ||4.5".split_floats("|") # c is [1.0, 0.0, 0.0, 4.5] + var b = "1| ||4.5".split_floats("|", false) # b is [1.0, 4.5] + [/codeblock] </description> </method> <method name="strip_edges" qualifiers="const"> @@ -752,13 +848,14 @@ <param index="0" name="left" type="bool" default="true" /> <param index="1" name="right" type="bool" default="true" /> <description> - Returns a copy of the string stripped of any non-printable character (including tabulations, spaces and line breaks) at the beginning and the end. The optional arguments are used to toggle stripping on the left and right edges respectively. + Strips all non-printable characters from the beginning and the end of the string. These include spaces, tabulations ([code]\t[/code]), and newlines ([code]\n[/code] [code]\r[/code]). + If [param left] is [code]false[/code], ignores the string's beginning. Likewise, if [param right] is [code]false[/code], ignores the string's end. </description> </method> <method name="strip_escapes" qualifiers="const"> <return type="String" /> <description> - Returns a copy of the string stripped of any escape character. These include all non-printable control characters of the first page of the ASCII table (< 32), such as tabulation ([code]\t[/code] in C) and newline ([code]\n[/code] and [code]\r[/code]) characters, but not spaces. + Strips all escape characters from the string. These include all non-printable control characters of the first page of the ASCII table (values from 0 to 31), such as tabulation ([code]\t[/code]) and newline ([code]\n[/code], [code]\r[/code]) characters, but [i]not[/i] spaces. </description> </method> <method name="substr" qualifiers="const"> @@ -766,13 +863,13 @@ <param index="0" name="from" type="int" /> <param index="1" name="len" type="int" default="-1" /> <description> - Returns part of the string from the position [param from] with length [param len]. Argument [param len] is optional and using [code]-1[/code] will return remaining characters from given position. + Returns part of the string from the position [param from] with length [param len]. If [param len] is [code]-1[/code] (as by default), returns the rest of the string starting from the given position. </description> </method> <method name="to_ascii_buffer" qualifiers="const"> <return type="PackedByteArray" /> <description> - Converts the String (which is a character array) to ASCII/Latin-1 encoded [PackedByteArray] (which is an array of bytes). The conversion is faster compared to [method to_utf8_buffer], as this method assumes that all the characters in the String are ASCII/Latin-1 characters, unsupported characters are replaced with spaces. + Converts the string to an [url=https://en.wikipedia.org/wiki/ASCII]ASCII[/url]/Latin-1 encoded [PackedByteArray]. This method is slightly faster than [method to_utf8_buffer], but replaces all unsupported characters with spaces. </description> </method> <method name="to_camel_case" qualifiers="const"> @@ -784,23 +881,25 @@ <method name="to_float" qualifiers="const"> <return type="float" /> <description> - Converts a string containing a decimal number into a [code]float[/code]. The method will stop on the first non-number character except the first [code].[/code] (decimal point), and [code]e[/code] which is used for exponential. + Converts the string representing a decimal number into a [float]. This method stops on the first non-number character, except the first decimal point ([code].[/code]) and the exponent letter ([code]e[/code]). See also [method is_valid_float]. [codeblock] - print("12.3".to_float()) # 12.3 - print("1.2.3".to_float()) # 1.2 - print("12ab3".to_float()) # 12 - print("1e3".to_float()) # 1000 + var a = "12.35".to_float() # a is 12.35 + var b = "1.2.3".to_float() # b is 1.2 + var c = "12xy3".to_float() # c is 12.0 + var d = "1e3".to_float() # d is 1000.0 + var e = "Hello!".to_int() # e is 0.0 [/codeblock] </description> </method> <method name="to_int" qualifiers="const"> <return type="int" /> <description> - Converts a string containing an integer number into an [code]int[/code]. The method will remove any non-number character and stop if it encounters a [code].[/code]. + Converts the string representing an integer number into an [int]. This method removes any non-number character and stops at the first decimal point ([code].[/code]). See also [method is_valid_int]. [codeblock] - print("123".to_int()) # 123 - print("a1b2c3".to_int()) # 123 - print("1.2.3".to_int()) # 1 + var a = "123".to_int() # a is 123 + var b = "x1y2z3".to_int() # b is 123 + var c = "-1.2.3".to_int() # c is -1 + var d = "Hello!".to_int() # d is 0 [/codeblock] </description> </method> @@ -831,33 +930,33 @@ <method name="to_utf16_buffer" qualifiers="const"> <return type="PackedByteArray" /> <description> - Converts the String (which is an array of characters) to UTF-16 encoded [PackedByteArray] (which is an array of bytes). + Converts the string to a [url=https://en.wikipedia.org/wiki/UTF-16]UTF-16[/url] encoded [PackedByteArray]. </description> </method> <method name="to_utf32_buffer" qualifiers="const"> <return type="PackedByteArray" /> <description> - Converts the String (which is an array of characters) to UTF-32 encoded [PackedByteArray] (which is an array of bytes). + Converts the string to a [url=https://en.wikipedia.org/wiki/UTF-32]UTF-32[/url] encoded [PackedByteArray]. </description> </method> <method name="to_utf8_buffer" qualifiers="const"> <return type="PackedByteArray" /> <description> - Converts the String (which is an array of characters) to UTF-8 encode [PackedByteArray] (which is an array of bytes). The conversion is a bit slower than [method to_ascii_buffer], but supports all UTF-8 characters. Therefore, you should prefer this function over [method to_ascii_buffer]. + Converts the string to a [url=https://en.wikipedia.org/wiki/UTF-8]UTF-8[/url] encoded [PackedByteArray]. This method is slightly slower than [method to_ascii_buffer], but supports all UTF-8 characters. For most cases, prefer using this method. </description> </method> <method name="trim_prefix" qualifiers="const"> <return type="String" /> <param index="0" name="prefix" type="String" /> <description> - Removes a given string from the start if it starts with it or leaves the string unchanged. + Removes the given [param prefix] from the start of the string, or returns the string unchanged. </description> </method> <method name="trim_suffix" qualifiers="const"> <return type="String" /> <param index="0" name="suffix" type="String" /> <description> - Removes a given string from the end if it ends with it or leaves the string unchanged. + Removes the given [param suffix] from the end of the string, or returns the string unchanged. </description> </method> <method name="unicode_at" qualifiers="const"> @@ -870,13 +969,15 @@ <method name="uri_decode" qualifiers="const"> <return type="String" /> <description> - Decodes a string in URL encoded format. This is meant to decode parameters in a URL when receiving an HTTP request. + Decodes the string from its URL-encoded format. This method is meant to properly decode the parameters in a URL when receiving an HTTP request. [codeblocks] [gdscript] - print("https://example.org/?escaped=" + "Godot%20Engine%3A%27docs%27".uri_decode()) + var url = "$DOCS_URL/?highlight=Godot%20Engine%3%docs" + print(url.uri_decode()) # Prints "$DOCS_URL/?hightlight=Godot Engine:docs" [/gdscript] [csharp] - GD.Print("https://example.org/?escaped=" + "Godot%20Engine%3a%27Docs%27".URIDecode()); + var url = "$DOCS_URL/?highlight=Godot%20Engine%3%docs" + GD.Print(url.URIDecode()) // Prints "$DOCS_URL/?hightlight=Godot Engine:docs" [/csharp] [/codeblocks] </description> @@ -884,13 +985,19 @@ <method name="uri_encode" qualifiers="const"> <return type="String" /> <description> - Encodes a string to URL friendly format. This is meant to encode parameters in a URL when sending an HTTP request. + Encodes the string to URL-friendly format. This method is meant to properly encode the parameters in a URL when sending an HTTP request. [codeblocks] [gdscript] - print("https://example.org/?escaped=" + "Godot Engine:'docs'".uri_encode()) + var prefix = "$DOCS_URL/?hightlight=" + var url = prefix + "Godot Engine:docs".uri_encode() + + print(url) # Prints "$DOCS_URL/?highlight=Godot%20Engine%3%docs" [/gdscript] [csharp] - GD.Print("https://example.org/?escaped=" + "Godot Engine:'docs'".URIEncode()); + var prefix = "$DOCS_URL/?hightlight="; + var url = prefix + "Godot Engine:docs".URIEncode(); + + GD.Print(url); // Prints "$DOCS_URL/?highlight=Godot%20Engine%3%docs" [/csharp] [/codeblocks] </description> @@ -898,7 +1005,7 @@ <method name="validate_node_name" qualifiers="const"> <return type="String" /> <description> - Removes any characters from the string that are prohibited in [Node] names ([code].[/code] [code]:[/code] [code]@[/code] [code]/[/code] [code]"[/code]). + Removes all characters that are not allowed in [member Node.name] from the string ([code].[/code] [code]:[/code] [code]@[/code] [code]/[/code] [code]"[/code] [code]%[/code]). </description> </method> <method name="xml_escape" qualifiers="const"> @@ -955,6 +1062,12 @@ Appends [param right] at the end of this [String], also known as a string concatenation. </description> </operator> + <operator name="operator +"> + <return type="String" /> + <param index="0" name="right" type="StringName" /> + <description> + </description> + </operator> <operator name="operator <"> <return type="bool" /> <param index="0" name="right" type="String" /> diff --git a/doc/classes/StringName.xml b/doc/classes/StringName.xml index 02e9c62cd6..e3cb6517f3 100644 --- a/doc/classes/StringName.xml +++ b/doc/classes/StringName.xml @@ -7,6 +7,8 @@ [StringName]s are immutable strings designed for general-purpose representation of unique names (also called "string interning"). [StringName] ensures that only one instance of a given name exists (so two [StringName]s with the same value are the same object). Comparing them is much faster than with regular [String]s, because only the pointers are compared, not the whole strings. You will usually just pass a [String] to methods expecting a [StringName] and it will be automatically converted, but you may occasionally want to construct a [StringName] ahead of time with [StringName] or, in GDScript, the literal syntax [code]&"example"[/code]. See also [NodePath], which is a similar concept specifically designed to store pre-parsed node paths. + Some string methods have corresponding variations. Variations suffixed with [code]n[/code] ([method countn], [method findn], [method replacen], etc.) are [b]case-insensitive[/b] (they make no distinction between uppercase and lowercase letters). Method variations prefixed with [code]r[/code] ([method rfind], [method rsplit], etc.) are reversed, and start from the end of the string, instead of the beginning. + [b]Note:[/b] In a boolean context, a [StringName] will evaluate to [code]false[/code] if it is empty ([code]StringName("")[/code]). Otherwise, a [StringName] will always evaluate to [code]true[/code]. </description> <tutorials> </tutorials> @@ -33,10 +35,897 @@ </constructor> </constructors> <methods> + <method name="begins_with" qualifiers="const"> + <return type="bool" /> + <param index="0" name="text" type="String" /> + <description> + Returns [code]true[/code] if the string begins with the given [param text]. See also [method ends_with]. + </description> + </method> + <method name="bigrams" qualifiers="const"> + <return type="PackedStringArray" /> + <description> + Returns an array containing the bigrams (pairs of consecutive characters) of this string. + [codeblock] + print("Get up!".bigrams()) # Prints ["Ge", "et", "t ", " u", "up", "p!"] + [/codeblock] + </description> + </method> + <method name="bin_to_int" qualifiers="const"> + <return type="int" /> + <description> + Converts the string representing a binary number into an [int]. The string may optionally be prefixed with [code]"0b"[/code], and an additional [code]-[/code] prefix for negative numbers. + [codeblocks] + [gdscript] + print("101".bin_to_int()) # Prints 5 + print("0b101".bin_to_int()) # Prints 5 + print("-0b10".bin_to_int()) # Prints -2 + [/gdscript] + [csharp] + GD.Print("101".BinToInt()); // Prints 5 + GD.Print("0b101".BinToInt()); // Prints 5 + GD.Print("-0b10".BinToInt()); // Prints -2 + [/csharp] + [/codeblocks] + </description> + </method> + <method name="c_escape" qualifiers="const"> + <return type="String" /> + <description> + Returns a copy of the string with special characters escaped using the C language standard. + </description> + </method> + <method name="c_unescape" qualifiers="const"> + <return type="String" /> + <description> + Returns a copy of the string with escaped characters replaced by their meanings. Supported escape sequences are [code]\'[/code], [code]\"[/code], [code]\\[/code], [code]\a[/code], [code]\b[/code], [code]\f[/code], [code]\n[/code], [code]\r[/code], [code]\t[/code], [code]\v[/code]. + [b]Note:[/b] Unlike the GDScript parser, this method doesn't support the [code]\uXXXX[/code] escape sequence. + </description> + </method> + <method name="capitalize" qualifiers="const"> + <return type="String" /> + <description> + Changes the appearance of the string: replaces underscores ([code]_[/code]) with spaces, adds spaces before uppercase letters in the middle of a word, converts all letters to lowercase, then converts the first one and each one following a space to uppercase. + [codeblocks] + [gdscript] + "move_local_x".capitalize() # Returns "Move Local X" + "sceneFile_path".capitalize() # Returns "Scene File Path" + [/gdscript] + [csharp] + "move_local_x".Capitalize(); // Returns "Move Local X" + "sceneFile_path".Capitalize(); // Returns "Scene File Path" + [/csharp] + [/codeblocks] + [b]Note:[/b] This method not the same as the default appearance of properties in the Inspector dock, as it does not capitalize acronyms ([code]"2D"[/code], [code]"FPS"[/code], [code]"PNG"[/code], etc.) as you may expect. + </description> + </method> + <method name="casecmp_to" qualifiers="const"> + <return type="int" /> + <param index="0" name="to" type="String" /> + <description> + Performs a case-sensitive comparison to another string. Returns [code]-1[/code] if less than, [code]1[/code] if greater than, or [code]0[/code] if equal. "Less than" and "greater than" are determined by the [url=https://en.wikipedia.org/wiki/List_of_Unicode_characters]Unicode code points[/url] of each string, which roughly matches the alphabetical order. + With different string lengths, returns [code]1[/code] if this string is longer than the [param to] string, or [code]-1[/code] if shorter. Note that the length of empty strings is [i]always[/i] [code]0[/code]. + To get a [bool] result from a string comparison, use the [code]==[/code] operator instead. See also [method nocasecmp_to] and [method naturalnocasecmp_to]. + </description> + </method> + <method name="contains" qualifiers="const"> + <return type="bool" /> + <param index="0" name="what" type="String" /> + <description> + Returns [code]true[/code] if the string contains [param what]. In GDScript, this corresponds to the [code]in[/code] operator. + [codeblocks] + [gdscript] + print("Node".contains("de")) # Prints true + print("team".contains("I")) # Prints false + print("I" in "team") # Prints false + [/gdscript] + [csharp] + GD.Print("Node".Contains("de")); // Prints true + GD.Print("team".Contains("I")); // Prints false + [/csharp] + [/codeblocks] + If you need to know where [param what] is within the string, use [method find]. + </description> + </method> + <method name="count" qualifiers="const"> + <return type="int" /> + <param index="0" name="what" type="String" /> + <param index="1" name="from" type="int" default="0" /> + <param index="2" name="to" type="int" default="0" /> + <description> + Returns the number of occurrences of the substring [param what] between [param from] and [param to] positions. If [param to] is 0, the search continues until the end of the string. + </description> + </method> + <method name="countn" qualifiers="const"> + <return type="int" /> + <param index="0" name="what" type="String" /> + <param index="1" name="from" type="int" default="0" /> + <param index="2" name="to" type="int" default="0" /> + <description> + Returns the number of occurrences of the substring [param what] between [param from] and [param to] positions, [b]ignoring case[/b]. If [param to] is 0, the search continues until the end of the string. + </description> + </method> + <method name="dedent" qualifiers="const"> + <return type="String" /> + <description> + Returns a copy of the string with indentation (leading tabs and spaces) removed. See also [method indent] to add indentation. + </description> + </method> + <method name="ends_with" qualifiers="const"> + <return type="bool" /> + <param index="0" name="text" type="String" /> + <description> + Returns [code]true[/code] if the string ends with the given [param text]. See also [method begins_with]. + </description> + </method> + <method name="find" qualifiers="const"> + <return type="int" /> + <param index="0" name="what" type="String" /> + <param index="1" name="from" type="int" default="0" /> + <description> + Returns the index of the [b]first[/b] occurrence of [param what] in this string, or [code]-1[/code] if there are none. The search's start can be specified with [param from], continuing to the end of the string. + [codeblocks] + [gdscript] + print("Team".find("I")) # Prints -1 + + print("Potato".find("t")) # Prints 2 + print("Potato".find("t", 3)) # Prints 4 + print("Potato".find("t", 5)) # Prints -1 + [/gdscript] + [csharp] + GD.Print("Team".Find("I")); // Prints -1 + + GD.Print("Potato".Find("t")); // Prints 2 + GD.print("Potato".Find("t", 3)); // Prints 4 + GD.print("Potato".Find("t", 5)); // Prints -1 + [/csharp] + [/codeblocks] + [b]Note:[/b] If you just want to know whether the string contains [param what], use [method contains]. In GDScript, you may also use the [code]in[/code] operator. + </description> + </method> + <method name="findn" qualifiers="const"> + <return type="int" /> + <param index="0" name="what" type="String" /> + <param index="1" name="from" type="int" default="0" /> + <description> + Returns the index of the [b]first[/b] [b]case-insensitive[/b] occurrence of [param what] in this string, or [code]-1[/code] if there are none. The starting search index can be specified with [param from], continuing to the end of the string. + </description> + </method> + <method name="format" qualifiers="const"> + <return type="String" /> + <param index="0" name="values" type="Variant" /> + <param index="1" name="placeholder" type="String" default=""{_}"" /> + <description> + Formats the string by replacing all occurrences of [param placeholder] with the elements of [param values]. + [param values] can be a [Dictionary] or an [Array]. Any underscores in [param placeholder] will be replaced with the corresponding keys in advance. Array elements use their index as keys. + [codeblock] + # Prints "Waiting for Godot is a play by Samuel Beckett, and Godot Engine is named after it." + var use_array_values = "Waiting for {0} is a play by {1}, and {0} Engine is named after it." + print(use_array_values.format(["Godot", "Samuel Beckett"])) + + # Prints "User 42 is Godot." + print("User {id} is {name}.".format({"id": 42, "name": "Godot"})) + [/codeblock] + Some additional handling is performed when [param values] is an [Array]. If [param placeholder] does not contain an underscore, the elements of the [param values] array will be used to replace one occurrence of the placeholder in order; If an element of [param values] is another 2-element array, it'll be interpreted as a key-value pair. + [codeblock] + # Prints "User 42 is Godot." + print("User {} is {}.".format([42, "Godot"], "{}")) + print("User {id} is {name}.".format([["id", 42], ["name", "Godot"]])) + [/codeblock] + See also the [url=$DOCS_URL/tutorials/scripting/gdscript/gdscript_format_string.html]GDScript format string[/url] tutorial. + </description> + </method> + <method name="get_base_dir" qualifiers="const"> + <return type="String" /> + <description> + If the string is a valid file path, returns the base directory name. + [codeblock] + var dir_path = "/path/to/file.txt".get_basename() # dir_path is "/path/to" + [/codeblock] + </description> + </method> + <method name="get_basename" qualifiers="const"> + <return type="String" /> + <description> + If the string is a valid file path, returns the full file path, without the extension. + [codeblock] + var base = "/path/to/file.txt".get_basename() # base is "/path/to/file" + [/codeblock] + </description> + </method> + <method name="get_extension" qualifiers="const"> + <return type="String" /> + <description> + If the string is a valid file name or path, returns the file extension without the leading period ([code].[/code]). Otherwise, returns an empty string. + [codeblock] + var a = "/path/to/file.txt".get_extension() # a is "txt" + var b = "cool.txt".get_extension() # b is "txt" + var c = "cool.font.tres".get_extension() # c is "tres" + var d = ".pack1".get_extension() # d is "pack1" + + var e = "file.txt.".get_extension() # e is "" + var f = "file.txt..".get_extension() # f is "" + var g = "txt".get_extension() # g is "" + var h = "".get_extension() # h is "" + [/codeblock] + </description> + </method> + <method name="get_file" qualifiers="const"> + <return type="String" /> + <description> + If the string is a valid file path, returns the file name, including the extension. + [codeblock] + var file = "/path/to/icon.png".get_file() # file is "icon.png" + [/codeblock] + </description> + </method> + <method name="get_slice" qualifiers="const"> + <return type="String" /> + <param index="0" name="delimiter" type="String" /> + <param index="1" name="slice" type="int" /> + <description> + Splits the string using a [param delimiter] and returns the substring at index [param slice]. Returns an empty string if the [param slice] does not exist. + This is faster than [method split], if you only need one substring. + [b]Example:[/b] + [codeblock] + print("i/am/example/hi".get_slice("/", 2)) # Prints "example" + [/codeblock] + </description> + </method> + <method name="get_slice_count" qualifiers="const"> + <return type="int" /> + <param index="0" name="delimiter" type="String" /> + <description> + Returns the total number of slices when the string is split with the given [param delimiter] (see [method split]). + </description> + </method> + <method name="get_slicec" qualifiers="const"> + <return type="String" /> + <param index="0" name="delimiter" type="int" /> + <param index="1" name="slice" type="int" /> + <description> + Splits the string using a Unicode character with code [param delimiter] and returns the substring at index [param slice]. Returns an empty string if the [param slice] does not exist. + This is faster than [method split], if you only need one substring. + </description> + </method> <method name="hash" qualifiers="const"> <return type="int" /> <description> - Returns the 32-bit hash value representing the [StringName]'s contents. + Returns the 32-bit hash value representing the string's contents. + [b]Note:[/b] Strings with equal hash values are [i]not[/i] guaranteed to be the same, as a result of hash collisions. On the countrary, strings with different hash values are guaranteed to be different. + </description> + </method> + <method name="hex_to_int" qualifiers="const"> + <return type="int" /> + <description> + Converts the string representing a hexadecimal number into an [int]. The string may be optionally prefixed with [code]"0x"[/code], and an additional [code]-[/code] prefix for negative numbers. + [codeblocks] + [gdscript] + print("0xff".hex_to_int()) # Prints 255 + print("ab".hex_to_int()) # Prints 171 + [/gdscript] + [csharp] + GD.Print("0xff".HexToInt()); // Prints 255 + GD.Print("ab".HexToInt()); // Prints 171 + [/csharp] + [/codeblocks] + </description> + </method> + <method name="indent" qualifiers="const"> + <return type="String" /> + <param index="0" name="prefix" type="String" /> + <description> + Indents every line of the string with the given [param prefix]. Empty lines are not indented. See also [method dedent] to remove indentation. + For example, the string can be indented with two tabulations using [code]"\t\t"[/code], or four spaces using [code]" "[/code]. + </description> + </method> + <method name="insert" qualifiers="const"> + <return type="String" /> + <param index="0" name="position" type="int" /> + <param index="1" name="what" type="String" /> + <description> + Inserts [param what] at the given [param position] in the string. + </description> + </method> + <method name="is_absolute_path" qualifiers="const"> + <return type="bool" /> + <description> + Returns [code]true[/code] if the string is a path to a file or directory, and its starting point is explicitly defined. This method is the opposite of [method is_relative_path]. + This includes all paths starting with [code]"res://"[/code], [code]"user://"[/code], [code]"C:\"[/code], [code]"/"[/code], etc. + </description> + </method> + <method name="is_empty" qualifiers="const"> + <return type="bool" /> + <description> + Returns [code]true[/code] if the string's length is [code]0[/code] ([code]""[/code]). See also [method length]. + </description> + </method> + <method name="is_relative_path" qualifiers="const"> + <return type="bool" /> + <description> + Returns [code]true[/code] if the string is a path, and its starting point is dependent on context. The path could begin from the current directory, or the current [Node] (if the string is derived from a [NodePath]), and may sometimes be prefixed with [code]"./"[/code]. This method is the opposite of [method is_absolute_path]. + </description> + </method> + <method name="is_subsequence_of" qualifiers="const"> + <return type="bool" /> + <param index="0" name="text" type="String" /> + <description> + Returns [code]true[/code] if all characters of this string can be found in [param text] in their original order. + [codeblock] + var text = "Wow, incredible!" + + print("inedible".is_subsequence_of(text)) # Prints true + print("Word!".is_subsequence_of(text)) # Prints true + print("Window".is_subsequence_of(text)) # Prints false + print("".is_subsequence_of(text)) # Prints true + [/codeblock] + </description> + </method> + <method name="is_subsequence_ofn" qualifiers="const"> + <return type="bool" /> + <param index="0" name="text" type="String" /> + <description> + Returns [code]true[/code] if all characters of this string can be found in [param text] in their original order, [b]ignoring case[/b]. + </description> + </method> + <method name="is_valid_filename" qualifiers="const"> + <return type="bool" /> + <description> + Returns [code]true[/code] if this string does not contain characters that are not allowed in file names ([code]:[/code] [code]/[/code] [code]\[/code] [code]?[/code] [code]*[/code] [code]"[/code] [code]|[/code] [code]%[/code] [code]<[/code] [code]>[/code]). + </description> + </method> + <method name="is_valid_float" qualifiers="const"> + <return type="bool" /> + <description> + Returns [code]true[/code] if this string represents a valid floating-point number. A valid float may contain only digits, one decimal point ([code].[/code]), and the exponent letter ([code]e[/code]). It may also be prefixed with a positive ([code]+[/code]) or negative ([code]-[/code]) sign. Any valid integer is also a valid float (see [method is_valid_int]). See also [method to_float]. + [codeblock] + print("1.7".is_valid_float()) # Prints true + print("24".is_valid_float()) # Prints true + print("7e3".is_valid_float()) # Prints true + print("Hello".is_valid_float()) # Prints false + [/codeblock] + </description> + </method> + <method name="is_valid_hex_number" qualifiers="const"> + <return type="bool" /> + <param index="0" name="with_prefix" type="bool" default="false" /> + <description> + Returns [code]true[/code] if this string is a valid hexadecimal number. A valid hexadecimal number only contains digits or letters [code]A[/code] to [code]F[/code] (either uppercase or lowercase), and may be prefixed with a positive ([code]+[/code]) or negative ([code]-[/code]) sign. + If [param with_prefix] is [code]true[/code], the hexadecimal number needs to prefixed by [code]"0x"[/code] to be considered valid. + [codeblock] + print("A08E".is_valid_hex_number()) # Prints true + print("-AbCdEf".is_valid_hex_number()) # Prints true + print("2.5".is_valid_hex_number()) # Prints false + + print("0xDEADC0DE".is_valid_hex_number(true)) # Prints true + [/codeblock] + </description> + </method> + <method name="is_valid_html_color" qualifiers="const"> + <return type="bool" /> + <description> + Returns [code]true[/code] if this string is a valid color in hexadecimal HTML notation. The string must be a hexadecimal value (see [method is_valid_hex_number]) of either 3, 4, 6 or 8 digits, and may be prefixed by a hash sign ([code]#[/code]). Other HTML notations for colors, such as names or [code]hsl()[/code], are not considered valid. See also [method Color.html]. + </description> + </method> + <method name="is_valid_identifier" qualifiers="const"> + <return type="bool" /> + <description> + Returns [code]true[/code] if this string is a valid identifier. A valid identifier may contain only letters, digits and underscores ([code]_[/code]), and the first character may not be a digit. + [codeblock] + print("node_2d".is_valid_identifier()) # Prints true + print("TYPE_FLOAT".is_valid_identifier()) # Prints true + print("1st_method".is_valid_identifier()) # Prints false + print("MyMethod#2".is_valid_identifier()) # Prints false + [/codeblock] + </description> + </method> + <method name="is_valid_int" qualifiers="const"> + <return type="bool" /> + <description> + Returns [code]true[/code] if this string represents a valid integer. A valid integer only contains digits, and may be prefixed with a positive ([code]+[/code]) or negative ([code]-[/code]) sign. See also [method to_int]. + [codeblock] + print("7".is_valid_int()) # Prints true + print("1.65".is_valid_int()) # Prints false + print("Hi".is_valid_int()) # Prints false + print("+3".is_valid_int()) # Prints true + print("-12".is_valid_int()) # Prints true + [/codeblock] + </description> + </method> + <method name="is_valid_ip_address" qualifiers="const"> + <return type="bool" /> + <description> + Returns [code]true[/code] if this string represents a well-formatted IPv4 or IPv6 address. This method considers [url=https://en.wikipedia.org/wiki/Reserved_IP_addresses]reserved IP addresses[/url] such as [code]"0.0.0.0"[/code] and [code]"ffff:ffff:ffff:ffff:ffff:ffff:ffff:ffff"[/code] as valid. + </description> + </method> + <method name="join" qualifiers="const"> + <return type="String" /> + <param index="0" name="parts" type="PackedStringArray" /> + <description> + Returns the concatenation of [param parts]' elements, with each element separated by the string calling this method. This method is the opposite of [method split]. + [b]Example:[/b] + [codeblocks] + [gdscript] + var fruits = ["Apple", "Orange", "Pear", "Kiwi"] + + print(", ".join(fruits)) # Prints "Apple, Orange, Pear, Kiwi" + print("---".join(fruits)) # Prints "Apple---Orange---Pear---Kiwi" + [/gdscript] + [csharp] + var fruits = new string[] {"Apple", "Orange", "Pear", "Kiwi"}; + + // In C#, this method is static. + GD.Print(string.Join(", ", fruits); // Prints "Apple, Orange, Pear, Kiwi" + GD.Print(string.Join("---", fruits)); // Prints "Apple---Orange---Pear---Kiwi" + [/csharp] + [/codeblocks] + </description> + </method> + <method name="json_escape" qualifiers="const"> + <return type="String" /> + <description> + Returns a copy of the string with special characters escaped using the JSON standard. Because it closely matches the C standard, it is possible to use [method c_unescape] to unescape the string, if necessary. + </description> + </method> + <method name="left" qualifiers="const"> + <return type="String" /> + <param index="0" name="length" type="int" /> + <description> + Returns the first [param length] characters from the beginning of the string. If [param length] is negative, strips the last [param length] characters from the string's end. + [codeblock] + print("Hello World!".left(3)) # Prints "Hel" + print("Hello World!".left(-4)) # Prints "Hello Wo" + [/codeblock] + </description> + </method> + <method name="length" qualifiers="const"> + <return type="int" /> + <description> + Returns the number of characters in the string. Empty strings ([code]""[/code]) always return [code]0[/code]. See also [method is_empty]. + </description> + </method> + <method name="lpad" qualifiers="const"> + <return type="String" /> + <param index="0" name="min_length" type="int" /> + <param index="1" name="character" type="String" default="" "" /> + <description> + Formats the string to be at least [param min_length] long by adding [param character]s to the left of the string, if necessary. See also [method rpad]. + </description> + </method> + <method name="lstrip" qualifiers="const"> + <return type="String" /> + <param index="0" name="chars" type="String" /> + <description> + Removes a set of characters defined in [param chars] from the string's beginning. See also [method rstrip]. + [b]Note:[/b] [param chars] is not a prefix. Use [method trim_prefix] to remove a single prefix, rather than a set of characters. + </description> + </method> + <method name="match" qualifiers="const"> + <return type="bool" /> + <param index="0" name="expr" type="String" /> + <description> + Does a simple expression match, where [code]*[/code] matches zero or more arbitrary characters and [code]?[/code] matches any single character except a period ([code].[/code]). An empty string or empty expression always evaluates to [code]false[/code]. + </description> + </method> + <method name="matchn" qualifiers="const"> + <return type="bool" /> + <param index="0" name="expr" type="String" /> + <description> + Does a simple [b]case-insensitive[/b] expression match, where [code]*[/code] matches zero or more arbitrary characters and [code]?[/code] matches any single character except a period ([code].[/code]). An empty string or empty expression always evaluates to [code]false[/code]. + </description> + </method> + <method name="md5_buffer" qualifiers="const"> + <return type="PackedByteArray" /> + <description> + Returns the [url=https://en.wikipedia.org/wiki/MD5]MD5 hash[/url] of the string as a [PackedByteArray]. + </description> + </method> + <method name="md5_text" qualifiers="const"> + <return type="String" /> + <description> + Returns the [url=https://en.wikipedia.org/wiki/MD5]MD5 hash[/url] of the string as another [String]. + </description> + </method> + <method name="naturalnocasecmp_to" qualifiers="const"> + <return type="int" /> + <param index="0" name="to" type="String" /> + <description> + Performs a [b]case-insensitive[/b], [i]natural order[/i] comparison to another string. Returns [code]-1[/code] if less than, [code]1[/code] if greater than, or [code]0[/code] if equal. "Less than" or "greater than" are determined by the [url=https://en.wikipedia.org/wiki/List_of_Unicode_characters]Unicode code points[/url] of each string, which roughly matches the alphabetical order. Internally, lowercase characters are converted to uppercase for the comparison. + When used for sorting, natural order comparison orders sequences of numbers by the combined value of each digit as is often expected, instead of the single digit's value. A sorted sequence of numbered strings will be [code]["1", "2", "3", ...][/code], not [code]["1", "10", "2", "3", ...][/code]. + With different string lengths, returns [code]1[/code] if this string is longer than the [param to] string, or [code]-1[/code] if shorter. Note that the length of empty strings is [i]always[/i] [code]0[/code]. + To get a [bool] result from a string comparison, use the [code]==[/code] operator instead. See also [method nocasecmp_to] and [method casecmp_to]. + </description> + </method> + <method name="nocasecmp_to" qualifiers="const"> + <return type="int" /> + <param index="0" name="to" type="String" /> + <description> + Performs a [b]case-insensitive[/b] comparison to another string. Returns [code]-1[/code] if less than, [code]1[/code] if greater than, or [code]0[/code] if equal. "Less than" or "greater than" are determined by the [url=https://en.wikipedia.org/wiki/List_of_Unicode_characters]Unicode code points[/url] of each string, which roughly matches the alphabetical order. Internally, lowercase characters are converted to uppercase for the comparison. + With different string lengths, returns [code]1[/code] if this string is longer than the [param to] string, or [code]-1[/code] if shorter. Note that the length of empty strings is [i]always[/i] [code]0[/code]. + To get a [bool] result from a string comparison, use the [code]==[/code] operator instead. See also [method casecmp_to] and [method naturalnocasecmp_to]. + </description> + </method> + <method name="pad_decimals" qualifiers="const"> + <return type="String" /> + <param index="0" name="digits" type="int" /> + <description> + Formats the string representing a number to have an exact number of [param digits] [i]after[/i] the decimal point. + </description> + </method> + <method name="pad_zeros" qualifiers="const"> + <return type="String" /> + <param index="0" name="digits" type="int" /> + <description> + Formats the string representing a number to have an exact number of [param digits] [i]before[/i] the decimal point. + </description> + </method> + <method name="path_join" qualifiers="const"> + <return type="String" /> + <param index="0" name="file" type="String" /> + <description> + Concatenates [param file] at the end of the string as a subpath, adding [code]/[/code] if necessary. + [b]Example:[/b] [code]"this/is".path_join("path") == "this/is/path"[/code]. + </description> + </method> + <method name="repeat" qualifiers="const"> + <return type="String" /> + <param index="0" name="count" type="int" /> + <description> + Repeats this string a number of times. [param count] needs to be greater than [code]0[/code]. Otherwise, returns an empty string. + </description> + </method> + <method name="replace" qualifiers="const"> + <return type="String" /> + <param index="0" name="what" type="String" /> + <param index="1" name="forwhat" type="String" /> + <description> + Replaces all occurrences of [param what] inside the string with the given [param forwhat]. + </description> + </method> + <method name="replacen" qualifiers="const"> + <return type="String" /> + <param index="0" name="what" type="String" /> + <param index="1" name="forwhat" type="String" /> + <description> + Replaces all [b]case-insensitive[/b] occurrences of [param what] inside the string with the given [param forwhat]. + </description> + </method> + <method name="rfind" qualifiers="const"> + <return type="int" /> + <param index="0" name="what" type="String" /> + <param index="1" name="from" type="int" default="-1" /> + <description> + Returns the index of the [b]last[/b] occurrence of [param what] in this string, or [code]-1[/code] if there are none. The search's start can be specified with [param from], continuing to the beginning of the string. This method is the reverse of [method find]. + </description> + </method> + <method name="rfindn" qualifiers="const"> + <return type="int" /> + <param index="0" name="what" type="String" /> + <param index="1" name="from" type="int" default="-1" /> + <description> + Returns the index of the [b]last[/b] [b]case-insensitive[/b] occurrence of [param what] in this string, or [code]-1[/code] if there are none. The starting search index can be specified with [param from], continuing to the beginning of the string. This method is the reverse of [method findn]. + </description> + </method> + <method name="right" qualifiers="const"> + <return type="String" /> + <param index="0" name="length" type="int" /> + <description> + Returns the last [param length] characters from the end of the string. If [param length] is negative, strips the first [param length] characters from the string's beginning. + [codeblock] + print("Hello World!".right(3)) # Prints "ld!" + print("Hello World!".right(-4)) # Prints "o World!" + [/codeblock] + </description> + </method> + <method name="rpad" qualifiers="const"> + <return type="String" /> + <param index="0" name="min_length" type="int" /> + <param index="1" name="character" type="String" default="" "" /> + <description> + Formats the string to be at least [param min_length] long, by adding [param character]s to the right of the string, if necessary. See also [method lpad]. + </description> + </method> + <method name="rsplit" qualifiers="const"> + <return type="PackedStringArray" /> + <param index="0" name="delimiter" type="String" default="""" /> + <param index="1" name="allow_empty" type="bool" default="true" /> + <param index="2" name="maxsplit" type="int" default="0" /> + <description> + Splits the string using a [param delimiter] and returns an array of the substrings, starting from the end of the string. The splits in the returned array appear in the same order as the original string. If [param delimiter] is an empty string, each substring will be a single character. + If [param allow_empty] is [code]false[/code], empty strings between adjacent delimiters are excluded from the array. + If [param maxsplit] is greater than [code]0[/code], the number of splits may not exceed [param maxsplit]. By default, the entire string is split, which is mostly identical to [method split]. + [b]Example:[/b] + [codeblocks] + [gdscript] + var some_string = "One,Two,Three,Four" + var some_array = some_string.rsplit(",", true, 1) + + print(some_array.size()) # Prints 2 + print(some_array[0]) # Prints "One,Two,Three" + print(some_array[1]) # Prints "Four" + [/gdscript] + [csharp] + // In C#, there is no String.RSplit() method. + [/csharp] + [/codeblocks] + </description> + </method> + <method name="rstrip" qualifiers="const"> + <return type="String" /> + <param index="0" name="chars" type="String" /> + <description> + Removes a set of characters defined in [param chars] from the string's end. See also [method lstrip]. + [b]Note:[/b] [param chars] is not a suffix. Use [method trim_suffix] to remove a single suffix, rather than a set of characters. + </description> + </method> + <method name="sha1_buffer" qualifiers="const"> + <return type="PackedByteArray" /> + <description> + Returns the [url=https://en.wikipedia.org/wiki/SHA-1]SHA-1[/url] hash of the string as a [PackedByteArray]. + </description> + </method> + <method name="sha1_text" qualifiers="const"> + <return type="String" /> + <description> + Returns the [url=https://en.wikipedia.org/wiki/SHA-1]SHA-1[/url] hash of the string as another [String]. + </description> + </method> + <method name="sha256_buffer" qualifiers="const"> + <return type="PackedByteArray" /> + <description> + Returns the [url=https://en.wikipedia.org/wiki/SHA-2]SHA-256[/url] hash of the string as a [PackedByteArray]. + </description> + </method> + <method name="sha256_text" qualifiers="const"> + <return type="String" /> + <description> + Returns the [url=https://en.wikipedia.org/wiki/SHA-2]SHA-256[/url] hash of the string as another [String]. + </description> + </method> + <method name="similarity" qualifiers="const"> + <return type="float" /> + <param index="0" name="text" type="String" /> + <description> + Returns the similarity index ([url=https://en.wikipedia.org/wiki/S%C3%B8rensen%E2%80%93Dice_coefficient]Sorensen-Dice coefficient[/url]) of this string compared to another. A result of [code]1.0[/code] means totally similar, while [code]0.0[/code] means totally dissimilar. + [codeblock] + print("ABC123".similarity("ABC123")) # Prints 1.0 + print("ABC123".similarity("XYZ456")) # Prints 0.0 + print("ABC123".similarity("123ABC")) # Prints 0.8 + print("ABC123".similarity("abc123")) # Prints 0.4 + [/codeblock] + </description> + </method> + <method name="simplify_path" qualifiers="const"> + <return type="String" /> + <description> + If the string is a valid file path, converts the string into a canonical path. This is the shortest possible path, without [code]"./"[/code], and all the unnecessary [code]".."[/code] and [code]"/"[/code]. + [codeblock] + var simple_path = "./path/to///../file".simplify_path() + print(simple_path) # Prints "path/file" + [/codeblock] + </description> + </method> + <method name="split" qualifiers="const"> + <return type="PackedStringArray" /> + <param index="0" name="delimiter" type="String" default="""" /> + <param index="1" name="allow_empty" type="bool" default="true" /> + <param index="2" name="maxsplit" type="int" default="0" /> + <description> + Splits the string using a [param delimiter] and returns an array of the substrings. If [param delimiter] is an empty string, each substring will be a single character. This method is the opposite of [method join]. + If [param allow_empty] is [code]false[/code], empty strings between adjacent delimiters are excluded from the array. + If [param maxsplit] is greater than [code]0[/code], the number of splits may not exceed [param maxsplit]. By default, the entire string is split. + [b]Example:[/b] + [codeblocks] + [gdscript] + var some_array = "One,Two,Three,Four".split(",", true, 2) + + print(some_array.size()) # Prints 3 + print(some_array[0]) # Prints "One" + print(some_array[1]) # Prints "Two" + print(some_array[2]) # Prints "Three,Four" + [/gdscript] + [csharp] + // C#'s `Split()` does not support the `maxsplit` parameter. + var someArray = "One,Two,Three".Split(","); + + GD.Print(someArray[0]); // Prints "One" + GD.Print(someArray[1]); // Prints "Two" + GD.Print(someArray[2]); // Prints "Three" + [/csharp] + [/codeblocks] + [b]Note:[/b] If you only need one substring from the array, consider using [method get_slice] which is faster. If you need to split strings with more complex rules, use the [RegEx] class instead. + </description> + </method> + <method name="split_floats" qualifiers="const"> + <return type="PackedFloat64Array" /> + <param index="0" name="delimiter" type="String" /> + <param index="1" name="allow_empty" type="bool" default="true" /> + <description> + Splits the string into floats by using a [param delimiter] and returns a [PackedFloat64Array]. + If [param allow_empty] is [code]false[/code], empty or invalid [float] conversions between adjacent delimiters are excluded. + [codeblock] + var a = "1,2,4.5".split_floats(",") # a is [1.0, 2.0, 4.5] + var c = "1| ||4.5".split_floats("|") # c is [1.0, 0.0, 0.0, 4.5] + var b = "1| ||4.5".split_floats("|", false) # b is [1.0, 4.5] + [/codeblock] + </description> + </method> + <method name="strip_edges" qualifiers="const"> + <return type="String" /> + <param index="0" name="left" type="bool" default="true" /> + <param index="1" name="right" type="bool" default="true" /> + <description> + Strips all non-printable characters from the beginning and the end of the string. These include spaces, tabulations ([code]\t[/code]), and newlines ([code]\n[/code] [code]\r[/code]). + If [param left] is [code]false[/code], ignores the string's beginning. Likewise, if [param right] is [code]false[/code], ignores the string's end. + </description> + </method> + <method name="strip_escapes" qualifiers="const"> + <return type="String" /> + <description> + Strips all escape characters from the string. These include all non-printable control characters of the first page of the ASCII table (values from 0 to 31), such as tabulation ([code]\t[/code]) and newline ([code]\n[/code], [code]\r[/code]) characters, but [i]not[/i] spaces. + </description> + </method> + <method name="substr" qualifiers="const"> + <return type="String" /> + <param index="0" name="from" type="int" /> + <param index="1" name="len" type="int" default="-1" /> + <description> + Returns part of the string from the position [param from] with length [param len]. If [param len] is [code]-1[/code] (as by default), returns the rest of the string starting from the given position. + </description> + </method> + <method name="to_ascii_buffer" qualifiers="const"> + <return type="PackedByteArray" /> + <description> + Converts the string to an [url=https://en.wikipedia.org/wiki/ASCII]ASCII[/url]/Latin-1 encoded [PackedByteArray]. This method is slightly faster than [method to_utf8_buffer], but replaces all unsupported characters with spaces. + </description> + </method> + <method name="to_camel_case" qualifiers="const"> + <return type="String" /> + <description> + Returns the string converted to [code]camelCase[/code]. + </description> + </method> + <method name="to_float" qualifiers="const"> + <return type="float" /> + <description> + Converts the string representing a decimal number into a [float]. This method stops on the first non-number character, except the first decimal point ([code].[/code]) and the exponent letter ([code]e[/code]). See also [method is_valid_float]. + [codeblock] + var a = "12.35".to_float() # a is 12.35 + var b = "1.2.3".to_float() # b is 1.2 + var c = "12xy3".to_float() # c is 12.0 + var d = "1e3".to_float() # d is 1000.0 + var e = "Hello!".to_int() # e is 0.0 + [/codeblock] + </description> + </method> + <method name="to_int" qualifiers="const"> + <return type="int" /> + <description> + Converts the string representing an integer number into an [int]. This method removes any non-number character and stops at the first decimal point ([code].[/code]). See also [method is_valid_int]. + [codeblock] + var a = "123".to_int() # a is 123 + var b = "x1y2z3".to_int() # b is 123 + var c = "-1.2.3".to_int() # c is -1 + var d = "Hello!".to_int() # d is 0 + [/codeblock] + </description> + </method> + <method name="to_lower" qualifiers="const"> + <return type="String" /> + <description> + Returns the string converted to lowercase. + </description> + </method> + <method name="to_pascal_case" qualifiers="const"> + <return type="String" /> + <description> + Returns the string converted to [code]PascalCase[/code]. + </description> + </method> + <method name="to_snake_case" qualifiers="const"> + <return type="String" /> + <description> + Returns the string converted to [code]snake_case[/code]. + </description> + </method> + <method name="to_upper" qualifiers="const"> + <return type="String" /> + <description> + Returns the string converted to uppercase. + </description> + </method> + <method name="to_utf16_buffer" qualifiers="const"> + <return type="PackedByteArray" /> + <description> + Converts the string to a [url=https://en.wikipedia.org/wiki/UTF-16]UTF-16[/url] encoded [PackedByteArray]. + </description> + </method> + <method name="to_utf32_buffer" qualifiers="const"> + <return type="PackedByteArray" /> + <description> + Converts the string to a [url=https://en.wikipedia.org/wiki/UTF-32]UTF-32[/url] encoded [PackedByteArray]. + </description> + </method> + <method name="to_utf8_buffer" qualifiers="const"> + <return type="PackedByteArray" /> + <description> + Converts the string to a [url=https://en.wikipedia.org/wiki/UTF-8]UTF-8[/url] encoded [PackedByteArray]. This method is slightly slower than [method to_ascii_buffer], but supports all UTF-8 characters. For most cases, prefer using this method. + </description> + </method> + <method name="trim_prefix" qualifiers="const"> + <return type="String" /> + <param index="0" name="prefix" type="String" /> + <description> + Removes the given [param prefix] from the start of the string, or returns the string unchanged. + </description> + </method> + <method name="trim_suffix" qualifiers="const"> + <return type="String" /> + <param index="0" name="suffix" type="String" /> + <description> + Removes the given [param suffix] from the end of the string, or returns the string unchanged. + </description> + </method> + <method name="unicode_at" qualifiers="const"> + <return type="int" /> + <param index="0" name="at" type="int" /> + <description> + Returns the character code at position [param at]. + </description> + </method> + <method name="uri_decode" qualifiers="const"> + <return type="String" /> + <description> + Decodes the string from its URL-encoded format. This method is meant to properly decode the parameters in a URL when receiving an HTTP request. + [codeblocks] + [gdscript] + var url = "$DOCS_URL/?highlight=Godot%20Engine%3%docs" + print(url.uri_decode()) # Prints "$DOCS_URL/?hightlight=Godot Engine:docs" + [/gdscript] + [csharp] + var url = "$DOCS_URL/?highlight=Godot%20Engine%3%docs" + GD.Print(url.URIDecode()) // Prints "$DOCS_URL/?hightlight=Godot Engine:docs" + [/csharp] + [/codeblocks] + </description> + </method> + <method name="uri_encode" qualifiers="const"> + <return type="String" /> + <description> + Encodes the string to URL-friendly format. This method is meant to properly encode the parameters in a URL when sending an HTTP request. + [codeblocks] + [gdscript] + var prefix = "$DOCS_URL/?hightlight=" + var url = prefix + "Godot Engine:docs".uri_encode() + + print(url) # Prints "$DOCS_URL/?highlight=Godot%20Engine%3%docs" + [/gdscript] + [csharp] + var prefix = "$DOCS_URL/?hightlight="; + var url = prefix + "Godot Engine:docs".URIEncode(); + + GD.Print(url); // Prints "$DOCS_URL/?highlight=Godot%20Engine%3%docs" + [/csharp] + [/codeblocks] + </description> + </method> + <method name="validate_node_name" qualifiers="const"> + <return type="String" /> + <description> + Removes all characters that are not allowed in [member Node.name] from the string ([code].[/code] [code]:[/code] [code]@[/code] [code]/[/code] [code]"[/code] [code]%[/code]). + </description> + </method> + <method name="xml_escape" qualifiers="const"> + <return type="String" /> + <param index="0" name="escape_quotes" type="bool" default="false" /> + <description> + Returns a copy of the string with special characters escaped using the XML standard. If [param escape_quotes] is [code]true[/code], the single quote ([code]'[/code]) and double quote ([code]"[/code]) characters are also escaped. + </description> + </method> + <method name="xml_unescape" qualifiers="const"> + <return type="String" /> + <description> + Returns a copy of the string with escaped characters replaced by their meanings according to the XML standard. </description> </method> </methods> @@ -55,6 +944,24 @@ Returns [code]true[/code] if the [StringName] and [param right] do not refer to the same name. Comparisons between [StringName]s are much faster than regular [String] comparisons. </description> </operator> + <operator name="operator %"> + <return type="String" /> + <param index="0" name="right" type="Variant" /> + <description> + </description> + </operator> + <operator name="operator +"> + <return type="String" /> + <param index="0" name="right" type="String" /> + <description> + </description> + </operator> + <operator name="operator +"> + <return type="String" /> + <param index="0" name="right" type="StringName" /> + <description> + </description> + </operator> <operator name="operator <"> <return type="bool" /> <param index="0" name="right" type="StringName" /> diff --git a/doc/classes/SystemFont.xml b/doc/classes/SystemFont.xml index b47d6ded7d..20bfd0d8ae 100644 --- a/doc/classes/SystemFont.xml +++ b/doc/classes/SystemFont.xml @@ -7,23 +7,32 @@ <description> [SystemFont] loads a font from a system font with the first matching name from [member font_names]. It will attempt to match font style, but it's not guaranteed. - The returned font might be part of a font collection or be a variable font with OpenType "weight" and/or "italic" features set. + The returned font might be part of a font collection or be a variable font with OpenType "weight", "width" and/or "italic" features set. You can create [FontVariation] of the system font for fine control over its features. </description> <tutorials> </tutorials> <members> + <member name="allow_system_fallback" type="bool" setter="set_allow_system_fallback" getter="is_allow_system_fallback" default="true"> + If set to [code]true[/code], system fonts can be automatically used as fallbacks. + </member> <member name="antialiasing" type="int" setter="set_antialiasing" getter="get_antialiasing" enum="TextServer.FontAntialiasing" default="1"> Font anti-aliasing mode. </member> <member name="fallbacks" type="Font[]" setter="set_fallbacks" getter="get_fallbacks" default="[]"> Array of fallback [Font]s. </member> + <member name="font_italic" type="bool" setter="set_font_italic" getter="get_font_italic" default="false"> + If set to [code]true[/code], italic or oblique font is preferred. + </member> <member name="font_names" type="PackedStringArray" setter="set_font_names" getter="get_font_names" default="PackedStringArray()"> Array of font family names to search, first matching font found is used. </member> - <member name="font_style" type="int" setter="set_font_style" getter="get_font_style" enum="TextServer.FontStyle" default="0"> - Font style flags, see [enum TextServer.FontStyle]. + <member name="font_stretch" type="int" setter="set_font_stretch" getter="get_font_stretch" default="100"> + Preferred font stretch amount, compared to a normal width. A percentage value between [code]50%[/code] and [code]200%[/code]. + </member> + <member name="font_weight" type="int" setter="set_font_weight" getter="get_font_weight" default="400"> + Preferred weight (boldness) of the font. A value in the [code]100...999[/code] range, normal font weight is [code]400[/code], bold font weight is [code]700[/code]. </member> <member name="force_autohinter" type="bool" setter="set_force_autohinter" getter="is_force_autohinter" default="false"> If set to [code]true[/code], auto-hinting is supported and preferred over font built-in hinting. diff --git a/doc/classes/TextServer.xml b/doc/classes/TextServer.xml index f4d92ab9b6..4fc6ee3312 100644 --- a/doc/classes/TextServer.xml +++ b/doc/classes/TextServer.xml @@ -235,7 +235,7 @@ <param index="1" name="size" type="Vector2i" /> <param index="2" name="glyph" type="int" /> <description> - Returns resource id of the cache texture containing the glyph. + Returns resource ID of the cache texture containing the glyph. [b]Note:[/b] If there are pending glyphs to render, calling this function might trigger the texture cache update. </description> </method> @@ -362,6 +362,13 @@ Returns list of the font sizes in the cache. Each size is [code]Vector2i[/code] with font size and outline size. </description> </method> + <method name="font_get_stretch" qualifiers="const"> + <return type="int" /> + <param index="0" name="font_rid" type="RID" /> + <description> + Returns font stretch amount, compared to a normal width. A percentage value between [code]50%[/code] and [code]200%[/code]. + </description> + </method> <method name="font_get_style" qualifiers="const"> <return type="int" enum="TextServer.FontStyle" /> <param index="0" name="font_rid" type="RID" /> @@ -446,6 +453,13 @@ Returns variation coordinates for the specified font cache entry. See [method font_supported_variation_list] for more info. </description> </method> + <method name="font_get_weight" qualifiers="const"> + <return type="int" /> + <param index="0" name="font_rid" type="RID" /> + <description> + Returns weight (boldness) of the font. A value in the [code]100...999[/code] range, normal font weight is [code]400[/code], bold font weight is [code]700[/code]. + </description> + </method> <method name="font_has_char" qualifiers="const"> <return type="bool" /> <param index="0" name="font_rid" type="RID" /> @@ -454,6 +468,13 @@ Returns [code]true[/code] if a Unicode [param char] is available in the font. </description> </method> + <method name="font_is_allow_system_fallback" qualifiers="const"> + <return type="bool" /> + <param index="0" name="font_rid" type="RID" /> + <description> + Returns [code]true[/code] if system fonts can be automatically used as fallbacks. + </description> + </method> <method name="font_is_force_autohinter" qualifiers="const"> <return type="bool" /> <param index="0" name="font_rid" type="RID" /> @@ -556,6 +577,14 @@ Renders the range of characters to the font cache texture. </description> </method> + <method name="font_set_allow_system_fallback"> + <return type="void" /> + <param index="0" name="font_rid" type="RID" /> + <param index="1" name="allow_system_fallback" type="bool" /> + <description> + If set to [code]true[/code], system fonts can be automatically used as fallbacks. + </description> + </method> <method name="font_set_antialiasing"> <return type="void" /> <param index="0" name="font_rid" type="RID" /> @@ -783,12 +812,22 @@ Adds override for [method font_is_script_supported]. </description> </method> + <method name="font_set_stretch"> + <return type="void" /> + <param index="0" name="font_rid" type="RID" /> + <param index="1" name="weight" type="int" /> + <description> + Sets font stretch amount, compared to a normal width. A percentage value between [code]50%[/code] and [code]200%[/code]. + [b]Note:[/b] This value is used for font matching only and will not affect font rendering. Use [method font_set_face_index], [method font_set_variation_coordinates], or [method font_set_transform] instead. + </description> + </method> <method name="font_set_style"> <return type="void" /> <param index="0" name="font_rid" type="RID" /> <param index="1" name="style" type="int" enum="TextServer.FontStyle" /> <description> Sets the font style flags, see [enum FontStyle]. + [b]Note:[/b] This value is used for font matching only and will not affect font rendering. Use [method font_set_face_index], [method font_set_variation_coordinates], [method font_set_embolden], or [method font_set_transform] instead. </description> </method> <method name="font_set_style_name"> @@ -862,6 +901,15 @@ Sets variation coordinates for the specified font cache entry. See [method font_supported_variation_list] for more info. </description> </method> + <method name="font_set_weight"> + <return type="void" /> + <param index="0" name="font_rid" type="RID" /> + <param index="1" name="weight" type="int" /> + <description> + Sets weight (boldness) of the font. A value in the [code]100...999[/code] range, normal font weight is [code]400[/code], bold font weight is [code]700[/code]. + [b]Note:[/b] This value is used for font matching only and will not affect font rendering. Use [method font_set_face_index], [method font_set_variation_coordinates], or [method font_set_embolden] instead. + </description> + </method> <method name="font_supported_feature_list" qualifiers="const"> <return type="Dictionary" /> <param index="0" name="font_rid" type="RID" /> diff --git a/doc/classes/TextServerExtension.xml b/doc/classes/TextServerExtension.xml index 37d2698dd4..4c9817fcd4 100644 --- a/doc/classes/TextServerExtension.xml +++ b/doc/classes/TextServerExtension.xml @@ -9,6 +9,11 @@ <tutorials> </tutorials> <methods> + <method name="_cleanup" qualifiers="virtual"> + <return type="void" /> + <description> + </description> + </method> <method name="_create_font" qualifiers="virtual"> <return type="RID" /> <description> @@ -306,6 +311,12 @@ <description> </description> </method> + <method name="_font_get_stretch" qualifiers="virtual const"> + <return type="int" /> + <param index="0" name="font_rid" type="RID" /> + <description> + </description> + </method> <method name="_font_get_style" qualifiers="virtual const"> <return type="int" enum="TextServer.FontStyle" /> <param index="0" name="font_rid" type="RID" /> @@ -379,6 +390,12 @@ <description> </description> </method> + <method name="_font_get_weight" qualifiers="virtual const"> + <return type="int" /> + <param index="0" name="font_rid" type="RID" /> + <description> + </description> + </method> <method name="_font_has_char" qualifiers="virtual const"> <return type="bool" /> <param index="0" name="font_rid" type="RID" /> @@ -386,6 +403,12 @@ <description> </description> </method> + <method name="_font_is_allow_system_fallback" qualifiers="virtual const"> + <return type="bool" /> + <param index="0" name="font_rid" type="RID" /> + <description> + </description> + </method> <method name="_font_is_force_autohinter" qualifiers="virtual const"> <return type="bool" /> <param index="0" name="font_rid" type="RID" /> @@ -474,6 +497,13 @@ <description> </description> </method> + <method name="_font_set_allow_system_fallback" qualifiers="virtual"> + <return type="void" /> + <param index="0" name="font_rid" type="RID" /> + <param index="1" name="allow_system_fallback" type="bool" /> + <description> + </description> + </method> <method name="_font_set_antialiasing" qualifiers="virtual"> <return type="void" /> <param index="0" name="font_rid" type="RID" /> @@ -680,6 +710,13 @@ <description> </description> </method> + <method name="_font_set_stretch" qualifiers="virtual"> + <return type="void" /> + <param index="0" name="font_rid" type="RID" /> + <param index="1" name="stretch" type="int" /> + <description> + </description> + </method> <method name="_font_set_style" qualifiers="virtual"> <return type="void" /> <param index="0" name="font_rid" type="RID" /> @@ -749,6 +786,13 @@ <description> </description> </method> + <method name="_font_set_weight" qualifiers="virtual"> + <return type="void" /> + <param index="0" name="font_rid" type="RID" /> + <param index="1" name="weight" type="int" /> + <description> + </description> + </method> <method name="_font_supported_feature_list" qualifiers="virtual const"> <return type="Dictionary" /> <param index="0" name="font_rid" type="RID" /> diff --git a/doc/classes/TileMap.xml b/doc/classes/TileMap.xml index 01246f0c2e..e9e2a738d3 100644 --- a/doc/classes/TileMap.xml +++ b/doc/classes/TileMap.xml @@ -174,7 +174,7 @@ Creates a new [TileMapPattern] from the given layer and set of cells. </description> </method> - <method name="get_surrounding_tiles"> + <method name="get_surrounding_cells"> <return type="Vector2i[]" /> <param index="0" name="coords" type="Vector2i" /> <description> diff --git a/doc/classes/Tree.xml b/doc/classes/Tree.xml index 6a016c3ebd..629c271417 100644 --- a/doc/classes/Tree.xml +++ b/doc/classes/Tree.xml @@ -70,7 +70,7 @@ <return type="int" /> <param index="0" name="position" type="Vector2" /> <description> - Returns the button id at [param position], or -1 if no button is there. + Returns the button ID at [param position], or -1 if no button is there. </description> </method> <method name="get_column_at_position" qualifiers="const"> diff --git a/doc/classes/TreeItem.xml b/doc/classes/TreeItem.xml index a8ffef427f..ec6b166e57 100644 --- a/doc/classes/TreeItem.xml +++ b/doc/classes/TreeItem.xml @@ -78,7 +78,7 @@ <param index="0" name="column" type="int" /> <param index="1" name="id" type="int" /> <description> - Returns the button index if there is a button with id [param id] in column [param column], otherwise returns -1. + Returns the button index if there is a button with ID [param id] in column [param column], otherwise returns -1. </description> </method> <method name="get_button_count" qualifiers="const"> @@ -93,7 +93,7 @@ <param index="0" name="column" type="int" /> <param index="1" name="button_idx" type="int" /> <description> - Returns the id for the button at index [param button_idx] in column [param column]. + Returns the ID for the button at index [param button_idx] in column [param column]. </description> </method> <method name="get_button_tooltip_text" qualifiers="const"> diff --git a/doc/classes/Vector2.xml b/doc/classes/Vector2.xml index 4156030d77..1cd73688ee 100644 --- a/doc/classes/Vector2.xml +++ b/doc/classes/Vector2.xml @@ -93,7 +93,7 @@ <param index="2" name="end" type="Vector2" /> <param index="3" name="t" type="float" /> <description> - Returns the derivative at the given [param t] on the [url=https://en.wikipedia.org/wiki/B%C3%A9zier_curve]Bezier curve[/url] defined by this vector and the given [param control_1], [param control_2], and [param end] points. + Returns the derivative at the given [param t] on the [url=https://en.wikipedia.org/wiki/B%C3%A9zier_curve]Bézier curve[/url] defined by this vector and the given [param control_1], [param control_2], and [param end] points. </description> </method> <method name="bezier_interpolate" qualifiers="const"> @@ -103,7 +103,7 @@ <param index="2" name="end" type="Vector2" /> <param index="3" name="t" type="float" /> <description> - Returns the point at the given [param t] on the [url=https://en.wikipedia.org/wiki/B%C3%A9zier_curve]Bezier curve[/url] defined by this vector and the given [param control_1], [param control_2], and [param end] points. + Returns the point at the given [param t] on the [url=https://en.wikipedia.org/wiki/B%C3%A9zier_curve]Bézier curve[/url] defined by this vector and the given [param control_1], [param control_2], and [param end] points. </description> </method> <method name="bounce" qualifiers="const"> diff --git a/doc/classes/Vector3.xml b/doc/classes/Vector3.xml index 2896408505..1d7eda6bb9 100644 --- a/doc/classes/Vector3.xml +++ b/doc/classes/Vector3.xml @@ -69,7 +69,7 @@ <param index="2" name="end" type="Vector3" /> <param index="3" name="t" type="float" /> <description> - Returns the derivative at the given [param t] on the [url=https://en.wikipedia.org/wiki/B%C3%A9zier_curve]Bezier curve[/url] defined by this vector and the given [param control_1], [param control_2], and [param end] points. + Returns the derivative at the given [param t] on the [url=https://en.wikipedia.org/wiki/B%C3%A9zier_curve]Bézier curve[/url] defined by this vector and the given [param control_1], [param control_2], and [param end] points. </description> </method> <method name="bezier_interpolate" qualifiers="const"> @@ -79,7 +79,7 @@ <param index="2" name="end" type="Vector3" /> <param index="3" name="t" type="float" /> <description> - Returns the point at the given [param t] on the [url=https://en.wikipedia.org/wiki/B%C3%A9zier_curve]Bezier curve[/url] defined by this vector and the given [param control_1], [param control_2], and [param end] points. + Returns the point at the given [param t] on the [url=https://en.wikipedia.org/wiki/B%C3%A9zier_curve]Bézier curve[/url] defined by this vector and the given [param control_1], [param control_2], and [param end] points. </description> </method> <method name="bounce" qualifiers="const"> diff --git a/doc/classes/Window.xml b/doc/classes/Window.xml index 8707ef003a..16ca486e4a 100644 --- a/doc/classes/Window.xml +++ b/doc/classes/Window.xml @@ -10,6 +10,66 @@ <tutorials> </tutorials> <methods> + <method name="add_theme_color_override"> + <return type="void" /> + <param index="0" name="name" type="StringName" /> + <param index="1" name="color" type="Color" /> + <description> + Creates a local override for a theme [Color] with the specified [param name]. Local overrides always take precedence when fetching theme items for the control. An override can be removed with [method remove_theme_color_override]. + See also [method get_theme_color] and [method Control.add_theme_color_override] for more details. + </description> + </method> + <method name="add_theme_constant_override"> + <return type="void" /> + <param index="0" name="name" type="StringName" /> + <param index="1" name="constant" type="int" /> + <description> + Creates a local override for a theme constant with the specified [param name]. Local overrides always take precedence when fetching theme items for the control. An override can be removed with [method remove_theme_constant_override]. + See also [method get_theme_constant]. + </description> + </method> + <method name="add_theme_font_override"> + <return type="void" /> + <param index="0" name="name" type="StringName" /> + <param index="1" name="font" type="Font" /> + <description> + Creates a local override for a theme [Font] with the specified [param name]. Local overrides always take precedence when fetching theme items for the control. An override can be removed with [method remove_theme_font_override]. + See also [method get_theme_font]. + </description> + </method> + <method name="add_theme_font_size_override"> + <return type="void" /> + <param index="0" name="name" type="StringName" /> + <param index="1" name="font_size" type="int" /> + <description> + Creates a local override for a theme font size with the specified [param name]. Local overrides always take precedence when fetching theme items for the control. An override can be removed with [method remove_theme_font_size_override]. + See also [method get_theme_font_size]. + </description> + </method> + <method name="add_theme_icon_override"> + <return type="void" /> + <param index="0" name="name" type="StringName" /> + <param index="1" name="texture" type="Texture2D" /> + <description> + Creates a local override for a theme icon with the specified [param name]. Local overrides always take precedence when fetching theme items for the control. An override can be removed with [method remove_theme_icon_override]. + See also [method get_theme_icon]. + </description> + </method> + <method name="add_theme_stylebox_override"> + <return type="void" /> + <param index="0" name="name" type="StringName" /> + <param index="1" name="stylebox" type="StyleBox" /> + <description> + Creates a local override for a theme [StyleBox] with the specified [param name]. Local overrides always take precedence when fetching theme items for the control. An override can be removed with [method remove_theme_stylebox_override]. + See also [method get_theme_stylebox] and [method Control.add_theme_stylebox_override] for more details. + </description> + </method> + <method name="begin_bulk_theme_override"> + <return type="void" /> + <description> + Prevents [code]*_theme_*_override[/code] methods from emitting [constant NOTIFICATION_THEME_CHANGED] until [method end_bulk_theme_override] is called. + </description> + </method> <method name="can_draw" qualifiers="const"> <return type="bool" /> <description> @@ -22,6 +82,12 @@ Requests an update of the [Window] size to fit underlying [Control] nodes. </description> </method> + <method name="end_bulk_theme_override"> + <return type="void" /> + <description> + Ends a bulk theme override update. See [method begin_bulk_theme_override]. + </description> + </method> <method name="get_contents_minimum_size" qualifiers="const"> <return type="Vector2" /> <description> @@ -41,7 +107,13 @@ Returns layout direction and text writing direction. </description> </method> - <method name="get_real_size" qualifiers="const"> + <method name="get_position_with_decorations" qualifiers="const"> + <return type="Vector2i" /> + <description> + Returns the window's position including its border. + </description> + </method> + <method name="get_size_with_decorations" qualifiers="const"> <return type="Vector2i" /> <description> Returns the window's size including its border. @@ -52,7 +124,7 @@ <param index="0" name="name" type="StringName" /> <param index="1" name="theme_type" type="StringName" default="""" /> <description> - Returns the [Color] at [param name] if the theme has [param theme_type]. + Returns a [Color] from the first matching [Theme] in the tree if that [Theme] has a color item with the specified [param name] and [param theme_type]. See [method Control.get_theme_color] for more details. </description> </method> @@ -61,29 +133,29 @@ <param index="0" name="name" type="StringName" /> <param index="1" name="theme_type" type="StringName" default="""" /> <description> - Returns the constant at [param name] if the theme has [param theme_type]. + Returns a constant from the first matching [Theme] in the tree if that [Theme] has a constant item with the specified [param name] and [param theme_type]. See [method Control.get_theme_color] for more details. </description> </method> <method name="get_theme_default_base_scale" qualifiers="const"> <return type="float" /> <description> - Returns the default base scale defined in the attached [Theme]. - See [member Theme.default_base_scale] for more details. + Returns the default base scale value from the first matching [Theme] in the tree if that [Theme] has a valid [member Theme.default_base_scale] value. + See [method Control.get_theme_color] for details. </description> </method> <method name="get_theme_default_font" qualifiers="const"> <return type="Font" /> <description> - Returns the default [Font] defined in the attached [Theme]. - See [member Theme.default_font] for more details. + Returns the default font from the first matching [Theme] in the tree if that [Theme] has a valid [member Theme.default_font] value. + See [method Control.get_theme_color] for details. </description> </method> <method name="get_theme_default_font_size" qualifiers="const"> <return type="int" /> <description> - Returns the default font size defined in the attached [Theme]. - See [member Theme.default_font_size] for more details. + Returns the default font size value from the first matching [Theme] in the tree if that [Theme] has a valid [member Theme.default_font_size] value. + See [method Control.get_theme_color] for details. </description> </method> <method name="get_theme_font" qualifiers="const"> @@ -91,8 +163,8 @@ <param index="0" name="name" type="StringName" /> <param index="1" name="theme_type" type="StringName" default="""" /> <description> - Returns the [Font] at [param name] if the theme has [param theme_type]. - See [method Control.get_theme_color] for more details. + Returns a [Font] from the first matching [Theme] in the tree if that [Theme] has a font item with the specified [param name] and [param theme_type]. + See [method Control.get_theme_color] for details. </description> </method> <method name="get_theme_font_size" qualifiers="const"> @@ -100,8 +172,8 @@ <param index="0" name="name" type="StringName" /> <param index="1" name="theme_type" type="StringName" default="""" /> <description> - Returns the font size at [param name] if the theme has [param theme_type]. - See [method Control.get_theme_color] for more details. + Returns a font size from the first matching [Theme] in the tree if that [Theme] has a font size item with the specified [param name] and [param theme_type]. + See [method Control.get_theme_color] for details. </description> </method> <method name="get_theme_icon" qualifiers="const"> @@ -109,8 +181,8 @@ <param index="0" name="name" type="StringName" /> <param index="1" name="theme_type" type="StringName" default="""" /> <description> - Returns the icon at [param name] if the theme has [param theme_type]. - See [method Control.get_theme_color] for more details. + Returns an icon from the first matching [Theme] in the tree if that [Theme] has an icon item with the specified [param name] and [param theme_type]. + See [method Control.get_theme_color] for details. </description> </method> <method name="get_theme_stylebox" qualifiers="const"> @@ -118,8 +190,8 @@ <param index="0" name="name" type="StringName" /> <param index="1" name="theme_type" type="StringName" default="""" /> <description> - Returns the [StyleBox] at [param name] if the theme has [param theme_type]. - See [method Control.get_theme_color] for more details. + Returns a [StyleBox] from the first matching [Theme] in the tree if that [Theme] has a stylebox item with the specified [param name] and [param theme_type]. + See [method Control.get_theme_color] for details. </description> </method> <method name="grab_focus"> @@ -139,7 +211,16 @@ <param index="0" name="name" type="StringName" /> <param index="1" name="theme_type" type="StringName" default="""" /> <description> - Returns [code]true[/code] if [Color] with [param name] is in [param theme_type]. + Returns [code]true[/code] if there is a matching [Theme] in the tree that has a color item with the specified [param name] and [param theme_type]. + See [method Control.get_theme_color] for details. + </description> + </method> + <method name="has_theme_color_override" qualifiers="const"> + <return type="bool" /> + <param index="0" name="name" type="StringName" /> + <description> + Returns [code]true[/code] if there is a local override for a theme [Color] with the specified [param name] in this [Control] node. + See [method add_theme_color_override]. </description> </method> <method name="has_theme_constant" qualifiers="const"> @@ -147,7 +228,16 @@ <param index="0" name="name" type="StringName" /> <param index="1" name="theme_type" type="StringName" default="""" /> <description> - Returns [code]true[/code] if constant with [param name] is in [param theme_type]. + Returns [code]true[/code] if there is a matching [Theme] in the tree that has a constant item with the specified [param name] and [param theme_type]. + See [method Control.get_theme_color] for details. + </description> + </method> + <method name="has_theme_constant_override" qualifiers="const"> + <return type="bool" /> + <param index="0" name="name" type="StringName" /> + <description> + Returns [code]true[/code] if there is a local override for a theme constant with the specified [param name] in this [Control] node. + See [method add_theme_constant_override]. </description> </method> <method name="has_theme_font" qualifiers="const"> @@ -155,7 +245,16 @@ <param index="0" name="name" type="StringName" /> <param index="1" name="theme_type" type="StringName" default="""" /> <description> - Returns [code]true[/code] if [Font] with [param name] is in [param theme_type]. + Returns [code]true[/code] if there is a matching [Theme] in the tree that has a font item with the specified [param name] and [param theme_type]. + See [method Control.get_theme_color] for details. + </description> + </method> + <method name="has_theme_font_override" qualifiers="const"> + <return type="bool" /> + <param index="0" name="name" type="StringName" /> + <description> + Returns [code]true[/code] if there is a local override for a theme [Font] with the specified [param name] in this [Control] node. + See [method add_theme_font_override]. </description> </method> <method name="has_theme_font_size" qualifiers="const"> @@ -163,7 +262,16 @@ <param index="0" name="name" type="StringName" /> <param index="1" name="theme_type" type="StringName" default="""" /> <description> - Returns [code]true[/code] if font size with [param name] is in [param theme_type]. + Returns [code]true[/code] if there is a matching [Theme] in the tree that has a font size item with the specified [param name] and [param theme_type]. + See [method Control.get_theme_color] for details. + </description> + </method> + <method name="has_theme_font_size_override" qualifiers="const"> + <return type="bool" /> + <param index="0" name="name" type="StringName" /> + <description> + Returns [code]true[/code] if there is a local override for a theme font size with the specified [param name] in this [Control] node. + See [method add_theme_font_size_override]. </description> </method> <method name="has_theme_icon" qualifiers="const"> @@ -171,7 +279,16 @@ <param index="0" name="name" type="StringName" /> <param index="1" name="theme_type" type="StringName" default="""" /> <description> - Returns [code]true[/code] if icon with [param name] is in [param theme_type]. + Returns [code]true[/code] if there is a matching [Theme] in the tree that has an icon item with the specified [param name] and [param theme_type]. + See [method Control.get_theme_color] for details. + </description> + </method> + <method name="has_theme_icon_override" qualifiers="const"> + <return type="bool" /> + <param index="0" name="name" type="StringName" /> + <description> + Returns [code]true[/code] if there is a local override for a theme icon with the specified [param name] in this [Control] node. + See [method add_theme_icon_override]. </description> </method> <method name="has_theme_stylebox" qualifiers="const"> @@ -179,7 +296,16 @@ <param index="0" name="name" type="StringName" /> <param index="1" name="theme_type" type="StringName" default="""" /> <description> - Returns [code]true[/code] if [StyleBox] with [param name] is in [param theme_type]. + Returns [code]true[/code] if there is a matching [Theme] in the tree that has a stylebox item with the specified [param name] and [param theme_type]. + See [method Control.get_theme_color] for details. + </description> + </method> + <method name="has_theme_stylebox_override" qualifiers="const"> + <return type="bool" /> + <param index="0" name="name" type="StringName" /> + <description> + Returns [code]true[/code] if there is a local override for a theme [StyleBox] with the specified [param name] in this [Control] node. + See [method add_theme_stylebox_override]. </description> </method> <method name="hide"> @@ -258,6 +384,48 @@ If the [Window] is embedded, has the same effect as [method popup]. </description> </method> + <method name="remove_theme_color_override"> + <return type="void" /> + <param index="0" name="name" type="StringName" /> + <description> + Removes a local override for a theme [Color] with the specified [param name] previously added by [method add_theme_color_override] or via the Inspector dock. + </description> + </method> + <method name="remove_theme_constant_override"> + <return type="void" /> + <param index="0" name="name" type="StringName" /> + <description> + Removes a local override for a theme constant with the specified [param name] previously added by [method add_theme_constant_override] or via the Inspector dock. + </description> + </method> + <method name="remove_theme_font_override"> + <return type="void" /> + <param index="0" name="name" type="StringName" /> + <description> + Removes a local override for a theme [Font] with the specified [param name] previously added by [method add_theme_font_override] or via the Inspector dock. + </description> + </method> + <method name="remove_theme_font_size_override"> + <return type="void" /> + <param index="0" name="name" type="StringName" /> + <description> + Removes a local override for a theme font size with the specified [param name] previously added by [method add_theme_font_size_override] or via the Inspector dock. + </description> + </method> + <method name="remove_theme_icon_override"> + <return type="void" /> + <param index="0" name="name" type="StringName" /> + <description> + Removes a local override for a theme icon with the specified [param name] previously added by [method add_theme_icon_override] or via the Inspector dock. + </description> + </method> + <method name="remove_theme_stylebox_override"> + <return type="void" /> + <param index="0" name="name" type="StringName" /> + <description> + Removes a local override for a theme [StyleBox] with the specified [param name] previously added by [method add_theme_stylebox_override] or via the Inspector dock. + </description> + </method> <method name="request_attention"> <return type="void" /> <description> @@ -367,8 +535,8 @@ The window's size in pixels. </member> <member name="theme" type="Theme" setter="set_theme" getter="get_theme"> - The [Theme] resource that determines the style of the underlying [Control] nodes. - [Window] styles will have no effect unless the window is embedded. + The [Theme] resource this node and all its [Control] and [Window] children use. If a child node has its own [Theme] resource set, theme items are merged with child's definitions having higher priority. + [b]Note:[/b] [Window] styles will have no effect unless the window is embedded. </member> <member name="theme_type_variation" type="StringName" setter="set_theme_type_variation" getter="get_theme_type_variation" default="&"""> The name of a theme type variation used by this [Window] to look up its own theme items. See [member Control.theme_type_variation] for more details. diff --git a/doc/classes/XRInterfaceExtension.xml b/doc/classes/XRInterfaceExtension.xml index 0fe54e947f..5ad67a7ea9 100644 --- a/doc/classes/XRInterfaceExtension.xml +++ b/doc/classes/XRInterfaceExtension.xml @@ -24,7 +24,7 @@ <method name="_get_camera_feed_id" qualifiers="virtual const"> <return type="int" /> <description> - Returns the camera feed id for the [CameraFeed] registered with the [CameraServer] that should be presented as the background on an AR capable device (if applicable). + Returns the camera feed ID for the [CameraFeed] registered with the [CameraServer] that should be presented as the background on an AR capable device (if applicable). </description> </method> <method name="_get_camera_transform" qualifiers="virtual"> diff --git a/doc/tools/make_rst.py b/doc/tools/make_rst.py index e5a0bbb008..1f71b77cbd 100755 --- a/doc/tools/make_rst.py +++ b/doc/tools/make_rst.py @@ -240,7 +240,7 @@ class State: enum_def = class_def.enums[enum] else: - enum_def = EnumDef(enum, is_bitfield) + enum_def = EnumDef(enum, TypeName("int", enum), is_bitfield) class_def.enums[enum] = enum_def enum_def.values[constant_name] = constant_def @@ -458,9 +458,10 @@ class ConstantDef(DefinitionBase): class EnumDef(DefinitionBase): - def __init__(self, name: str, bitfield: bool) -> None: + def __init__(self, name: str, type_name: TypeName, bitfield: bool) -> None: super().__init__("enum", name) + self.type_name = type_name self.values: OrderedDict[str, ConstantDef] = OrderedDict() self.is_bitfield = bitfield @@ -754,7 +755,8 @@ def make_rst_class(class_def: ClassDef, state: State, dry_run: bool, output_dir: f.write(f".. _class_{class_name}:\n\n") f.write(make_heading(class_name, "=", False)) - # Inheritance tree + ### INHERITANCE TREE ### + # Ascendants if class_def.inherits: inherits = class_def.inherits.strip() @@ -788,6 +790,8 @@ def make_rst_class(class_def: ClassDef, state: State, dry_run: bool, output_dir: f.write(make_type(child, state)) f.write("\n\n") + ### INTRODUCTION ### + has_description = False # Brief description @@ -800,7 +804,9 @@ def make_rst_class(class_def: ClassDef, state: State, dry_run: bool, output_dir: if class_def.description is not None and class_def.description.strip() != "": has_description = True + f.write(".. rst-class:: classref-introduction-group\n\n") f.write(make_heading("Description", "-")) + f.write(f"{format_text_block(class_def.description.strip(), class_def, state)}\n\n") if not has_description: @@ -814,14 +820,22 @@ def make_rst_class(class_def: ClassDef, state: State, dry_run: bool, output_dir: # Online tutorials if len(class_def.tutorials) > 0: + f.write(".. rst-class:: classref-introduction-group\n\n") f.write(make_heading("Tutorials", "-")) + for url, title in class_def.tutorials: f.write(f"- {make_link(url, title)}\n\n") - # Properties overview + ### REFERENCE TABLES ### + + # Reused container for reference tables. ml: List[Tuple[Optional[str], ...]] = [] + + # Properties reference table if len(class_def.properties) > 0: + f.write(".. rst-class:: classref-reftable-group\n\n") f.write(make_heading("Properties", "-")) + ml = [] for property_def in class_def.properties.values(): type_rst = property_def.type_name.to_rst(state) @@ -833,76 +847,108 @@ def make_rst_class(class_def: ClassDef, state: State, dry_run: bool, output_dir: else: ref = f":ref:`{property_def.name}<class_{class_name}_property_{property_def.name}>`" ml.append((type_rst, ref, default)) + format_table(f, ml, True) - # Constructors, Methods, Operators overview + # Constructors, Methods, Operators reference tables if len(class_def.constructors) > 0: + f.write(".. rst-class:: classref-reftable-group\n\n") f.write(make_heading("Constructors", "-")) + ml = [] for method_list in class_def.constructors.values(): for m in method_list: ml.append(make_method_signature(class_def, m, "constructor", state)) + format_table(f, ml) if len(class_def.methods) > 0: + f.write(".. rst-class:: classref-reftable-group\n\n") f.write(make_heading("Methods", "-")) + ml = [] for method_list in class_def.methods.values(): for m in method_list: ml.append(make_method_signature(class_def, m, "method", state)) + format_table(f, ml) if len(class_def.operators) > 0: + f.write(".. rst-class:: classref-reftable-group\n\n") f.write(make_heading("Operators", "-")) + ml = [] for method_list in class_def.operators.values(): for m in method_list: ml.append(make_method_signature(class_def, m, "operator", state)) + format_table(f, ml) - # Theme properties + # Theme properties reference table if len(class_def.theme_items) > 0: + f.write(".. rst-class:: classref-reftable-group\n\n") f.write(make_heading("Theme Properties", "-")) - pl: List[Tuple[Optional[str], ...]] = [] + + ml = [] for theme_item_def in class_def.theme_items.values(): ref = f":ref:`{theme_item_def.name}<class_{class_name}_theme_{theme_item_def.data_name}_{theme_item_def.name}>`" - pl.append((theme_item_def.type_name.to_rst(state), ref, theme_item_def.default_value)) - format_table(f, pl, True) + ml.append((theme_item_def.type_name.to_rst(state), ref, theme_item_def.default_value)) + + format_table(f, ml, True) - # Signals + ### DETAILED DESCRIPTIONS ### + + # Signal descriptions if len(class_def.signals) > 0: + f.write(make_separator(True)) + f.write(".. rst-class:: classref-descriptions-group\n\n") f.write(make_heading("Signals", "-")) + index = 0 for signal in class_def.signals.values(): if index != 0: - f.write("----\n\n") + f.write(make_separator()) + + # Create signal signature and anchor point. f.write(f".. _class_{class_name}_signal_{signal.name}:\n\n") + f.write(".. rst-class:: classref-signal\n\n") + _, signature = make_method_signature(class_def, signal, "", state) - f.write(f"- {signature}\n\n") + f.write(f"{signature}\n\n") + + # Add signal description, or a call to action if it's missing. if signal.description is not None and signal.description.strip() != "": f.write(f"{format_text_block(signal.description.strip(), signal, state)}\n\n") + else: + f.write(".. container:: contribute\n\n\t") + f.write( + translate( + "There is currently no description for this signal. Please help us by :ref:`contributing one <doc_updating_the_class_reference>`!" + ) + + "\n\n" + ) index += 1 - # Enums + # Enumeration descriptions if len(class_def.enums) > 0: + f.write(make_separator(True)) + f.write(".. rst-class:: classref-descriptions-group\n\n") f.write(make_heading("Enumerations", "-")) + index = 0 for e in class_def.enums.values(): if index != 0: - f.write("----\n\n") + f.write(make_separator()) + + # Create enumeration signature and anchor point. f.write(f".. _enum_{class_name}_{e.name}:\n\n") - # Sphinx seems to divide the bullet list into individual <ul> tags if we weave the labels into it. - # As such I'll put them all above the list. Won't be perfect but better than making the list visually broken. - # As to why I'm not modifying the reference parser to directly link to the _enum label: - # If somebody gets annoyed enough to fix it, all existing references will magically improve. - for value in e.values.values(): - f.write(f".. _class_{class_name}_constant_{value.name}:\n\n") + f.write(".. rst-class:: classref-enumeration\n\n") if e.is_bitfield: f.write(f"flags **{e.name}**:\n\n") @@ -910,45 +956,66 @@ def make_rst_class(class_def: ClassDef, state: State, dry_run: bool, output_dir: f.write(f"enum **{e.name}**:\n\n") for value in e.values.values(): - f.write(f"- **{value.name}** = **{value.value}**") + # Also create signature and anchor point for each enum constant. + + f.write(f".. _class_{class_name}_constant_{value.name}:\n\n") + f.write(".. rst-class:: classref-enumeration-constant\n\n") + + f.write(f"{e.type_name.to_rst(state)} **{value.name}** = ``{value.value}``\n\n") + + # Add enum constant description. + if value.text is not None and value.text.strip() != "": - # If value.text contains a bullet point list, each entry needs additional indentation - f.write(f" --- {indent_bullets(format_text_block(value.text.strip(), value, state))}") + f.write(f"{format_text_block(value.text.strip(), value, state)}") f.write("\n\n") index += 1 - # Constants + # Constant descriptions if len(class_def.constants) > 0: + f.write(make_separator(True)) + f.write(".. rst-class:: classref-descriptions-group\n\n") f.write(make_heading("Constants", "-")) - # Sphinx seems to divide the bullet list into individual <ul> tags if we weave the labels into it. - # As such I'll put them all above the list. Won't be perfect but better than making the list visually broken. + for constant in class_def.constants.values(): + # Create constant signature and anchor point. + f.write(f".. _class_{class_name}_constant_{constant.name}:\n\n") + f.write(".. rst-class:: classref-constant\n\n") + + f.write(f"**{constant.name}** = ``{constant.value}``\n\n") + + # Add enum constant description. - for constant in class_def.constants.values(): - f.write(f"- **{constant.name}** = **{constant.value}**") if constant.text is not None and constant.text.strip() != "": - f.write(f" --- {format_text_block(constant.text.strip(), constant, state)}") + f.write(f"{format_text_block(constant.text.strip(), constant, state)}") f.write("\n\n") - # Annotations + # Annotation descriptions if len(class_def.annotations) > 0: + f.write(make_separator(True)) f.write(make_heading("Annotations", "-")) + index = 0 for method_list in class_def.annotations.values(): # type: ignore for i, m in enumerate(method_list): if index != 0: - f.write("----\n\n") + f.write(make_separator()) + + # Create annotation signature and anchor point. if i == 0: f.write(f".. _class_{class_name}_annotation_{m.name}:\n\n") + f.write(".. rst-class:: classref-annotation\n\n") + _, signature = make_method_signature(class_def, m, "", state) - f.write(f"- {signature}\n\n") + f.write(f"{signature}\n\n") + + # Add annotation description, or a call to action if it's missing. if m.description is not None and m.description.strip() != "": f.write(f"{format_text_block(m.description.strip(), m, state)}\n\n") @@ -965,7 +1032,10 @@ def make_rst_class(class_def: ClassDef, state: State, dry_run: bool, output_dir: # Property descriptions if any(not p.overrides for p in class_def.properties.values()) > 0: + f.write(make_separator(True)) + f.write(".. rst-class:: classref-descriptions-group\n\n") f.write(make_heading("Property Descriptions", "-")) + index = 0 for property_def in class_def.properties.values(): @@ -973,22 +1043,36 @@ def make_rst_class(class_def: ClassDef, state: State, dry_run: bool, output_dir: continue if index != 0: - f.write("----\n\n") + f.write(make_separator()) + + # Create property signature and anchor point. f.write(f".. _class_{class_name}_property_{property_def.name}:\n\n") - f.write(f"- {property_def.type_name.to_rst(state)} **{property_def.name}**\n\n") + f.write(".. rst-class:: classref-property\n\n") - info: List[Tuple[Optional[str], ...]] = [] - # Not using translate() for now as it breaks table formatting. + property_default = "" if property_def.default_value is not None: - info.append(("*Default*", property_def.default_value)) + property_default = f" = {property_def.default_value}" + f.write(f"{property_def.type_name.to_rst(state)} **{property_def.name}**{property_default}\n\n") + + # Create property setter and getter records. + + property_setget = "" + if property_def.setter is not None and not property_def.setter.startswith("_"): - info.append(("*Setter*", f"{property_def.setter}(value)")) + property_setter = make_setter_signature(class_def, property_def, state) + property_setget += f"- {property_setter}\n" + if property_def.getter is not None and not property_def.getter.startswith("_"): - info.append(("*Getter*", f"{property_def.getter}()")) + property_getter = make_getter_signature(class_def, property_def, state) + property_setget += f"- {property_getter}\n" + + if property_setget != "": + f.write(".. rst-class:: classref-property-setget\n\n") + f.write(property_setget) + f.write("\n") - if len(info) > 0: - format_table(f, info) + # Add property description, or a call to action if it's missing. if property_def.text is not None and property_def.text.strip() != "": f.write(f"{format_text_block(property_def.text.strip(), property_def, state)}\n\n") @@ -1005,19 +1089,28 @@ def make_rst_class(class_def: ClassDef, state: State, dry_run: bool, output_dir: # Constructor, Method, Operator descriptions if len(class_def.constructors) > 0: + f.write(make_separator(True)) + f.write(".. rst-class:: classref-descriptions-group\n\n") f.write(make_heading("Constructor Descriptions", "-")) + index = 0 for method_list in class_def.constructors.values(): for i, m in enumerate(method_list): if index != 0: - f.write("----\n\n") + f.write(make_separator()) + + # Create constructor signature and anchor point. if i == 0: f.write(f".. _class_{class_name}_constructor_{m.name}:\n\n") + f.write(".. rst-class:: classref-constructor\n\n") + ret_type, signature = make_method_signature(class_def, m, "", state) - f.write(f"- {ret_type} {signature}\n\n") + f.write(f"{ret_type} {signature}\n\n") + + # Add constructor description, or a call to action if it's missing. if m.description is not None and m.description.strip() != "": f.write(f"{format_text_block(m.description.strip(), m, state)}\n\n") @@ -1033,19 +1126,28 @@ def make_rst_class(class_def: ClassDef, state: State, dry_run: bool, output_dir: index += 1 if len(class_def.methods) > 0: + f.write(make_separator(True)) + f.write(".. rst-class:: classref-descriptions-group\n\n") f.write(make_heading("Method Descriptions", "-")) + index = 0 for method_list in class_def.methods.values(): for i, m in enumerate(method_list): if index != 0: - f.write("----\n\n") + f.write(make_separator()) + + # Create method signature and anchor point. if i == 0: f.write(f".. _class_{class_name}_method_{m.name}:\n\n") + f.write(".. rst-class:: classref-method\n\n") + ret_type, signature = make_method_signature(class_def, m, "", state) - f.write(f"- {ret_type} {signature}\n\n") + f.write(f"{ret_type} {signature}\n\n") + + # Add method description, or a call to action if it's missing. if m.description is not None and m.description.strip() != "": f.write(f"{format_text_block(m.description.strip(), m, state)}\n\n") @@ -1061,20 +1163,31 @@ def make_rst_class(class_def: ClassDef, state: State, dry_run: bool, output_dir: index += 1 if len(class_def.operators) > 0: + f.write(make_separator(True)) + f.write(".. rst-class:: classref-descriptions-group\n\n") f.write(make_heading("Operator Descriptions", "-")) + index = 0 for method_list in class_def.operators.values(): for i, m in enumerate(method_list): if index != 0: - f.write("----\n\n") - out = f".. _class_{class_name}_operator_{sanitize_operator_name(m.name, state)}" + f.write(make_separator()) + + # Create operator signature and anchor point. + + operator_anchor = f".. _class_{class_name}_operator_{sanitize_operator_name(m.name, state)}" for parameter in m.parameters: - out += f"_{parameter.type_name.type_name}" - out += f":\n\n" - f.write(out) + operator_anchor += f"_{parameter.type_name.type_name}" + operator_anchor += f":\n\n" + f.write(operator_anchor) + + f.write(".. rst-class:: classref-operator\n\n") + ret_type, signature = make_method_signature(class_def, m, "", state) - f.write(f"- {ret_type} {signature}\n\n") + f.write(f"{ret_type} {signature}\n\n") + + # Add operator description, or a call to action if it's missing. if m.description is not None and m.description.strip() != "": f.write(f"{format_text_block(m.description.strip(), m, state)}\n\n") @@ -1091,23 +1204,27 @@ def make_rst_class(class_def: ClassDef, state: State, dry_run: bool, output_dir: # Theme property descriptions if len(class_def.theme_items) > 0: + f.write(make_separator(True)) + f.write(".. rst-class:: classref-descriptions-group\n\n") f.write(make_heading("Theme Property Descriptions", "-")) + index = 0 for theme_item_def in class_def.theme_items.values(): if index != 0: - f.write("----\n\n") + f.write(make_separator()) + + # Create theme property signature and anchor point. f.write(f".. _class_{class_name}_theme_{theme_item_def.data_name}_{theme_item_def.name}:\n\n") - f.write(f"- {theme_item_def.type_name.to_rst(state)} **{theme_item_def.name}**\n\n") + f.write(".. rst-class:: classref-themeproperty\n\n") - info = [] + theme_item_default = "" if theme_item_def.default_value is not None: - # Not using translate() for now as it breaks table formatting. - info.append(("*Default*", theme_item_def.default_value)) + theme_item_default = f" = {theme_item_def.default_value}" + f.write(f"{theme_item_def.type_name.to_rst(state)} **{theme_item_def.name}**{theme_item_default}\n\n") - if len(info) > 0: - format_table(f, info) + # Add theme property description, or a call to action if it's missing. if theme_item_def.text is not None and theme_item_def.text.strip() != "": f.write(f"{format_text_block(theme_item_def.text.strip(), theme_item_def, state)}\n\n") @@ -1216,6 +1333,39 @@ def make_method_signature( return ret_type, out +def make_setter_signature(class_def: ClassDef, property_def: PropertyDef, state: State) -> str: + if property_def.setter is None: + return "" + + # If setter is a method available as a method definition, we use that. + if property_def.setter in class_def.methods: + setter = class_def.methods[property_def.setter][0] + # Otherwise we fake it with the information we have available. + else: + setter_params: List[ParameterDef] = [] + setter_params.append(ParameterDef("value", property_def.type_name, None)) + setter = MethodDef(property_def.setter, TypeName("void"), setter_params, None, None) + + ret_type, signature = make_method_signature(class_def, setter, "", state) + return f"{ret_type} {signature}" + + +def make_getter_signature(class_def: ClassDef, property_def: PropertyDef, state: State) -> str: + if property_def.getter is None: + return "" + + # If getter is a method available as a method definition, we use that. + if property_def.getter in class_def.methods: + getter = class_def.methods[property_def.getter][0] + # Otherwise we fake it with the information we have available. + else: + getter_params: List[ParameterDef] = [] + getter = MethodDef(property_def.getter, property_def.type_name, getter_params, None, None) + + ret_type, signature = make_method_signature(class_def, getter, "", state) + return f"{ret_type} {signature}" + + def make_heading(title: str, underline: str, l10n: bool = True) -> str: if l10n: new_title = translate(title) @@ -1247,6 +1397,14 @@ def make_footer() -> str: ) +def make_separator(section_level: bool = False) -> str: + separator_class = "item" + if section_level: + separator_class = "section" + + return f".. rst-class:: classref-{separator_class}-separator\n\n----\n\n" + + def make_link(url: str, title: str) -> str: match = GODOT_DOCS_PATTERN.search(url) if match: @@ -1407,10 +1565,10 @@ def format_text_block( escape_post = False # Tag is a reference to a class. - if tag_text in state.classes: + if tag_text in state.classes and not inside_code: if tag_text == state.current_class: - # Don't create a link to the same class, format it as inline code. - tag_text = f"``{tag_text}``" + # Don't create a link to the same class, format it as strong emphasis. + tag_text = f"**{tag_text}**" else: tag_text = make_type(tag_text, state) escape_pre = True @@ -1872,6 +2030,11 @@ def format_table(f: TextIO, data: List[Tuple[Optional[str], ...]], remove_empty_ if len(data) == 0: return + f.write(".. table::\n") + f.write(" :widths: auto\n\n") + + # Calculate the width of each column first, we will use this information + # to properly format RST-style tables. column_sizes = [0] * len(data[0]) for row in data: for i, text in enumerate(row): @@ -1879,14 +2042,21 @@ def format_table(f: TextIO, data: List[Tuple[Optional[str], ...]], remove_empty_ if text_length > column_sizes[i]: column_sizes[i] = text_length + # Each table row is wrapped in two separators, consecutive rows share the same separator. + # All separators, or rather borders, have the same shape and content. We compose it once, + # then reuse it. + sep = "" for size in column_sizes: if size == 0 and remove_empty_columns: continue - sep += "+" + "-" * (size + 2) + sep += "+" + "-" * (size + 2) # Content of each cell is padded by 1 on each side. sep += "+\n" - f.write(sep) + # Draw the first separator. + f.write(f" {sep}") + + # Draw each row and close it with a separator. for row in data: row_text = "|" for i, text in enumerate(row): @@ -1894,8 +2064,10 @@ def format_table(f: TextIO, data: List[Tuple[Optional[str], ...]], remove_empty_ continue row_text += f' {(text or "").ljust(column_sizes[i])} |' row_text += "\n" - f.write(row_text) - f.write(sep) + + f.write(f" {row_text}") + f.write(f" {sep}") + f.write("\n") @@ -1957,24 +2129,5 @@ def sanitize_operator_name(dirty_name: str, state: State) -> str: return clear_name -def indent_bullets(text: str) -> str: - # Take the text and check each line for a bullet point represented by "-". - # Where found, indent the given line by a further "\t". - # Used to properly indent bullet points contained in the description for enum values. - # Ignore the first line - text will be prepended to it so bullet points wouldn't work anyway. - bullet_points = "-" - - lines = text.splitlines(keepends=True) - for line_index, line in enumerate(lines[1:], start=1): - pos = 0 - while pos < len(line) and line[pos] == "\t": - pos += 1 - - if pos < len(line) and line[pos] in bullet_points: - lines[line_index] = f"{line[:pos]}\t{line[pos:]}" - - return "".join(lines) - - if __name__ == "__main__": main() |