Oggetti evento

Tipi di oggetti evento

Ogni oggetto evento è associato a un tipo di evento. I tipi di evento sono registrati nella proprietà Event.type sotto forma di valori stringa. È utile conoscere il tipo a cui appartiene un oggetto evento per permettere al codice di distinguere tra loro gli oggetti che appartengono a tipi diversi. L'esempio di codice seguente specifica che la funzione listener clickHandler() deve rispondere a qualsiasi oggetto evento click del mouse passato a myDisplayObject :

myDisplayObject.addEventListener(MouseEvent.CLICK, clickHandler);

Alla classe Event sono associate circa una ventina di tipi di evento che sono rappresentati da costanti della classe Event. Alcune di queste costanti sono indicate nella porzione di codice che rappresenta la definizione della classe Event:

package flash.events 
{ 
    public class Event 
    { 
        // class constants 
        public static const ACTIVATE:String = "activate"; 
        public static const ADDED:String= "added"; 
        // remaining constants omitted for brevity 
    } 
}

Queste costanti rappresentano un modo semplice per fare riferimento a tipi di evento specifici. Si consiglia di usare le costanti al posto delle stringhe che rappresentano perché il compilatore è in grado di rilevare un eventuale errore di ortografia nel nome di una costante. Se invece fate un errore di ortografia in una stringa, l'errore potrebbe passare inosservato in fase di compilazione ma generare comportamenti imprevisti che sarebbero difficili da individuare in seguito. Per aggiungere un listener di eventi, ad esempio, utilizzate il codice seguente:

myDisplayObject.addEventListener(MouseEvent.CLICK, clickHandler);

anziché:

myDisplayObject.addEventListener("click", clickHandler);

Informazioni sui comportamenti predefiniti

Il codice può verificare se è possibile disattivare il comportamento predefinito di un oggetto evento analizzando la proprietà cancelable . La proprietà cancelable contiene un valore booleano che indica se un comportamento predefinito può essere disattivato. Potete disattivare, cioè annullare, il comportamento predefinito associato a un piccolo numero di eventi usando il metodo preventDefault() . Per ulteriori informazioni, vedete la sezione Disattivazione del comportamento predefinito di un evento in Nozioni fondamentali sui metodi della classe Event .

Informazioni sul flusso di eventi

Le proprietà rimanenti della classe Event contengono informazioni importanti sull'oggetto evento e il suo rapporto con il flusso di eventi, come descritto nell'elenco seguente:

• La proprietà bubbles contiene informazioni sulle parti del flusso a cui l'oggetto evento partecipa.

• La proprietà eventPhase indica la fase corrente del flusso di eventi.

• La proprietà target registra un riferimento al destinatario dell'evento.

• La proprietà currentTarget registra un riferimento all'oggetto dell'elenco di visualizzazione che sta elaborando l'oggetto evento.

La proprietà bubbles

Se un oggetto evento partecipa alla fase di bubbling del flusso di eventi significa che l'oggetto evento viene fatto risalire dal nodo target fino allo stage. La proprietà Event.bubbles registra un valore booleano che indica se l'oggetto evento partecipa alla fase di bubbling. Dal momento che gli eventi che partecipano alla fase di bubbling partecipano anche alle fasi di cattura e target, se il valore della proprietà è true , l'oggetto evento partecipa a tutte le tre fasi. Se il valore è false , l'oggetto evento non partecipa alla fase di bubbling.

La proprietà eventPhase

Per stabilire la fase in cui si trova un oggetto evento è sufficiente analizzarne la proprietà eventPhase . La proprietà eventPhase contiene un valore intero senza segno che rappresenta una delle tre fasi del flusso di eventi. L'API Flash Player definisce una classe EventPhase separata che contiene tre costanti che corrispondono ai tre valori interi senza segno, come dimostra la seguente porzione di codice:

package flash.events 
{ 
    public final class EventPhase 
    { 
        public static const CAPTURING_PHASE:uint = 1; 
        public static const AT_TARGET:uint = 2; 
        public static const BUBBLING_PHASE:uint= 3; 
    } 
}

Queste costanti corrispondono ai tre valori validi della proprietà eventPhase e concorrono a rendere il codice più leggibile. Per fare in modo, ad esempio, che la funzione myFunc() sia chiamata solo se il destinatario dell'evento si trova nella fase target, potete usare il codice seguente per verificare questa condizione:

