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")  # Друкує "привіт, світ".
    callable.call(Vector2.UP, 42, callable)  # Prints "(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); // Prints "(0, -1) 42 Node(Node.cs)::PrintArgs"
    callable.Call("invalid"); // Недійсний виклик, має бути 3 аргументи.
}

У GDScript можна створювати лямбда-функції всередині методу. Лямбда-функції – це користувацькі виклики, які не пов'язані з екземпляром Object. За бажанням, лямбда-функції також можна іменувати. Ім'я буде відображатися в налагоджувачі або під час виклику методу get_method().

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

    # Prints "Hello everyone!"
    my_lambda.call("Hello everyone!")

    # Виводить "Attack!", коли випромінюється сигнал button_pressed.
    button_pressed.connect(func(): print("Attack!"))

У 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 із С#. Більше інформації: ref:doc_c_sharp_differences.

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

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 у вказаному variant. Для представлення методу вбудованого типу Variant використовується настроюваний виклик (див. is_custom()). Якщо variant дорівнює Object, замість цього буде створено стандартний виклик.

**Примітка: ** Цей метод завжди необхідний для типу Dictionary, оскільки для доступу до його записів використовується синтаксис властивості. Ви також можете використовувати цей метод, коли тип variant невідомий заздалегідь (для поліморфізму).

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, повертає назву функції або "<анонімний лямбда>".

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 занурюють ті ж індивідуальні цілі.