mirror of
https://github.com/godotengine/godot-docs.git
synced 2026-01-03 05:48:42 +03:00
479 lines
21 KiB
ReStructuredText
479 lines
21 KiB
ReStructuredText
: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/Callable.xml.
|
|
|
|
.. _class_Callable:
|
|
|
|
Callable
|
|
========
|
|
|
|
A built-in type representing a method or a standalone function.
|
|
|
|
.. rst-class:: classref-introduction-group
|
|
|
|
Description
|
|
-----------
|
|
|
|
**Callable** is a built-in :ref:`Variant<class_Variant>` type that represents a function. It can either be a method within an :ref:`Object<class_Object>` instance, or a standalone function not related to any object, like a lambda function. Like all :ref:`Variant<class_Variant>` types, it can be stored in variables and passed to other functions. It is most commonly used for signal callbacks.
|
|
|
|
\ **Example:**\
|
|
|
|
|
|
.. tabs::
|
|
|
|
.. code-tab:: gdscript
|
|
|
|
func print_args(arg1, arg2, arg3 = ""):
|
|
prints(arg1, arg2, arg3)
|
|
|
|
func test():
|
|
var callable = Callable(self, "print_args")
|
|
callable.call("hello", "world") # Prints "hello world ".
|
|
callable.call(Vector2.UP, 42, callable) # Prints "(0, -1) 42 Node(node.gd)::print_args".
|
|
callable.call("invalid") # Invalid call, should have at least 2 arguments.
|
|
|
|
.. code-tab:: csharp
|
|
|
|
// Default parameter values are not supported.
|
|
public void PrintArgs(Variant arg1, Variant arg2, Variant arg3 = default)
|
|
{
|
|
GD.PrintS(arg1, arg2, arg3);
|
|
}
|
|
|
|
public void Test()
|
|
{
|
|
// Invalid calls fail silently.
|
|
Callable callable = new Callable(this, MethodName.PrintArgs);
|
|
callable.Call("hello", "world"); // Default parameter values are not supported, should have 3 arguments.
|
|
callable.Call(Vector2.Up, 42, callable); // Prints "(0, -1) 42 Node(Node.cs)::PrintArgs".
|
|
callable.Call("invalid"); // Invalid call, should have 3 arguments.
|
|
}
|
|
|
|
|
|
|
|
In GDScript, it's possible to create lambda functions within a method. Lambda functions are custom callables that are not associated with an :ref:`Object<class_Object>` instance. Optionally, lambda functions can also be named. The name will be displayed in the debugger, or when calling :ref:`get_method<class_Callable_method_get_method>`.
|
|
|
|
::
|
|
|
|
func _init():
|
|
var my_lambda = func (message):
|
|
print(message)
|
|
|
|
# Prints Hello everyone!
|
|
my_lambda.call("Hello everyone!")
|
|
|
|
# Prints "Attack!", when the button_pressed signal is emitted.
|
|
button_pressed.connect(func(): print("Attack!"))
|
|
|
|
.. note::
|
|
|
|
There are notable differences when using this API with C#. See :ref:`doc_c_sharp_differences` for more information.
|
|
|
|
.. rst-class:: classref-reftable-group
|
|
|
|
Constructors
|
|
------------
|
|
|
|
.. table::
|
|
:widths: auto
|
|
|
|
+---------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------+
|
|
| :ref:`Callable<class_Callable>` | :ref:`Callable<class_Callable_constructor_Callable>`\ (\ ) |
|
|
+---------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------+
|
|
| :ref:`Callable<class_Callable>` | :ref:`Callable<class_Callable_constructor_Callable>`\ (\ from\: :ref:`Callable<class_Callable>`\ ) |
|
|
+---------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------+
|
|
| :ref:`Callable<class_Callable>` | :ref:`Callable<class_Callable_constructor_Callable>`\ (\ object\: :ref:`Object<class_Object>`, method\: :ref:`StringName<class_StringName>`\ ) |
|
|
+---------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------+
|
|
|
|
.. rst-class:: classref-reftable-group
|
|
|
|
Methods
|
|
-------
|
|
|
|
.. table::
|
|
:widths: auto
|
|
|
|
+-------------------------------------+----------------------------------------------------------------------------------------------------------+
|
|
| :ref:`Callable<class_Callable>` | :ref:`bind<class_Callable_method_bind>`\ (\ ...\ ) |vararg| |const| |
|
|
+-------------------------------------+----------------------------------------------------------------------------------------------------------+
|
|
| :ref:`Callable<class_Callable>` | :ref:`bindv<class_Callable_method_bindv>`\ (\ arguments\: :ref:`Array<class_Array>`\ ) |
|
|
+-------------------------------------+----------------------------------------------------------------------------------------------------------+
|
|
| :ref:`Variant<class_Variant>` | :ref:`call<class_Callable_method_call>`\ (\ ...\ ) |vararg| |const| |
|
|
+-------------------------------------+----------------------------------------------------------------------------------------------------------+
|
|
| |void| | :ref:`call_deferred<class_Callable_method_call_deferred>`\ (\ ...\ ) |vararg| |const| |
|
|
+-------------------------------------+----------------------------------------------------------------------------------------------------------+
|
|
| :ref:`Variant<class_Variant>` | :ref:`callv<class_Callable_method_callv>`\ (\ arguments\: :ref:`Array<class_Array>`\ ) |const| |
|
|
+-------------------------------------+----------------------------------------------------------------------------------------------------------+
|
|
| :ref:`Array<class_Array>` | :ref:`get_bound_arguments<class_Callable_method_get_bound_arguments>`\ (\ ) |const| |
|
|
+-------------------------------------+----------------------------------------------------------------------------------------------------------+
|
|
| :ref:`int<class_int>` | :ref:`get_bound_arguments_count<class_Callable_method_get_bound_arguments_count>`\ (\ ) |const| |
|
|
+-------------------------------------+----------------------------------------------------------------------------------------------------------+
|
|
| :ref:`StringName<class_StringName>` | :ref:`get_method<class_Callable_method_get_method>`\ (\ ) |const| |
|
|
+-------------------------------------+----------------------------------------------------------------------------------------------------------+
|
|
| :ref:`Object<class_Object>` | :ref:`get_object<class_Callable_method_get_object>`\ (\ ) |const| |
|
|
+-------------------------------------+----------------------------------------------------------------------------------------------------------+
|
|
| :ref:`int<class_int>` | :ref:`get_object_id<class_Callable_method_get_object_id>`\ (\ ) |const| |
|
|
+-------------------------------------+----------------------------------------------------------------------------------------------------------+
|
|
| :ref:`int<class_int>` | :ref:`hash<class_Callable_method_hash>`\ (\ ) |const| |
|
|
+-------------------------------------+----------------------------------------------------------------------------------------------------------+
|
|
| :ref:`bool<class_bool>` | :ref:`is_custom<class_Callable_method_is_custom>`\ (\ ) |const| |
|
|
+-------------------------------------+----------------------------------------------------------------------------------------------------------+
|
|
| :ref:`bool<class_bool>` | :ref:`is_null<class_Callable_method_is_null>`\ (\ ) |const| |
|
|
+-------------------------------------+----------------------------------------------------------------------------------------------------------+
|
|
| :ref:`bool<class_bool>` | :ref:`is_standard<class_Callable_method_is_standard>`\ (\ ) |const| |
|
|
+-------------------------------------+----------------------------------------------------------------------------------------------------------+
|
|
| :ref:`bool<class_bool>` | :ref:`is_valid<class_Callable_method_is_valid>`\ (\ ) |const| |
|
|
+-------------------------------------+----------------------------------------------------------------------------------------------------------+
|
|
| |void| | :ref:`rpc<class_Callable_method_rpc>`\ (\ ...\ ) |vararg| |const| |
|
|
+-------------------------------------+----------------------------------------------------------------------------------------------------------+
|
|
| |void| | :ref:`rpc_id<class_Callable_method_rpc_id>`\ (\ peer_id\: :ref:`int<class_int>`, ...\ ) |vararg| |const| |
|
|
+-------------------------------------+----------------------------------------------------------------------------------------------------------+
|
|
| :ref:`Callable<class_Callable>` | :ref:`unbind<class_Callable_method_unbind>`\ (\ argcount\: :ref:`int<class_int>`\ ) |const| |
|
|
+-------------------------------------+----------------------------------------------------------------------------------------------------------+
|
|
|
|
.. rst-class:: classref-reftable-group
|
|
|
|
Operators
|
|
---------
|
|
|
|
.. table::
|
|
:widths: auto
|
|
|
|
+-------------------------+---------------------------------------------------------------------------------------------------------+
|
|
| :ref:`bool<class_bool>` | :ref:`operator !=<class_Callable_operator_neq_Callable>`\ (\ right\: :ref:`Callable<class_Callable>`\ ) |
|
|
+-------------------------+---------------------------------------------------------------------------------------------------------+
|
|
| :ref:`bool<class_bool>` | :ref:`operator ==<class_Callable_operator_eq_Callable>`\ (\ right\: :ref:`Callable<class_Callable>`\ ) |
|
|
+-------------------------+---------------------------------------------------------------------------------------------------------+
|
|
|
|
.. rst-class:: classref-section-separator
|
|
|
|
----
|
|
|
|
.. rst-class:: classref-descriptions-group
|
|
|
|
Constructor Descriptions
|
|
------------------------
|
|
|
|
.. _class_Callable_constructor_Callable:
|
|
|
|
.. rst-class:: classref-constructor
|
|
|
|
:ref:`Callable<class_Callable>` **Callable**\ (\ )
|
|
|
|
Constructs an empty **Callable**, with no object nor method bound.
|
|
|
|
.. rst-class:: classref-item-separator
|
|
|
|
----
|
|
|
|
.. rst-class:: classref-constructor
|
|
|
|
:ref:`Callable<class_Callable>` **Callable**\ (\ from\: :ref:`Callable<class_Callable>`\ )
|
|
|
|
Constructs a **Callable** as a copy of the given **Callable**.
|
|
|
|
.. rst-class:: classref-item-separator
|
|
|
|
----
|
|
|
|
.. rst-class:: classref-constructor
|
|
|
|
:ref:`Callable<class_Callable>` **Callable**\ (\ object\: :ref:`Object<class_Object>`, method\: :ref:`StringName<class_StringName>`\ )
|
|
|
|
Creates a new **Callable** for the method named ``method`` in the specified ``object``.
|
|
|
|
.. rst-class:: classref-section-separator
|
|
|
|
----
|
|
|
|
.. rst-class:: classref-descriptions-group
|
|
|
|
Method Descriptions
|
|
-------------------
|
|
|
|
.. _class_Callable_method_bind:
|
|
|
|
.. rst-class:: classref-method
|
|
|
|
:ref:`Callable<class_Callable>` **bind**\ (\ ...\ ) |vararg| |const|
|
|
|
|
Returns a copy of this **Callable** with one or more arguments bound. When called, the bound arguments are passed *after* the arguments supplied by :ref:`call<class_Callable_method_call>`. See also :ref:`unbind<class_Callable_method_unbind>`.
|
|
|
|
\ **Note:** When this method is chained with other similar methods, the order in which the argument list is modified is read from right to left.
|
|
|
|
.. rst-class:: classref-item-separator
|
|
|
|
----
|
|
|
|
.. _class_Callable_method_bindv:
|
|
|
|
.. rst-class:: classref-method
|
|
|
|
:ref:`Callable<class_Callable>` **bindv**\ (\ arguments\: :ref:`Array<class_Array>`\ )
|
|
|
|
Returns a copy of this **Callable** with one or more arguments bound, reading them from an array. When called, the bound arguments are passed *after* the arguments supplied by :ref:`call<class_Callable_method_call>`. See also :ref:`unbind<class_Callable_method_unbind>`.
|
|
|
|
\ **Note:** When this method is chained with other similar methods, the order in which the argument list is modified is read from right to left.
|
|
|
|
.. rst-class:: classref-item-separator
|
|
|
|
----
|
|
|
|
.. _class_Callable_method_call:
|
|
|
|
.. rst-class:: classref-method
|
|
|
|
:ref:`Variant<class_Variant>` **call**\ (\ ...\ ) |vararg| |const|
|
|
|
|
Calls the method represented by this **Callable**. Arguments can be passed and should match the method's signature.
|
|
|
|
.. rst-class:: classref-item-separator
|
|
|
|
----
|
|
|
|
.. _class_Callable_method_call_deferred:
|
|
|
|
.. rst-class:: classref-method
|
|
|
|
|void| **call_deferred**\ (\ ...\ ) |vararg| |const|
|
|
|
|
Calls the method represented by this **Callable** in deferred mode, i.e. at the end of the current frame. Arguments can be passed and should match the method's signature.
|
|
|
|
|
|
.. tabs::
|
|
|
|
.. code-tab:: gdscript
|
|
|
|
func _ready():
|
|
grab_focus.call_deferred()
|
|
|
|
.. code-tab:: csharp
|
|
|
|
public override void _Ready()
|
|
{
|
|
Callable.From(GrabFocus).CallDeferred();
|
|
}
|
|
|
|
|
|
|
|
See also :ref:`Object.call_deferred<class_Object_method_call_deferred>`.
|
|
|
|
.. rst-class:: classref-item-separator
|
|
|
|
----
|
|
|
|
.. _class_Callable_method_callv:
|
|
|
|
.. rst-class:: classref-method
|
|
|
|
:ref:`Variant<class_Variant>` **callv**\ (\ arguments\: :ref:`Array<class_Array>`\ ) |const|
|
|
|
|
Calls the method represented by this **Callable**. Unlike :ref:`call<class_Callable_method_call>`, this method expects all arguments to be contained inside the ``arguments`` :ref:`Array<class_Array>`.
|
|
|
|
.. rst-class:: classref-item-separator
|
|
|
|
----
|
|
|
|
.. _class_Callable_method_get_bound_arguments:
|
|
|
|
.. rst-class:: classref-method
|
|
|
|
:ref:`Array<class_Array>` **get_bound_arguments**\ (\ ) |const|
|
|
|
|
Return the bound arguments (as long as :ref:`get_bound_arguments_count<class_Callable_method_get_bound_arguments_count>` is greater than zero), or empty (if :ref:`get_bound_arguments_count<class_Callable_method_get_bound_arguments_count>` is less than or equal to zero).
|
|
|
|
.. rst-class:: classref-item-separator
|
|
|
|
----
|
|
|
|
.. _class_Callable_method_get_bound_arguments_count:
|
|
|
|
.. rst-class:: classref-method
|
|
|
|
:ref:`int<class_int>` **get_bound_arguments_count**\ (\ ) |const|
|
|
|
|
Returns the total amount of arguments bound (or unbound) via successive :ref:`bind<class_Callable_method_bind>` or :ref:`unbind<class_Callable_method_unbind>` calls. If the amount of arguments unbound is greater than the ones bound, this function returns a value less than zero.
|
|
|
|
.. rst-class:: classref-item-separator
|
|
|
|
----
|
|
|
|
.. _class_Callable_method_get_method:
|
|
|
|
.. rst-class:: classref-method
|
|
|
|
:ref:`StringName<class_StringName>` **get_method**\ (\ ) |const|
|
|
|
|
Returns the name of the method represented by this **Callable**. If the callable is a GDScript lambda function, returns the function's name or ``"<anonymous lambda>"``.
|
|
|
|
.. rst-class:: classref-item-separator
|
|
|
|
----
|
|
|
|
.. _class_Callable_method_get_object:
|
|
|
|
.. rst-class:: classref-method
|
|
|
|
:ref:`Object<class_Object>` **get_object**\ (\ ) |const|
|
|
|
|
Returns the object on which this **Callable** is called.
|
|
|
|
.. rst-class:: classref-item-separator
|
|
|
|
----
|
|
|
|
.. _class_Callable_method_get_object_id:
|
|
|
|
.. rst-class:: classref-method
|
|
|
|
:ref:`int<class_int>` **get_object_id**\ (\ ) |const|
|
|
|
|
Returns the ID of this **Callable**'s object (see :ref:`Object.get_instance_id<class_Object_method_get_instance_id>`).
|
|
|
|
.. rst-class:: classref-item-separator
|
|
|
|
----
|
|
|
|
.. _class_Callable_method_hash:
|
|
|
|
.. rst-class:: classref-method
|
|
|
|
:ref:`int<class_int>` **hash**\ (\ ) |const|
|
|
|
|
Returns the 32-bit hash value of this **Callable**'s object.
|
|
|
|
\ **Note:** **Callable**\ s with equal content will always produce identical hash values. However, the reverse is not true. Returning identical hash values does *not* imply the callables are equal, because different callables can have identical hash values due to hash collisions. The engine uses a 32-bit hash algorithm for :ref:`hash<class_Callable_method_hash>`.
|
|
|
|
.. rst-class:: classref-item-separator
|
|
|
|
----
|
|
|
|
.. _class_Callable_method_is_custom:
|
|
|
|
.. rst-class:: classref-method
|
|
|
|
:ref:`bool<class_bool>` **is_custom**\ (\ ) |const|
|
|
|
|
Returns ``true`` if this **Callable** is a custom callable. Custom callables are created from :ref:`bind<class_Callable_method_bind>` or :ref:`unbind<class_Callable_method_unbind>`. In GDScript, lambda functions are also custom callables.
|
|
|
|
.. rst-class:: classref-item-separator
|
|
|
|
----
|
|
|
|
.. _class_Callable_method_is_null:
|
|
|
|
.. rst-class:: classref-method
|
|
|
|
:ref:`bool<class_bool>` **is_null**\ (\ ) |const|
|
|
|
|
Returns ``true`` if this **Callable** has no target to call the method on.
|
|
|
|
.. rst-class:: classref-item-separator
|
|
|
|
----
|
|
|
|
.. _class_Callable_method_is_standard:
|
|
|
|
.. rst-class:: classref-method
|
|
|
|
:ref:`bool<class_bool>` **is_standard**\ (\ ) |const|
|
|
|
|
Returns ``true`` if this **Callable** is a standard callable. This method is the opposite of :ref:`is_custom<class_Callable_method_is_custom>`. Returns ``false`` if this callable is a lambda function.
|
|
|
|
.. rst-class:: classref-item-separator
|
|
|
|
----
|
|
|
|
.. _class_Callable_method_is_valid:
|
|
|
|
.. rst-class:: classref-method
|
|
|
|
:ref:`bool<class_bool>` **is_valid**\ (\ ) |const|
|
|
|
|
Returns ``true`` if the callable's object exists and has a valid method name assigned, or is a custom callable.
|
|
|
|
.. rst-class:: classref-item-separator
|
|
|
|
----
|
|
|
|
.. _class_Callable_method_rpc:
|
|
|
|
.. rst-class:: classref-method
|
|
|
|
|void| **rpc**\ (\ ...\ ) |vararg| |const|
|
|
|
|
Perform an RPC (Remote Procedure Call) on all connected peers. This is used for multiplayer and is normally not available, unless the function being called has been marked as *RPC* (using :ref:`@GDScript.@rpc<class_@GDScript_annotation_@rpc>` or :ref:`Node.rpc_config<class_Node_method_rpc_config>`). Calling this method on unsupported functions will result in an error. See :ref:`Node.rpc<class_Node_method_rpc>`.
|
|
|
|
.. rst-class:: classref-item-separator
|
|
|
|
----
|
|
|
|
.. _class_Callable_method_rpc_id:
|
|
|
|
.. rst-class:: classref-method
|
|
|
|
|void| **rpc_id**\ (\ peer_id\: :ref:`int<class_int>`, ...\ ) |vararg| |const|
|
|
|
|
Perform an RPC (Remote Procedure Call) on a specific peer ID (see multiplayer documentation for reference). This is used for multiplayer and is normally not available unless the function being called has been marked as *RPC* (using :ref:`@GDScript.@rpc<class_@GDScript_annotation_@rpc>` or :ref:`Node.rpc_config<class_Node_method_rpc_config>`). Calling this method on unsupported functions will result in an error. See :ref:`Node.rpc_id<class_Node_method_rpc_id>`.
|
|
|
|
.. rst-class:: classref-item-separator
|
|
|
|
----
|
|
|
|
.. _class_Callable_method_unbind:
|
|
|
|
.. rst-class:: classref-method
|
|
|
|
:ref:`Callable<class_Callable>` **unbind**\ (\ argcount\: :ref:`int<class_int>`\ ) |const|
|
|
|
|
Returns a copy of this **Callable** with a number of arguments unbound. In other words, when the new callable is called the last few arguments supplied by the user are ignored, according to ``argcount``. The remaining arguments are passed to the callable. This allows to use the original callable in a context that attempts to pass more arguments than this callable can handle, e.g. a signal with a fixed number of arguments. See also :ref:`bind<class_Callable_method_bind>`.
|
|
|
|
\ **Note:** When this method is chained with other similar methods, the order in which the argument list is modified is read from right to left.
|
|
|
|
::
|
|
|
|
func _ready():
|
|
foo.unbind(1).call(1, 2) # Calls foo(1).
|
|
foo.bind(3, 4).unbind(1).call(1, 2) # Calls foo(1, 3, 4), note that it does not change the arguments from bind.
|
|
|
|
.. rst-class:: classref-section-separator
|
|
|
|
----
|
|
|
|
.. rst-class:: classref-descriptions-group
|
|
|
|
Operator Descriptions
|
|
---------------------
|
|
|
|
.. _class_Callable_operator_neq_Callable:
|
|
|
|
.. rst-class:: classref-operator
|
|
|
|
:ref:`bool<class_bool>` **operator !=**\ (\ right\: :ref:`Callable<class_Callable>`\ )
|
|
|
|
Returns ``true`` if both **Callable**\ s invoke different targets.
|
|
|
|
.. rst-class:: classref-item-separator
|
|
|
|
----
|
|
|
|
.. _class_Callable_operator_eq_Callable:
|
|
|
|
.. rst-class:: classref-operator
|
|
|
|
:ref:`bool<class_bool>` **operator ==**\ (\ right\: :ref:`Callable<class_Callable>`\ )
|
|
|
|
Returns ``true`` if both **Callable**\ s invoke the same custom target.
|
|
|
|
.. |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.)`
|
|
.. |void| replace:: :abbr:`void (No return value.)`
|