Gestione di eventi relativi a HTML in AIR

Adobe AIR 1.0 e versioni successive

Un sistema di gestione degli eventi permette ai programmatori di elaborare risposte adeguate all'input degli utenti e agli eventi del sistema. Il modello di eventi di Adobe® AIR® non è solo utile, ma anche conforme agli standard. Questo modello di eventi, che si basa sulla specifica DOM (Document Object Model) Level 3, un'architettura di gestione degli eventi considerata uno standard del settore, è uno strumento di gestione degli eventi efficace e al contempo intuitivo dedicato ai programmatori.

Eventi HTMLLoader

Un oggetto HTMLLoader invia i seguenti eventi di Adobe® ActionScript®3.0:

Evento

Descrizione

htmlDOMInitialize

Inviato quando si crea il documento HTML, ma prima dell'analisi di qualsiasi script o dell'aggiunta di nodi DOM alla pagina.

complete

Inviato quando l'HTML DOM è stato creato in risposta a un'operazione di carico, immediatamente dopo l'evento onload nella pagina HTML.

htmlBoundsChanged

Inviato quando si sono modificate una o entrambe le proprietà contentWidth e contentHeight .

locationChange

Inviato quando si è modificata la proprietà location dell'HTMLLoader.

locationChanging

Inviato prima che la posizione di HTMLLoader cambi a causa della navigazione utente, una chiamata JavaScript o un reindirizzamento. L'evento locationChanging non viene inviato quando si chiamano i metodi load() , loadString() , reload() , historyGo() , historyForward() o historyBack() .

Se si chiama il metodo preventDefault() dell'evento inviato, l'oggetto annulla la navigazione.

Se si apre un collegamento nel browser di sistema, un evento locationChanging non viene inviato poiché HTMLLoader non cambia posizione.

scroll

