Objetos de evento

Tipos de objetos de evento

Todo objeto de evento tem um tipo de evento associado. Os tipos de evento são armazenados na propriedade Event.type como valores de sequência. Isso é útil para saber o tipo de objeto de evento, de modo que seu código possa distinguir entre objetos de tipos diferentes. Por exemplo, o código a seguir especifica que a função do ouvinte clickHandler() deve responder a qualquer objeto de evento de clique de mouse transmitido para myDisplayObject :

myDisplayObject.addEventListener(MouseEvent.CLICK, clickHandler);

Vinte e quatro tipos de evento são associados à classe Event propriamente dita e representados por constantes da classe Event; alguns deles são mostrados no trecho a seguir da definição da 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 
    } 
}

Essas constantes facilitam a referência a tipos de evento específicos. Use essas constantes em vez das strings que representam. Se você digitar o nome de uma constante incorretamente no código, o compilador detectará o erro, mas, se as strings forem utilizadas, um erro tipográfico talvez não se manifeste no tempo de compilação e gere um comportamento inesperado difícil de depurar. Por exemplo, ao adicionar um ouvinte de evento, use o seguinte código:

myDisplayObject.addEventListener(MouseEvent.CLICK, clickHandler);

em vez de:

myDisplayObject.addEventListener("click", clickHandler);

Informações de comportamento padrão

Seu código pode verificar se o comportamento padrão de um objeto de evento determinado pode ser impedido, acessando a propriedade cancelable . A propriedade cancelable tem um valor booliano que indica se um comportamento padrão pode ou não ser impedido. Você pode impedir ou cancelar o comportamento padrão associado a um pequeno número de eventos, usando o método preventDefault() . Para obter mais informações, consulte Cancelamento do comportamento padrão do evento em Noções básicas dos métodos da classe Event .

Informações sobre o fluxo de evento

As demais propriedades da classe Event contêm informações importantes sobre um objeto de evento e sua relação com o fluxo de evento, conforme descrito na lista a seguir:

• A propriedade bubbles contém informações sobre as partes do fluxo nas quais o objeto de evento participa.

• A propriedade eventPhase indica a fase atual no fluxo de evento.

• A propriedade target armazena uma referência ao destino do evento.

• A propriedade currentTarget armazena uma referência ao objeto da lista de exibição que está processando o objeto de evento no momento.

A propriedade bubbles

Um evento é animado se seu objeto participa da fase de bolhas do fluxo de evento, o que significa que o objeto de evento volta do nó de destino para seu ancestral até chegar ao palco. A propriedade Event.bubbles armazena um valor booliano que indica se o objeto de evento participa na fase de bolhas. Como todos os eventos que são animados também participam nas fases de captura e de destino, qualquer evento animado participa das três fases do fluxo de evento. Se o valor for true , o objeto de evento participará das três fases. Se o valor for false , o objeto de evento não participará na fase de bolhas.

A propriedade eventPhase

Você pode determinar a fase de qualquer objeto de evento investigando a propriedade eventPhase . A propriedade eventPhase contém um valor inteiro sem sinal que representa uma das três fases do fluxo de evento. A API do Flash Player define uma classe EventPhase separada que contém três constantes que correspondem a três valores inteiros sem sinal, como mostra o seguinte trecho de código:

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

Essa constantes correspondem a três valores válidos da propriedade eventPhase . Você pode usar essas constantes para deixar seu código mais legível. Por exemplo, se desejar assegurar que uma função myFunc() seja chamada somente se o destino do evento estiver no palco de destino, use o código a seguir para testar essa condição:

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

A propriedade target

A propriedade target armazena uma referência ao objeto que é o destino do evento. Em alguns casos, isso é simples, como quando um microfone é ativado; o destino do objeto de evento é o objeto Microphone. No entanto, se o destino estiver na lista de exibição, a hierarquia da lista deve ser levada em consideração. Por exemplo, se o usuário inserir um clique de mouse em um ponto que inclui objetos sobrepostos da lista de exibição, o Flash Player e o AIR sempre escolherão o objeto mais distante do palco como destino do evento.

Para arquivos SWF complexos, especialmente aqueles nos quais os botões são decorados regularmente com objetos filho menores, a propriedade target talvez não seja usada com frequência porque, em geral, apontará para o objeto filho de um botão, não para o botão. Nesses casos, a prática comum é adicionar ouvintes de evento ao botão e usar a propriedade currentTarget que aponta para o botão, já que a propriedade target pode apontar para um filho do botão.

A propriedade currentTarget

A propriedade currentTarget contém uma referência ao objeto que está processando o objeto de evento no momento. Embora possa parecer estranho não saber qual nó está processando o objeto de evento que você está examinando no momento, é possível adicionar uma função de ouvinte a qualquer objeto de exibição do fluxo desse objeto de evento; a função de ouvinte pode ser colocada em qualquer lugar. Além disso, a mesma função de ouvinte pode ser adicionada a diferentes objetos de exibição. À medida que aumenta o tamanho e a complexidade de um projeto, a propriedade currentTarget fica cada vez mais útil.

Métodos utilitários da classe Event

Existem dois métodos de utilitário na classe Event. O método clone() permite criar cópias de um objeto de evento. O método toString() permite gerar uma representação de string das propriedades de um objeto de evento juntamente com os respectivos valores. Esses dois métodos são usados internamente pelo sistema de modelo de evento, mais são expostos aos desenvolvedores para uso geral.

Para desenvolvedores avançados que criam subclasses de Event, é necessário substituir e implementar versões dos dois métodos de utilitário para garantir que a subclasse funcione corretamente.

Interrupção do fluxo de evento

Você pode chamar o método Event.stopPropagation() ou o método Event.stopImmediatePropagation() para impedir que um objeto de evento continue seu percurso no fluxo. Os dois métodos são praticamente idênticos e diferem apenas quanto aos ouvintes de evento do nó atual que podem ser executados:

• O método Event.stopPropagation() impede que o objeto de evento se mova para o próximo nó, mas só depois que algum outro ouvinte de evento do nó atual tenha permissão para ser executado.

• O método Event.stopImmediatePropagation() também impede que o objeto de evento se mova para o próximo nó, mas não permite que outros ouvintes de evento do nó atual sejam executados.

Chamar um desses métodos não afeta a ocorrência do comportamento padrão associado a um evento. Use os métodos do comportamento padrão da classe Event para impedir tal comportamento.

Cancelamento de comportamento de evento padrão

Os dois métodos pertinentes ao cancelamento de comportamento padrão são os métodos preventDefault() e isDefaultPrevented() . Chame o método preventDefault() para cancelar o comportamento padrão associado ao evento. Para verificar se preventDefault() já foi chamado em um objeto de evento, chame o método isDefaultPrevented() , que retorna o valor true se o método já tiver sido chamado; caso contrário, retornará false .

O método preventDefault() só funcionará se o comportamento padrão do evento puder ser cancelado. Para verificar isso, consulte a documentação da API para esse tipo de evento ou use o ActionScript para examinar a propriedade cancelable do objeto de evento.

Cancelar o comportamento padrão não tem nenhum efeito no andamento de um objeto de evento através do fluxo de evento. Use os métodos de fluxo de evento da classe Event para remover um objeto de evento do fluxo de evento.