Merge pull request #34155 from Calinou/doc-richtexteffect

Document RichTextEffect and CharFXTransform
This commit is contained in:
Rémi Verschelde 2019-12-06 23:14:05 +01:00 committed by GitHub
commit 111ba06310
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
2 changed files with 34 additions and 0 deletions

View file

@ -1,10 +1,14 @@
<?xml version="1.0" encoding="UTF-8" ?> <?xml version="1.0" encoding="UTF-8" ?>
<class name="CharFXTransform" inherits="Reference" category="Core" version="3.2"> <class name="CharFXTransform" inherits="Reference" category="Core" version="3.2">
<brief_description> <brief_description>
Controls how an individual character will be displayed in a [RichTextEffect].
</brief_description> </brief_description>
<description> <description>
By setting various properties on this object, you can control how individual characters will be displayed in a [RichTextEffect].
</description> </description>
<tutorials> <tutorials>
<link>http://docs.godotengine.org/en/latest/tutorials/gui/bbcode_in_richtextlabel.html</link>
<link>https://github.com/Eoin-ONeill-Yokai/Godot-Rich-Text-Effect-Test-Project</link>
</tutorials> </tutorials>
<methods> <methods>
<method name="get_value_or"> <method name="get_value_or">
@ -15,25 +19,44 @@
<argument index="1" name="default_value" type="Variant"> <argument index="1" name="default_value" type="Variant">
</argument> </argument>
<description> <description>
Returns the value for [code]key[/code] in the [member env] [Dictionary], or [code]default_value[/code] if [code]key[/code] isn't defined in [member env]. If the value's type doesn't match [code]default_value[/code]'s type, this method will return [code]default_value[/code].
</description> </description>
</method> </method>
</methods> </methods>
<members> <members>
<member name="absolute_index" type="int" setter="set_absolute_index" getter="get_absolute_index" default="0"> <member name="absolute_index" type="int" setter="set_absolute_index" getter="get_absolute_index" default="0">
The index of the current character (starting from 0). Setting this property won't affect drawing.
</member> </member>
<member name="character" type="int" setter="set_character" getter="get_character" default="0"> <member name="character" type="int" setter="set_character" getter="get_character" default="0">
The Unicode codepoint the character will use. This only affects non-whitespace characters. [method @GDScript.ord] can be useful here. For example, the following will replace all characters with asterisks:
[codeblock]
# `char_fx` is the CharFXTransform parameter from `_process_custom_fx()`.
# See the RichTextEffect documentation for details.
char_fx.character = ord("*")
[/codeblock]
</member> </member>
<member name="color" type="Color" setter="set_color" getter="get_color" default="Color( 0, 0, 0, 1 )"> <member name="color" type="Color" setter="set_color" getter="get_color" default="Color( 0, 0, 0, 1 )">
The color the character will be drawn with.
</member> </member>
<member name="elapsed_time" type="float" setter="set_elapsed_time" getter="get_elapsed_time" default="0.0"> <member name="elapsed_time" type="float" setter="set_elapsed_time" getter="get_elapsed_time" default="0.0">
The time elapsed since the [RichTextLabel] was added to the scene tree (in seconds). Time stops when the project is paused, unless the [RichTextLabel]'s [member Node.pause_mode] is set to [constant Node.PAUSE_MODE_PROCESS].
[b]Note:[/b] Time still passes while the [RichTextLabel] is hidden.
</member> </member>
<member name="env" type="Dictionary" setter="set_environment" getter="get_environment" default="{}"> <member name="env" type="Dictionary" setter="set_environment" getter="get_environment" default="{}">
Contains the arguments passed in the opening BBCode tag. By default, arguments are strings; if their contents match a type such as [bool], [int] or [float], they will be converted automatically. Color codes in the form [code]#rrggbb[/code] or [code]#rgb[/code] will be converted to an opaque [Color]. String arguments may not contain spaces, even if they're quoted. If present, quotes will also be present in the final string.
For example, the opening BBCode tag [code][example foo=hello bar=true baz=42 color=#ffffff][/code] will map to the following [Dictionary]:
[codeblock]
{"foo": "hello", "bar": true, "baz": 42, "color": Color(1, 1, 1, 1)}
[/codeblock]
</member> </member>
<member name="offset" type="Vector2" setter="set_offset" getter="get_offset" default="Vector2( 0, 0 )"> <member name="offset" type="Vector2" setter="set_offset" getter="get_offset" default="Vector2( 0, 0 )">
The position offset the character will be drawn with (in pixels).
</member> </member>
<member name="relative_index" type="int" setter="set_relative_index" getter="get_relative_index" default="0"> <member name="relative_index" type="int" setter="set_relative_index" getter="get_relative_index" default="0">
The index of the current character (starting from 0). Setting this property won't affect drawing.
</member> </member>
<member name="visible" type="bool" setter="set_visibility" getter="is_visible" default="true"> <member name="visible" type="bool" setter="set_visibility" getter="is_visible" default="true">
If [code]true[/code], the character will be drawn. If [code]false[/code], the character will be hidden. Characters around hidden characters will reflow to take the space of hidden characters. If this is not desired, set their [member color] to [code]Color(1, 1, 1, 0)[/code] instead.
</member> </member>
</members> </members>
<constants> <constants>

View file

@ -1,10 +1,20 @@
<?xml version="1.0" encoding="UTF-8" ?> <?xml version="1.0" encoding="UTF-8" ?>
<class name="RichTextEffect" inherits="Resource" category="Core" version="3.2"> <class name="RichTextEffect" inherits="Resource" category="Core" version="3.2">
<brief_description> <brief_description>
A custom effect for use with [RichTextLabel].
</brief_description> </brief_description>
<description> <description>
A custom effect for use with [RichTextLabel].
[b]Note:[/b] For a [RichTextEffect] to be usable, a BBCode tag must be defined as a member variable called [code]bbcode[/code] in the script.
[codeblock]
# The RichTextEffect will be usable like this: `[example]Some text[/example]`
var bbcode = "example"
[/codeblock]
[b]Note:[/b] As soon as a [RichTextLabel] contains at least one [RichTextEffect], it will continuously process the effect unless the project is paused. This may impact battery life negatively.
</description> </description>
<tutorials> <tutorials>
<link>http://docs.godotengine.org/en/latest/tutorials/gui/bbcode_in_richtextlabel.html</link>
<link>https://github.com/Eoin-ONeill-Yokai/Godot-Rich-Text-Effect-Test-Project</link>
</tutorials> </tutorials>
<methods> <methods>
<method name="_process_custom_fx" qualifiers="virtual"> <method name="_process_custom_fx" qualifiers="virtual">
@ -13,6 +23,7 @@
<argument index="0" name="char_fx" type="CharFXTransform"> <argument index="0" name="char_fx" type="CharFXTransform">
</argument> </argument>
<description> <description>
Override this method to modify properties in [code]char_fx[/code]. The method must return [code]true[/code] if the character could be transformed successfully. If the method returns [code]false[/code], it will skip transformation to avoid displaying broken text.
</description> </description>
</method> </method>
</methods> </methods>