CompositionEvent#
CompositionEvent.initCompositionEvent()#
Metoda initCompositionEvent()
inicjuje dane zdarzenie wartościami przekazanymi do metody.
Składnia#
Samo wywołanie i poszczególne jego części najlepiej objaśnić na zapisie składniowym:
compositionEvent.initCompositionEvent(type, bubbles, cancelable, view, data, locale);
gdzie poszczególne człony oznaczają:
compositionEvent
- zdarzenie będące obiektem kontekstu.type
- typ zdarzenia w postaci łańcucha znakowego. Może to być dowolny łańcuch znakowy (nawet pusty).bubbles
- boolowskietrue
oznacza, że zdarzenie zezwala na obsługę fazy bąbelkowania. Boolowskiefalse
zabrania bąbelkowania.cancelable
- boolowskietrue
oznacza, że domyślne akcje dla zdarzenia mogą zostać anulowane. Boolowskiefalse
nie zezwala na przerywanie domyślnych akcji.view
- obiekt okna lub wartośćnull
.data
- łańcuch znakowy reprezentujący wygenerowane przez metodę wejściową znaki.locale
- łańcuch znakowy reprezentujący język z ustawień regionalnych, w którym metoda wejściowa wygenerowała znaki.
Algorytm wywołania metody initCompositionEvent(type, bubbles, cancelable, view, data, locale)
nie jest skomplikowany. Dla lepszego zrozumienia tematu prezentuję go w całości:
- Wykonaj inicjowanie z typem
type
, bąbelkowaniembubbles
oraz anulowaniemcancelable
na obiekcie kontekstu, a następnie ustaw kolejno jego właściwośćview
naview
,data
nadata
orazlocale
nalocale
.
Inicjowanie zdarzeń metodą initCompositionEvent()
jest obowiązkowe w przypadku niezaufanych zdarzeń, przed ich wysłaniem za pomocą metody EventTarget.dispatchEvent()
, które utworzone zostały za pomocą polecenia Document.createEvent()
. Zdarzenia tworzone za pomocą konstruktora new CompositionEvent()
, i pochodnych, są inicjowane automatycznie. Także zaufane zdarzenia są inicjowane automatycznie przez daną implementacje.
W ramach uzupełnienia warto przeanalizować wady i zalety poszczególnych poleceń odpowiedzialnych za tworzenie niezaufanych zdarzeń.
Jeśli metoda initCompositionEvent()
jest wielokrotnie wywoływana przed wysłaniem zdarzenia, to pod uwagę brane jest ostatnie takie wywołanie. Jeśli metoda initCompositionEvent()
zostanie wywołana w trakcie propagacji zdarzenia (np. przez jakiś uchwyt zdarzenia), to nie powoduje ona żadnego efektu i musi zostać natychmiastowo zakończona.
Ze względów bezpieczeństwa zdarzenia modyfikowane przy użyciu metody initCompositionEvent()
muszą ustawiać wartość właściwości Event.isTrusted
na boolowskie false
.
Prosty przykład:
<script>
// Tworzymy nowe zdarzenie z domyślnymi wartościami
var compositionEvent = document.createEvent("CompositionEvent");
document.write(compositionEvent); // [object CompositionEvent]
document.write("<br>");
document.write(compositionEvent.type); // "" - pusty łańcuch
document.write("<br>");
document.write(compositionEvent.bubbles); // false
document.write("<br>");
document.write(compositionEvent.cancelable); // false
document.write("<br>");
document.write(compositionEvent.view); // null
document.write("<br>");
document.write(compositionEvent.detail); // 0
document.write("<br>");
document.write(compositionEvent.data); // "" - pusty łańcuch
document.write("<br>");
document.write(compositionEvent.locale); // "" - pusty łańcuch
document.write("<br>");
document.write(compositionEvent.defaultPrevented); // false
document.write("<br>");
document.write(compositionEvent.isTrusted); // false
document.write("<br>");
document.write(compositionEvent.eventPhase); // 0
document.write("<br>");
document.write(compositionEvent.timeStamp); // liczba całkowita z wartością zależną od chwili uruchomienia przykładu
document.write("<br>");
document.write(compositionEvent.currentTarget); // null
document.write("<br>");
document.write(compositionEvent.target); // null
document.write("<br><br>");
compositionEvent.initCompositionEvent("piesek", true, true,
window, "husky", "pl"); // inicjujemy zdarzenie własnymi wartościami
document.write(compositionEvent); // [object CompositionEvent]
document.write("<br>");
document.write(compositionEvent.type); // piesek
document.write("<br>");
document.write(compositionEvent.bubbles); // true
document.write("<br>");
document.write(compositionEvent.cancelable); // true
document.write("<br>");
document.write(compositionEvent.view); // [object Window]
document.write("<br>");
document.write(compositionEvent.detail); // 0
document.write("<br>");
document.write(compositionEvent.data); // husky
document.write("<br>");
document.write(compositionEvent.locale); // pl
document.write("<br>");
document.write(compositionEvent.defaultPrevented); // false
document.write("<br>");
document.write(compositionEvent.isTrusted); // false
document.write("<br>");
document.write(compositionEvent.eventPhase); // 0
document.write("<br>");
document.write(compositionEvent.timeStamp); // liczba całkowita z wartością zależną od chwili uruchomienia przykładu
document.write("<br>");
document.write(compositionEvent.currentTarget); // null
document.write("<br>");
document.write(compositionEvent.target); // null
</script>
Metodę initCompositionEvent()
pozostawiono ze względu na polecenie Document.createEvent()
. Warto nadmienić, że po zakończeniu obsługi wszystkich faz zdarzenia może ono zostać ponownie wysłane. Dzięki metodzie initCompositionEvent()
można zmienić jego podstawowe parametry, co byłoby niemożliwe przy wykorzystaniu właściwości zdarzeń, ponieważ są one tylko do odczytu.
Interfejs Web IDL#
void initCompositionEvent(DOMString type, boolean bubbles, boolean cancelable, Window? view, DOMString data, DOMString locale);