Obiekty zdarzeń

Flash Player 9 i nowsze wersje, Adobe AIR 1.0 i nowsze wersje

Obiekty zdarzeń mają dwie funkcje w nowym systemie obsługi zdarzeń. Po pierwsze: obiekty zdarzeń reprezentują rzeczywiste zdarzenia, ponieważ zapisują informacje o konkretnych zdarzeniach w zestawie właściwości. Po drugie: obiekty zdarzeń zawierają zestaw metod, które umożliwiają manipulowanie obiektami zdarzeń oraz wpływają na zachowanie systemu obsługi zdarzeń.

Interfejs API programu Flash Player zawiera definicję klasy Event, która ułatwia dostęp do tych właściwości i metod, a ponadto służy jako klasa podstawowa dla wszystkich obiektów zdarzeń. Klasa Event definiuje podstawowy zestaw właściwości i metod, które są wspólne dla wszystkich obiektów zdarzeń.

Niniejsza sekcja rozpoczyna się od opisu właściwości klasy Event, następnie zawiera opis metod klasy Event, a kończy się wyjaśnieniem przyczyny powstania klasy Event.

Omówienie właściwości klasy Event

Klasa Event definiuje pewną liczbę właściwości i stałych tylko do odczytu, które udostępniają istotne informacje o obiekcie zdarzenia. Poniżej przedstawiono najważniejsze z nich:

  • Typy obiektów Event są reprezentowane przez stałe i zapisywane we właściwości Event.type .

  • Informacja o tym, czy można zapobiec domyślnemu zachowaniu zdarzenia, jest reprezentowana przez wartość logiczną i zapisana we właściwości Event.cancelable .

  • Informacje o strumieniu zdarzenia są zawarte w pozostałych właściwościach.

Typy obiektów zdarzeń

Z każdym obiektem zdarzenia skojarzony jest typ zdarzenia. Typy zdarzeń są zapisane we właściwości Event.type jako wartości ciągu. Znajomość typu obiektu zdarzenia jest bardzo użyteczna — dzięki temu kod może odróżniać obiekty określonych typów od innych. Na przykład: poniższy kod określa, że funkcja detektora clickHandler() powinna reagować na obiekty zdarzenia click, które zostały przekazane do myDisplayObject :

myDisplayObject.addEventListener(MouseEvent.CLICK, clickHandler);

Z samą klasą Event skojarzonych jest ponad dwadzieścia typów zdarzeń i te typy są reprezentowane przez stałe klasy Event, a niektóre z nich zostały przedstawione w poniższym fragmencie definicji klasy 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 
    } 
}

Te stałe stanowią łatwy sposób odwołania do określonych typów zdarzeń. Należy korzystać z tych stałych zamiast z ciągów, które reprezentują. Jeśli nazwa stałej zostanie błędnie wpisana do kodu, kompilator znajdzie błąd, ale jeśli zamiast stałej zostaną wykorzystane ciągi, wówczas może się zdarzyć, że błąd w pisowni nie zostanie znaleziony podczas kompilacji, a to może prowadzić do nieoczekiwanego zachowania, które może być trudne do zdebugowania. Przykład: podczas dodawania detektora zdarzeń należy użyć następującego kodu:

myDisplayObject.addEventListener(MouseEvent.CLICK, clickHandler);

a nie:

myDisplayObject.addEventListener("click", clickHandler);

Informacje o zachowaniu domyślnym

Kod może sprawdzać, czy możliwe jest zapobieganie zachowaniu domyślnemu dowolnego obiektu zdarzenia, uzyskując dostęp do właściwości cancelable . Właściwość cancelable zawiera wartość logiczną, która określa, czy zapobieganie domyślnemu zachowaniu jest możliwe, czy nie. Za pomocą metody preventDefault() można zapobiegać zachowaniom domyślnym skojarzonym z niewielką liczbą zdarzeń. Więcej informacji zawiera sekcja Anulowanie domyślnego zachowania zdarzenia w rozdziale Omówienie metod klasy Event .

Informacje o przepływie zdarzenia

Pozostałe właściwości klasy Event zawierają istotne informacje o obiekcie zdarzenia oraz o jego relacji ze strumieniem zdarzenia, co zostało przedstawione w poniższej liście:

  • Właściwość bubbles zawiera informacje o częściach strumienia zdarzenia, w których uczestniczy obiekt zdarzenia.

  • Właściwość eventPhase wskazuje bieżącą fazę w strumieniu zdarzenia.

  • Właściwość target zawiera odwołanie do celu zdarzenia.

  • Właściwość currentTarget zawiera odwołanie do obiektu listy wyświetlania, który aktualnie przetwarza obiekt zdarzenia.

