Attention
You are reading the latest
(unstable) version of this documentation, which may document features not available
or compatible with Godot 3.x.
Checking the stable version of the documentation...
Work in progress
Godot documentation is being updated to reflect the latest changes in version
4.0
. Some documentation pages may
still state outdated information. This banner will tell you if you're reading one of such pages.
The contents of this page are up to date. If you can still find outdated information, please open an issue.
Callable¶
Built-in type representing a method in an object instance or a standalone function.
Description¶
Callable is a built-in Variant type that represents a function. It can either be a method within an Object instance, or a standalone function not related to any object, like a lambda function. Like all Variant types, it can be stored in variables and passed to other functions. It is most commonly used for signal callbacks.
Example:
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.
// 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 Object instance. Optionally, lambda functions can also be named. The name will be displayed in the debugger, or when calling 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!"))
Constructors¶
Callable ( ) |
|
Callable ( Object object, StringName method ) |
Methods¶
bind ( ... ) vararg const |
|
call ( ... ) vararg const |
|
void |
call_deferred ( ... ) vararg const |
get_bound_arguments ( ) const |
|
get_bound_arguments_count ( ) const |
|
get_method ( ) const |
|
get_object ( ) const |
|
get_object_id ( ) const |
|
hash ( ) const |
|
is_custom ( ) const |
|
is_null ( ) const |
|
is_standard ( ) const |
|
is_valid ( ) const |
|
void |
rpc ( ... ) vararg const |
void |
|
Operators¶
operator != ( Callable right ) |
|
operator == ( Callable right ) |
Constructor Descriptions¶
Callable Callable ( )
Constructs an empty Callable, with no object nor method bound.
Callable Callable ( Callable from )
Constructs a Callable as a copy of the given Callable.
Callable Callable ( Object object, StringName method )
Creates a new Callable for the method named method
in the specified object
.
Method Descriptions¶
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 call.
Callable bindv ( Array arguments )
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 call.
Variant call ( ... ) vararg const
Calls the method represented by this Callable. Arguments can be passed and should match the method's signature.
void call_deferred ( ... ) vararg const
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.
func _ready():
grab_focus.call_deferred()
Variant callv ( Array arguments ) const
Calls the method represented by this Callable. Unlike call, this method expects all arguments to be contained inside the arguments
Array.
Array get_bound_arguments ( ) const
Return the bound arguments (as long as get_bound_arguments_count is greater than zero), or empty (if get_bound_arguments_count is less than or equal to zero).
int get_bound_arguments_count ( ) const
Returns the total amount of arguments bound (or unbound) via successive bind or unbind calls. If the amount of arguments unbound is greater than the ones bound, this function returns a value less than zero.
StringName get_method ( ) const
Returns the name of the method represented by this Callable. If the callable is a lambda function, returns the function's name.
Object get_object ( ) const
Returns the object on which this Callable is called.
int get_object_id ( ) const
Returns the ID of this Callable's object (see Object.get_instance_id).
int hash ( ) const
Returns the 32-bit hash value of this Callable's object.
Note: Callables 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 hash.
bool is_custom ( ) const
Returns true
if this Callable is a custom callable. Custom callables are created from bind or unbind. In GDScript, lambda functions are also custom callables.
bool is_null ( ) const
Returns true
if this Callable has no target to call the method on.
bool is_standard ( ) const
Returns true
if this Callable is a standard callable. This method is the opposite of is_custom. Returns false
if this callable is a lambda function.
bool is_valid ( ) const
Returns true
if the callable's object exists and has a valid method name assigned, or is a custom callable.
void rpc ( ... ) vararg const
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. See Node.rpc.
void rpc_id ( int peer_id, ... ) 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. Calling this method on unsupported functions will result in an error. See Node.rpc_id.
Callable unbind ( int argcount ) const
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.
Operator Descriptions¶
bool operator != ( Callable right )
Returns true
if both Callables invoke different targets.
bool operator == ( Callable right )
Returns true
if both Callables invoke the same custom target.