diff --git a/tutorials/scripting/c_sharp/c_sharp_signals.rst b/tutorials/scripting/c_sharp/c_sharp_signals.rst index 763e4020534..8138fe1fa50 100644 --- a/tutorials/scripting/c_sharp/c_sharp_signals.rst +++ b/tutorials/scripting/c_sharp/c_sharp_signals.rst @@ -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`. +Signals are implemented using C# events, the idiomatic way to represent +:ref:`the observer pattern` 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()` and +:ref:`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 ` 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()` and +:ref:`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 ` +and passing :ref:`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