Właściwość bubbles

Zdarzenie propaguje, gdy obiekt zdarzenia uczestniczy w fazie propagacji strumienia zdarzeń, co oznacza, że obiekt zdarzenia jest przekazywany z węzła docelowego z powrotem przez przodków, aż do węzła Stage. Właściwość Event.bubbles zawiera wartość logiczną, która wskazuje, czy obiekt zdarzenia uczestniczy w fazie propagacji. Wszystkie zdarzenia, które propagują również uczestniczą w fazie przechwytywania i fazie docelowej, dlatego każde zdarzenie, które propaguje, uczestniczy we wszystkich trzech fazach strumienia zdarzenia. Jeśli wartość jest równa true , obiekt zdarzenia uczestniczy we wszystkich trzech fazach. Jeśli wartość jest równa false , obiekt zdarzenia nie uczestniczy w fazie propagacji.

Właściwość eventPhase

Aby określić fazę zdarzenia dla dowolnego obiektu zdarzenia, należy sprawdzić właściwość eventPhase . Właściwość eventPhase zawiera liczbę całkowitą bez znaku, która reprezentuje jedną z trzech faz strumienia zdarzenia. Interfejs API Flash Player zawiera definicję osobnej klasy EventPhase, która zawiera trzy stałe odpowiadające trzem wartościom całkowitym bez znaku, które przedstawiono w poniższym fragmencie kodu:

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

Te stałe odpowiadają trzem poprawnym wartościom właściwości eventPhase . Korzystanie z tych stałych sprawia, że kod jest bardziej czytelny. Na przykład: aby zapewnić wywoływanie funkcji myFunc() tylko wówczas, gdy cel zdarzenia znajduje się w fazie docelowej, można użyć poniższego kodu w celu testowania tego warunku:

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

Właściwość target

Właściwość target zawiera odwołanie do obiektu, który jest celem zdarzenia. W niektórych przypadkach odwołanie jest bezpośrednie, np. gdy mikrofon staje się aktywny, wówczas celem obiektu zdarzenia jest obiekt Microphone. Jeśli cel znajduje się na liście wyświetlania, wówczas konieczne jest uwzględnienie hierarchii listy wyświetlania. Na przykład: jeśli użytkownik kliknie punkt, który zawiera nachodzące na siebie obiekty listy wyświetlania, programy Flash Player i AIR zawsze wybierają na cel zdarzenia obiekt, który znajduje się najdalej od węzła Stage.

Dla złożonych plików SWF, szczególnie tych, w których przyciski są rutynowo dekorowane mniejszymi obiektami podrzędnymi, właściwość target nie może być często używana, ponieważ często wskazuje na obiekt podrzędny przycisku zamiast na przycisk. W tych sytuacjach zwykle dodaje się detektory zdarzeń do przycisku, a także używa się właściwości currentTarget , ponieważ wskazuje na przycisk, a właściwość target może wskazywać na obiekt podrzędny przycisku.

Właściwość currentTarget

Właściwość currentTarget zawiera odwołanie do obiektu listy wyświetlania, który aktualnie przetwarza obiekt zdarzenia. Mimo że nieznajomość węzła, który aktualnie przetwarza badany obiekt zdarzenia, może wydawać się dziwna, jednak należy pamiętać o tym, że do każdego obiektu wyświetlanego w strumieniu tego obiektu zdarzenia można dodać funkcję detektora, a funkcja detektora może zostać umieszczona w dowolnym miejscu. Ponadto tę samą funkcję detektora można dodać do różnych obiektów wyświetlanych. W miarę wzrostu wielkości i złożoności projektu właściwość currentTarget staje się coraz bardziej użyteczna.

Omówienie metod klasy Event

Istnieją trzy kategorie metod klasy Event:

  • Metody narzędziowe, które mogą tworzyć kopie obiektu zdarzenia lub konwertować obiekt na ciąg

  • Metody strumienia zdarzenia, które usuwają obiekty zdarzenia ze strumienia zdarzenia

  • Metody zachowania domyślnego, które zapobiegają zachowaniu domyślnemu lub sprawdzają, czy takie zachowanie zostało już anulowane

Metody narzędziowe klasy Event

