From 4534de065f0a2164abcefa48c21d7af67f0de016 Mon Sep 17 00:00:00 2001 From: Micky Date: Sat, 5 Nov 2022 18:07:53 +0100 Subject: [PATCH] Tweak Signal Documentation - Add missing Operator and leading description - Avoid calling "Signal" an object or class. - Add more details to `connect` and `disconnect` --- doc/classes/Signal.xml | 45 ++++++++++++++++++++++++++++++------------ 1 file changed, 32 insertions(+), 13 deletions(-) diff --git a/doc/classes/Signal.xml b/doc/classes/Signal.xml index 3c98a0a0e1b..ce2d443ba77 100644 --- a/doc/classes/Signal.xml +++ b/doc/classes/Signal.xml @@ -1,11 +1,29 @@ - Class representing a signal defined in an object. + Built-in type representing a signal defined in an object. - Signals can be connected to [Callable]s and emitted. When a signal is emitted, all connected callables are called. - Usually signals are accessed as properties of objects, but it's also possible to assign them to variables and pass them around, allowing for more dynamic connections. + [Signal] is a built-in [Variant] type that represents a signal of an [Object] instance. Like all [Variant] types, it can be stored in variables and passed to functions. Signals allow all connected [Callable]s (and by extension their respective objects) to listen and react to events, without directly referencing one another. This keeps the code flexible and easier to manage. + In GDScript, signals can be declared with the [code]signal[/code] keyword. In C#, you may use the [code][Signal][/code] attribute on a delegate. + [codeblock] + [gdscript] + signal attacked + + # Additional arguments may be declared. + # These arguments must be passed when the signal is emitted. + signal item_dropped(item_name, amount) + [/gdscript] + [csharp] + [Signal] + delegate void Attacked(); + + // Additional arguments may be declared. + // These arguments must be passed when the signal is emitted. + [Signal] + delegate void ItemDropped(itemName: string, amount: int); + [/csharp] + [/codeblock] $DOCS_URL/getting_started/step_by_step/signals.html @@ -15,7 +33,7 @@ - Constructs a null [Signal] with no object nor signal name bound. + Constructs an empty [Signal] with no object nor signal name bound. @@ -30,7 +48,7 @@ - Creates a new [Signal] with the name [param signal] in the specified [param object]. + Creates a new [Signal] named [param signal] in the specified [param object]. @@ -40,12 +58,13 @@ - Connects this signal to the specified [Callable], optionally providing connection flags. You can provide additional arguments to the connected method call by using [method Callable.bind]. + Connects this signal to the specified [param callable]. Optional [param flags] can be also added to configure the connection's behavior (see [enum Object.ConnectFlags] constants). You can provide additional arguments to the connected [param callable] by using [method Callable.bind]. + A signal can only be connected once to the same [Callable]. If the signal is already connected, returns [constant ERR_INVALID_PARAMETER] and pushes an error message, unless the signal is connected with [constant Object.CONNECT_REFERENCE_COUNTED]. To prevent this, use [method is_connected] first to check for existing connections. [codeblock] for button in $Buttons.get_children(): - button.pressed.connect(on_pressed.bind(button)) + button.pressed.connect(_on_pressed.bind(button)) - func on_pressed(button): + func _on_pressed(button): print(button.name, " was pressed") [/codeblock] @@ -54,13 +73,13 @@ - Disconnects this signal from the specified [Callable]. + Disconnects this signal from the specified [Callable]. If the connection does not exist, generates an error. Use [method is_connected] to make sure that the connection exists. - Emits this signal to all connected objects. + Emits this signal. All [Callable]s connected to this signal will be triggered. This method supports a variable number of arguments, so parameters can be passed as a comma separated list. @@ -97,7 +116,7 @@ - Returns [code]true[/code] if either object or signal name are not valid. + Returns [code]true[/code] if the signal's name does not exist in its object, or the object is not valid. @@ -106,14 +125,14 @@ - Returns [code]true[/code] if two signals are not equal. + Returns [code]true[/code] if the signals do not share the same object and name. - Returns [code]true[/code] if two signals are equal, i.e. their object and name are the same. + Returns [code]true[/code] if both signals share the same object and name.