Tratamento de eventos relacionados a HTML no AIR

Adobe AIR 1.0 e posterior

O sistema de tratamento de eventos permite que os programadores respondam às entradas de usuários e eventos do sistema de forma conveniente. O modelo de evento do Adobe® AIR® não é apenas conveniente, mas também compatível com os padrões. Com base na Especificação de eventos DOM (Modelo de objeto de documento) de Nível 3, uma arquitetura de tratamento de eventos padrão do segmento, o modelo de evento oferece uma ferramenta de tratamento de eventos eficiente e intuitiva para programadores.

eventos HTMLLoader

O objeto HTMLLoader despacha os seguintes eventos do Adobe® ActionScript®3.0:

Evento

Descrição

htmlDOMInitialize

Despachado quando o documento HTML é criado, mas antes que qualquer script seja analisado ou que os nós DOM sejam adicionados à página.

complete

Despachado quando o HTML DOM tiver sido criado em resposta à operação de carregamento, logo após o evento onload na página HTML.

htmlBoundsChanged

Despachado quando uma ou as duas propriedades contentWidth e contentHeight são alteradas.

locationChange

Despachado quando a propriedade location do HTMLLoader foi alterada.

locationChanging

Despachado antes que o local do HTMLLoader seja alterado por causa da navegação do usuário, de uma chamada do JavaScript ou de um redirecionamento. O evento locationChanging não é despachado quando os métodos load() , loadString() , reload() , historyGo() , historyForward() e historyBack() são chamados.

A chamada do método preventDefault() do objeto event despachado cancela a navegação.

Se um link for aberto no navegador do sistema, um evento locationChanging não será despachado até que HTMLLoader não seja mudado de local.

scroll

Despachado a sempre que o mecanismo HTML altera a posição de rolagem. Eventos de rolagem podem ocorrer devido à navegação para ancorar links ( nº de links) na página ou devido às chamadas do método window.scrollTo() . Inserir texto em uma entrada de texto ou área de texto também pode gerar um evento de rolagem.

uncaughtScriptException

Despachado quando ocorre uma exceção JavaScript no HTMLLoader e a exceção não é capturada no código JavaScript.

Você também pode registrar uma função ActionScript para o evento JavaScript (como onClick ). Para obter detalhes, consulte Tratamento de eventos DOM com o ActionScript .

Tratamento de eventos DOM com o ActionScript

Você pode registrar as funções do ActionScript para que respondam a eventos JavaScript. Por exemplo, considere o seguinte conteúdo HTML: 

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

Você pode registrar uma função do ActionScript como manipulador de qualquer evento na página. Por exemplo, o código a seguir adiciona a função clickHandler() como o ouvinte do evento onclick do elemento testLink na página 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 ); 
}

O objeto de evento despachado não é do tipo flash.events.Event nem uma das subclasses Event. Use a classe Object para declarar um tipo para o argumento da função de tratamento de evento.

Você também pode usar o método addEventListener() para se registrar para esses eventos. Por exemplo, você pode substituir o método completeHandler() no exemplo anterior pelo seguinte código: 

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

Quando um ouvinte se refere a um elemento DOM específico, é bom aguardar que o HTMLLoader pai despache o evento complete antes de adicionar os ouvintes de evento. As páginas HTML com frequência carregam vários arquivos e o HTML DOM não é criado totalmente até que todos os arquivos sejam carregados e analisados. O HTMLLoader despacha o evento complete quando todos os elementos tiverem sido criados.

Resposta a exceções JavaScript não capturadas

Considere o seguinte HTML: 

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

Ele contém uma função JavaScript, throwError() , que faz referência a uma variável desconhecida, melbaToast : 

var x = 400 * melbaToast;

Quando a operação de JavaScript encontra uma operação ilegal não capturada no código JavaScript com uma estrutura try / catch , o objeto HTMLLoader que contém a página despacha um evento HTMLUncaughtScriptExceptionEvent. Você pode registrar um manipulador para esse evento, como no código a seguir: 

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

No JavaScript, você pode tratar o mesmo evento usando a propriedade 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>

O manipulador de eventos htmlErrorHandler() cancela o comportamento padrão do evento (que é enviar a mensagem de erro de JavaScript para a saída trace do AIR) e gera sua própria mensagem de saída. Ele produz o valor do exceptionValue do objeto HTMLUncaughtScriptExceptionEvent. Ele produz as propriedades de cada objeto na matriz stackTrace : 

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

Tratamento de eventos de tempo de execução com JavaScript

As classes de tempo de execução oferecem suporte à adição de manipuladores de eventos com o método addEventListener() . Para adicionar uma função do manipulador a um evento, chame o método addEventListener() do objeto que despacha o evento, fornecendo o tipo de evento e a função de tratamento. Por exemplo, para ouvir o evento closing despachado quando o usuário clica no botão Fechar da janela na barra de título, use a seguinte instrução: 

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

Criação de função do manipulador de eventos

O código a seguir cria um arquivo HTML simples que exibe informações sobre a posição da janela principal. A função do manipulador, chamada de moveHandler() , ouve o evento move (definido pela classe NativeWindowBoundsEvent) da janela principal. 

<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 o usuário move a janela, os elementos da área de texto exibem as posições X e Y atualizadas da janela:

Observe que o objeto de evento é passado como argumento para o método moveHandler() . O parâmetro event permite que a função do manipulador examine o objeto de evento. Neste exemplo, você usa a propriedade type do objeto de evento para informar que o evento é um evento move .

Remoção de ouvintes de eventos

Você pode usar o método removeEventListener() para remover um ouvinte de evento que não seja mais necessário. É uma boa ideia remover o ouvinte que não será mais usado. Entre os parâmetros obrigatórios estão eventName e listener , que são os mesmos parâmetros obrigatórios no método addEventListener() .

Remoção de ouvintes de eventos nas páginas HTML que navegam

Quando o conteúdo HTML é navegado ou quando é descartado porque a janela que o contém é fechada, os ouvintes de eventos que fazem referência a objetos na página não carregada não são removidos automaticamente. Quando um objeto envia um evento para um manipulador que já foi descarregado, a mensagem de erro a seguir é exibida: "O aplicativo tentou criar uma referência a um objeto JavaScript e uma página HTML que não está mais carregada.”

Para evitar esse tipo de erro, remova os ouvintes de eventos JavaScript da página HTML antes que ele parta. No caso de navegação de página (em um objeto HTMLLoader), remova o ouvinte de evento durante o evento unload do objeto window .

Por exemplo, o código JavaScript a seguir remove um ouvinte de evento de um evento uncaughtScriptException : 

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

Para impedir que o erro ocorra ao fechar janelas que contêm esse conteúdo HTML, chame uma função de limpeza em resposta ao evento closing do objeto NativeWindow ( window.nativeWindow ). Por exemplo, o código JavaScript a seguir remove um ouvinte de evento de um evento uncaughtScriptException : 

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

Você também pode impedir esse erro removendo um ouvinte de evento tão logo seja executado (se o evento só precisar ser tratado uma vez). Por exemplo, o código JavaScript a seguir cria uma janela html chamando o método createRootWindow() da classe HTMLLoader e adiciona um ouvinte de evento ao evento complete . Quando o manipulador de eventos complete é chamado, ele remove o próprio ouvinte de evento usando a função 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"));

Remover ouvintes de evento desnecessários também permite que o coletor de lixo do sistema recupere qualquer memória associada a esses ouvintes.

Verificação da existência de ouvintes de eventos

O método hasEventListener() permite verificar a existência de um ouvinte de evento em um objeto.