godotengine/godot-docs
1
0
Fork 0
mirror of https://github.com/godotengine/godot-docs.git synced 2026-01-05 22:09:56 +03:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #8812 from 31/dev/31/signal-connect

Browse Source 
Elaborate on C# Connect/Disconnect
This commit is contained in:
Matthew
2024-01-22 18:34:06 -05:00
committed by GitHub
parent d847e2711e 6a6cdf94eb
commit 829619ecf8
2 changed files with 79 additions and 4 deletions
Download Patch File Download Diff File Expand all files Collapse all files

46
tutorials/scripting/c_sharp/c_sharp_signals.rst
View File

@@ -6,8 +6,14 @@ C# signals
For a detailed explanation of signals in general, see the :ref:`doc_signals` section in the step
by step tutorial.
While it is still possible to use signals through the ``Connect``/``Disconnect`` API, C# gives us
a more idiomatic way to implement the :ref:`observer pattern<doc_key_concepts_signals>`.
Signals are implemented using C# events, the idiomatic way to represent
:ref:`the observer pattern<doc_key_concepts_signals>` in C#. This is the
recommended way to use signals in C# and the focus of this page.
In some cases it's necessary to use the older
:ref:`Connect()<class_object_method_connect>` and
:ref:`Disconnect()<class_object_method_disconnect>` APIs.
See :ref:`using_connect_and_disconnect` for more details.
Signals as C# events
--------------------
@@ -30,8 +36,11 @@ In addition, you can always access signal names associated with a node type thro
.. warning::
While all engine signals connected as events are automatically disconnected when nodes are freed, custom
signals aren't. Meaning that: you will need to manually disconnect (using ``-=``) all the custom signals you
connected as C# events (using ``+=``).
signals connected using ``+=`` aren't. This means you will need to manually disconnect (using ``-=``)
all the custom signals you connected as C# events (using ``+=``).
An alternative to manually disconnecting using ``-=`` is to
:ref:`use Connect <using_connect_and_disconnect>` rather than ``+=``.
Custom signals as C# events
---------------------------
@@ -146,3 +155,32 @@ connecting to them or emitting them). Also, note that signals created this way w
AddUserSignal("MyCustomSignal");
EmitSignal("MyCustomSignal");
}
.. _using_connect_and_disconnect:
Using Connect and Disconnect
----------------------------
In general, it isn't recommended to use
:ref:`Connect()<class_object_method_connect>` and
:ref:`Disconnect()<class_object_method_disconnect>`. These APIs don't provide as
much type safety as the events. However, they're necessary for
:ref:`connecting to signals defined by GDScript <connecting_to_signals_cross_language>`
and passing :ref:`ConnectFlags<enum_Object_ConnectFlags>`.
In the following example, pressing the button for the first time prints
``Greetings!``. ``OneShot`` disconnects the signal, so pressing the button again
does nothing.
.. code-block:: csharp
public override void _Ready()
{
Button button = GetNode<Button>("GreetButton");
button.Connect(Button.SignalName.Pressed, Callable.From(OnButtonPressed), (uint)GodotObject.ConnectFlags.OneShot);
}
public void OnButtonPressed()
{
GD.Print("Greetings!");
}