Update C# signal documentation and remove bind array

- Updates C# signal documentation and code examples to the new API in 4.0
- Replace all `nameof` usages with the exposed `StringName`
This commit is contained in:
Raul Santos 2022-08-26 16:21:45 +02:00
parent 1f22c482e1
commit 92e4b4e888
No known key found for this signature in database
GPG key ID: B532473AE3A803E4
9 changed files with 48 additions and 50 deletions

View file

@ -18,17 +18,19 @@
callable.call("invalid") # Invalid call, should have at least 2 arguments. callable.call("invalid") # Invalid call, should have at least 2 arguments.
[/gdscript] [/gdscript]
[csharp] [csharp]
public void PrintArgs(object arg1, object arg2, object arg3 = null) // Default parameter values are not supported.
public void PrintArgs(Variant arg1, Variant arg2, Variant arg3 = default)
{ {
GD.PrintS(arg1, arg2, arg3); GD.PrintS(arg1, arg2, arg3);
} }
public void Test() public void Test()
{ {
Callable callable = new Callable(this, nameof(PrintArgs)); // Invalid calls fail silently.
callable.Call("hello", "world"); // Prints "hello world null". Callable callable = new Callable(this, MethodName.PrintArgs);
callable.Call("hello", "world"); // Default parameter values are not supported, should have 3 arguments.
callable.Call(Vector2.Up, 42, callable); // Prints "(0, -1) 42 Node(Node.cs)::PrintArgs". callable.Call(Vector2.Up, 42, callable); // Prints "(0, -1) 42 Node(Node.cs)::PrintArgs".
callable.Call("invalid"); // Invalid call, should have at least 2 arguments. callable.Call("invalid"); // Invalid call, should have 3 arguments.
} }
[/csharp] [/csharp]
[/codeblocks] [/codeblocks]

View file

@ -16,7 +16,7 @@
[csharp] [csharp]
EditorCommandPalette commandPalette = GetEditorInterface().GetCommandPalette(); EditorCommandPalette commandPalette = GetEditorInterface().GetCommandPalette();
// ExternalCommand is a function that will be called with the command is executed. // ExternalCommand is a function that will be called with the command is executed.
Callable commandCallable = new Callable(this, nameof(ExternalCommand)); Callable commandCallable = new Callable(this, MethodName.ExternalCommand);
commandPalette.AddCommand("command", "test/command", commandCallable) commandPalette.AddCommand("command", "test/command", commandCallable)
[/csharp] [/csharp]
[/codeblocks] [/codeblocks]

View file

@ -28,7 +28,7 @@
public override void _Ready() public override void _Ready()
{ {
GetNode("LineEdit").TextSubmitted += OnTextEntered; GetNode<LineEdit>("LineEdit").TextSubmitted += OnTextEntered;
} }
private void OnTextEntered(string command) private void OnTextEntered(string command)

View file

