Aan HTML gerelateerde gebeurtenissen in AIR afhandelen

Adobe AIR 1.0 of hoger

Met een systeem voor gebeurtenisafhandeling kunnen programmeurs op een gemakkelijke manier reageren op gebruikersinvoer en systeemgebeurtenissen. Het Adobe® AIR®-gebeurtenismodel is niet alleen handig, maar voldoet ook aan de standaarden. Het gebeurtenismodel is gebaseerd op de DOM (Document Object Model) Level 3 Events Specification, een industriestandaard voor de gebeurtenisafhandelingsarchitectuur, en bevat een krachtig en toch intuïtief gebeurtenisafhandelingsmechanisme voor programmeurs.

HTMLLoader-gebeurtenissen

Een HTMLLoader-object verzendt de volgende Adobe® ActionScript® 3.0-gebeurtenissen:

Gebeurtenis

Beschrijving

htmlDOMInitialize

Wordt verzonden wanneer het HTML-document wordt gemaakt, maar voordat scripts worden geparseerd of DOM-knooppunten worden toegevoegd aan de pagina.

complete

Wordt verzonden wanneer het HTML DOM is gemaakt als reactie op een laadbewerking onmiddellijk na de gebeurtenis onload in de HTML-pagina.

htmlBoundsChanged

Wordt verzonden wanneer een van de eigenschappen contentWidth of contentHeight (of allebei) is gewijzigd.

locationChange

Wordt verzonden wanneer de eigenschap location van de HTMLLoader is gewijzigd.

locationChanging

Verzonden voordat de locatie van HTMLLoader verandert door gebruikersnavigatie, een JavaScript-aanroep of een omleiding. De gebeurtenis locationChanging wordt niet verzonden wanneer u de methoden load() , loadString() , reload() , historyGo() , historyForward() of historyBack() aanroept.

Als u de methode preventDefault() van het verzonden gebeurtenisobject aanroept, wordt de navigatie geannuleerd.

Als een koppeling wordt geopend in de systeembrowser, wordt er geen locationChanging-gebeurtenis verzonden, aangezien de locatie van HTMLLoader niet verandert.

scroll

Wordt altijd verzonden wanneer de HTML-engine de scrollpositie wijzigt. Scroll-gebeurtenissen kunnen plaatsvinden vanwege navigatie naar ankerkoppelingen ( # -koppelingen) op de pagina of vanwege het oproepen van de methode window.scrollTo() . De gebeurtenis scroll kan ook worden veroorzaakt door het invoeren van tekst in een tekstinvoergebied of tekstgebied.

uncaughtScriptException

Wordt verzonden wanneer in de HTMLLoader een JavaScript-uitzondering optreedt waarvoor geen voorziening is getroffen in de JavaScript-code.

U kunt ook een ActionScript-functie registreren voor een JavaScript-gebeurtenis (zoals onClick ). Zie DOM-gebeurtenissen afhandelen met ActionScript voor meer informatie.

DOM-gebeurtenissen afhandelen met ActionScript

U kunt ActionScript-functies registreren zodat ze reageren op JavaScript-gebeurtenissen. Kijk bijvoorbeeld naar de volgende HTML-inhoud: 

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

U kunt een ActionScript-functie registreren als handler voor een willekeurige gebeurtenis in de pagina. Met de volgende code voegt u bijvoorbeeld de functie clickHandler() toe als listener voor de gebeurtenis onclick van het element testLink in de HTML-pagina: 

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 ); 
}

Het verzonden gebeurtenisobject is niet van het type flash.events.Event of een van de Event-subklassen. Gebruik de Objectklasse om een type van het functieargument van de gebeurtenishandler te declareren.

U kunt ook de methode addEventListener() gebruiken om te registreren voor deze gebeurtenissen. U kunt bijvoorbeeld de methode completeHandler() in het vorige voorbeeld vervangen door de volgende code: 

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

Wanneer een listener verwijst naar een specifiek DOM-element, is het aan te raden te wachten totdat de bovenliggende HTMLLoader de gebeurtenis complete heeft verzonden alvorens de gebeurtenislisteners toe te voegen. HTML-pagina's laden vaak meerdere bestanden en het HTML DOM wordt pas volledig samengesteld als alle bestanden zijn geladen en geparseerd. De HTMLLoader verzendt de gebeurtenis complete wanneer alle elementen zijn gemaakt.

Reageren op niet-onderschepte JavaScript-uitzonderingen

Bekijk de volgende HTML-code: 

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

Deze bevat de JavaScript-functie throwError() , die verwijst naar de onbekende variabele melbaToast : 

var x = 400 * melbaToast;

Als een JavaScript-bewerking een ongeldige bewerking tegenkomt die niet in de JavaScript-code wordt onderschept via een try / catch -structuur, verzendt het HTMLLoader-object dat de pagina bevat, de gebeurtenis HTMLUncaughtScriptExceptionEvent. U kunt een handler voor deze gebeurtenis registreren, zoals in de volgende code: 

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); 
    } 
}

