Skip to content

Commit

Permalink
Merge pull request #82952 from AbelToy/gds-export-array
Browse files Browse the repository at this point in the history 
Allow `@export`ed Arrays to set property hints for their elements
  • Loading branch information
@akien-mga
akien-mga committed Mar 6, 2024
2 parents 1b2e0b3 + 882441a commit 0acc427
Show file tree
Hide file tree
Showing 14 changed files with 470 additions and 73 deletions.
8 changes: 7 additions & 1 deletion doc/tools/make_rst.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -1737,7 +1737,7 @@ def make_rst_index(grouped_classes: Dict[str, List[str]], dry_run: bool, output_
# Formatting helpers.


RESERVED_FORMATTING_TAGS = ["i", "b", "u", "code", "kbd", "center", "url", "br"]
RESERVED_FORMATTING_TAGS = ["i", "b", "u", "lb", "rb", "code", "kbd", "center", "url", "br"]
RESERVED_LAYOUT_TAGS = ["codeblocks"]
RESERVED_CODEBLOCK_TAGS = ["codeblock", "gdscript", "csharp"]
RESERVED_CROSSLINK_TAGS = [
Expand Down Expand Up @@ -2311,6 +2311,12 @@ def format_text_block(
escape_pre = True
tag_text = ""

elif tag_state.name == "lb":
tag_text = "\\["

elif tag_state.name == "rb":
tag_text = "\\]"

elif tag_state.name == "kbd":
tag_text = "`"
if tag_state.closing:
Expand Down
16 changes: 8 additions & 8 deletions editor/editor_properties.cpp
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3869,27 +3869,27 @@ EditorProperty *EditorInspectorDefaultPlugin::get_editor_for_property(Object *p_
} break;
case Variant::PACKED_BYTE_ARRAY: {
EditorPropertyArray *editor = memnew(EditorPropertyArray);
editor->setup(Variant::PACKED_BYTE_ARRAY);
editor->setup(Variant::PACKED_BYTE_ARRAY, p_hint_text);
return editor;
} break;
case Variant::PACKED_INT32_ARRAY: {
EditorPropertyArray *editor = memnew(EditorPropertyArray);
editor->setup(Variant::PACKED_INT32_ARRAY);
editor->setup(Variant::PACKED_INT32_ARRAY, p_hint_text);
return editor;
} break;
case Variant::PACKED_INT64_ARRAY: {
EditorPropertyArray *editor = memnew(EditorPropertyArray);
editor->setup(Variant::PACKED_INT64_ARRAY);
editor->setup(Variant::PACKED_INT64_ARRAY, p_hint_text);
return editor;
} break;
case Variant::PACKED_FLOAT32_ARRAY: {
EditorPropertyArray *editor = memnew(EditorPropertyArray);
editor->setup(Variant::PACKED_FLOAT32_ARRAY);
editor->setup(Variant::PACKED_FLOAT32_ARRAY, p_hint_text);
return editor;
} break;
case Variant::PACKED_FLOAT64_ARRAY: {
EditorPropertyArray *editor = memnew(EditorPropertyArray);
editor->setup(Variant::PACKED_FLOAT64_ARRAY);
editor->setup(Variant::PACKED_FLOAT64_ARRAY, p_hint_text);
return editor;
} break;
case Variant::PACKED_STRING_ARRAY: {
Expand All @@ -3899,17 +3899,17 @@ EditorProperty *EditorInspectorDefaultPlugin::get_editor_for_property(Object *p_
} break;
case Variant::PACKED_VECTOR2_ARRAY: {
EditorPropertyArray *editor = memnew(EditorPropertyArray);
editor->setup(Variant::PACKED_VECTOR2_ARRAY);
editor->setup(Variant::PACKED_VECTOR2_ARRAY, p_hint_text);
return editor;
} break;
case Variant::PACKED_VECTOR3_ARRAY: {
EditorPropertyArray *editor = memnew(EditorPropertyArray);
editor->setup(Variant::PACKED_VECTOR3_ARRAY);
editor->setup(Variant::PACKED_VECTOR3_ARRAY, p_hint_text);
return editor;
} break;
case Variant::PACKED_COLOR_ARRAY: {
EditorPropertyArray *editor = memnew(EditorPropertyArray);
editor->setup(Variant::PACKED_COLOR_ARRAY);
editor->setup(Variant::PACKED_COLOR_ARRAY, p_hint_text);
return editor;
} break;
default: {
Expand Down
47 changes: 37 additions & 10 deletions modules/gdscript/doc_classes/@GDScript.xml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -333,33 +333,38 @@
<annotation name="@export_color_no_alpha">
<return type="void" />
<description>
Export a [Color] property without allowing its transparency ([member Color.a]) to be edited.
Export a [Color], [Array][lb][Color][rb], or [PackedColorArray] property without allowing its transparency ([member Color.a]) to be edited.
See also [constant PROPERTY_HINT_COLOR_NO_ALPHA].
[codeblock]
@export_color_no_alpha var dye_color: Color
@export_color_no_alpha var dye_colors: Array[Color]
[/codeblock]
</description>
</annotation>
<annotation name="@export_dir">
<return type="void" />
<description>
Export a [String] property as a path to a directory. The path will be limited to the project folder and its subfolders. See [annotation @export_global_dir] to allow picking from the entire filesystem.
Export a [String], [Array][lb][String][rb], or [PackedStringArray] property as a path to a directory. The path will be limited to the project folder and its subfolders. See [annotation @export_global_dir] to allow picking from the entire filesystem.
See also [constant PROPERTY_HINT_DIR].
[codeblock]
@export_dir var sprite_folder_path: String
@export_dir var sprite_folder_paths: Array[String]
[/codeblock]
</description>
</annotation>
<annotation name="@export_enum" qualifiers="vararg">
<return type="void" />
<param index="0" name="names" type="String" />
<description>
Export an [int] or [String] property as an enumerated list of options. If the property is an [int], then the index of the value is stored, in the same order the values are provided. You can add explicit values using a colon. If the property is a [String], then the value is stored.
Export an [int], [String], [Array][lb][int][rb], [Array][lb][String][rb], [PackedByteArray], [PackedInt32Array], [PackedInt64Array], or [PackedStringArray] property as an enumerated list of options (or an array of options). If the property is an [int], then the index of the value is stored, in the same order the values are provided. You can add explicit values using a colon. If the property is a [String], then the value is stored.
See also [constant PROPERTY_HINT_ENUM].
[codeblock]
@export_enum("Warrior", "Magician", "Thief") var character_class: int
@export_enum("Slow:30", "Average:60", "Very Fast:200") var character_speed: int
@export_enum("Rebecca", "Mary", "Leah") var character_name: String

@export_enum("Sword", "Spear", "Mace") var character_items: Array[int]
@export_enum("double_jump", "climb", "dash") var character_skills: Array[String]
[/codeblock]
If you want to set an initial value, you must specify it explicitly:
[codeblock]
Expand All @@ -369,6 +374,9 @@
[codeblock]
enum CharacterName {REBECCA, MARY, LEAH}
@export var character_name: CharacterName

enum CharacterItem {SWORD, SPEAR, MACE}
@export var character_items: Array[CharacterItem]
[/codeblock]
</description>
</annotation>
Expand All @@ -382,19 +390,21 @@
@export_exp_easing var transition_speed
@export_exp_easing("attenuation") var fading_attenuation
@export_exp_easing("positive_only") var effect_power
@export_exp_easing var speeds: Array[float]
[/codeblock]
</description>
</annotation>
<annotation name="@export_file" qualifiers="vararg">
<return type="void" />
<param index="0" name="filter" type="String" default="&quot;&quot;" />
<description>
Export a [String] property as a path to a file. The path will be limited to the project folder and its subfolders. See [annotation @export_global_file] to allow picking from the entire filesystem.
Export a [String], [Array][lb][String][rb], or [PackedStringArray] property as a path to a file. The path will be limited to the project folder and its subfolders. See [annotation @export_global_file] to allow picking from the entire filesystem.
If [param filter] is provided, only matching files will be available for picking.
See also [constant PROPERTY_HINT_FILE].
[codeblock]
@export_file var sound_effect_path: String
@export_file("*.txt") var notes_path: String
@export_file var level_paths: Array[String]
[/codeblock]
</description>
</annotation>
Expand All @@ -421,6 +431,10 @@
[codeblock]
@export_flags("A:16", "B", "C") var x
[/codeblock]
You can also use the annotation on [Array][lb][int][rb], [PackedByteArray], [PackedInt32Array], and [PackedInt64Array]
[codeblock]
@export_flags("Fire", "Water", "Earth", "Wind") var phase_elements: Array[int]
[/codeblock]
</description>
</annotation>
<annotation name="@export_flags_2d_navigation">
Expand All @@ -430,6 +444,7 @@
See also [constant PROPERTY_HINT_LAYERS_2D_NAVIGATION].
[codeblock]
@export_flags_2d_navigation var navigation_layers: int
@export_flags_2d_navigation var navigation_layers_array: Array[int]
[/codeblock]
</description>
</annotation>
Expand All @@ -440,6 +455,7 @@
See also [constant PROPERTY_HINT_LAYERS_2D_PHYSICS].
[codeblock]
@export_flags_2d_physics var physics_layers: int
@export_flags_2d_physics var physics_layers_array: Array[int]
[/codeblock]
</description>
</annotation>
Expand All @@ -450,6 +466,7 @@
See also [constant PROPERTY_HINT_LAYERS_2D_RENDER].
[codeblock]
@export_flags_2d_render var render_layers: int
@export_flags_2d_render var render_layers_array: Array[int]
[/codeblock]
</description>
</annotation>
Expand All @@ -460,6 +477,7 @@
See also [constant PROPERTY_HINT_LAYERS_3D_NAVIGATION].
[codeblock]
@export_flags_3d_navigation var navigation_layers: int
@export_flags_3d_navigation var navigation_layers_array: Array[int]
[/codeblock]
</description>
</annotation>
Expand All @@ -470,6 +488,7 @@
See also [constant PROPERTY_HINT_LAYERS_3D_PHYSICS].
[codeblock]
@export_flags_3d_physics var physics_layers: int
@export_flags_3d_physics var physics_layers_array: Array[int]
[/codeblock]
</description>
</annotation>
Expand All @@ -480,6 +499,7 @@
See also [constant PROPERTY_HINT_LAYERS_3D_RENDER].
[codeblock]
@export_flags_3d_render var render_layers: int
@export_flags_3d_render var render_layers_array: Array[int]
[/codeblock]
</description>
</annotation>
Expand All @@ -490,29 +510,32 @@
See also [constant PROPERTY_HINT_LAYERS_AVOIDANCE].
[codeblock]
@export_flags_avoidance var avoidance_layers: int
@export_flags_avoidance var avoidance_layers_array: Array[int]
[/codeblock]
</description>
</annotation>
<annotation name="@export_global_dir">
<return type="void" />
<description>
Export a [String] property as an absolute path to a directory. The path can be picked from the entire filesystem. See [annotation @export_dir] to limit it to the project folder and its subfolders.
Export a [String], [Array][lb][String][rb], or [PackedStringArray] property as an absolute path to a directory. The path can be picked from the entire filesystem. See [annotation @export_dir] to limit it to the project folder and its subfolders.
See also [constant PROPERTY_HINT_GLOBAL_DIR].
[codeblock]
@export_global_dir var sprite_folder_path: String
@export_global_dir var sprite_folder_paths: Array[String]
[/codeblock]
</description>
</annotation>
<annotation name="@export_global_file" qualifiers="vararg">
<return type="void" />
<param index="0" name="filter" type="String" default="&quot;&quot;" />
<description>
Export a [String] property as an absolute path to a file. The path can be picked from the entire filesystem. See [annotation @export_file] to limit it to the project folder and its subfolders.
Export a [String], [Array][lb][String][rb], or [PackedStringArray] property as an absolute path to a file. The path can be picked from the entire filesystem. See [annotation @export_file] to limit it to the project folder and its subfolders.
If [param filter] is provided, only matching files will be available for picking.
See also [constant PROPERTY_HINT_GLOBAL_FILE].
[codeblock]
@export_global_file var sound_effect_path: String
@export_global_file("*.txt") var notes_path: String
@export_global_file var multiple_paths: Array[String]
[/codeblock]
</description>
</annotation>
Expand Down Expand Up @@ -542,21 +565,23 @@
<annotation name="@export_multiline">
<return type="void" />
<description>
Export a [String] property with a large [TextEdit] widget instead of a [LineEdit]. This adds support for multiline content and makes it easier to edit large amount of text stored in the property.
Export a [String], [Array][lb][String][rb], [PackedStringArray], [Dictionary] or [Array][lb][Dictionary][rb] property with a large [TextEdit] widget instead of a [LineEdit]. This adds support for multiline content and makes it easier to edit large amount of text stored in the property.
See also [constant PROPERTY_HINT_MULTILINE_TEXT].
[codeblock]
@export_multiline var character_biography
@export_multiline var npc_dialogs: Array[String]
[/codeblock]
</description>
</annotation>
<annotation name="@export_node_path" qualifiers="vararg">
<return type="void" />
<param index="0" name="type" type="String" default="&quot;&quot;" />
<description>
Export a [NodePath] property with a filter for allowed node types.
Export a [NodePath] or [Array][lb][NodePath][rb] property with a filter for allowed node types.
See also [constant PROPERTY_HINT_NODE_PATH_VALID_TYPES].
[codeblock]
@export_node_path("Button", "TouchScreenButton") var some_button
@export_node_path("Button", "TouchScreenButton") var many_buttons: Array[NodePath]
[/codeblock]
[b]Note:[/b] The type must be a native class or a globally registered script (using the [code]class_name[/code] keyword) that inherits [Node].
</description>
Expand All @@ -565,10 +590,11 @@
<return type="void" />
<param index="0" name="placeholder" type="String" />
<description>
Export a [String] property with a placeholder text displayed in the editor widget when no value is present.
Export a [String], [Array][lb][String][rb], or [PackedStringArray] property with a placeholder text displayed in the editor widget when no value is present.
See also [constant PROPERTY_HINT_PLACEHOLDER_TEXT].
[codeblock]
@export_placeholder("Name in lowercase") var character_id: String
@export_placeholder("Name in lowercase") var friend_ids: Array[String]
[/codeblock]
</description>
</annotation>
Expand All @@ -579,14 +605,15 @@
<param index="2" name="step" type="float" default="1.0" />
<param index="3" name="extra_hints" type="String" default="&quot;&quot;" />
<description>
Export an [int] or [float] property as a range value. The range must be defined by [param min] and [param max], as well as an optional [param step] and a variety of extra hints. The [param step] defaults to [code]1[/code] for integer properties. For floating-point numbers this value depends on your [member EditorSettings.interface/inspector/default_float_step] setting.
Export an [int], [float], [Array][lb][int][rb], [Array][lb][float][rb], [PackedByteArray], [PackedInt32Array], [PackedInt64Array], [PackedFloat32Array], or [PackedFloat64Array] property as a range value. The range must be defined by [param min] and [param max], as well as an optional [param step] and a variety of extra hints. The [param step] defaults to [code]1[/code] for integer properties. For floating-point numbers this value depends on your [member EditorSettings.interface/inspector/default_float_step] setting.
If hints [code]"or_greater"[/code] and [code]"or_less"[/code] are provided, the editor widget will not cap the value at range boundaries. The [code]"exp"[/code] hint will make the edited values on range to change exponentially. The [code]"hide_slider"[/code] hint will hide the slider element of the editor widget.
Hints also allow to indicate the units for the edited value. Using [code]"radians_as_degrees"[/code] you can specify that the actual value is in radians, but should be displayed in degrees in the Inspector dock (the range values are also in degrees). [code]"degrees"[/code] allows to add a degree sign as a unit suffix (the value is unchanged). Finally, a custom suffix can be provided using [code]"suffix:unit"[/code], where "unit" can be any string.
See also [constant PROPERTY_HINT_RANGE].
[codeblock]
@export_range(0, 20) var number
@export_range(-10, 20) var number
@export_range(-10, 20, 0.2) var number: float
@export_range(0, 20) var numbers: Array[float]

@export_range(0, 100, 1, "or_greater") var power_percent
@export_range(0, 100, 1, "or_greater", "or_less") var health_delta
Expand Down
Loading

0 comments on commit 0acc427

Please sign in to comment.