Callable

Un type intégré représentant une méthode ou une fonction autonome.

Description

Callable (litt. Appelable) est un type Variant intégré qui représente une fonction. Il peut soit être une méthode dans une instance d'Object, soit un callable personnalisé utilisé à des fins différentes (voir is_custom()). Comme tous les types Variant, il peut être stocké dans des variables et transmis à d'autres fonctions. Il est le plus souvent utilisé pour les callbacks de signaux.

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

func test():
    var callable = Callable(self, "afficher_args")
    callable.call("bonjour", "monde")  # Affiche "bonjour monde".
    callable.call(Vector2.UP, 42, callable)  # Affiche "(0.0, -1.0) 42 Node(node.gd)::print_args"
    callable.call("invalide")  # Appel invalide, devrait avoir au moins deux arguments.

// Les valeurs de paramètre par défaut ne sont pas supportées.
public void AfficherArgs(Variant arg1, Variant arg2, Variant arg3 = default)
{
    GD.PrintS(arg1, arg2, arg3);
}

public void Test()
{
    // Les appels invalides échouent silencieusement.
    Callable callable = new Callable(this, MethodName.AfficherArgs);
    callable.Call("bonjour", "monde"); // Les valeurs de paramètre par défaut ne sont pas supportées, il devrait y avoir trois arguments.
    callable.Call(Vector2.Up, 42, callable); // Affiche "(0, -1) 42 Node(Node.cs)::PrintArgs"
    callable.Call("invalid"); //  Appel invalide, devrait avoir trois arguments.
}

En GDScript, il est possible de créer des fonctions lambda dans une méthode. Les fonctions lambda sont des callables personnalisés qui ne sont pas associés à une instance Object. Optionnellement, les fonctions lambda peuvent également être nommées. Le nom sera affiché dans le débogueur, ou lors de l'appel à get_method().

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

    # Affiche "Bonjour tout le monde !"
    mon_lambda.call("Bonjour tout le monde !")

    # Affiche "Attaque !", quand le signal bouton_appuye est émis.
    bouton_appuye.connect(func(): print("Attaque !"))

En GDScript, vous pouvez accéder aux méthodes et fonctions globales comme des Callables

tween.tween_callback(noeud.queue_free)  # Méthodes d'objet.
tween.tween_callback(tableau.clear)  # Méthodes de types intégrés.
tween.tween_callback(print.bind("Test"))  # Fonctions globales.

Note : Dictionary ne supporte pas le code ci-dessus du à une ambiguïté avec les clés.

var dictionnaire = {"bonjour": "monde"}

# Cela ne fonctionnera pas, `clear` est traité comme une clé.
tween.tween_callback(dictionnaire.clear)

# Cela fonctionnera.
tween.tween_callback(Callable.create(dictionnaire, "clear"))

Note

Il y a des différences notables dans l'utilisation de cette API en C#. Voir Différences de l'API C# par rapport à GDScript pour plus d'informations.

Constructeurs

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

Méthodes

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

Opérateurs

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

Descriptions des constructeurs

Callable Callable() 🔗

Construit un Callable vide, sans objet ni méthode lié.

Callable Callable(from: Callable)

Construit un Callable en tant que copie du Callable donné.

Callable Callable(object: Object, method: StringName)

Crée un nouveau Callable pour la méthode nommée method dans l'objet object spécifié.

Note : Pour les méthodes de types Variant intégrés, utilisez plutôt create().

Descriptions des méthodes

Callable bind(...) vararg const 🔗

Renvoie une copie de ce Callable avec un ou plusieurs arguments liés. Lorsqu'appelée, les arguments liés sont passés après les arguments fournis par call(). Voir aussi unbind().

Note : Lorsque cette méthode est enchaînée avec d'autres méthodes similaires, l'ordre dans lequel la liste des arguments est modifiée est lu de droite à gauche.

Callable bindv(arguments: Array) 🔗

Renvoie une copie de ce Callable avec un ou plusieurs arguments liés, en les lisant d'un tableau. Lorsqu'appelée, les arguments liés sont passés après les arguments fournis par call(). Voir aussi unbind().

Note : Lorsque cette méthode est enchaînée avec d'autres méthodes similaires, l'ordre dans lequel la liste des arguments est modifiée est lu de droite à gauche.

Variant call(...) vararg const 🔗

Appelle la méthode représentée par ce Callable. Les arguments peuvent être passés et devraient correspondre à la signature de la méthode.

void call_deferred(...) vararg const 🔗

Appelle la méthode représentée par ce Callable en mode différé, c.-à-d. à la fin de la trame courante. Des arguments peuvent être passés et doivent correspondre à la signature de la méthode.

func _ready():
    grab_focus.call_deferred()

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

Note : Les appels différés sont traités lors des moments d'inaction. Les moments d'inaction se produisent principalement à la fin des trames de traitement et de physique. Dans ce cas, les appels différés seront lancés jusqu'à ce qu'il n'y en ait plus, ce qui signifie que vous pouvez différer des appels depuis des appels différés et qu'ils seront toujours exécutés dans le cycle de temps d'inaction actuel. Cela signifie que vous ne devriez pas appeler une méthode différée depuis elle-même (ou d'une méthode qu'elle appelle), car cela provoque une récursion infinie de la même manière que si vous aviez appelé la méthode directement.

Voir aussi Object.call_deferred().

Variant callv(arguments: Array) const 🔗

Appelle la méthode représentée par ce Callable. Contrairement à call(), cette méthode s'attend à ce que tous les arguments soient contenus dans l'Array arguments.

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

Crée un nouveau Callable pour la méthode nommée method dans le variant spécifié. Pour représenter une méthode d'un type intégré Variant, un callable personnalisé est utilisé (voir is_custom()). Si variant est Object, alors un callable standard sera créé à la place.