Binnen JavaScript kunt u dezelfde gebeurtenis afhandelen via de eigenschap 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>

De gebeurtenishandler htmlErrorHandler() annuleert het standaardgedrag van de gebeurtenis (dat wil zeggen, het verzenden van een JavaScript-foutbericht naar de AIR trace-output) en genereert een eigen outputbericht. Deze output bevat de waarde van de exceptionValue van het HTMLUncaughtScriptExceptionEvent-object. De output bevat de eigenschappen van ieder object in de stackTrace -array: 

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

Runtimegebeurtenissen afhandelen met JavaScript

De runtimeklassen ondersteunen het toevoegen van gebeurtenishandlers met de methode addEventListener() . Om een handlerfunctie voor een gebeurtenis toe te voegen, roept u de methode addEventListener() op van het object dat de gebeurtenis verzendt. U geeft hierbij het gebeurtenistype en de afhandelingsfunctie op. Als u bijvoorbeeld wilt luisteren naar de gebeurtenis closing die wordt verzonden wanneer een gebruiker op het sluitvak van een venster op de titelbalk klikt, gebruikt u de volgende opdracht: 

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

Gebeurtenishandlerfuncties maken

Met de volgende code maakt u een eenvoudig HTML-bestand dat informatie weergeeft over de positie van het hoofdvenster. Een handlerfunctie met de naam moveHandler() luistert naar een verplaatsingsgebeurtenis (gedefinieerd door de klasse NativeWindowBoundsEvent) van het hoofdvenster. 

<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>

Wanneer een gebruiker het venster verplaatst, geven de textarea-elementen de bijgewerkte X- en Y-positie van het venster weer:

Het gebeurtenisobject wordt als argument doorgegeven aan de methode moveHandler() . Met de parameter event kan uw handlerfunctie het gebeurtenisobject onderzoeken. In dit voorbeeld gebruikt u de eigenschap type van het gebeurtenisobject om te rapporteren dat de gebeurtenis van het type move is.

Gebeurtenislisteners verwijderen

U kunt de methode removeEventListener() gebruiken om een gebeurtenislistener te verwijderen die u niet meer nodig hebt. Het is raadzaam om alle listeners die niet meer worden gebruikt, te verwijderen. Vereiste parameters zijn onder meer de parameters eventName en listener . Dit zijn dezelfde vereiste parameters als voor de methode addEventListener() .

Gebeurtenislisteners verwijderen in HTML-pagina's die navigeren

Wanneer HTML-inhoud navigeert, of wanneer HTML-inhoud wordt verwijderd omdat een venster dat deze inhoud bevat wordt gesloten, worden de gebeurtenislisteners die verwijzen naar objecten op de ongeladen pagina, niet automatisch verwijderd. Wanneer een object een gebeurtenis verzendt naar een handler die al is verwijderd, wordt er een foutmelding weergegeven dat de toepassing heeft geprobeerd te verwijzen naar een JavaScript-object in een HTML-pagina die niet meer is geladen.

Om deze fout te voorkomen, verwijdert u JavaScript-gebeurtenislisteners in een HTML-pagina voordat deze verdwijnt. In het geval van paginanavigatie (binnen een HTMLLoader-object) verwijdert u de gebeurtenislistener tijdens de gebeurtenis unload van het window -object.

De volgende JavaScript-code verwijdert bijvoorbeeld een gebeurtenislistener voor de gebeurtenis uncaughtScriptException : 

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

Om te voorkomen dat de fout optreedt wanneer vensters met HTML-inhoud worden gesloten, roept u een opschoningsfunctie op als reactie op de gebeurtenis closing van het NativeWindow-object ( window.nativeWindow ). De volgende JavaScript-code verwijdert bijvoorbeeld een gebeurtenislistener voor de gebeurtenis uncaughtScriptException : 

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

U kunt deze fout ook voorkomen door een gebeurtenishandler te verwijderen wanneer deze wordt uitgevoerd (als de gebeurtenis slechts eenmaal moet worden uitgevoerd). De volgende JavaScript-code maakt bijvoorbeeld een HTML-venster door de methode createRootWindow() van de klasse HTMLLoader op te roepen; hier wordt een gebeurtenislistener voor de gebeurtenis complete toegevoegd. Wanneer de gebeurtenishandler complete wordt opgeroepen, verwijdert deze zijn eigen gebeurtenislistener met behulp van de functie 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"));

Door overbodige gebeurtenislisteners te verwijderen, kan de opschoonfunctie van het systeem ook het geheugen vrijmaken dat is gekoppeld aan die listeners.

Controleren op bestaande gebeurtenislisteners

Met de methode hasEventListener() kunt u controleren op de aanwezigheid van gebeurtenislisteners op een object.