Attention: Here be dragons

This is the latest (unstable) version of this documentation, which may document features not available in or compatible with released stable versions of Godot.

Checking the stable version of the documentation...

Signal

Un tipo integrato che rappresenta un segnale di un Object.

Descrizione

Signal è un tipo Variant integrato che rappresenta un segnale di un'istanza di Object. Come tutti i tipi di Variant, può essere memorizzato nelle variabili e passato alle funzioni. I segnali consentono a tutti i Callable connessi (e per estensione ai rispettivi oggetti) di ascoltare e reagire agli eventi, senza fare riferimento diretto l'uno all'altro. Questo mantiene il codice flessibile e più facile da gestire. È possibile verificare se un Object ha il nome di un segnale specifico tramite Object.has_signal().

In GDScript, è possibile dichiarare i segnali con la parola chiave signal. In C#, è possibile utilizzare l'attributo [Signal] su un delegato.

signal attacked

# È possibile dichiarare argomenti aggiuntivi.
# Questi argomenti devono essere passati quando viene emesso il segnale.
signal item_dropped(item_name, amount)

[Signal]
delegate void AttackedEventHandler();

// È possibile dichiarare argomenti aggiuntivi.
// Questi argomenti devono essere passati quando viene emesso il segnale.
[Signal]
delegate void ItemDroppedEventHandler(string itemName, int amount);

La connessione dei segnali è una delle operazioni più comuni in Godot e l'API offre numerose opzioni per farlo, descritte più avanti. Il blocco di codice seguente mostra l'approccio consigliato.

func _ready():
    var button = Button.new()
    # `button_down` qui è un tipo Variant di Signal. Pertanto, chiamiamo il metodo Signal.connect(), non Object.connect().
    # Vedi la discussione seguente per una panoramica più approfondita dell'API.
    button.button_down.connect(_on_button_down)

    # Questo presuppone che esista una classe `Player`, che definisce un segnale `hit`.
    var player = Player.new()
    # # Usiamo di nuovo Signal.connect() e anche il metodo Callable.bind(),
    # che restituisce un nuovo Callable con il parametro binds.
    player.hit.connect(_on_player_hit.bind("sword", 100))

func _on_button_down():
    print("Button down!")

func _on_player_hit(weapon_type, damage):
    print("Hit with weapon %s for %d damage." % [weapon_type, damage])

public override void _Ready()
{
    var button = new Button();
    // C# consente di passare i segnali come eventi, quindi possiamo usare questo costrutto idiomatico:
    button.ButtonDown += OnButtonDown;

    // Questo presuppone che esista una classe `Player`, che definisce un segnale `Hit`.
    var player = new Player();
    // Possiamo usare le lambda quando dobbiamo associare parametri aggiuntivi.
    player.Hit += () => OnPlayerHit("sword", 100);
}

private void OnButtonDown()
{
    GD.Print("Button down!");
}

private void OnPlayerHit(string weaponType, int damage)
{
    GD.Print($"Hit with weapon {weaponType} for {damage} damage.");
}

Object.connect() o Signal.connect()?

Come visto in precedenza, il metodo consigliato per connettere i segnali non è Object.connect(). Il blocco di codice seguente mostra le quattro opzioni per connettere i segnali, utilizzando questo metodo legacy o il connect() consigliato, e utilizzando un Callable implicito o uno definito manualmente.

func _ready():
    var button = Button.new()
    # Opzione 1: Object.connect() con un Callable implicito per la funzione definita.
    button.connect("button_down", _on_button_down)
    # Opzione 2: Object.connect() con un Callable costruito con un oggetto di destinazione e il nome di un metodo.
    button.connect("button_down", Callable(self, "_on_button_down"))
    # Opzione 3: Signal.connect() con un Callable implicito per la funzione definita.
    button.button_down.connect(_on_button_down)
    # Opzione 4: Signal.connect() con un Callable costruito con un oggetto di destinazione e il nome di un metodo.
    button.button_down.connect(Callable(self, "_on_button_down"))

func _on_button_down():
    print("Button down!")

public override void _Ready()
{
    var button = new Button();
    // Opzione 1: In C#, possiamo usare i segnali come eventi e connetterlicon questa sintassi idiomatica:
    button.ButtonDown += OnButtonDown;
    // Opzione 2: GodotObject.Connect() con un Callable costruito da un gruppo di metodi.
    button.Connect(Button.SignalName.ButtonDown, Callable.From(OnButtonDown));
    // Opzione 3: GodotObject.Connect() con un Callable costruito con un oggetto di destinazione e il nome di un metodo.
    button.Connect(Button.SignalName.ButtonDown, new Callable(this, MethodName.OnButtonDown));
}

private void OnButtonDown()
{
    GD.Print("Button down!");
}

Sebbene tutte le opzioni abbiano lo stesso risultato (il segnale BaseButton.button_down di button sarà connesso a _on_button_down), l'opzione 3 offre la migliore validazione: stamperà un errore in fase di compilazione se il Signal button_down o il Callable _on_button_down non sono definiti. D'altra parte, l'opzione 2 dipende solo dai nomi in stringa e sarà in grado di validare solo uno dei due nomi in fase di esecuzione: genererà un errore in fase di esecuzione se "button_down" non è un segnale, o se "_on_button_down" non è un metodo nell'oggetto self. Il motivo principale per utilizzare le opzioni 1, 2 o 4 è quando le stringhe servono effettivamente (ad esempio, per connettere segnali in modo programmatico, in base a stringhe lette da un file di configurazione). Altrimenti, l'opzione 3 è il metodo consigliato (e il più veloce).

Associazione e passaggio di parametri:

La sintassi per l'associazione dei parametri è tramite Callable.bind(), che restituisce una copia del Callable con i suoi parametri associati.

Quando si chiama emit() o Object.emit_signal(), è possibile passare anche i parametri di un segnale. Gli esempi seguenti mostrano la relazione tra questi parametri di un segnale e i parametri associati.

func _ready():
    # Questo presuppone che esista una classe `Player`, che definisce un segnale `hit`.
    var player = Player.new()
    # Tramite Callable.bind().
    player.hit.connect(_on_player_hit.bind("sword", 100))

    # I parametri aggiunti al l'emissione del segnale vengono passati per primi.
    player.hit.emit("Dark lord", 5)

# Passiamo due argomenti all'emissione (`hit_by`, `level`),
# e ne associamo altri due alla connessione (`weapon_type`, `damage`).
func _on_player_hit(hit_by, level, weapon_type, damage):
    print("Hit by %s (level %d) with weapon %s for %d damage." % [hit_by, level, weapon_type, damage])

public override void _Ready()
{
    // Questo presuppone che esista una classe `Player`, che definisce un segnale `Hit`.
    var player = new Player();
    // Tramite espressioni lambda che creano una chiusura che cattura i parametri aggiuntivi.
    // La lambda riceve solo i parametri definiti dal delegato del segnale.
    player.Hit += (hitBy, level) => OnPlayerHit(hitBy, level, "sword", 100);

    // I parametri aggiunti al l'emissione del segnale vengono passati per primi.
    player.EmitSignal(SignalName.Hit, "Dark lord", 5);
}

// Passiamo due argomenti all'emissione (`hit_by`, `level`),
// e ne associamo altri due alla connessione (`weapon_type`, `damage`).
private void OnPlayerHit(string hitBy, int level, string weaponType, int damage)
{
    GD.Print($"Hit by {hitBy} (level {level}) with weapon {weaponType} for {damage} damage.");
}

Nota: In un contesto booleano, un segnale verrà valutato come false se è nullo (vedi is_null()). Altrimenti, un segnale verrà sempre valutato come true.

Nota

Ci sono differenze sostanziali quando si usa questa API con C#. Vedi Differenze dell'API C# rispetto a GDScript per maggiori informazioni.

Tutorial

Costruttori

Signal	Signal()
Signal	Signal(from: Signal)
Signal	Signal(object: Object, signal: StringName)

Metodi

int	connect(callable: Callable, flags: int = 0)
void	disconnect(callable: Callable)
void	emit(...) vararg const
Array	get_connections() const
StringName	get_name() const
Object	get_object() const
int	get_object_id() const
bool	has_connections() const
bool	is_connected(callable: Callable) const
bool	is_null() const

Operatori

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

Descrizioni dei costruttori

Signal Signal() 🔗

Costruisce un Signal vuoto senza oggetto né nome di segnale associato.

Signal Signal(from: Signal)

Costruisce un Signal come copia del Signal specificato.

Signal Signal(object: Object, signal: StringName)

Crea un nuovo oggetto Signal che fa riferimento a un segnale denominato signal nell'oggetto object.

Descrizioni dei metodi

int connect(callable: Callable, flags: int = 0) 🔗

Collega questo segnale al chiamabile callable. È possibile aggiungere anche flags facoltativi per configurare il comportamento della connessione (vedi le costanti di ConnectFlags). È possibile fornire argomenti aggiuntivi al callable connesso tramite Callable.bind().

Un segnale può essere connesso solo una volta allo stesso Callable. Se il segnale è già connesso, restituisce @GlobalScope.ERR_INVALID_PARAMETER e invia un messaggio di errore, a meno che il segnale non sia connesso con Object.CONNECT_REFERENCE_COUNTED. Per evitare ciò, usa prima is_connected() per verificare le connessioni esistenti.

for button in $Buttons.get_children():
    button.pressed.connect(_on_pressed.bind(button))

func _on_pressed(button):
    print(button.name, " was pressed")

Nota: Se l'oggetto del callable è liberato, la connessione sarà persa.

void disconnect(callable: Callable) 🔗

Disconnette questo segnale dal Callable specificato. Se la connessione non esiste, genera un errore. Usa is_connected() per assicurarti che la connessione esista.

void emit(...) vararg const 🔗

Emette questo segnale. Tutti i Callable connessi a questo segnale verranno attivati. Questo metodo supporta un numero variabile di argomenti, quindi i parametri possono essere passati come un elenco separato da virgole.

Array get_connections() const 🔗

Restituisce un Array di connessioni per questo segnale. Ogni connessione è rappresentata come Dictionary che contiene tre voci:

signal è un riferimento a questo segnale;
callable è un riferimento al Callable connesso;
flags è una combinazione di ConnectFlags.

StringName get_name() const 🔗

Restituisce il nome di questo segnale.

Object get_object() const 🔗

Restituisce l'oggetto che emette questo segnale.

int get_object_id() const 🔗

Restituisce l'ID dell'oggetto che emette questo segnale (vedi Object.get_instance_id()).

bool has_connections() const 🔗

Restituisce true se qualsiasi Callable è collegato a questo segnale.

bool is_connected(callable: Callable) const 🔗

Restituisce true se il Callable specificato è collegato a questo segnale.

bool is_null() const 🔗

Restituisce true se questo Signal non ha un oggetto e il nome del segnale è vuoto. Equivale a signal == Signal().

Descrizioni degli operatori

bool operator !=(right: Signal) 🔗

Restituisce true se i segnali non condividono lo stesso oggetto e nome.

bool operator ==(right: Signal) 🔗

Restituisce true se entrambi i segnali condividono lo stesso oggetto e nome.