@ -69,7 +69,7 @@
} }
// Called when the HTTP request is completed. // Called when the HTTP request is completed.
private void HttpRequestCompleted(int result, int response_code, string[] headers, byte[] body) private void HttpRequestCompleted(int result, int responseCode, string[] headers, byte[] body)
{ {
var json = new JSON(); var json = new JSON();
json.Parse(body.GetStringFromUTF8()); json.Parse(body.GetStringFromUTF8());
@ -128,7 +128,7 @@
} }
// Called when the HTTP request is completed. // Called when the HTTP request is completed.
private void HttpRequestCompleted(int result, int response_code, string[] headers, byte[] body) private void HttpRequestCompleted(int result, int responseCode, string[] headers, byte[] body)
{ {
if (result != (int)HTTPRequest.Result.Success) if (result != (int)HTTPRequest.Result.Success)
{ {

View file

@ -305,7 +305,7 @@
[/gdscript] [/gdscript]
[csharp] [csharp]
var node = new Node3D(); var node = new Node3D();
node.Call("rotate", new Vector3(1f, 0f, 0f), 1.571f); node.Call(Node3D.MethodName.Rotate, new Vector3(1f, 0f, 0f), 1.571f);
[/csharp] [/csharp]
[/codeblocks] [/codeblocks]
[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. [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.
@ -323,7 +323,7 @@
[/gdscript] [/gdscript]
[csharp] [csharp]
var node = new Node3D(); var node = new Node3D();
node.CallDeferred("rotate", new Vector3(1f, 0f, 0f), 1.571f); node.CallDeferred(Node3D.MethodName.Rotate, new Vector3(1f, 0f, 0f), 1.571f);
[/csharp] [/csharp]
[/codeblocks] [/codeblocks]
[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. [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.
@ -342,7 +342,7 @@
[/gdscript] [/gdscript]
[csharp] [csharp]
var node = new Node3D(); var node = new Node3D();
node.Callv("rotate", new Godot.Collections.Array { new Vector3(1f, 0f, 0f), 1.571f }); node.Callv(Node3D.MethodName.Rotate, new Godot.Collections.Array { new Vector3(1f, 0f, 0f), 1.571f });
[/csharp] [/csharp]
[/codeblocks] [/codeblocks]
[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 [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
@ -394,8 +394,8 @@
// This assumes that a `Player` class exists, which defines a `Hit` signal. // This assumes that a `Player` class exists, which defines a `Hit` signal.
var player = new Player(); var player = new Player();
// Signals as events (`player.Hit += OnPlayerHit;`) do not support argument binding. You have to use: // We can use lambdas when we need to bind additional parameters.
player.Hit.Connect(OnPlayerHit, new Godot.Collections.Array {"sword", 100 }); player.Hit += () => OnPlayerHit("sword", 100);
} }
private void OnButtonDown() private void OnButtonDown()
@ -405,7 +405,7 @@
private void OnPlayerHit(string weaponType, int damage) private void OnPlayerHit(string weaponType, int damage)
{ {
GD.Print(String.Format("Hit with weapon {0} for {1} damage.", weaponType, damage)); GD.Print($"Hit with weapon {weaponType} for {damage} damage.");
} }
[/csharp] [/csharp]
[/codeblocks] [/codeblocks]
@ -431,16 +431,12 @@
public override void _Ready() public override void _Ready()
{ {
var button = new Button(); var button = new Button();
// Option 1: Object.Connect() with an implicit Callable for the defined function. // Option 1: In C#, we can use signals as events and connect with this idiomatic syntax:
button.Connect("button_down", OnButtonDown);
// Option 2: Object.connect() with a constructed Callable using a target object and method name.
button.Connect("button_down", new Callable(self, nameof(OnButtonDown)));
// Option 3: Signal.connect() with an implicit Callable for the defined function.
button.ButtonDown.Connect(OnButtonDown);
// Option 3b: In C#, we can use signals as events and connect with this more idiomatic syntax:
button.ButtonDown += OnButtonDown; button.ButtonDown += OnButtonDown;
// Option 4: Signal.connect() with a constructed Callable using a target object and method name. // Option 2: Object.Connect() with a constructed Callable from a method group.
button.ButtonDown.Connect(new Callable(self, nameof(OnButtonDown))); button.Connect(Button.SignalName.ButtonDown, Callable.From(OnButtonDown));
// Option 3: Object.Connect() with a constructed Callable using a target object and method name.
button.Connect(Button.SignalName.ButtonDown, new Callable(this, MethodName.OnButtonDown));
} }
private void OnButtonDown() private void OnButtonDown()
@ -458,6 +454,7 @@
func _ready(): func _ready():
# This assumes that a `Player` class exists, which defines a `hit` signal. # This assumes that a `Player` class exists, which defines a `hit` signal.
var player = Player.new() var player = Player.new()
# Using Callable.bind().
player.hit.connect(_on_player_hit.bind("sword", 100)) player.hit.connect(_on_player_hit.bind("sword", 100))
# Parameters added when emitting the signal are passed first. # Parameters added when emitting the signal are passed first.
@ -473,20 +470,19 @@
{ {
// This assumes that a `Player` class exists, which defines a `Hit` signal. // This assumes that a `Player` class exists, which defines a `Hit` signal.
var player = new Player(); var player = new Player();
// Option 1: Using Callable.Bind(). This way we can still use signals as events. // Using lambda expressions that create a closure that captures the additional parameters.
player.Hit += OnPlayerHit.Bind("sword", 100); // The lambda only receives the parameters defined by the signal's delegate.
// Option 2: Using a `binds` Array in Signal.Connect(). player.Hit += (hitBy, level) => OnPlayerHit(hitBy, level, "sword", 100);
player.Hit.Connect(OnPlayerHit, new Godot.Collections.Array{ "sword", 100 });
// Parameters added when emitting the signal are passed first. // Parameters added when emitting the signal are passed first.
player.EmitSignal("hit", "Dark lord", 5); player.EmitSignal(SignalName.Hit, "Dark lord", 5);
} }
// We pass two arguments when emitting (`hit_by`, `level`), // We pass two arguments when emitting (`hit_by`, `level`),
// and bind two more arguments when connecting (`weapon_type`, `damage`). // and bind two more arguments when connecting (`weapon_type`, `damage`).
private void OnPlayerHit(string hitBy, int level, string weaponType, int damage) private void OnPlayerHit(string hitBy, int level, string weaponType, int damage)
{ {
GD.Print(String.Format("Hit by {0} (level {1}) with weapon {2} for {3} damage.", hitBy, level, weaponType, damage)); GD.Print($"Hit by {hitBy} (level {level}) with weapon {weaponType} for {damage} damage.");
} }
[/csharp] [/csharp]
[/codeblocks] [/codeblocks]
@ -512,8 +508,8 @@
emit_signal("game_over") emit_signal("game_over")
[/gdscript] [/gdscript]
[csharp] [csharp]
EmitSignal("Hit", "sword", 100); EmitSignal(SignalName.Hit, "sword", 100);
EmitSignal("GameOver"); EmitSignal(SignalName.GameOver);
[/csharp] [/csharp]
[/codeblocks] [/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. [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.
@ -581,7 +577,7 @@
var b = node.GetIndexed("position:y"); // b is -10 var b = node.GetIndexed("position:y"); // b is -10
[/csharp] [/csharp]
[/codeblocks] [/codeblocks]
[b]Note:[/b] In C#, [param property_path] must be in snake_case when referring to built-in Godot properties. [b]Note:[/b] In C#, [param property_path] 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.
[b]Note:[/b] This method does not support actual paths to nodes in the [SceneTree], only sub-property paths. In the context of nodes, use [method Node.get_node_and_resource] instead. [b]Note:[/b] This method does not support actual paths to nodes in the [SceneTree], only sub-property paths. In the context of nodes, use [method Node.get_node_and_resource] instead.
</description> </description>
</method> </method>
@ -868,7 +864,7 @@
GD.Print(node.Position); // Prints (42, -10) GD.Print(node.Position); // Prints (42, -10)
[/csharp] [/csharp]
[/codeblocks] [/codeblocks]
[b]Note:[/b] In C#, [param property_path] must be in snake_case when referring to built-in Godot properties. [b]Note:[/b] In C#, [param property_path] 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.
</description> </description>
</method> </method>
<method name="set_message_translation"> <method name="set_message_translation">

View file

@ -45,7 +45,7 @@
[csharp] [csharp]
public override void _Ready() public override void _Ready()
{ {
var monitorValue = new Callable(this, nameof(GetMonitorValue)); var monitorValue = new Callable(this, MethodName.GetMonitorValue);
// Adds monitor with name "MyName" to category "MyCategory". // Adds monitor with name "MyName" to category "MyCategory".
Performance.AddCustomMonitor("MyCategory/MyMonitor", monitorValue); Performance.AddCustomMonitor("MyCategory/MyMonitor", monitorValue);

View file

@ -16,12 +16,12 @@
[/gdscript] [/gdscript]
[csharp] [csharp]
[Signal] [Signal]
delegate void Attacked(); delegate void AttackedEventHandler();
// Additional arguments may be declared. // Additional arguments may be declared.
// These arguments must be passed when the signal is emitted. // These arguments must be passed when the signal is emitted.
[Signal] [Signal]
delegate void ItemDropped(itemName: string, amount: int); delegate void ItemDroppedEventHandler(string itemName, int amount);
[/csharp] [/csharp]
[/codeblocks] [/codeblocks]
</description> </description>

View file

@ -19,7 +19,7 @@
Tween tween = GetTree().CreateTween(); Tween tween = GetTree().CreateTween();
tween.TweenProperty(GetNode("Sprite"), "modulate", Colors.Red, 1.0f); tween.TweenProperty(GetNode("Sprite"), "modulate", Colors.Red, 1.0f);
tween.TweenProperty(GetNode("Sprite"), "scale", Vector2.Zero, 1.0f); tween.TweenProperty(GetNode("Sprite"), "scale", Vector2.Zero, 1.0f);
tween.TweenCallback(new Callable(GetNode("Sprite").QueueFree)); tween.TweenCallback(Callable.From(GetNode("Sprite").QueueFree));
[/csharp] [/csharp]
[/codeblocks] [/codeblocks]
This sequence will make the [code]$Sprite[/code] node turn red, then shrink, before finally calling [method Node.queue_free] to free the sprite. [Tweener]s are executed one after another by default. This behavior can be changed using [method parallel] and [method set_parallel]. This sequence will make the [code]$Sprite[/code] node turn red, then shrink, before finally calling [method Node.queue_free] to free the sprite. [Tweener]s are executed one after another by default. This behavior can be changed using [method parallel] and [method set_parallel].
@ -35,7 +35,7 @@
Tween tween = GetTree().CreateTween(); Tween tween = GetTree().CreateTween();
tween.TweenProperty(GetNode("Sprite"), "modulate", Colors.Red, 1.0f).SetTrans(Tween.TransitionType.Sine); tween.TweenProperty(GetNode("Sprite"), "modulate", Colors.Red, 1.0f).SetTrans(Tween.TransitionType.Sine);
tween.TweenProperty(GetNode("Sprite"), "scale", Vector2.Zero, 1.0f).SetTrans(Tween.TransitionType.Bounce); tween.TweenProperty(GetNode("Sprite"), "scale", Vector2.Zero, 1.0f).SetTrans(Tween.TransitionType.Bounce);
tween.TweenCallback(new Callable(GetNode("Sprite").QueueFree)); tween.TweenCallback(Callable.From(GetNode("Sprite").QueueFree));
[/csharp] [/csharp]
[/codeblocks] [/codeblocks]
Most of the [Tween] methods can be chained this way too. In the following example the [Tween] is bound to the running script's node and a default transition is set for its [Tweener]s: Most of the [Tween] methods can be chained this way too. In the following example the [Tween] is bound to the running script's node and a default transition is set for its [Tweener]s:
@ -50,7 +50,7 @@
var tween = GetTree().CreateTween().BindNode(this).SetTrans(Tween.TransitionType.Elastic); var tween = GetTree().CreateTween().BindNode(this).SetTrans(Tween.TransitionType.Elastic);
tween.TweenProperty(GetNode("Sprite"), "modulate", Colors.Red, 1.0f); tween.TweenProperty(GetNode("Sprite"), "modulate", Colors.Red, 1.0f);
tween.TweenProperty(GetNode("Sprite"), "scale", Vector2.Zero, 1.0f); tween.TweenProperty(GetNode("Sprite"), "scale", Vector2.Zero, 1.0f);
tween.TweenCallback(new Callable(GetNode("Sprite").QueueFree)); tween.TweenCallback(Callable.From(GetNode("Sprite").QueueFree));
[/csharp] [/csharp]
[/codeblocks] [/codeblocks]
Another interesting use for [Tween]s is animating arbitrary sets of objects: Another interesting use for [Tween]s is animating arbitrary sets of objects:
@ -281,7 +281,7 @@
[/gdscript] [/gdscript]
[csharp] [csharp]
Tween tween = GetTree().CreateTween().SetLoops(); Tween tween = GetTree().CreateTween().SetLoops();
tween.TweenCallback(new Callable(Shoot)).SetDelay(1.0f); tween.TweenCallback(Callable.From(Shoot)).SetDelay(1.0f);
[/csharp] [/csharp]
[/codeblocks] [/codeblocks]
[b]Example:[/b] Turning a sprite red and then blue, with 2 second delay: [b]Example:[/b] Turning a sprite red and then blue, with 2 second delay:
@ -294,8 +294,8 @@
[csharp] [csharp]
Tween tween = GetTree().CreateTween(); Tween tween = GetTree().CreateTween();
Sprite2D sprite = GetNode&lt;Sprite2D&gt;("Sprite"); Sprite2D sprite = GetNode&lt;Sprite2D&gt;("Sprite");
tween.TweenCallback(new Callable(() =&gt; sprite.Modulate = Colors.Red)).SetDelay(2.0f); tween.TweenCallback(Callable.From(() =&gt; sprite.Modulate = Colors.Red)).SetDelay(2.0f);
tween.TweenCallback(new Callable(() =&gt; sprite.Modulate = Colors.Blue)).SetDelay(2.0f); tween.TweenCallback(Callable.From(() =&gt; sprite.Modulate = Colors.Blue)).SetDelay(2.0f);
[/csharp] [/csharp]
[/codeblocks] [/codeblocks]
</description> </description>
@ -332,10 +332,10 @@
[csharp] [csharp]
Tween tween = CreateTween().SetLoops(); Tween tween = CreateTween().SetLoops();
tween.TweenProperty(GetNode("Sprite"), "position:x", 200.0f, 1.0f).AsRelative(); tween.TweenProperty(GetNode("Sprite"), "position:x", 200.0f, 1.0f).AsRelative();
tween.TweenCallback(new Callable(Jump)); tween.TweenCallback(Callable.From(Jump));
tween.TweenInterval(2.0f); tween.TweenInterval(2.0f);
tween.TweenProperty(GetNode("Sprite"), "position:x", -200.0f, 1.0f).AsRelative(); tween.TweenProperty(GetNode("Sprite"), "position:x", -200.0f, 1.0f).AsRelative();
tween.TweenCallback(new Callable(Jump)); tween.TweenCallback(Callable.From(Jump));
tween.TweenInterval(2.0f); tween.TweenInterval(2.0f);
[/csharp] [/csharp]
[/codeblocks] [/codeblocks]
@ -357,7 +357,7 @@
[/gdscript] [/gdscript]
[csharp] [csharp]
Tween tween = CreateTween(); Tween tween = CreateTween();
tween.TweenMethod(new Callable(() =&gt; LookAt(Vector3.Up)), new Vector3(-1.0f, 0.0f, -1.0f), new Vector3(1.0f, 0.0f, -1.0f), 1.0f); // The LookAt() method takes up vector as second argument. tween.TweenMethod(Callable.From(() =&gt; LookAt(Vector3.Up)), new Vector3(-1.0f, 0.0f, -1.0f), new Vector3(1.0f, 0.0f, -1.0f), 1.0f); // The LookAt() method takes up vector as second argument.
[/csharp] [/csharp]
[/codeblocks] [/codeblocks]
[b]Example:[/b] Setting the text of a [Label], using an intermediate method and after a delay: [b]Example:[/b] Setting the text of a [Label], using an intermediate method and after a delay:
@ -376,7 +376,7 @@
base._Ready(); base._Ready();
Tween tween = CreateTween(); Tween tween = CreateTween();
tween.TweenMethod(new Callable(SetLabelText), 0.0f, 10.0f, 1.0f).SetDelay(1.0f); tween.TweenMethod(Callable.From&lt;int&gt;(SetLabelText), 0.0f, 10.0f, 1.0f).SetDelay(1.0f);
} }
private void SetLabelText(int value) private void SetLabelText(int value)

View file

@ -48,10 +48,10 @@
{ {
var node = GetNode&lt;Node2D&gt;("MyNode2D"); var node = GetNode&lt;Node2D&gt;("MyNode2D");
UndoRedo.CreateAction("Move the node"); UndoRedo.CreateAction("Move the node");
UndoRedo.AddDoMethod(this, nameof(DoSomething)); UndoRedo.AddDoMethod(this, MethodName.DoSomething);
UndoRedo.AddUndoMethod(this, nameof(UndoSomething)); UndoRedo.AddUndoMethod(this, MethodName.UndoSomething);
UndoRedo.AddDoProperty(node, "position", new Vector2(100, 100)); UndoRedo.AddDoProperty(node, Node2D.PropertyName.Position, new Vector2(100, 100));
UndoRedo.AddUndoProperty(node, "position", node.Position); UndoRedo.AddUndoProperty(node, Node2D.PropertyName.Position, node.Position);
UndoRedo.CommitAction(); UndoRedo.CommitAction();
} }
[/csharp] [/csharp]