Inviato ogni qual volta il motore HTML cambia la posizione di scroll. Possono essere eventi scroll per lo spostamento a collegamenti di ancoraggio ( # ) nella pagina o per chiamate al metodo window.scrollTo() . L'inserimento di testo in un'area testo o ingresso testo può inoltre determinare un evento scroll.

uncaughtScriptException

Inviato quando si verifica un'eccezione JavaScript nell'HTMLLoader e l'eccezione non viene identificata nel codice JavaScript.

È possibile inoltre registrare una funzione ActionScript per un evento JavaScript (come onClick ). Per informazioni dettagliate, consultate Gestione di eventi DOM con ActionScript .

Gestione di eventi DOM con ActionScript

È possibile registrare le funzioni ActionScript per rispondere a eventi JavaScript. Ad esempio, considerate il seguente elemento HTML: 

<html> 
<body> 
    <a href="#" id="testLink">Click me.</a> 
</html>

È possibile registrare una funzione ActionScript come gestore di qualsiasi evento nella pagina. Ad esempio, il codice seguente aggiunge la funzione clickHandler() come listener per l'evento onclick dell'elemento testLink nella pagina HTML: 

var html:HTMLLoader = new HTMLLoader( ); 
var urlReq:URLRequest = new URLRequest("test.html"); 
html.load(urlReq); 
html.addEventListener(Event.COMPLETE, completeHandler); 
 
function completeHandler(event:Event):void { 
    html.window.document.getElementById("testLink").onclick = clickHandler; 
} 
 
function clickHandler( event:Object ):void { 
    trace("Event of type: " + event.type ); 
}

L'oggetto evento inviato non è del tipo flash.events.Event o una delle sottoclassi Event. Utilizzate la classe Object per dichiarare un tipo per l'argomento della funzione di gestione degli eventi.

È possibile utilizzare inoltre il metodo addEventListener() per registrare per questi eventi. Ad esempio, è possibile sostituire il metodo completeHandler() nell'esempio precedente con il codice seguente: 

function completeHandler(event:Event):void { 
    var testLink:Object = html.window.document.getElementById("testLink"); 
    testLink.addEventListener("click", clickHandler); 
}

Quando un listener fa riferimento a un elemento DOM specifico, è consigliabile attendere il principale HTMLLoader per inviare l'evento complete prima di aggiungere i listener di eventi. Le pagine HTML spesso caricano più file e l'HTML DOM non è completamente realizzato finché tutti i file non vengono caricati e analizzati. L'HTMLLoader invia l'elemento complete quando sono stati creati tutti gli elementi.

Risposta a eccezioni JavaScript non identificate

Considerate il seguente codice HTML: 

<html> 
<head> 
    <script> 
        function throwError() { 
            var x = 400 * melbaToast; 
        } 
    </script> 
</head> 
<body> 
    <a href="#" onclick="throwError()">Click me.</a> 
</html>

Contiene una funzione JavaScript, throwError() , che fa riferimento a una variabile sconosciuta, melbaToast : 

var x = 400 * melbaToast;

Quando un'operazione JavaScript rileva un'operazione errata che non è identificata nel codice JavaScript con un struttura try / catch , l'oggetto HTMLLoader contenente la pagina invia un evento HTMLUncaughtScriptExceptionEvent. È possibile registrare un gestore per questo evento, come nel codice seguente: 

var html:HTMLLoader = new HTMLLoader(); 
var urlReq:URLRequest = new URLRequest("test.html"); 
html.load(urlReq); 
html.width = container.width; 
html.height = container.height; 
container.addChild(html); 
html.addEventListener(HTMLUncaughtScriptExceptionEvent.UNCAUGHT_SCRIPT_EXCEPTION, 
                           htmlErrorHandler); 
function htmlErrorHandler(event:HTMLUncaughtJavaScriptExceptionEvent):void  
{ 
    event.preventDefault(); 
    trace("exceptionValue:", event.exceptionValue) 
    for (var i:int = 0; i < event.stackTrace.length; i++) 
    { 
        trace("sourceURL:", event.stackTrace[i].sourceURL); 
        trace("line:", event.stackTrace[i].line); 
        trace("function:", event.stackTrace[i].functionName); 
    } 
}

In JavaScript, è possibile gestire lo stesso evento mediante la proprietà window.htmlLoader: 

<html> 
<head> 
<script language="javascript" type="text/javascript" src="AIRAliases.js"></script> 
 
    <script> 
        function throwError() { 
            var x = 400 * melbaToast; 
        } 
         
        function htmlErrorHandler(event) { 
            event.preventDefault(); 
            var message = "exceptionValue:" + event.exceptionValue + "\n"; 
            for (var i = 0; i < event.stackTrace.length; i++){ 
                message += "sourceURL:" + event.stackTrace[i].sourceURL +"\n"; 
                message += "line:" + event.stackTrace[i].line +"\n"; 
                message += "function:" + event.stackTrace[i].functionName + "\n"; 
            } 
            alert(message); 
        } 
         
        window.htmlLoader.addEventListener("uncaughtScriptException", htmlErrorHandler); 
    </script> 
</head> 
<body> 
    <a href="#" onclick="throwError()">Click me.</a> 
</html>

Il gestore eventi htmlErrorHandler() annulla il comportamento predefinito dell'evento (che deve inviare il messaggio di errore di JavaScript alcun output di tracciamento AIR) e genera il relativo messaggio di output. Emette il valore di exceptionValue dell'oggetto HTMLUncaughtScriptExceptionEvent. Emette la proprietà di ciascun oggetto nell'array stackTrace : 

exceptionValue: ReferenceError: Can't find variable: melbaToast 
sourceURL: app:/test.html 
line: 5 
function: throwError 
sourceURL: app:/test.html 
line: 10 
function: onclick

Gestione di eventi runtime con JavaScript

Le classi runtime supportano altri gestori di eventi con il metodo addEventListener() . Per aggiungere una funzione di gestore per un evento, chiamate il metodo addEventListener() dell'oggetto che invia l'evento, offrendo il tipo di evento e la funzione di gestione. Ad esempio, per intercettare l'evento closing inviato quando un utente fa clic sul pulsante di chiusura della finestra nella barra del titolo, utilizzate la seguente istruzione: 

window.nativeWindow.addEventListener(air.NativeWindow.CLOSING, handleWindowClosing);

Creazione di una funzione di gestore eventi

Il codice seguente crea un semplice file HTML che visualizza informazioni sulla posizione della finestra principale. Un funzione gestore denominata moveHandler() intercetta un evento di spostamento (definito dalla classe NativeWindowBoundsEvent) della finestra principale. 

<html> 
    <script src="AIRAliases.js" /> 
    <script> 
        function init() { 
            writeValues(); 
            window.nativeWindow.addEventListener(air.NativeWindowBoundsEvent.MOVE, 
                                                     moveHandler); 
        } 
        function writeValues() { 
            document.getElementById("xText").value = window.nativeWindow.x; 
            document.getElementById("yText").value = window.nativeWindow.y; 
        } 
        function moveHandler(event) { 
            air.trace(event.type); // move 
            writeValues(); 
        } 
    </script> 
    <body onload="init()" /> 
        <table> 
            <tr> 
                <td>Window X:</td> 
                <td><textarea id="xText"></textarea></td> 
            </tr> 
            <tr> 
                <td>Window Y:</td> 
                <td><textarea id="yText"></textarea></td> 
            </tr> 
        </table> 
    </body> 
</html>

Quando un utente sposta la finestra, gli elementi textarea visualizzano le posizioni X e Y aggiornate della finestra:

Notate che l'oggetto evento viene passato come argomento al metodo moveHandler() . Il parametro evento consente alla funzione del gestore di esaminare l'oggetto evento. In questo esempio, si usa la proprietà type dell'oggetto evento per riportare che l'evento è un evento move .

Eliminazione dei listener di eventi

Per rimuovere i listener di eventi inutilizzati si può usare il metodo removeEventListener() . È buona norma rimuovere i listener diventati superflui. I parametri obbligatori sono eventName e listener , cioè gli stessi parametri del metodo addEventListener() .

Rimozione di listener di eventi in pagine HTML visualizzate

Quando si visualizza contenuto HTML o quando tale contenuto viene eliminato perché una finestra che lo contiene viene chiusa, i listener di eventi che fanno riferimento a oggetti presenti in una pagina non caricata vengono automaticamente rimossi. Quando un oggetto invia un evento a un gestore che è già stato caricato, viene visualizzato il seguente messaggio di errore: “The application attempted to reference a JavaScript object in an HTML page that is no longer loaded.” (L'applicazione ha tentato di fare riferimento a un oggetto JavaScript in un pagina HTML che non è più caricata).

Per evitare questo errore, eliminare i listener di eventi JavaScript in una pagina HTML prima che scompaia. Nel caso di spostamento di pagine (in un oggetto HTMLLoader), eliminare il listener di eventi durante l'evento unload dell'oggetto window .

Ad esempio, il seguente codice JavaScript rimuove un listener di eventi per un oggetto uncaughtScriptException : 

window.onunload = cleanup; 
window.htmlLoader.addEventListener('uncaughtScriptException', uncaughtScriptException); 
function cleanup() 
{ 
    window.htmlLoader.removeEventListener('uncaughtScriptException', 
                            uncaughtScriptExceptionHandler); 
}

Per evitare il verificarsi dell'errore quando si chiudono le finestre contenenti il contenuto HTML, chiamate una funzione di pulizia in risposta all'evento closing dell'oggetto NativeWindow ( window.nativeWindow ). Ad esempio, il seguente codice JavaScript rimuove un listener di eventi per un oggetto uncaughtScriptException : 

window.nativeWindow.addEventListener(air.Event.CLOSING, cleanup); 
function cleanup() 
{ 
    window.htmlLoader.removeEventListener('uncaughtScriptException', 
                            uncaughtScriptExceptionHandler); 
}

Potete inoltre evitare questo errore eliminando un listener di eventi non appena viene eseguito (se l'evento deve essere gestito una sola volta). Ad esempio, il seguente codice JavaScript crea una finestra html chiamando il metodo createRootWindow() della classe HTMLLoader e aggiunge un listener di eventi per l'evento complete . Quando viene chiamato il gestore eventi complete , elimina il relativo listener di eventi mediante la funzione removeEventListener() : 

var html = runtime.flash.html.HTMLLoader.createRootWindow(true); 
html.addEventListener('complete', htmlCompleteListener); 
function htmlCompleteListener() 
{ 
    html.removeEventListener(complete, arguments.callee) 
    // handler code.. 
} 
html.load(new runtime.flash.net.URLRequest("second.html"));

La rimozione di listener di eventi non necessari consente inoltre che il garbage collector del sistema riutilizzi qualsiasi memoria associata a tali listener.

Verifica della presenza di listener di eventi

Il metodo hasEventListener() permette di verificare la presenza di un listener di eventi in un oggetto.