Klasa Event zawiera dwie metody narzędziowe. Metoda clone() umożliwia tworzenie kopii obiektu zdarzenia. Metoda toString() umożliwia generowanie reprezentacji właściwości obiektu zdarzenia wraz z ich wartościami w postaci ciągu. Obydwie te metody są używane wewnętrznie przez system modelu zdarzenia, ale są również dostępne dla programistów, którzy mogą z nich korzystać.

Zaawansowani programiści tworzący podklasy klasy Event muszą zastępować i implementować wersje obydwu metod narzędziowych, aby zapewnić, że podklasa Event będzie działała poprawnie.

Zatrzymywanie strumienia zdarzenia

Aby zapobiec przesuwaniu obiektu zdarzenia w strumieniu zdarzenia, należy wywołać metodę Event.stopPropagation() lub metodę Event.stopImmediatePropagation() . Obydwie te metody są niemal identyczne i odróżnia je tylko to, czy umożliwiają działanie innych detektorów zdarzeń bieżącego węzła:

  • Metoda Event.stopPropagation() zapobiega przesunięciu obiektu zdarzenia do kolejnego węzła, ale tylko wówczas, gdy możliwe jest uruchomienie innych detektorów zdarzeń w bieżącym węźle.

  • Metoda Event.stopImmediatePropagation() również zapobiega przesunięciu obiektu zdarzeń do kolejnego węzła, ale nie zezwala na uruchamianie innych detektorów zdarzeń w bieżącym węźle.

Wywołanie dowolnej z tych metod nie ma wpływu na to, czy wystąpi zachowanie domyślne skojarzone ze zdarzeniem. Aby zapobiegać zachowaniu domyślnemu, należy użyć metod zachowania domyślnego klasy Event.

Anulowanie domyślnego zachowania zdarzenia

Dwie metody, które są związane z anulowaniem domyślnego działania, to: preventDefault() i isDefaultPrevented() . Wywołując metodę preventDefault() , można anulować zachowanie domyślne skojarzone ze zdarzeniem. Aby sprawdzić, czy metoda preventDefault() została już wywołana w obiekcie zdarzenia, wywołaj metodę isDefaultPrevented() , która zwraca wartość true po wywołaniu metody i wartość false w przeciwnym wypadku.

Metoda preventDefault() zadziała tylko wówczas, gdy możliwe jest anulowanie domyślnego zachowania zdarzenia. Aby sprawdzić, czy jest to możliwe, należy zapoznać się z dokumentacją API dotyczącą zdarzeń określonego typu, lub użyć języka ActionScript w celu sprawdzenia właściwości cancelable konkretnego obiektu zdarzenia.

Anulowanie zachowania domyślnego nie ma wpływu na postęp obiektu zdarzenia w strumieniu zdarzenia. Aby usunąć obiekt zdarzenia ze strumienia zdarzenia, należy użyć metod strumienia zdarzenia klasy Event.

Podklasy klasy Event

Dla wielu zdarzeń wspólny zestaw właściwości zdefiniowanych w klasie Event jest wystarczający. Jednak inne zdarzenia mają unikalne cechy, które nie mogą być przechwytywane przez właściwości dostępne w klasie Event. Dla tych zdarzeń język ActionScript 3.0 definiuje kilka podklas klasy Event.

Każda podklasa udostępnia dodatkowe właściwości i typy zdarzeń, które są unikalne dla danej kategorii zdarzeń. Na przykład: zdarzenia powiązane z kliknięciem mają kilka unikalnych cech, które nie mogą być przechwytywane przez właściwości zdefiniowane w klasie Event. Klasa MouseEvent stanowi rozszerzenie klasy Event — udostępnia dziesięć właściwości, które zawierają informacje, takie jak lokalizacja zdarzenia myszy i informacje o tym, które przyciski zostały naciśnięte podczas tego zdarzenia.

Podklasa Event również zawiera stałe, które reprezentują typy zdarzeń skojarzone z daną podklasą. Na przykład: klasa MouseEvent definiuje stałe dla kilku typów zdarzeń myszy, między innymi dla typów zdarzeń: click , doubleClick , mouseDown i mouseUp .

Zgodnie z opisem w sekcji Metody narzędziowe klasy Event (w sekcji Obiekty zdarzeń ) — podczas tworzenia podklasy Event należy zastąpić metody clone() i toString() , aby zapewnić funkcjonalność odpowiednią dla danej podklasy.