1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
|
<?xml version="1.0" encoding="UTF-8" ?>
<class name="Callable" version="4.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
<brief_description>
Built-in type representing a method in an object instance 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 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.
[b]Example:[/b]
[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, -1) 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]
</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].
</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].
</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].
</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. during the idle frame. Arguments can be passed and should match the method's signature.
[codeblock]
func _ready():
grab_focus.call_deferred()
[/codeblock]
</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="get_bound_arguments" qualifiers="const">
<return type="Array" />
<description>
Return the bound arguments (as long as [method get_bound_arguments_count] is greater than zero), or empty (if [method get_bound_arguments_count] is less than or equal to zero).
</description>
</method>
<method name="get_bound_arguments_count" qualifiers="const">
<return type="int" />
<description>
Returns the total amount of arguments bound (or unbound) via successive [method bind] or [method unbind] calls. If the amount of arguments unbound is greater than the ones bound, this function returns a value less than zero.
</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 lambda function, returns the function's name.
</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="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 created from [method bind] or [method unbind]. In GDScript, lambda functions are also custom callables.
</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.
</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). This is used for multiplayer and is normally not available, unless the function being called has been marked as [i]RPC[/i]. 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]. 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 the arguments unbound, as defined by [param 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.
</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>
|