From e27f127a7405914b38917ef65da0c804d9ef42db Mon Sep 17 00:00:00 2001 From: Raul Santos Date: Thu, 24 Nov 2022 00:30:05 +0100 Subject: Fix C# documentation for Godot.Object - Add and fix a few C# examples - Add tips about avoiding allocating StringNames --- doc/classes/Object.xml | 197 ++++++++++++++++++++++++++++++++++++++++++------- 1 file changed, 170 insertions(+), 27 deletions(-) (limited to 'doc/classes') diff --git a/doc/classes/Object.xml b/doc/classes/Object.xml index 8ae82e4c48..bf15f96291 100644 --- a/doc/classes/Object.xml +++ b/doc/classes/Object.xml @@ -34,7 +34,8 @@ Override this method to customize the behavior of [method get]. Should return the given [param property]'s value, or [code]null[/code] if the [param property] should be handled normally. Combined with [method _set] and [method _get_property_list], this method allows defining custom properties, which is particularly useful for editor plugins. Note that a property must be present in [method get_property_list], otherwise this method will not be called. - [codeblock] + [codeblocks] + [gdscript] func _get(property): if (property == "fake_property"): print("Getting my property!") @@ -44,7 +45,31 @@ return [ { "name": "fake_property", "type": TYPE_INT } ] - [/codeblock] + [/gdscript] + [csharp] + public override Variant _Get(StringName property) + { + if (property == "FakeProperty") + { + GD.Print("Getting my property!"); + return 4; + } + return default; + } + + public override Godot.Collections.Array<Godot.Collections.Dictionary> _GetPropertyList() + { + return new Godot.Collections.Array<Godot.Collections.Dictionary>() + { + new Godot.Collections.Dictionary() + { + { "name", "FakeProperty" }, + { "type", (int)Variant.Type.Int } + } + }; + } + [/csharp] + [/codeblocks] @@ -53,7 +78,8 @@ Override this method to customize how script properties should be handled by the engine. Should return a property list, as an [Array] of dictionaries. The result is added to the array of [method get_property_list], and should be formatted in the same way. Each [Dictionary] must at least contain the [code]name[/code] and [code]type[/code] entries. The example below displays [code]hammer_type[/code] in the Inspector dock, only if [code]holding_hammer[/code] is [code]true[/code]: - [codeblock] + [codeblocks] + [gdscript] @tool extends Node2D @@ -80,7 +106,51 @@ }) return properties - [/codeblock] + [/gdscript] + [csharp] + [Tool] + public class MyNode2D : Node2D + { + private bool _holdingHammer; + + [Export] + public bool HoldingHammer + { + get => _holdingHammer; + set + { + _holdingHammer = value; + NotifyPropertyListChanged(); + } + } + + public int HammerType { get; set; } + + public override Godot.Collections.Array<Godot.Collections.Dictionary> _GetPropertyList() + { + // By default, `HammerType` is not visible in the editor. + var propertyUsage = PropertyUsageFlags.NoEditor; + + if (HoldingHammer) + { + propertyUsage = PropertyUsageFlags.Default; + } + + var properties = new Godot.Collections.Array<Godot.Collections.Dictionary>(); + properties.Add(new Godot.Collections.Dictionary() + { + { "name", "HammerType" }, + { "type", (int)Variant.Type.Int }, + { "usage", (int)propertyUsage }, // See above assignment. + { "hint", (int)PropertyHint.Enum }, + { "hint_string", "Wooden,Iron,Golden,Enchanted" } + }); + + return properties; + } + } + [/csharp] + [/codeblocks] [b]Note:[/b] This method is intended for advanced purposes. For most common use cases, the scripting languages offer easier ways to handle properties. See [annotation @GDScript.@export], [annotation @GDScript.@export_enum], [annotation @GDScript.@export_group], etc. [b]Note:[/b] If the object's script is not [annotation @GDScript.@tool], this method will not be called in the editor. @@ -97,11 +167,22 @@ Called when the object receives a notification, which can be identified in [param what] by comparing it with a constant. See also [method notification]. - [codeblock] + [codeblocks] + [gdscript] func _notification(what): if what == NOTIFICATION_PREDELETE: print("Goodbye!") - [/codeblock] + [/gdscript] + [csharp] + public override void _Notification(long what) + { + if (what == NotificationPredelete) + { + GD.Print("Goodbye!"); + } + } + [/csharp] + [/codeblocks] [b]Note:[/b] The base [Object] defines a few notifications ([constant NOTIFICATION_POSTINITIALIZE] and [constant NOTIFICATION_PREDELETE]). Inheriting classes such as [Node] define a lot more notifications, which are also received by this method. @@ -128,7 +209,8 @@ Override this method to customize the behavior of [method set]. Should set the [param property] to [param value] and return [code]true[/code], or [code]false[/code] if the [param property] should be handled normally. The [i]exact[/i] way to set the [param property] is up to this method's implementation. Combined with [method _get] and [method _get_property_list], this method allows defining custom properties, which is particularly useful for editor plugins. Note that a property [i]must[/i] be present in [method get_property_list], otherwise this method will not be called. - [codeblock] + [codeblocks] + [gdscript] func _set(property, value): if (property == "fake_property"): print("Setting my property to ", value) @@ -137,7 +219,32 @@ return [ { "name": "fake_property", "type": TYPE_INT } ] - [/codeblock] + [/gdscript] + [csharp] + public override void _Set(StringName property, Variant value) + { + if (property == "FakeProperty") + { + GD.Print($"Setting my property to {value}"); + return true; + } + + return false; + } + + public override Godot.Collections.Array<Godot.Collections.Dictionary> _GetPropertyList() + { + return new Godot.Collections.Array<Godot.Collections.Dictionary>() + { + new Godot.Collections.Dictionary() + { + { "name", "FakeProperty" }, + { "type", (int)Variant.Type.Int } + } + }; + } + [/csharp] + [/codeblocks] @@ -160,12 +267,29 @@ Adds a user-defined [param signal]. Optional arguments for the signal can be added as an [Array] of dictionaries, each defining a [code]name[/code] [String] and a [code]type[/code] [int] (see [enum Variant.Type]). See also [method has_user_signal]. - [codeblock] + [codeblocks] + [gdscript] add_user_signal("hurt", [ { "name": "damage", "type": TYPE_INT }, { "name": "source", "type": TYPE_OBJECT } ]) - [/codeblock] + [/gdscript] + [csharp] + AddUserSignal("Hurt", new Godot.Collections.Array() + { + new Godot.Collections.Dictionary() + { + { "name", "damage" }, + { "type", (int)Variant.Type.Int } + }, + new Godot.Collections.Dictionary() + { + { "name", "source" }, + { "type", (int)Variant.Type.Object } + } + }); + [/csharp] + [/codeblocks] @@ -183,7 +307,7 @@ node.Call("rotate", new Vector3(1f, 0f, 0f), 1.571f); [/csharp] [/codeblocks] - [b]Note:[/b] In C#, [param method] must be in snake_case when referring to built-in Godot methods. + [b]Note:[/b] In C#, [param method] must be in snake_case when referring to built-in Godot methods. Prefer using the names exposed in the [code]MethodName[/code] class to avoid allocating a new [StringName] on each call. @@ -201,7 +325,7 @@ node.CallDeferred("rotate", new Vector3(1f, 0f, 0f), 1.571f); [/csharp] [/codeblocks] - [b]Note:[/b] In C#, [param method] must be in snake_case when referring to built-in Godot methods. + [b]Note:[/b] In C#, [param method] must be in snake_case when referring to built-in Godot methods. Prefer using the names exposed in the [code]MethodName[/code] class to avoid allocating a new [StringName] on each call. @@ -220,7 +344,7 @@ node.Callv("rotate", new Godot.Collections.Array { new Vector3(1f, 0f, 0f), 1.571f }); [/csharp] [/codeblocks] - [b]Note:[/b] In C#, [param method] must be in snake_case when referring to built-in Godot methods. + [b]Note:[/b] In C#, [param method] must be in snake_case when referring to built-in Godot methods. Prefer using the names exposed in the [code]MethodName[/code] class to avoid allocating a new [StringName] on each call @@ -387,10 +511,11 @@ emit_signal("game_over") [/gdscript] [csharp] - EmitSignal("hit", "sword", 100); - EmitSignal("game_over"); + EmitSignal("Hit", "sword", 100); + EmitSignal("GameOver"); [/csharp] [/codeblocks] + [b]Note:[/b] In C#, [param signal] must be in snake_case when referring to built-in Godot signals. Prefer using the names exposed in the [code]SignalName[/code] class to avoid allocating a new [StringName] on each call. @@ -416,7 +541,7 @@ var a = node.Get("rotation"); // a is 1.5 [/csharp] [/codeblocks] - [b]Note:[/b] In C#, [param property] must be in snake_case when referring to built-in Godot properties. + [b]Note:[/b] In C#, [param property] must be in snake_case when referring to built-in Godot properties. Prefer using the names exposed in the [code]PropertyName[/code] class to avoid allocating a new [StringName] on each call. @@ -451,8 +576,8 @@ [csharp] var node = new Node2D(); node.Position = new Vector2(5, -10); - var a = node.GetIndexed("position"); # a is Vector2(5, -10) - var b = node.GetIndexed("position:y"); # b is -10 + var a = node.GetIndexed("position"); // a is Vector2(5, -10) + var b = node.GetIndexed("position:y"); // b is -10 [/csharp] [/codeblocks] [b]Note:[/b] In C#, [param property_path] must be in snake_case when referring to built-in Godot properties. @@ -541,6 +666,7 @@ Returns [code]true[/code] if the the given [param method] name exists in the object. + [b]Note:[/b] In C#, [param method] must be in snake_case when referring to built-in Godot methods. Prefer using the names exposed in the [code]MethodName[/code] class to avoid allocating a new [StringName] on each call. @@ -548,6 +674,7 @@ Returns [code]true[/code] if the given [param signal] name exists in the object. + [b]Note:[/b] In C#, [param signal] must be in snake_case when referring to built-in Godot methods. Prefer using the names exposed in the [code]SignalName[/code] class to avoid allocating a new [StringName] on each call. @@ -577,9 +704,9 @@ [/gdscript] [csharp] var sprite2d = new Sprite2D(); - sprite2d.IsClass("Sprite2D") // Returns true - sprite2d.IsClass("Node") // Returns true - sprite2d.IsClass("Node3D") // Returns false + sprite2d.IsClass("Sprite2D"); // Returns true + sprite2d.IsClass("Node"); // Returns true + sprite2d.IsClass("Node3D"); // Returns false [/csharp] [/codeblocks] [b]Note:[/b] This method ignores [code]class_name[/code] declarations in the object's script. @@ -591,6 +718,7 @@ Returns [code]true[/code] if a connection exists between the given [param signal] name and [param callable]. + [b]Note:[/b] In C#, [param signal] must be in snake_case when referring to built-in Godot methods. Prefer using the names exposed in the [code]SignalName[/code] class to avoid allocating a new [StringName] on each call. @@ -606,7 +734,8 @@ Sends the given [param what] notification to all classes inherited by the object, triggering calls to [method _notification], starting from the highest ancestor (the [Object] class) and going down to the object's script. If [param reversed] is [code]true[/code], the call order is reversed. - [codeblock] + [codeblocks] + [gdscript] var player = Node2D.new() player.set_script(load("res://player.gd")) @@ -615,7 +744,18 @@ player.notification(NOTIFICATION_ENTER_TREE, true) # The call order is player.gd -> Node2D -> Node -> Object. - [/codeblock] + [/gdscript] + [csharp] + var player = new Node2D(); + player.SetScript(GD.Load("res://player.gd")); + + player.Notification(NotificationEnterTree); + // The call order is Object -> Node -> Node2D -> player.gd. + + player.notification(NotificationEnterTree, true); + // The call order is player.gd -> Node2D -> Node -> Object. + [/csharp] + [/codeblocks] @@ -647,10 +787,10 @@ [csharp] var node = new Node2D(); node.Set("global_scale", new Vector2(8, 2.5)); - GD.Print(node.GlobalScale); # Prints Vector2(8, 2.5) + GD.Print(node.GlobalScale); // Prints Vector2(8, 2.5) [/csharp] [/codeblocks] - [b]Note:[/b] In C#, [param property] must be in snake_case when referring to built-in Godot properties. + [b]Note:[/b] In C#, [param property] must be in snake_case when referring to built-in Godot properties. Prefer using the names exposed in the [code]PropertyName[/code] class to avoid allocating a new [StringName] on each call. @@ -682,10 +822,13 @@ var node = new Node2D(); node.Rotation = 45f; node.SetDeferred("rotation", 90f); - GD.Print(node.Rotation); # Prints 45f; + GD.Print(node.Rotation); // Prints 45.0 + + await ToSignal(GetTree(), SceneTree.SignalName.ProcessFrame); + GD.Print(node.Rotation); // Prints 90.0 [/csharp] [/codeblocks] - [b]Note:[/b] In C#, [param property] must be in snake_case when referring to built-in Godot properties. + [b]Note:[/b] In C#, [param property] must be in snake_case when referring to built-in Godot properties. Prefer using the names exposed in the [code]PropertyName[/code] class to avoid allocating a new [StringName] on each call. -- cgit v1.2.3