Objetos de evento

Flash Player 9 y posterior, Adobe AIR 1.0 y posterior

Los objetos de evento tienen una doble finalidad en el nuevo sistema de gestión de eventos. Primero, representan los eventos reales, guardando información acerca de eventos concretos en una serie de propiedades. En segundo lugar, los objetos de evento contienen una serie de métodos que permiten manipular los objetos de evento y afectan al comportamiento del sistema de gestión de eventos.

Para facilitar el acceso a estas propiedades y métodos, la API de Flash Player define una clase Event que constituye la clase base de todos los objetos de evento. La clase Event define una serie fundamental de propiedades y métodos que son comunes a todos los objetos de evento.

Esta sección comienza con una explicación de las propiedades de la clase Event, prosigue con una descripción de los métodos de la clase Event y finaliza con un análisis de las razones por las que existen subclases de la clase Event.

Aspectos básicos de las propiedades de la clase Event

La clase Event define una serie de propiedades y constantes de solo lectura que proporcionan información importante acerca de un objeto de evento. Las siguientes son especialmente importantes:

  • Los tipos de objetos de evento se representan mediante constantes y se almacenan en la propiedad Event.type .

  • La posibilidad de impedir el comportamiento predeterminado de un evento se representa mediante un valor booleano y se almacena en la propiedad Event.cancelable .

  • La información del flujo del evento está contenida en las propiedades restantes.

Tipos de objetos de evento

Todos los objetos de evento están asociados a algún tipo de evento. Los tipos de evento se guardan en la propiedad Event.type como valores de cadena. Es útil saber de qué tipo es el objeto de evento para que el código pueda distinguir entre objetos de distintos tipos Por ejemplo, el siguiente código especifica que la función de detector clickHandler() debe responder a cualquier objeto de evento de clic del ratón que se pase a myDisplayObject : 

myDisplayObject.addEventListener(MouseEvent.CLICK, clickHandler);

Existen unos veinte tipos de eventos asociados a la clase Event, los cuales se representan con constantes de clase Event, algunas de las cuales se muestran en el siguiente extracto de la definición de la clase 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 
    } 
}

Estas constantes proporcionan una forma sencilla de hacer referencia a tipos de eventos específicos. Es aconsejable utilizar estas constantes en lugar de las cadenas a las que representan. Si se escribe incorrectamente el nombre de una constante en el código, el compilador detectará el error, pero si se usan cadenas, un error tipográfico podría pasarse por alto durante la compilación y dar lugar a un comportamiento inesperado difícil de depurar. Por ejemplo, al añadir un detector de eventos, es preferible usar el siguiente código: 

myDisplayObject.addEventListener(MouseEvent.CLICK, clickHandler);

en lugar de: 

myDisplayObject.addEventListener("click", clickHandler);

Información sobre el comportamiento predeterminado

El código puede comprobar si el comportamiento predeterminado para un objeto de evento en particular puede impedirse a través de la propiedad cancelable . La propiedad cancelable contiene un valor booleano que indica si es posible impedir un comportamiento predeterminado. Para impedir o cancelar el comportamiento predeterminado asociado con algunos eventos se puede utilizar el método preventDefault() . Para obtener más información, consulte Cancelación del comportamiento predeterminado de eventos en Aspectos básicos de los métodos de la clase Event .

Información sobre el flujo del evento

Las demás propiedades de la clase Event contienen información importante acerca de un objeto de evento y su relación con el flujo del evento, según se describe en la siguiente lista:

  • La propiedad bubbles contiene información acerca de las partes del flujo del evento en el que participa el objeto de evento.

  • La propiedad eventPhase indica la fase en curso del flujo del evento.

  • La propiedad target almacena una referencia al destino del evento.

  • La propiedad currentTarget almacena una referencia al objeto de la lista de visualización que está procesando en ese momento el objeto de evento.

La propiedad bubbles

Se dice que un evento se propaga ("bubbles", en inglés) si su objeto de evento participa en la fase de propagación del flujo del evento, lo que quiere decir que dicho objeto regresa desde el nodo de destino, a través de sus ascendientes, hasta alcanzar el objeto Stage. La propiedad Event.bubbles almacena un valor booleano que indica si el objeto de evento participa en la fase de propagación. Dado que todos los eventos que se propagan también participan en las fases de captura y destino, cualquier evento que se propague participa en las tres fases del flujo del evento. Si el valor es true , el objeto de evento participa en las tres fases. Si es false , el objeto de evento no participa en la fase de propagación.

La propiedad eventPhase

Es posible determinar la fase del evento de un objeto de evento estudiando su propiedad eventPhase. La propiedad eventPhase contiene un valor entero sin signo que representa una de las tres fases del flujo del evento. La API de Flash Player define una clase EventPhase independiente que contiene tres constantes que se corresponden con los tres valores enteros sin signo, según se muestra en el siguiente extracto 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; 
    } 
}

Estas constantes corresponden a los tres valores válidos de la propiedad eventPhase. Es aconsejable usar estas constantes para hacer que el código sea más legible. Por ejemplo, para asegurarse de que una función denominada miFunc() solo se llame si el destino del evento está en la fase de destino, es posible usar el siguiente código para probar dicha condición: 

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

La propiedad target

