godot-docs/classes/class_signal.rst

:github_url: hide

.. DO NOT EDIT THIS FILE!!!
.. Generated automatically from Godot engine sources.
.. Generator: https://github.com/godotengine/godot/tree/master/doc/tools/make_rst.py.
.. XML source: https://github.com/godotengine/godot/tree/master/doc/classes/Signal.xml.

.. _class_Signal:

Signal
======

A built-in type representing a signal of an :ref:`Object<class_Object>`.

.. rst-class:: classref-introduction-group

Description
-----------

**Signal** is a built-in :ref:`Variant<class_Variant>` type that represents a signal of an :ref:`Object<class_Object>` instance. Like all :ref:`Variant<class_Variant>` types, it can be stored in variables and passed to functions. Signals allow all connected :ref:`Callable<class_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 ``signal`` keyword. In C#, you may use the ``[Signal]`` attribute on a delegate.


.. tabs::

 .. code-tab:: gdscript

    signal attacked
    
    # Additional arguments may be declared.
    # These arguments must be passed when the signal is emitted.
    signal item_dropped(item_name, amount)

 .. code-tab:: 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);



.. note::

	There are notable differences when using this API with C#. See :ref:`doc_c_sharp_differences` for more information.

.. rst-class:: classref-introduction-group

Tutorials
---------

- :doc:`Using Signals <../getting_started/step_by_step/signals>`

- `GDScript Basics <../tutorials/scripting/gdscript/gdscript_basics.html#signals>`__

.. rst-class:: classref-reftable-group

Constructors
------------

.. table::
   :widths: auto

   +-----------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+
   | :ref:`Signal<class_Signal>` | :ref:`Signal<class_Signal_constructor_Signal>` **(** **)**                                                                                |
   +-----------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+
   | :ref:`Signal<class_Signal>` | :ref:`Signal<class_Signal_constructor_Signal>` **(** :ref:`Signal<class_Signal>` from **)**                                               |
   +-----------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+
   | :ref:`Signal<class_Signal>` | :ref:`Signal<class_Signal_constructor_Signal>` **(** :ref:`Object<class_Object>` object, :ref:`StringName<class_StringName>` signal **)** |
   +-----------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+

.. rst-class:: classref-reftable-group

Methods
-------

.. table::
   :widths: auto

   +-------------------------------------+---------------------------------------------------------------------------------------------------------------------------------+
   | :ref:`int<class_int>`               | :ref:`connect<class_Signal_method_connect>` **(** :ref:`Callable<class_Callable>` callable, :ref:`int<class_int>` flags=0 **)** |
   +-------------------------------------+---------------------------------------------------------------------------------------------------------------------------------+
   | void                                | :ref:`disconnect<class_Signal_method_disconnect>` **(** :ref:`Callable<class_Callable>` callable **)**                          |
   +-------------------------------------+---------------------------------------------------------------------------------------------------------------------------------+
   | void                                | :ref:`emit<class_Signal_method_emit>` **(** ... **)** |vararg| |const|                                                          |
   +-------------------------------------+---------------------------------------------------------------------------------------------------------------------------------+
   | :ref:`Array<class_Array>`           | :ref:`get_connections<class_Signal_method_get_connections>` **(** **)** |const|                                                 |
   +-------------------------------------+---------------------------------------------------------------------------------------------------------------------------------+
   | :ref:`StringName<class_StringName>` | :ref:`get_name<class_Signal_method_get_name>` **(** **)** |const|                                                               |
   +-------------------------------------+---------------------------------------------------------------------------------------------------------------------------------+
   | :ref:`Object<class_Object>`         | :ref:`get_object<class_Signal_method_get_object>` **(** **)** |const|                                                           |
   +-------------------------------------+---------------------------------------------------------------------------------------------------------------------------------+
   | :ref:`int<class_int>`               | :ref:`get_object_id<class_Signal_method_get_object_id>` **(** **)** |const|                                                     |
   +-------------------------------------+---------------------------------------------------------------------------------------------------------------------------------+
   | :ref:`bool<class_bool>`             | :ref:`is_connected<class_Signal_method_is_connected>` **(** :ref:`Callable<class_Callable>` callable **)** |const|              |
   +-------------------------------------+---------------------------------------------------------------------------------------------------------------------------------+
   | :ref:`bool<class_bool>`             | :ref:`is_null<class_Signal_method_is_null>` **(** **)** |const|                                                                 |
   +-------------------------------------+---------------------------------------------------------------------------------------------------------------------------------+

.. rst-class:: classref-reftable-group

Operators
---------

.. table::
   :widths: auto

   +-------------------------+----------------------------------------------------------------------------------------------------+
   | :ref:`bool<class_bool>` | :ref:`operator !=<class_Signal_operator_neq_Signal>` **(** :ref:`Signal<class_Signal>` right **)** |
   +-------------------------+----------------------------------------------------------------------------------------------------+
   | :ref:`bool<class_bool>` | :ref:`operator ==<class_Signal_operator_eq_Signal>` **(** :ref:`Signal<class_Signal>` right **)**  |
   +-------------------------+----------------------------------------------------------------------------------------------------+

.. rst-class:: classref-section-separator

----

.. rst-class:: classref-descriptions-group

Constructor Descriptions
------------------------

.. _class_Signal_constructor_Signal:

.. rst-class:: classref-constructor

:ref:`Signal<class_Signal>` **Signal** **(** **)**

Constructs an empty **Signal** with no object nor signal name bound.

.. rst-class:: classref-item-separator