Note : Cette méthode est toujours nécessaire pour le type Dictionary, car la syntaxe de propriété est utilisée pour accéder à ses entrées. Vous pouvez également utiliser cette méthode lorsque le type de variant n'est pas connu à l'avance (pour le polymorphisme).

int get_argument_count() const 🔗

Renvoie le nombre total d'arguments que ce Callable devrait prendre, y compris les arguments optionnels. Cela signifie que tous les arguments liés avec bind() sont soustraits du résultat, et tous les arguments déliés avec unbind() sont ajoutés au résultat.

Array get_bound_arguments() const 🔗

Renvoie le tableau des arguments liés par des appels successifs à bind() ou unbind(). Ces arguments seront ajoutés après les arguments passés à l'appel, desquels get_unbound_arguments_count() arguments sur la droite ont été précédemment exclus.

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

int get_bound_arguments_count() const 🔗

Renvoie le montant total d'arguments liés par des appels successifs à bind() ou unbind(). Ceci est identique à la taille du tableau renvoyé par get_bound_arguments(). Voir get_bound_arguments() pour plus de détails.

Note : Les méthodes get_bound_arguments_count() et get_unbound_arguments_count() peuvent toutes les deux renvoyer des valeurs positives.

StringName get_method() const 🔗

Renvoie le nom de la méthode représentée par ce Callable. Si le callable est une fonction lambda GDScript, renvoie le nom de la fonction ou "<anonymous lambda>".

Object get_object() const 🔗

Renvoie l'objet sur lequel ce Callable est appelé.

int get_object_id() const 🔗

Renvoie l'ID de l'objet de ce Callable (voir Object.get_instance_id()).

int get_unbound_arguments_count() const 🔗

Renvoie la quantité totale d'arguments non liés par des appels successifs à bind() ou unbind(). Voir get_bound_arguments() pour plus de détails.

Note : Les méthodes get_bound_arguments_count() et get_unbound_arguments_count() peuvent toutes les deux renvoyer des valeurs positives.

int hash() const 🔗

Renvoie la valeur de hachage sur 32 bits de l'objet de ce Callable

Note : Des Callables avec un contenu égal produiront toujours des valeurs de hachage identiques. Cependant, l'inverse n'est pas vrai. Renvoyer des valeurs de hachage identiques n'implique pas que les callables sont égaux, car différents callables peuvent avoir des valeurs de hachage identiques en raison de collisions de hachage. Le moteur utilise un algorithme de hachage sur 32 bits pour hash().

bool is_custom() const 🔗

Renvoie true si ce Callable est un callable personnalisé. Les callables personnalisés sont utilisés :

pour lier/délier des arguments (voir bind() et unbind());
pour représenter les méthodes de types Variant intégrés (voir create());
pour représenter les fonctions globales, lambda et RPC en GDScript;
à d'autres fins dans le noyau, les GDExtension, et le C#.

bool is_null() const 🔗

Renvoie true si ce Callable n'a pas de cible sur laquelle appeler la méthode. Équivalent à callable == Callable().

Note : Ce n'est pas identique à not is_valid() et l'utilisation de not is_null() ne garantira pas que ce callable puisse être appelé. Utilisez is_valid() à la place.

bool is_standard() const 🔗

Renvoie true si ce Callable est un callable standard. Cette méthode est le contraire de is_custom(). Renvoie false si ce callable est une fonction lambda.

bool is_valid() const 🔗

Renvoie true si l'objet du callable existe et a un nom de méthode valide assigné, ou est un callable personnalisé.

void rpc(...) vararg const 🔗

Effectue une RPC (Remote Procedure Call, litt. Appel de procédure à distance) sur tous les pairs connectés. Ceci est utilisé pour le multijoueur et n'est normalement pas disponible, sauf si la fonction appelée a été marquée comme RPC (en utilisant @GDScript.@rpc ou Node.rpc_config()). Appeler cette méthode sur des fonctions non supportées entraînera une erreur. Voir Node.rpc().

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

Effectue une RPC (Remote Procedure Call, litt. Appel de procédure à distance) sur un ID de pair spécifique (voir la documentation du multijoueur comme référence). Ceci est utilisé pour le multijoueur et n'est normalement pas disponible, sauf si la fonction appelée a été marquée comme RPC (en utilisant @GDScript.@rpc ou Node.rpc_config()). Appeler cette méthode sur des fonctions non supportées entraînera une erreur. Voir Node.rpc().

Callable unbind(argcount: int) const 🔗

Renvoie une copie de ce Callable avec un certain nombre d'arguments déliés. En d'autres termes, lorsque le nouveau callable est appelé, les derniers arguments fournis par l'utilisateur sont ignorés, selon argcount. Les arguments restants sont transmis au callable. Cela permet d'utiliser le callable original dans un contexte qui tente de passer plus d'arguments que cet appelable peut gérer, par exemple un signal avec un nombre fixe d'arguments. Voir aussi bind().

Note : Lorsque cette méthode est enchaînée avec d'autres méthodes similaires, l'ordre dans lequel la liste des arguments est modifiée est lu de droite à gauche.

func _ready():
    foo.unbind(1).call(1, 2) # Appelle foo(1).
    foo.bind(3, 4).unbind(1).call(1, 2) # Appelle foo(1, 3, 4), notez que cela ne change pas les arguments de bind.

Descriptions des opérateurs

bool operator !=(right: Callable) 🔗

Renvoie true si les deux Callable invoquent des cibles différentes.

bool operator ==(right: Callable) 🔗

Renvoie true si les deux Callables invoquent la même cible personnalisée.