La propiedad target contiene una referencia al objeto que es el destino del evento. En algunas situaciones esto resulta evidente, como cuando se activa un micrófono, en cuyo caso el destino del objeto de evento es el objeto Microphone. Sin embargo, si el destino se encuentra en la lista de visualización, es necesario tener en cuenta la jerarquía de esta. Por ejemplo, si un usuario hace clic con el ratón en un punto que incluye objetos solapados de la lista de visualización, Flash Player o AIR siempre seleccionan el objeto que se encuentra más lejos del objeto Stage como destino del evento.

En el caso de archivos SWF complejos, especialmente aquellos en los que los botones se decoran sistemáticamente con objetos secundarios menores, la propiedad target no puede usarse con demasiada frecuencia, ya que en muchas ocasiones señalará a los objetos secundarios de los botones en lugar de a los propios botones. En estas situaciones, lo habitual es añadir detectores de eventos al botón y usar la propiedad currentTarget , ya que esta señala al botón, mientras que la propiedad target puede señalar a un elemento secundario del mismo.

La propiedad currentTarget

La propiedad currentTarget contiene una referencia al objeto que está procesando en ese momento al objeto de evento. Aunque puede parecer extraño no saber qué nodo está procesando en ese momento al objeto de evento que se está examinando, es necesario recordar que se puede añadir una función de detector a cualquier objeto de visualización en el flujo del evento de ese objeto de evento y que dicha función puede colocarse en cualquier lugar. Además, es posible añadir la misma función de detector a distintos objetos de visualización. A medida que el tamaño y la complejidad de un proyecto crecen, la propiedad currentTarget resulta cada vez más útil.

Aspectos básicos de los métodos de la clase Event

Existen tres categorías de los métodos de la clase Events:

  • Métodos de utilidad, que pueden crear copias de un objeto de evento o convertirlo en una cadena.

  • Métodos de flujo del evento, que eliminan objetos de evento del flujo del evento.

  • Métodos de comportamiento predeterminado, que impiden que se produzca el comportamiento predeterminado o comprueban si se ha impedido

Métodos de utilidad de la clase Event

Existen dos métodos de utilidad en la clase Event. El método clone() permite crear copias de un objeto de evento. El método toString() permite generar una representación en forma de cadena de las propiedades de un objeto de evento, junto con sus valores. El sistema de modelos de evento usa ambos métodos internamente, pero están a disposición de los desarrolladores para el uso general.

Los desarrolladores avanzados que deseen crear subclases de la clase Event deben sustituir e implementar versiones de ambos métodos de utilidad para asegurarse de que la subclase de eventos funcionará correctamente.

Detener el flujo del evento

Se puede llamar al método Event.stopPropagation() o Event.stopImmediatePropagation() para impedir que un objeto de evento siga moviéndose por el flujo del evento. Ambos métodos son casi idénticos y solo se diferencian en que uno permite que se ejecuten los demás detectores de eventos del nodo en curso y el otro no:

  • El método Event.stopPropagation() impide que el objeto de evento avance hasta el siguiente nodo, pero solo después de permitir que se ejecuten todos los demás detectores de eventos del nodo en curso.

  • El método Event.stopImmediatePropagation() también impide que el objeto de evento avance hasta el siguiente nodo, pero no permite que se ejecute ningún otro detector de eventos del nodo en curso.

Las llamadas a cualquiera de estos dos métodos no afectan a la aplicación del comportamiento predeterminado asociado a un evento. Es necesario usar los métodos de comportamiento predeterminado de la clase Event para impedir dicho comportamiento.

Cancelación del comportamiento predeterminado de un evento

Para cancelar el comportamiento predeterminado hay dos métodos: preventDefault() y isDefaultPrevented() . Para cancelar el comportamiento predeterminado asociado con un evento, llame al método preventDefault() . mientras que para comprobar si ya se ha llamado a preventDefault() en un objeto de evento, es necesario llamar al método isDefaultPrevented() , que devuelve el valor true si ya se ha llamado al método o false en caso contrario.

El método preventDefault() solo funcionará si es posible cancelar el comportamiento predeterminado del evento. Se puede comprobar si esto es posible consultando la documentación de la API para ese tipo de evento o usando ActionScript para examinar la propiedad cancelable del objeto de evento.

La cancelación del comportamiento predeterminado no afecta al progreso de un objeto de evento en el flujo de eventos. Si desea eliminar un objeto de evento del flujo de eventos, utilice los métodos de flujo de eventos de la clase Event.

Subclases de la clase Event

Para muchos eventos es suficiente el conjunto común de propiedades que se definen en la clase Event. No obstante, otros eventos tienen características únicas que no es posible capturar mediante las propiedades de la clase Event. Para estos eventos, ActionScript 3.0 define varias subclases de la clase Event.

Cada subclase brinda propiedades y tipos de eventos adicionales que son exclusivos para esa categoría de eventos. Por ejemplo, los eventos relacionados con la entrada del ratón tienen algunas características únicas que no es posible capturar mediante las propiedades definidas en la clase Event. La clase MouseEvent amplía la clase Event añadiendo diez propiedades que contienen datos como la ubicación del evento de ratón y si se presionaron teclas específicas durante dicho evento.

Las subclases de Event también contienen constantes que representan los tipos de eventos asociados a la subclase. Por ejemplo, la clase MouseEvent define constantes para varios tipos de eventos de ratón e incluye los tipos de evento click , doubleClick , mouseDown y mouseUp .

Tal como se describe en la sección Métodos de utilidad de la clase Event en Objetos de evento , al crear una subclase de Event es necesario sustituir los métodos clone() y toString() para ofrecer una funcionalidad específica de la subclase.