class_callable.rst 19 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444
  1. :github_url: hide
  2. .. DO NOT EDIT THIS FILE!!!
  3. .. Generated automatically from Godot engine sources.
  4. .. Generator: https://github.com/godotengine/godot/tree/master/doc/tools/make_rst.py.
  5. .. XML source: https://github.com/godotengine/godot/tree/master/doc/classes/Callable.xml.
  6. .. _class_Callable:
  7. Callable
  8. ========
  9. Built-in type representing a method in an object instance or a standalone function.
  10. .. rst-class:: classref-introduction-group
  11. Description
  12. -----------
  13. **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.
  14. \ **Example:**\
  15. .. tabs::
  16. .. code-tab:: gdscript
  17. func print_args(arg1, arg2, arg3 = ""):
  18. prints(arg1, arg2, arg3)
  19. func test():
  20. var callable = Callable(self, "print_args")
  21. callable.call("hello", "world") # Prints "hello world ".
  22. callable.call(Vector2.UP, 42, callable) # Prints "(0, -1) 42 Node(Node.gd)::print_args".
  23. callable.call("invalid") # Invalid call, should have at least 2 arguments.
  24. .. code-tab:: csharp
  25. public void PrintArgs(object arg1, object arg2, object arg3 = null)
  26. {
  27. GD.PrintS(arg1, arg2, arg3);
  28. }
  29. public void Test()
  30. {
  31. Callable callable = new Callable(this, nameof(PrintArgs));
  32. callable.Call("hello", "world"); // Prints "hello world null".
  33. callable.Call(Vector2.Up, 42, callable); // Prints "(0, -1) 42 Node(Node.cs)::PrintArgs".
  34. callable.Call("invalid"); // Invalid call, should have at least 2 arguments.
  35. }
  36. 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>`.
  37. ::
  38. func _init():
  39. var my_lambda = func (message):
  40. print(message)
  41. # Prints Hello everyone!
  42. my_lambda.call("Hello everyone!")
  43. # Prints "Attack!", when the button_pressed signal is emitted.
  44. button_pressed.connect(func(): print("Attack!"))
  45. .. rst-class:: classref-reftable-group
  46. Constructors
  47. ------------
  48. .. table::
  49. :widths: auto
  50. +---------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------+
  51. | :ref:`Callable<class_Callable>` | :ref:`Callable<class_Callable_constructor_Callable>` **(** **)** |
  52. +---------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------+
  53. | :ref:`Callable<class_Callable>` | :ref:`Callable<class_Callable_constructor_Callable>` **(** :ref:`Callable<class_Callable>` from **)** |
  54. +---------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------+
  55. | :ref:`Callable<class_Callable>` | :ref:`Callable<class_Callable_constructor_Callable>` **(** :ref:`Object<class_Object>` object, :ref:`StringName<class_StringName>` method **)** |
  56. +---------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------+
  57. .. rst-class:: classref-reftable-group
  58. Methods
  59. -------
  60. .. table::
  61. :widths: auto
  62. +-------------------------------------+-------------------------------------------------------------------------------------------------------------+
  63. | :ref:`Callable<class_Callable>` | :ref:`bind<class_Callable_method_bind>` **(** ... **)** |vararg| |const| |
  64. +-------------------------------------+-------------------------------------------------------------------------------------------------------------+
  65. | :ref:`Callable<class_Callable>` | :ref:`bindv<class_Callable_method_bindv>` **(** :ref:`Array<class_Array>` arguments **)** |
  66. +-------------------------------------+-------------------------------------------------------------------------------------------------------------+
  67. | :ref:`Variant<class_Variant>` | :ref:`call<class_Callable_method_call>` **(** ... **)** |vararg| |const| |
  68. +-------------------------------------+-------------------------------------------------------------------------------------------------------------+
  69. | void | :ref:`call_deferred<class_Callable_method_call_deferred>` **(** ... **)** |vararg| |const| |
  70. +-------------------------------------+-------------------------------------------------------------------------------------------------------------+
  71. | :ref:`Variant<class_Variant>` | :ref:`callv<class_Callable_method_callv>` **(** :ref:`Array<class_Array>` arguments **)** |const| |
  72. +-------------------------------------+-------------------------------------------------------------------------------------------------------------+
  73. | :ref:`Array<class_Array>` | :ref:`get_bound_arguments<class_Callable_method_get_bound_arguments>` **(** **)** |const| |
  74. +-------------------------------------+-------------------------------------------------------------------------------------------------------------+
  75. | :ref:`int<class_int>` | :ref:`get_bound_arguments_count<class_Callable_method_get_bound_arguments_count>` **(** **)** |const| |
  76. +-------------------------------------+-------------------------------------------------------------------------------------------------------------+
  77. | :ref:`StringName<class_StringName>` | :ref:`get_method<class_Callable_method_get_method>` **(** **)** |const| |
  78. +-------------------------------------+-------------------------------------------------------------------------------------------------------------+
  79. | :ref:`Object<class_Object>` | :ref:`get_object<class_Callable_method_get_object>` **(** **)** |const| |
  80. +-------------------------------------+-------------------------------------------------------------------------------------------------------------+
  81. | :ref:`int<class_int>` | :ref:`get_object_id<class_Callable_method_get_object_id>` **(** **)** |const| |
  82. +-------------------------------------+-------------------------------------------------------------------------------------------------------------+
  83. | :ref:`int<class_int>` | :ref:`hash<class_Callable_method_hash>` **(** **)** |const| |
  84. +-------------------------------------+-------------------------------------------------------------------------------------------------------------+
  85. | :ref:`bool<class_bool>` | :ref:`is_custom<class_Callable_method_is_custom>` **(** **)** |const| |
  86. +-------------------------------------+-------------------------------------------------------------------------------------------------------------+
  87. | :ref:`bool<class_bool>` | :ref:`is_null<class_Callable_method_is_null>` **(** **)** |const| |
  88. +-------------------------------------+-------------------------------------------------------------------------------------------------------------+
  89. | :ref:`bool<class_bool>` | :ref:`is_standard<class_Callable_method_is_standard>` **(** **)** |const| |
  90. +-------------------------------------+-------------------------------------------------------------------------------------------------------------+
  91. | :ref:`bool<class_bool>` | :ref:`is_valid<class_Callable_method_is_valid>` **(** **)** |const| |
  92. +-------------------------------------+-------------------------------------------------------------------------------------------------------------+
  93. | void | :ref:`rpc<class_Callable_method_rpc>` **(** ... **)** |vararg| |const| |
  94. +-------------------------------------+-------------------------------------------------------------------------------------------------------------+
  95. | void | :ref:`rpc_id<class_Callable_method_rpc_id>` **(** :ref:`int<class_int>` peer_id, ... **)** |vararg| |const| |
  96. +-------------------------------------+-------------------------------------------------------------------------------------------------------------+
  97. | :ref:`Callable<class_Callable>` | :ref:`unbind<class_Callable_method_unbind>` **(** :ref:`int<class_int>` argcount **)** |const| |
  98. +-------------------------------------+-------------------------------------------------------------------------------------------------------------+
  99. .. rst-class:: classref-reftable-group
  100. Operators
  101. ---------
  102. .. table::
  103. :widths: auto
  104. +-------------------------+------------------------------------------------------------------------------------------------------------+
  105. | :ref:`bool<class_bool>` | :ref:`operator !=<class_Callable_operator_neq_Callable>` **(** :ref:`Callable<class_Callable>` right **)** |
  106. +-------------------------+------------------------------------------------------------------------------------------------------------+
  107. | :ref:`bool<class_bool>` | :ref:`operator ==<class_Callable_operator_eq_Callable>` **(** :ref:`Callable<class_Callable>` right **)** |
  108. +-------------------------+------------------------------------------------------------------------------------------------------------+
  109. .. rst-class:: classref-section-separator
  110. ----
  111. .. rst-class:: classref-descriptions-group
  112. Constructor Descriptions
  113. ------------------------
  114. .. _class_Callable_constructor_Callable:
  115. .. rst-class:: classref-constructor
  116. :ref:`Callable<class_Callable>` **Callable** **(** **)**
  117. Constructs an empty **Callable**, with no object nor method bound.
  118. .. rst-class:: classref-item-separator
  119. ----
  120. .. rst-class:: classref-constructor
  121. :ref:`Callable<class_Callable>` **Callable** **(** :ref:`Callable<class_Callable>` from **)**
  122. Constructs a **Callable** as a copy of the given **Callable**.
  123. .. rst-class:: classref-item-separator
  124. ----
  125. .. rst-class:: classref-constructor
  126. :ref:`Callable<class_Callable>` **Callable** **(** :ref:`Object<class_Object>` object, :ref:`StringName<class_StringName>` method **)**
  127. Creates a new **Callable** for the method named ``method`` in the specified ``object``.
  128. .. rst-class:: classref-section-separator
  129. ----
  130. .. rst-class:: classref-descriptions-group
  131. Method Descriptions
  132. -------------------
  133. .. _class_Callable_method_bind:
  134. .. rst-class:: classref-method
  135. :ref:`Callable<class_Callable>` **bind** **(** ... **)** |vararg| |const|
  136. 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>`.
  137. .. rst-class:: classref-item-separator
  138. ----
  139. .. _class_Callable_method_bindv:
  140. .. rst-class:: classref-method
  141. :ref:`Callable<class_Callable>` **bindv** **(** :ref:`Array<class_Array>` arguments **)**
  142. 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>`.
  143. .. rst-class:: classref-item-separator
  144. ----
  145. .. _class_Callable_method_call:
  146. .. rst-class:: classref-method
  147. :ref:`Variant<class_Variant>` **call** **(** ... **)** |vararg| |const|
  148. Calls the method represented by this **Callable**. Arguments can be passed and should match the method's signature.
  149. .. rst-class:: classref-item-separator
  150. ----
  151. .. _class_Callable_method_call_deferred:
  152. .. rst-class:: classref-method
  153. void **call_deferred** **(** ... **)** |vararg| |const|
  154. Calls the method represented by this **Callable** in deferred mode, i.e. during the idle frame. Arguments can be passed and should match the method's signature.
  155. ::
  156. func _ready():
  157. grab_focus.call_deferred()
  158. .. rst-class:: classref-item-separator
  159. ----
  160. .. _class_Callable_method_callv:
  161. .. rst-class:: classref-method
  162. :ref:`Variant<class_Variant>` **callv** **(** :ref:`Array<class_Array>` arguments **)** |const|
  163. 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>`.
  164. .. rst-class:: classref-item-separator
  165. ----
  166. .. _class_Callable_method_get_bound_arguments:
  167. .. rst-class:: classref-method
  168. :ref:`Array<class_Array>` **get_bound_arguments** **(** **)** |const|
  169. 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).
  170. .. rst-class:: classref-item-separator
  171. ----
  172. .. _class_Callable_method_get_bound_arguments_count:
  173. .. rst-class:: classref-method
  174. :ref:`int<class_int>` **get_bound_arguments_count** **(** **)** |const|
  175. 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.
  176. .. rst-class:: classref-item-separator
  177. ----
  178. .. _class_Callable_method_get_method:
  179. .. rst-class:: classref-method
  180. :ref:`StringName<class_StringName>` **get_method** **(** **)** |const|
  181. Returns the name of the method represented by this **Callable**. If the callable is a lambda function, returns the function's name.
  182. .. rst-class:: classref-item-separator
  183. ----
  184. .. _class_Callable_method_get_object:
  185. .. rst-class:: classref-method
  186. :ref:`Object<class_Object>` **get_object** **(** **)** |const|
  187. Returns the object on which this **Callable** is called.
  188. .. rst-class:: classref-item-separator
  189. ----
  190. .. _class_Callable_method_get_object_id:
  191. .. rst-class:: classref-method
  192. :ref:`int<class_int>` **get_object_id** **(** **)** |const|
  193. Returns the ID of this **Callable**'s object (see :ref:`Object.get_instance_id<class_Object_method_get_instance_id>`).
  194. .. rst-class:: classref-item-separator
  195. ----
  196. .. _class_Callable_method_hash:
  197. .. rst-class:: classref-method
  198. :ref:`int<class_int>` **hash** **(** **)** |const|
  199. Returns the 32-bit hash value of this **Callable**'s object.
  200. \ **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>`.
  201. .. rst-class:: classref-item-separator
  202. ----
  203. .. _class_Callable_method_is_custom:
  204. .. rst-class:: classref-method
  205. :ref:`bool<class_bool>` **is_custom** **(** **)** |const|
  206. 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.
  207. .. rst-class:: classref-item-separator
  208. ----
  209. .. _class_Callable_method_is_null:
  210. .. rst-class:: classref-method
  211. :ref:`bool<class_bool>` **is_null** **(** **)** |const|
  212. Returns ``true`` if this **Callable** has no target to call the method on.
  213. .. rst-class:: classref-item-separator
  214. ----
  215. .. _class_Callable_method_is_standard:
  216. .. rst-class:: classref-method
  217. :ref:`bool<class_bool>` **is_standard** **(** **)** |const|
  218. 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.
  219. .. rst-class:: classref-item-separator
  220. ----
  221. .. _class_Callable_method_is_valid:
  222. .. rst-class:: classref-method
  223. :ref:`bool<class_bool>` **is_valid** **(** **)** |const|
  224. Returns ``true`` if the callable's object exists and has a valid method name assigned, or is a custom callable.
  225. .. rst-class:: classref-item-separator
  226. ----
  227. .. _class_Callable_method_rpc:
  228. .. rst-class:: classref-method
  229. void **rpc** **(** ... **)** |vararg| |const|
  230. Perform an RPC (Remote Procedure Call). This is used for multiplayer and is normally not available, unless the function being called has been marked as *RPC*. Calling this method on unsupported functions will result in an error.
  231. .. rst-class:: classref-item-separator
  232. ----
  233. .. _class_Callable_method_rpc_id:
  234. .. rst-class:: classref-method
  235. void **rpc_id** **(** :ref:`int<class_int>` peer_id, ... **)** |vararg| |const|
  236. 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*. Calling this method on unsupported functions will result in an error.
  237. .. rst-class:: classref-item-separator
  238. ----
  239. .. _class_Callable_method_unbind:
  240. .. rst-class:: classref-method
  241. :ref:`Callable<class_Callable>` **unbind** **(** :ref:`int<class_int>` argcount **)** |const|
  242. Returns a copy of this **Callable** with the arguments unbound, as defined by ``argcount``. Calling the returned **Callable** will call the method without the extra arguments that are supplied in the **Callable** on which you are calling this method.
  243. .. rst-class:: classref-section-separator
  244. ----
  245. .. rst-class:: classref-descriptions-group
  246. Operator Descriptions
  247. ---------------------
  248. .. _class_Callable_operator_neq_Callable:
  249. .. rst-class:: classref-operator
  250. :ref:`bool<class_bool>` **operator !=** **(** :ref:`Callable<class_Callable>` right **)**
  251. Returns ``true`` if both **Callable**\ s invoke different targets.
  252. .. rst-class:: classref-item-separator
  253. ----
  254. .. _class_Callable_operator_eq_Callable:
  255. .. rst-class:: classref-operator
  256. :ref:`bool<class_bool>` **operator ==** **(** :ref:`Callable<class_Callable>` right **)**
  257. Returns ``true`` if both **Callable**\ s invoke the same custom target.
  258. .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)`
  259. .. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)`
  260. .. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)`
  261. .. |constructor| replace:: :abbr:`constructor (This method is used to construct a type.)`
  262. .. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)`
  263. .. |operator| replace:: :abbr:`operator (This method describes a valid operator to use with this type as left-hand operand.)`