Callable

Встроенный тип, представляющий метод или отдельную функцию.

Описание

Callable — это встроенный тип Variant, представляющий функцию. Он может быть методом внутри экземпляра Object или пользовательским вызываемым объектом, используемым для различных целей (см. is_custom()). Как и все типы Variant, он может храниться в переменных и передаваться другим функциям. Чаще всего он используется для обратных вызовов сигналов.

func print_args(arg1, arg2, arg3 = ""):
    prints(arg1, arg2, arg3)

func test():
    var callable = Callable(self, "print_args")
    callable.call("hello", "world")  # Выводит "hello world ".
    callable.call(Vector2.UP, 42, callable)  # Выводит "(0.0, -1.0) 42 Node(node.gd)::print_args"
    callable.call("invalid")  # Неверный вызов, должно быть не менее 2 аргументов.

// Значения параметров по умолчанию не поддерживаются.
public void PrintArgs(Variant arg1, Variant arg2, Variant arg3 = default)
{
    GD.PrintS(arg1, arg2, arg3);
}

public void Test()
{
    // Недействительные вызовы молча завершаются ошибкой.
    Callable callable = new Callable(this, MethodName.PrintArgs);
    callable.Call("hello", "world"); // Значения параметров по умолчанию не поддерживаются, должно быть 3 аргумента.
    callable.Call(Vector2.Up, 42, callable); // Выводит "(0, -1) 42 Node(Node.cs)::PrintArgs"
    callable.Call("invalid"); // Неверный вызов, должно быть 3 аргумента.
}

В GDScript можно создавать лямбда-функции внутри метода. Лямбда-функции — это вызываемые пользователем объекты, не связанные с экземпляром Object. При желании лямбда-функциям можно присваивать имена. Имя будет отображаться в отладчике или при вызове get_method().

func _init():
    var my_lambda = func (message):
        print(message)

    # Выводит "Всем привет!"
    my_lambda.call("Всем привет!")

    # Выводит сообщение «Атака!» при выдаче сигнала button_pressed.
    button_pressed.connect(func(): print("Атака!"))

В GDScript вы можете получить доступ к методам и глобальным функциям как к Callable:

tween.tween_callback(node.queue_free)  # Методы объекта.
tween.tween_callback(array.clear)  # Методы встроенных типов.
tween.tween_callback(print.bind("Test"))  # Глобальные функции.

Примечание: Dictionary не поддерживает вышеизложенное из-за неоднозначности ключей.

var dictionary = { "hello": "world" }

# Это не сработает, `clear` рассматривается как ключ.
tween.tween_callback(dictionary.clear)

# Это сработает.
tween.tween_callback(Callable.create(dictionary, "clear"))

Примечание

Существуют заметные различия при использовании данного API с C#. Подробнее см. API различия C# и GDScript.

Конструкторы

Callable	Callable()
Callable	Callable(from: Callable)
Callable	Callable(object: Object, method: StringName)

Методы

Callable	bind(...) vararg const
Callable	bindv(arguments: Array)
Variant	call(...) vararg const
void	call_deferred(...) vararg const
Variant	callv(arguments: Array) const
Callable	create(variant: Variant, method: StringName) static
int	get_argument_count() const
Array	get_bound_arguments() const
int	get_bound_arguments_count() const
StringName	get_method() const
Object	get_object() const
int	get_object_id() const
int	get_unbound_arguments_count() const
int	hash() const
bool	is_custom() const
bool	is_null() const
bool	is_standard() const
bool	is_valid() const
void	rpc(...) vararg const
void	rpc_id(peer_id: int, ...) vararg const
Callable	unbind(argcount: int) const

Операторы

bool	operator !=(right: Callable)
bool	operator ==(right: Callable)

Описания конструктора

Callable Callable() 🔗

Создает пустой Callable без привязанных объектов и методов.

Callable Callable(from: Callable)

Создает Callable как копию заданного Callable.

Callable Callable(object: Object, method: StringName)

