mirror of
https://github.com/godotengine/godot
synced 2024-09-05 18:19:34 +00:00
![Raul Santos](/assets/img/avatar_default.png)
- Updates C# signal documentation and code examples to the new API in 4.0 - Replace all `nameof` usages with the exposed `StringName`
140 lines
5.6 KiB
XML
140 lines
5.6 KiB
XML
<?xml version="1.0" encoding="UTF-8" ?>
|
|
<class name="Signal" version="4.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
|
|
<brief_description>
|
|
Built-in type representing a signal defined in an object.
|
|
</brief_description>
|
|
<description>
|
|
[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.
|
|
[codeblocks]
|
|
[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 AttackedEventHandler();
|
|
|
|
// Additional arguments may be declared.
|
|
// These arguments must be passed when the signal is emitted.
|
|
[Signal]
|
|
delegate void ItemDroppedEventHandler(string itemName, int amount);
|
|
[/csharp]
|
|
[/codeblocks]
|
|
</description>
|
|
<tutorials>
|
|
<link title="Using Signals">$DOCS_URL/getting_started/step_by_step/signals.html</link>
|
|
<link title="GDScript Basics">$DOCS_URL/tutorials/scripting/gdscript/gdscript_basics.html#signals</link>
|
|
</tutorials>
|
|
<constructors>
|
|
<constructor name="Signal">
|
|
<return type="Signal" />
|
|
<description>
|
|
Constructs an empty [Signal] with no object nor signal name bound.
|
|
</description>
|
|
</constructor>
|
|
<constructor name="Signal">
|
|
<return type="Signal" />
|
|
<param index="0" name="from" type="Signal" />
|
|
<description>
|
|
Constructs a [Signal] as a copy of the given [Signal].
|
|
</description>
|
|
</constructor>
|
|
<constructor name="Signal">
|
|
<return type="Signal" />
|
|
<param index="0" name="object" type="Object" />
|
|
<param index="1" name="signal" type="StringName" />
|
|
<description>
|
|
Creates a new [Signal] named [param signal] in the specified [param object].
|
|
</description>
|
|
</constructor>
|
|
</constructors>
|
|
<methods>
|
|
<method name="connect">
|
|
<return type="int" />
|
|
<param index="0" name="callable" type="Callable" />
|
|
<param index="1" name="flags" type="int" default="0" />
|
|
<description>
|
|
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))
|
|
|
|
func _on_pressed(button):
|
|
print(button.name, " was pressed")
|
|
[/codeblock]
|
|
</description>
|
|
</method>
|
|
<method name="disconnect">
|
|
<return type="void" />
|
|
<param index="0" name="callable" type="Callable" />
|
|
<description>
|
|
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.
|
|
</description>
|
|
</method>
|
|
<method name="emit" qualifiers="vararg const">
|
|
<return type="void" />
|
|
<description>
|
|
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.
|
|
</description>
|
|
</method>
|
|
<method name="get_connections" qualifiers="const">
|
|
<return type="Array" />
|
|
<description>
|
|
Returns the list of [Callable]s connected to this signal.
|
|
</description>
|
|
</method>
|
|
<method name="get_name" qualifiers="const">
|
|
<return type="StringName" />
|
|
<description>
|
|
Returns the name of this signal.
|
|
</description>
|
|
</method>
|
|
<method name="get_object" qualifiers="const">
|
|
<return type="Object" />
|
|
<description>
|
|
Returns the object emitting this signal.
|
|
</description>
|
|
</method>
|
|
<method name="get_object_id" qualifiers="const">
|
|
<return type="int" />
|
|
<description>
|
|
Returns the ID of the object emitting this signal (see [method Object.get_instance_id]).
|
|
</description>
|
|
</method>
|
|
<method name="is_connected" qualifiers="const">
|
|
<return type="bool" />
|
|
<param index="0" name="callable" type="Callable" />
|
|
<description>
|
|
Returns [code]true[/code] if the specified [Callable] is connected to this signal.
|
|
</description>
|
|
</method>
|
|
<method name="is_null" qualifiers="const">
|
|
<return type="bool" />
|
|
<description>
|
|
Returns [code]true[/code] if the signal's name does not exist in its object, or the object is not valid.
|
|
</description>
|
|
</method>
|
|
</methods>
|
|
<operators>
|
|
<operator name="operator !=">
|
|
<return type="bool" />
|
|
<param index="0" name="right" type="Signal" />
|
|
<description>
|
|
Returns [code]true[/code] if the signals do not share the same object and name.
|
|
</description>
|
|
</operator>
|
|
<operator name="operator ==">
|
|
<return type="bool" />
|
|
<param index="0" name="right" type="Signal" />
|
|
<description>
|
|
Returns [code]true[/code] if both signals share the same object and name.
|
|
</description>
|
|
</operator>
|
|
</operators>
|
|
</class>
|