Callable.xml

<?xml version="1.0" encoding="UTF-8" ?>
<class name="Callable" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
	<brief_description>
		A built-in type representing a method or a standalone function.
	</brief_description>
	<description>
		[Callable] is a built-in [Variant] type that represents a function. It can either be a method within an [Object] instance, or a custom callable used for different purposes (see [method is_custom]). Like all [Variant] types, it can be stored in variables and passed to other functions. It is most commonly used for signal callbacks.
		[codeblocks]
		[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.0, -1.0) 42 Node(node.gd)::print_args"
		    callable.call("invalid")  # Invalid call, should have at least 2 arguments.
		[/gdscript]
		[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.
		}
		[/csharp]
		[/codeblocks]
		In GDScript, it's possible to create lambda functions within a method. Lambda functions are custom callables that are not associated with an [Object] instance. Optionally, lambda functions can also be named. The name will be displayed in the debugger, or when calling [method get_method].
		[codeblock]
		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!"))
		[/codeblock]
		In GDScript, you can access methods and global functions as [Callable]s:
		[codeblock]
		tween.tween_callback(node.queue_free)  # Object methods.
		tween.tween_callback(array.clear)  # Methods of built-in types.
		tween.tween_callback(print.bind("Test"))  # Global functions.
		[/codeblock]
		[b]Note:[/b] [Dictionary] does not support the above due to ambiguity with keys.
		[codeblock]
		var dictionary = {"hello": "world"}

		# This will not work, `clear` is treated as a key.
		tween.tween_callback(dictionary.clear)

		# This will work.
		tween.tween_callback(Callable.create(dictionary, "clear"))
		[/codeblock]
	</description>
	<tutorials>
	</tutorials>
	<constructors>
		<constructor name="Callable">
			<return type="Callable" />
			<description>
				Constructs an empty [Callable], with no object nor method bound.
			</description>
		</constructor>
		<constructor name="Callable">
			<return type="Callable" />
			<param index="0" name="from" type="Callable" />
			<description>
				Constructs a [Callable] as a copy of the given [Callable].
			</description>
		</constructor>
		<constructor name="Callable">
			<return type="Callable" />
			<param index="0" name="object" type="Object" />
			<param index="1" name="method" type="StringName" />
			<description>
				Creates a new [Callable] for the method named [param method] in the specified [param object].
				[b]Note:[/b] For methods of built-in [Variant] types, use [method create] instead.
			</description>
		</constructor>
	</constructors>
	<methods>
		<method name="bind" qualifiers="vararg const">
			<return type="Callable" />
			<description>
				Returns a copy of this [Callable] with one or more arguments bound. When called, the bound arguments are passed [i]after[/i] the arguments supplied by [method call]. See also [method unbind].
				[b]Note:[/b] When this method is chained with other similar methods, the order in which the argument list is modified is read from right to left.
			</description>
		</method>
		<method name="bindv">
			<return type="Callable" />
			<param index="0" name="arguments" type="Array" />
			<description>
				Returns a copy of this [Callable] with one or more arguments bound, reading them from an array. When called, the bound arguments are passed [i]after[/i] the arguments supplied by [method call]. See also [method unbind].
				[b]Note:[/b] When this method is chained with other similar methods, the order in which the argument list is modified is read from right to left.
			</description>
		</method>
		<method name="call" qualifiers="vararg const">
			<return type="Variant" />
			<description>
				Calls the method represented by this [Callable]. Arguments can be passed and should match the method's signature.
			</description>
		</method>
		<method name="call_deferred" qualifiers="vararg const">
			<return type="void" />
			<description>
				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.
				[codeblocks]
				[gdscript]
				func _ready():
				    grab_focus.call_deferred()
				[/gdscript]
				[csharp]
				public override void _Ready()
				{
				    Callable.From(GrabFocus).CallDeferred();
				}
				[/csharp]
				[/codeblocks]
				[b]Note:[/b] Deferred calls are processed at idle time. Idle time happens mainly at the end of process and physics frames. In it, deferred calls will be run until there are none left, which means you can defer calls from other deferred calls and they'll still be run in the current idle time cycle. This means you should not call a method deferred from itself (or from a method called by it), as this causes infinite recursion the same way as if you had called the method directly.
				See also [method Object.call_deferred].
			</description>
		</method>
		<method name="callv" qualifiers="const">
			<return type="Variant" />
			<param index="0" name="arguments" type="Array" />
			<description>
				Calls the method represented by this [Callable]. Unlike [method call], this method expects all arguments to be contained inside the [param arguments] [Array].
			</description>
		</method>
		<method name="create" qualifiers="static">
			<return type="Callable" />
			<param index="0" name="variant" type="Variant" />
			<param index="1" name="method" type="StringName" />
			<description>
				Creates a new [Callable] for the method named [param method] in the specified [param variant]. To represent a method of a built-in [Variant] type, a custom callable is used (see [method is_custom]). If [param variant] is [Object], then a standard callable will be created instead.
				[b]Note:[/b] This method is always necessary for the [Dictionary] type, as property syntax is used to access its entries. You may also use this method when [param variant]'s type is not known in advance (for polymorphism).
			</description>
		</method>
		<method name="get_argument_count" qualifiers="const">
			<return type="int" />
			<description>
				Returns the total number of arguments this [Callable] should take, including optional arguments. This means that any arguments bound with [method bind] are [i]subtracted[/i] from the result, and any arguments unbound with [method unbind] are [i]added[/i] to the result.
			</description>
		</method>
		<method name="get_bound_arguments" qualifiers="const">
			<return type="Array" />
			<description>
				Returns the array of arguments bound via successive [method bind] or [method unbind] calls. These arguments will be added [i]after[/i] the arguments passed to the call, from which [method get_unbound_arguments_count] arguments on the right have been previously excluded.
				[codeblock]
				func get_effective_arguments(callable, call_args):
				    assert(call_args.size() - callable.get_unbound_arguments_count() &gt;= 0)
				    var result = call_args.slice(0, call_args.size() - callable.get_unbound_arguments_count())
				    result.append_array(callable.get_bound_arguments())
				    return result
				[/codeblock]
			</description>
		</method>
		<method name="get_bound_arguments_count" qualifiers="const">
			<return type="int" />
			<description>
				Returns the total amount of arguments bound via successive [method bind] or [method unbind] calls. This is the same as the size of the array returned by [method get_bound_arguments]. See [method get_bound_arguments] for details.
				[b]Note:[/b] The [method get_bound_arguments_count] and [method get_unbound_arguments_count] methods can both return positive values.
			</description>
		</method>
		<method name="get_method" qualifiers="const">
			<return type="StringName" />
			<description>
				Returns the name of the method represented by this [Callable]. If the callable is a GDScript lambda function, returns the function's name or [code]"&lt;anonymous lambda&gt;"[/code].
			</description>
		</method>
		<method name="get_object" qualifiers="const">
			<return type="Object" />
			<description>
				Returns the object on which this [Callable] is called.
			</description>
		</method>
		<method name="get_object_id" qualifiers="const">
			<return type="int" />
			<description>
				Returns the ID of this [Callable]'s object (see [method Object.get_instance_id]).
			</description>
		</method>
		<method name="get_unbound_arguments_count" qualifiers="const">
			<return type="int" />
			<description>
				Returns the total amount of arguments unbound via successive [method bind] or [method unbind] calls. See [method get_bound_arguments] for details.
				[b]Note:[/b] The [method get_bound_arguments_count] and [method get_unbound_arguments_count] methods can both return positive values.
			</description>
		</method>
		<method name="hash" qualifiers="const">
			<return type="int" />
			<description>
				Returns the 32-bit hash value of this [Callable]'s object.
				[b]Note:[/b] [Callable]s with equal content will always produce identical hash values. However, the reverse is not true. Returning identical hash values does [i]not[/i] 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 [method hash].
			</description>
		</method>
		<method name="is_custom" qualifiers="const">
			<return type="bool" />
			<description>
				Returns [code]true[/code] if this [Callable] is a custom callable. Custom callables are used:
				- for binding/unbinding arguments (see [method bind] and [method unbind]);
				- for representing methods of built-in [Variant] types (see [method create]);
				- for representing global, lambda, and RPC functions in GDScript;
				- for other purposes in the core, GDExtension, and C#.
			</description>
		</method>
		<method name="is_null" qualifiers="const">
			<return type="bool" />
			<description>
				Returns [code]true[/code] if this [Callable] has no target to call the method on. Equivalent to [code]callable == Callable()[/code].
				[b]Note:[/b] This is [i]not[/i] the same as [code]not is_valid()[/code] and using [code]not is_null()[/code] will [i]not[/i] guarantee that this callable can be called. Use [method is_valid] instead.
			</description>
		</method>
		<method name="is_standard" qualifiers="const">
			<return type="bool" />
			<description>
				Returns [code]true[/code] if this [Callable] is a standard callable. This method is the opposite of [method is_custom]. Returns [code]false[/code] if this callable is a lambda function.
			</description>
		</method>
		<method name="is_valid" qualifiers="const">
			<return type="bool" />
			<description>
				Returns [code]true[/code] if the callable's object exists and has a valid method name assigned, or is a custom callable.
			</description>
		</method>
		<method name="rpc" qualifiers="vararg const">
			<return type="void" />
			<description>
				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 [i]RPC[/i] (using [annotation @GDScript.@rpc] or [method Node.rpc_config]). Calling this method on unsupported functions will result in an error. See [method Node.rpc].
			</description>
		</method>
		<method name="rpc_id" qualifiers="vararg const">
			<return type="void" />
			<param index="0" name="peer_id" type="int" />
			<description>
				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 [i]RPC[/i] (using [annotation @GDScript.@rpc] or [method Node.rpc_config]). Calling this method on unsupported functions will result in an error. See [method Node.rpc_id].
			</description>
		</method>
		<method name="unbind" qualifiers="const">
			<return type="Callable" />
			<param index="0" name="argcount" type="int" />
			<description>
				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 [param 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 [method bind].
				[b]Note:[/b] When this method is chained with other similar methods, the order in which the argument list is modified is read from right to left.
				[codeblock]
				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.
				[/codeblock]
			</description>
		</method>
	</methods>
	<operators>
		<operator name="operator !=">
			<return type="bool" />
			<param index="0" name="right" type="Callable" />
			<description>
				Returns [code]true[/code] if both [Callable]s invoke different targets.
			</description>
		</operator>
		<operator name="operator ==">
			<return type="bool" />
			<param index="0" name="right" type="Callable" />
			<description>
				Returns [code]true[/code] if both [Callable]s invoke the same custom target.
			</description>
		</operator>
	</operators>
</class>