Создает новый Callable для метода с именем method в указанном object.

Примечание: Для методов встроенных типов Variant используйте вместо этого create().

Описания метода

Callable bind(...) vararg const 🔗

Возвращает копию этого Callable с одним или несколькими связанными аргументами. При вызове связанные аргументы передаются после аргументов, предоставленных call(). См. также unbind().

Примечание: Когда этот метод связан с другими похожими методами, порядок изменения списка аргументов считывается справа налево.

Callable bindv(arguments: Array) 🔗

Возвращает копию этого Callable с одним или несколькими связанными аргументами, считывая их из массива. При вызове связанные аргументы передаются после аргументов, предоставленных call(). См. также unbind().

Примечание: Когда этот метод связан с другими похожими методами, порядок изменения списка аргументов считывается справа налево.

Variant call(...) vararg const 🔗

Вызывает метод, представленный этим Callable. Аргументы могут быть переданы и должны соответствовать сигнатуре метода.

void call_deferred(...) vararg const 🔗

Вызывает метод, представленный этим Callable, в отложенном режиме, т. е. в конце текущего кадра. Аргументы могут быть переданы и должны соответствовать сигнатуре метода.

func _ready():
    grab_focus.call_deferred()

public override void _Ready()
{
    Callable.From(GrabFocus).CallDeferred();
}

Примечание: Отложенные вызовы обрабатываются во время простоя. Время простоя в основном происходит в конце кадров процесса и физики. В нем отложенные вызовы будут выполняться до тех пор, пока не останется ни одного, что означает, что вы можете отложить вызовы из других отложенных вызовов, и они все равно будут выполняться в текущем цикле времени простоя. Это означает, что вы не должны вызывать метод, отложенный из самого себя (или из метода, вызванного им), так как это вызывает бесконечную рекурсию так же, как если бы вы вызвали метод напрямую.

См. также Object.call_deferred().

Variant callv(arguments: Array) const 🔗

Вызывает метод, представленный этим Callable. В отличие от call(), этот метод ожидает, что все аргументы будут содержаться внутри arguments Array.

Callable create(variant: Variant, method: StringName) static 🔗

Создает новый Callable для метода с именем method в указанном variation. Для представления метода встроенного типа Variant используется пользовательский вызываемый объект (см. is_custom()). Если variation — это Object, то вместо него будет создан стандартный вызываемый объект.

Примечание: Этот метод всегда необходим для типа Dictionary, так как для доступа к его записям используется синтаксис свойств. Вы также можете использовать этот метод, когда тип variation заранее неизвестен (для полиморфизма).

int get_argument_count() const 🔗

Возвращает общее количество аргументов, которые должен принимать этот Callable, включая необязательные аргументы. Это означает, что любые аргументы, связанные с bind(), вычитаются из результата, а любые аргументы, несвязанные с unbind(), добавляются к результату.

Array get_bound_arguments() const 🔗

Возвращает массив аргументов, связанных через последовательные вызовы bind() или unbind(). Эти аргументы будут добавлены после аргументов, переданных вызову, из которого get_unbound_arguments_count() аргументов справа были ранее исключены.

func get_effective_arguments(callable, call_args):
    assert(call_args.size() - callable.get_unbound_arguments_count() >= 0)
    var result = call_args.slice(0, call_args.size() - callable.get_unbound_arguments_count())
    result.append_array(callable.get_bound_arguments())
    return result

int get_bound_arguments_count() const 🔗

Возвращает общее количество аргументов, связанных через последовательные вызовы bind() или unbind(). Это то же самое, что и размер массива, возвращаемого get_bound_arguments(). Подробности см. в get_bound_arguments().

Примечание: Методы get_bound_arguments_count() и get_unbound_arguments_count() могут возвращать положительные значения.

StringName get_method() const 🔗

Возвращает имя метода, представленного этим Callable. Если вызываемый объект является лямбда-функцией GDScript, возвращает имя функции или "<anonymous lambda>".