if (event.eventPhase == EventPhase.AT_TARGET) 
{ 
    myFunc(); 
}

La proprietà target

La proprietà target contiene un riferimento all'oggetto che rappresenta il destinatario dell'evento. In alcuni casi il destinatario è semplice: quando un microfono diventa attivo, il destinatario dell'evento è l'oggetto Microphone. Se il destinatario si trova nell'elenco di visualizzazione, tuttavia, è necessario considerare anche la gerarchia dell'elenco di visualizzazione. Se, ad esempio, un utente esegue un clic del mouse in un punto che comprende più oggetti dell'elenco di visualizzazione sovrapposti, Flash Player e AIR scelgono come destinatario dell'evento l'oggetto più distante dallo stage.

Nei file SWF particolarmente complessi, in particolare quelli in cui i pulsanti sono normalmente decorati con piccoli oggetti secondari, la proprietà target spesso può non essere utilizzata poiché punterebbe a un oggetto secondario e non al pulsante. Un metodo comunemente usato in questi casi consiste nell'aggiungere listener di eventi al pulsante e usare la proprietà currentTarget perché ha la particolarità di puntare al pulsante, mentre la proprietà target potrebbe puntare a un oggetto secondario del pulsante.

La proprietà currentTarget

La proprietà currentTarget contiene un riferimento all'oggetto che sta elaborando l'oggetto evento. Anche se può apparire strano non sapere quale nodo sta attualmente elaborando l'oggetto evento che si sta analizzando, considerate che potete aggiungere una funzione listener a qualsiasi oggetto di visualizzazione del flusso dell'oggetto e che la funzione listener può essere inserita in qualsiasi posizione. Inoltre, la stessa funzione listener può essere aggiunta a vari oggetti di visualizzazione. Man mano che la dimensione e la complessità di un progetto crescono, la proprietà currentTarget diventa sempre più utile.

Metodi di utilità della classe Event

Esistono due metodi di utilità nella classe Event. Il metodo clone() permette di creare copie di un oggetto evento, mentre il metodo toString() permette di convertire in stringa le proprietà e i relativi valori di un oggetto evento. Entrambi questi metodi vengono utilizzati internamente dal sistema di gestione degli eventi ma sono disponibili anche per gli sviluppatori.

Per gli sviluppatori esperti che creano sottoclassi della classe Event: affinché la sottoclasse della classe Event funzioni correttamente, è necessario sostituire e implementare le versioni di entrambi i metodi di utilità.

Arresto del flusso di eventi

Per interrompere il tragitto dell'oggetto evento lungo il flusso di eventi, potete chiamare il metodo Event.stopPropagation() o il metodo Event.stopImmediatePropagation() . L'unica differenza tra i due metodi è la possibilità di eseguire gli altri listener di eventi del nodo corrente:

• Il metodo Event.stopPropagation() impedisce all'oggetto evento di passare al nodo seguente solo una volta eseguiti gli altri listener di eventi del nodo corrente.

• Anche il metodo Event.stopImmediatePropagation() impedisce all'oggetto evento di passare al nodo seguente, ma non permette l'esecuzione degli altri listener di eventi del nodo corrente.

La chiamata a uno di questi due metodi non influisce sull'esecuzione del comportamento predefinito associato a un evento. Per impedire l'esecuzione di un comportamento predefinito, usate i metodi dei comportamenti predefiniti della classe Event.

Annullamento del comportamento predefinito di eventi

I due metodi che agiscono sulla disattivazione del comportamento predefinito sono il metodo preventDefault() e il metodo isDefaultPrevented() . Chiamate il metodo preventDefault() per annullare un comportamento predefinito associato a un evento. Per verificare se preventDefault() è già stato chiamato su un oggetto evento, chiamate il metodo isDefaultPrevented() che restituisce il valore true se il metodo è già stato chiamato oppure il valore false in caso contrario.

Il metodo preventDefault() funziona solo se il comportamento predefinito dell'evento può essere disattivato. Per accertarvi di questa possibilità, vedete la documentazione API relativa a quel tipo di evento o usare ActionScript per analizzare la proprietà cancelable dell'oggetto evento.

La disattivazione del comportamento predefinito non influisce sull'avanzamento dell'oggetto evento all'interno del flusso di eventi. Usate i metodi del flusso di eventi della classe Event per eliminare un oggetto evento dal flusso di eventi.