----

.. rst-class:: classref-constructor

:ref:`Signal<class_Signal>` **Signal** **(** :ref:`Signal<class_Signal>` from **)**

Constructs a **Signal** as a copy of the given **Signal**.

.. rst-class:: classref-item-separator

----

.. rst-class:: classref-constructor

:ref:`Signal<class_Signal>` **Signal** **(** :ref:`Object<class_Object>` object, :ref:`StringName<class_StringName>` signal **)**

Creates a new **Signal** named ``signal`` in the specified ``object``.

.. rst-class:: classref-section-separator

----

.. rst-class:: classref-descriptions-group

Method Descriptions
-------------------

.. _class_Signal_method_connect:

.. rst-class:: classref-method

:ref:`int<class_int>` **connect** **(** :ref:`Callable<class_Callable>` callable, :ref:`int<class_int>` flags=0 **)**

Connects this signal to the specified ``callable``. Optional ``flags`` can be also added to configure the connection's behavior (see :ref:`ConnectFlags<enum_Object_ConnectFlags>` constants). You can provide additional arguments to the connected ``callable`` by using :ref:`Callable.bind<class_Callable_method_bind>`.

A signal can only be connected once to the same :ref:`Callable<class_Callable>`. If the signal is already connected, returns :ref:`@GlobalScope.ERR_INVALID_PARAMETER<class_@GlobalScope_constant_ERR_INVALID_PARAMETER>` and pushes an error message, unless the signal is connected with :ref:`Object.CONNECT_REFERENCE_COUNTED<class_Object_constant_CONNECT_REFERENCE_COUNTED>`. To prevent this, use :ref:`is_connected<class_Signal_method_is_connected>` first to check for existing connections.

::

    for button in $Buttons.get_children():
        button.pressed.connect(_on_pressed.bind(button))
    
    func _on_pressed(button):
        print(button.name, " was pressed")

.. rst-class:: classref-item-separator

----

.. _class_Signal_method_disconnect:

.. rst-class:: classref-method

void **disconnect** **(** :ref:`Callable<class_Callable>` callable **)**

Disconnects this signal from the specified :ref:`Callable<class_Callable>`. If the connection does not exist, generates an error. Use :ref:`is_connected<class_Signal_method_is_connected>` to make sure that the connection exists.

.. rst-class:: classref-item-separator

----

.. _class_Signal_method_emit:

.. rst-class:: classref-method

void **emit** **(** ... **)** |vararg| |const|

Emits this signal. All :ref:`Callable<class_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.

.. rst-class:: classref-item-separator

----

.. _class_Signal_method_get_connections:

.. rst-class:: classref-method

:ref:`Array<class_Array>` **get_connections** **(** **)** |const|

Returns an :ref:`Array<class_Array>` of connections for this signal. Each connection is represented as a :ref:`Dictionary<class_Dictionary>` that contains three entries:

- ``signal`` is a reference to this signal;

- ``callable`` is a reference to the connected :ref:`Callable<class_Callable>`;

- ``flags`` is a combination of :ref:`ConnectFlags<enum_Object_ConnectFlags>`.

.. rst-class:: classref-item-separator

----

.. _class_Signal_method_get_name:

.. rst-class:: classref-method

:ref:`StringName<class_StringName>` **get_name** **(** **)** |const|

Returns the name of this signal.

.. rst-class:: classref-item-separator

----

.. _class_Signal_method_get_object:

.. rst-class:: classref-method

:ref:`Object<class_Object>` **get_object** **(** **)** |const|

Returns the object emitting this signal.

.. rst-class:: classref-item-separator

----

.. _class_Signal_method_get_object_id:

.. rst-class:: classref-method

:ref:`int<class_int>` **get_object_id** **(** **)** |const|

Returns the ID of the object emitting this signal (see :ref:`Object.get_instance_id<class_Object_method_get_instance_id>`).

.. rst-class:: classref-item-separator

----

.. _class_Signal_method_is_connected:

.. rst-class:: classref-method

:ref:`bool<class_bool>` **is_connected** **(** :ref:`Callable<class_Callable>` callable **)** |const|

Returns ``true`` if the specified :ref:`Callable<class_Callable>` is connected to this signal.

.. rst-class:: classref-item-separator

----

.. _class_Signal_method_is_null:

.. rst-class:: classref-method

:ref:`bool<class_bool>` **is_null** **(** **)** |const|

Returns ``true`` if the signal's name does not exist in its object, or the object is not valid.

.. rst-class:: classref-section-separator

----

.. rst-class:: classref-descriptions-group

Operator Descriptions
---------------------

.. _class_Signal_operator_neq_Signal:

.. rst-class:: classref-operator

:ref:`bool<class_bool>` **operator !=** **(** :ref:`Signal<class_Signal>` right **)**

Returns ``true`` if the signals do not share the same object and name.

.. rst-class:: classref-item-separator

----

.. _class_Signal_operator_eq_Signal:

.. rst-class:: classref-operator

:ref:`bool<class_bool>` **operator ==** **(** :ref:`Signal<class_Signal>` right **)**

Returns ``true`` if both signals share the same object and name.

.. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)`
.. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)`
.. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)`
.. |constructor| replace:: :abbr:`constructor (This method is used to construct a type.)`
.. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)`
.. |operator| replace:: :abbr:`operator (This method describes a valid operator to use with this type as left-hand operand.)`
.. |bitfield| replace:: :abbr:`BitField (This value is an integer composed as a bitmask of the following flags.)`