Object get_object() const 🔗

Возвращает объект, для которого вызывается этот Callable.

int get_object_id() const 🔗

Возвращает идентификатор этого объекта Callable (см. Object.get_instance_id()).

int get_unbound_arguments_count() const 🔗

Возвращает общее количество аргументов, освобожденных с помощью последовательных вызовов bind() или unbind(). Подробности см. в get_bound_arguments().

Примечание: Методы get_bound_arguments_count() и get_unbound_arguments_count() могут возвращать положительные значения.

int hash() const 🔗

Возвращает 32-битное хэш-значение этого объекта Callable.

Примечание: Callable с одинаковым содержимым всегда будут выдавать идентичные хэш-значения. Однако обратное неверно. Возврат идентичных хэш-значений не ** означает, что вызываемые объекты равны, поскольку разные вызываемые объекты могут иметь идентичные хэш-значения из-за коллизий хэшей. Движок использует 32-битный хэш-алгоритм для hash().

bool is_custom() const 🔗

Возвращает true, если этот Callable является пользовательским вызываемым. Пользовательские вызываемые используются:

для привязки/отмены привязки аргументов (см. bind() и unbind());
для представления методов встроенных типов Variant (см. create());
для представления глобальных, лямбда-функций и функций RPC в GDScript;
для других целей в ядре, GDExtension и C#.

bool is_null() const 🔗

Возвращает true, если у этого Callable нет цели для вызова метода. Эквивалентно callable == Callable().

Примечание: Это не то же самое, что not is_valid(), и использование not is_null() не гарантирует, что этот вызываемый может быть вызван. Вместо этого используйте is_valid().

bool is_standard() const 🔗

Возвращает true, если этот Callable является стандартным вызываемым. Этот метод противоположен is_custom(). Возвращает false, если этот вызываемый является лямбда-функцией.

bool is_valid() const 🔗

Возвращает true, если вызываемый объект существует и имеет назначенное допустимое имя метода или является пользовательским вызываемым объектом.

void rpc(...) vararg const 🔗

Выполнить RPC (удаленный вызов процедуры) на всех подключенных пирах. Это используется для многопользовательской игры и обычно недоступно, если только вызываемая функция не помечена как RPC (используя @GDScript.@rpc или Node.rpc_config()). Вызов этого метода для неподдерживаемых функций приведет к ошибке. См. Node.rpc().

void rpc_id(peer_id: int, ...) vararg const 🔗

Выполнить RPC (удаленный вызов процедуры) для определенного идентификатора однорангового сервера (см. документацию по многопользовательской игре для справки). Это используется для многопользовательской игры и обычно недоступно, если вызываемая функция не помечена как RPC (используя @GDScript.@rpc или Node.rpc_config()). Вызов этого метода для неподдерживаемых функций приведет к ошибке. См. Node.rpc_id().

Callable unbind(argcount: int) const 🔗

Возвращает копию этого Callable с несколькими несвязанными аргументами. Другими словами, когда вызывается новый вызываемый, последние несколько аргументов, предоставленных пользователем, игнорируются в соответствии с argcount. Оставшиеся аргументы передаются вызываемому. Это позволяет использовать исходный вызываемый в контексте, который пытается передать больше аргументов, чем этот вызываемый может обработать, например, сигнал с фиксированным количеством аргументов. См. также bind().

Примечание: Когда этот метод связан с другими похожими методами, порядок, в котором изменяется список аргументов, считывается справа налево.

func _ready():
    foo.unbind(1).call(1, 2) # Вызывает foo(1).
    foo.bind(3, 4).unbind(1).call(1, 2) # Вызывает foo(1, 3, 4), обратите внимание, что он не изменяет аргументы из bind.

Описания оператора

bool operator !=(right: Callable) 🔗

Возвращает true, если оба Callable вызывают разные цели.

bool operator ==(right: Callable) 🔗

Возвращает true, если оба Callable вызывают одну и ту же пользовательскую цель.