MouseEvent#
new MouseEvent()#
Interfejs MouseEvent może być wywoływany w roli konstruktora, dzięki czemu pozwala na bezpośrednie tworzenie nowych zdarzeń myszy (syntetycznych) wprost z interfejsu. Przy tworzeniu nowego zdarzenia od razu ustalany jest jego typ (pierwszy argument) oraz specyficzne cechy ustawiane za pomocą opcjonalnego słownika MouseEventInit (drugi argument).
Składnia#
Samo wywołanie i poszczególne jego części najlepiej objaśnić na zapisie składniowym:
var new_mouseEvent = new MouseEvent(type [, mouseEventInitDict]);
gdzie poszczególne człony oznaczają:
new_mouseEvent- referencja do nowego zdarzenia.type- typ zdarzenia w postaci łańcucha znakowego. Może to być dowolny łańcuch znakowy (nawet pusty).mouseEventInitDict- opcjonalny obiekt określający szczegółowe kryteria inicjalizacji zdarzenia. Oto dostępne właściwości dla obiektu:bubbles- boolowskietrueoznacza, że zdarzenie zezwala na obsługę fazy bąbelkowania. Domyślną wartością jest boolowskiefalse(dziedziczone z EventInit).cancelable- boolowskietrueoznacza, że domyślne akcje dla zdarzenia mogą zostać anulowane. Domyślną wartością jest boolowskiefalse(dziedziczone z EventInit).view- obiekt okna lub wartośćnull. Domyślną wartością jest wartośćnull(dziedziczone z UIEventInit).detail- szczegółowe informacje w postaci liczby całkowitej. Domyślną wartością jest0(dziedziczone z UIEventInit).screenX- współrzędna pozioma miejsca wystąpienia zdarzenia w stosunku do ekranu urządzenia. Domyślną wartością jest0.screenY- współrzędna pionowa miejsca wystąpienia zdarzenia w stosunku do ekranu urządzenia. Domyślną wartością jest0.clientX- współrzędna pozioma miejsca wystąpienia zdarzenia w stosunku do obszaru operacyjnego. Domyślną wartością jest0.clientY- współrzędna pionowa miejsca wystąpienia zdarzenia w stosunku do obszaru operacyjnego. Domyślną wartością jest0.altKey- boolowskietrueoznacza aktywność klawisza alternatywy w chwili wysłania zdarzenia. Domyślną wartością jest boolowskiefalse.ctrlKey- boolowskietrueoznacza aktywność klawisza kontrolnego w chwili wysłania zdarzenia. Domyślną wartością jest boolowskiefalse.metaKey- boolowskietrueoznacza aktywność klawisza mety w chwili wysłania zdarzenia. Domyślną wartością jest boolowskiefalse.shiftKey- boolowskietrueoznacza aktywność klawisza zmiany w chwili wysłania zdarzenia. Domyślną wartością jest boolowskiefalse.button- liczba całkowita reprezentującą aktywność konkretnego przycisku w chwili wysłania zdarzenia. Domyślną wartością jest0.buttons- liczba całkowita w postaci maski bitowej reprezentująca stany wszystkich przycisków w chwili wysłania zdarzenia. Domyślną wartością jest0.relatedTarget- dodatkowy obiekt, który jest powiązany z nowym zdarzeniem. Domyślną wartością jest wartośćnull.
Na podstawie współrzędnych
clientXiclientYimplementacje mogą obliczać inne współrzędne, jak np. współrzędne celu lub inne rozszerzające właściwości zdarzeń myszy (np.pageXczypageY).
Algorytm wywołania konstruktora new MouseEvent(type, mouseEventInitDict) nie jest skomplikowany. Dla lepszego zrozumienia tematu prezentuję go w całości:
- Zwróć nowe zdarzenie myszy za pomocą algorytmu tworzenia zdarzenia z typem
typei słownikiemmouseEventInitDict(jeśli występuje).
Obiekt zwracany przez konstruktor new MouseEvent() implementuje interfejs MouseEvent, dlatego ma dostęp do wszystkich poleceń z tego interfejsu (oraz z kolejnych interfejsów w łańcuchu dziedziczenia). Warto podkreślić, że i opcjonalny słownik MouseEventInit dziedziczy ze słownika UIEventInit, dlatego ma dostęp do wszystkich jego członków w chwili przekazania do konstruktora.
Nowy obiekt zdarzenia będzie miał ustawiane domyślne wartości dla wszystkich swoich właściwości i dodatkowo zostanie automatycznie zainicjowany zgodnie z przekazanymi argumentami przy jego wywołaniu, w przeciwieństwie do polecenia Document.createEvent(), dlatego może być od razu wysłany za pomocą metody EventTarget.dispatchEvent().
W ramach uzupełnienia warto przeanalizować wady i zalety poszczególnych poleceń odpowiedzialnych za tworzenie niezaufanych zdarzeń.
Ze względów bezpieczeństwa zdarzenia generowane przy użyciu konstruktora new MouseEvent() muszą ustawiać wartość właściwości Event.isTrusted na boolowskie false.
Prosty przykład:
<script>
// Tworzymy nowe zdarzenie
var mouseEvent1 = new MouseEvent("piesek");
document.write(mouseEvent1); // [object MouseEvent]
document.write("<br>");
document.write(mouseEvent1.type); // piesek
document.write("<br>");
document.write(mouseEvent1.bubbles); // false
document.write("<br>");
document.write(mouseEvent1.cancelable); // false
document.write("<br>");
document.write(mouseEvent1.view); // null
document.write("<br>");
document.write(mouseEvent1.detail); // 0
document.write("<br>");
document.write(mouseEvent1.screenX); // 0
document.write("<br>");
document.write(mouseEvent1.screenY); // 0
document.write("<br>");
document.write(mouseEvent1.clientX); // 0
document.write("<br>");
document.write(mouseEvent1.clientY); // 0
document.write("<br>");
document.write(mouseEvent1.altKey); // false
document.write("<br>");
document.write(mouseEvent1.ctrlKey); // false
document.write("<br>");
document.write(mouseEvent1.metaKey); // false
document.write("<br>");
document.write(mouseEvent1.shiftKey); // false
document.write("<br>");
document.write(mouseEvent1.button); // 0
document.write("<br>");
document.write(mouseEvent1.buttons); // 0
document.write("<br>");
document.write(mouseEvent1.relatedTarget); // null
document.write("<br>");
document.write(mouseEvent1.defaultPrevented); // false
document.write("<br>");
document.write(mouseEvent1.isTrusted); // false
document.write("<br>");
document.write(mouseEvent1.eventPhase); // 0
document.write("<br>");
document.write(mouseEvent1.timeStamp); // liczba całkowita z wartością zależną od chwili uruchomienia przykładu
document.write("<br>");
document.write(mouseEvent1.currentTarget); // null
document.write("<br>");
document.write(mouseEvent1.target); // null
document.write("<br><br>");
// Tworzymy kolejne zdarzenie
var mouseEvent2 = new MouseEvent("piesek", {
bubbles: true,
cancelable: true,
view: window,
detail: 69,
screenX: 50,
screenY: 100,
clientX: 150,
clientY: 200,
altKey: true,
ctrlKey: true,
metaKey: true,
shiftKey: true,
button: 1,
buttons: 7,
relatedTarget: document.documentElement
});
document.write(mouseEvent2); // [object MouseEvent]
document.write("<br>");
document.write(mouseEvent2.type); // piesek
document.write("<br>");
document.write(mouseEvent2.bubbles); // true
document.write("<br>");
document.write(mouseEvent2.cancelable); // true
document.write("<br>");
document.write(mouseEvent2.view); // [object Window]
document.write("<br>");
document.write(mouseEvent2.detail); // 69
document.write("<br>");
document.write(mouseEvent2.screenX); // 50
document.write("<br>");
document.write(mouseEvent2.screenY); // 100
document.write("<br>");
document.write(mouseEvent2.clientX); // 150
document.write("<br>");
document.write(mouseEvent2.clientY); // 200
document.write("<br>");
document.write(mouseEvent2.altKey); // true
document.write("<br>");
document.write(mouseEvent2.ctrlKey); // true
document.write("<br>");
document.write(mouseEvent2.metaKey); // true
document.write("<br>");
document.write(mouseEvent2.shiftKey); // true
document.write("<br>");
document.write(mouseEvent2.button); // 1
document.write("<br>");
document.write(mouseEvent2.buttons); // 7
document.write("<br>");
document.write(mouseEvent2.relatedTarget); // [object HTMLHtmlElement]
document.write("<br>");
document.write(mouseEvent2.defaultPrevented); // false
document.write("<br>");
document.write(mouseEvent2.isTrusted); // false
document.write("<br>");
document.write(mouseEvent2.eventPhase); // 0
document.write("<br>");
document.write(mouseEvent2.timeStamp); // liczba całkowita z wartością zależną od chwili uruchomienia przykładu
document.write("<br>");
document.write(mouseEvent2.currentTarget); // null
document.write("<br>");
document.write(mouseEvent2.target); // null
</script>Na chwilę obecną wszystkie aktualne przeglądarki pozwalają na wywoływanie interfejsu MouseEvent w roli konstruktora, oczywiście z wyjątkiem IE11.
Interfejs Web IDL#
[Constructor(DOMString type, optional MouseEventInit mouseEventInitDict)]
interface MouseEvent : UIEvent {
};
dictionary MouseEventInit : UIEventInit {
long screenX = 0;
long screenY = 0;
long clientX = 0;
long clientY = 0;
boolean ctrlKey = false;
boolean shiftKey = false;
boolean altKey = false;
boolean metaKey = false;
short button = 0;
unsigned short buttons = 0;
EventTarget? relatedTarget = null;
};