KeyboardEvent#

KeyboardEvent.initKeyboardEvent()#

Metoda initKeyboardEvent() 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:

keyboardEvent.initKeyboardEvent(type, bubbles, cancelable, view,
				key, location, modifiersList, repeat,
				locale);

gdzie poszczególne człony oznaczają:

keyboardEvent - 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 - boolowskie true oznacza, że zdarzenie zezwala na obsługę fazy bąbelkowania. Boolowskie false zabrania bąbelkowania.
cancelable - boolowskie true oznacza, że domyślne akcje dla zdarzenia mogą zostać anulowane. Boolowskie false nie zezwala na przerywanie domyślnych akcji.
view - obiekt okna lub wartość null.
key - łańcuch znakowy reprezentujący wciśnięty klawisz (po uwzględnieniu wszelkich zmian klawiaturowych).
location - liczba całkowita reprezentująca lokalizację klawisza na urządzeniu wejściowym.
modifiersList - łańcuch znakowy reprezentujący klawisz modyfikujący lub listę klawiszy modyfikujących oddzielonych spacjami, które uważane są za aktywne (np. "Ctrl Alt Shift").
repeat - boolowskie true oznacza, że klawisz dla danego zdarzenia był wciśnięty w sposób trwały. Boolowskie false wskazuje na brak trwałości.
locale - łańcuch znakowy reprezentujący język z ustawień regionalnych, w którym klawiatura wygenerowała znaki.

Algorytm wywołania metody initKeyboardEvent(type, bubbles, cancelable, view, key, location, modifiersList, repeat, locale) nie jest skomplikowany. Dla lepszego zrozumienia tematu prezentuję go w całości:

Wykonaj inicjowanie z typem type, bąbelkowaniem bubbles oraz anulowaniem cancelable na obiekcie kontekstu, a następnie ustaw kolejno jego właściwość view na view, key na key, location na location, repeat na repeat, locale na repeat oraz odpowiadające właściwości klawiszy modyfikujących wymienione w modifiersList (jeśli istnieją).

Inicjowanie zdarzeń metodą initKeyboardEvent() 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 KeyboardEvent(), 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 initKeyboardEvent() jest wielokrotnie wywoływana przed wysłaniem zdarzenia, to pod uwagę brane jest ostatnie takie wywołanie. Jeśli metoda initKeyboardEvent() 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 initKeyboardEvent() 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 keyboardEvent = document.createEvent("KeyboardEvent");

	document.write(keyboardEvent); // [object KeyboardEvent]
	document.write("<br>");
	document.write(keyboardEvent.type); // "" - pusty łańcuch
	document.write("<br>");
	document.write(keyboardEvent.bubbles); // false
	document.write("<br>");
	document.write(keyboardEvent.cancelable); // false
	document.write("<br>");
	document.write(keyboardEvent.view); // null
	document.write("<br>");
	document.write(keyboardEvent.detail); // 0
	document.write("<br>");
	document.write(keyboardEvent.key); // "" - pusty łańcuch
	document.write("<br>");
	document.write(keyboardEvent.location); // 0
	document.write("<br>");
	document.write(keyboardEvent.repeat); // false
	document.write("<br>");
	document.write(keyboardEvent.locale); // "" - pusty łańcuch
	document.write("<br>");
	document.write(keyboardEvent.altKey); // false
	document.write("<br>");
	document.write(keyboardEvent.ctrlKey); // false
	document.write("<br>");
	document.write(keyboardEvent.metaKey); // false
	document.write("<br>");
	document.write(keyboardEvent.shiftKey); // false
	document.write("<br>");
	document.write(keyboardEvent.defaultPrevented); // false
	document.write("<br>");
	document.write(keyboardEvent.isTrusted); // false
	document.write("<br>");
	document.write(keyboardEvent.eventPhase); // 0
	document.write("<br>");
	document.write(keyboardEvent.timeStamp); // liczba całkowita z wartością zależną od chwili uruchomienia przykładu
	document.write("<br>");
	document.write(keyboardEvent.currentTarget); // null
	document.write("<br>");
	document.write(keyboardEvent.target); // null

	document.write("<br><br>");

	// Inicjujemy zdarzenie własnymi wartościami
	keyboardEvent.initKeyboardEvent("piesek", true, true, window,
				   "husky", "3", "Alt Control Shift Meta", true,
				   "pl");

	document.write(keyboardEvent); // [object KeyboardEvent]
	document.write("<br>");
	document.write(keyboardEvent.type); // piesek
	document.write("<br>");
	document.write(keyboardEvent.bubbles); // true
	document.write("<br>");
	document.write(keyboardEvent.cancelable); // true
	document.write("<br>");
	document.write(keyboardEvent.view); // [object Window]
	document.write("<br>");
	document.write(keyboardEvent.detail); // 0
	document.write("<br>");
	document.write(keyboardEvent.key); // husky
	document.write("<br>");
	document.write(keyboardEvent.location); // 3
	document.write("<br>");
	document.write(keyboardEvent.repeat); // true
	document.write("<br>");
	document.write(keyboardEvent.locale); // "pl"
	document.write("<br>");
	document.write(keyboardEvent.altKey); // true
	document.write("<br>");
	document.write(keyboardEvent.ctrlKey); // true
	document.write("<br>");
	document.write(keyboardEvent.metaKey); // true
	document.write("<br>");
	document.write(keyboardEvent.shiftKey); // true
	document.write("<br>");
	document.write(keyboardEvent.defaultPrevented); // false
	document.write("<br>");
	document.write(keyboardEvent.isTrusted); // false
	document.write("<br>");
	document.write(keyboardEvent.eventPhase); // 0
	document.write("<br>");
	document.write(keyboardEvent.timeStamp); // liczba całkowita z wartością zależną od chwili uruchomienia przykładu
	document.write("<br>");
	document.write(keyboardEvent.currentTarget); // null
	document.write("<br>");
	document.write(keyboardEvent.target); // null

</script>

Metodę initKeyboardEvent() 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 initKeyboardEvent() można zmienić jego podstawowe parametry, co byłoby niemożliwe przy wykorzystaniu właściwości zdarzeń, ponieważ są one tylko do odczytu.

Na chwilę obecną jedynie przeglądarka IE11 obsługuje metodę initKeyboardEvent() zgodnie z wytycznymi specyfikacji D3E. Chrome nie przestrzega ustalonej ilości i kolejności przy przekazywaniu argumentów do metody, a ekipa Firefoksa zadecydowała, że nigdy jej nie zaimplementuje (ze względu na negatywny wpływ dla wykrywania nieobecnej do tej pory metody).

Interfejs Web IDL#

void initKeyboardEvent(DOMString type, boolean bubbles, boolean cancelable,
		       Window? view, DOMString key, unsigned long location,
		       DOMString modifiersList, boolean repeat, DOMString locale);

Specyfikacje i inne materiały#

DOM Level 3 Events

Mozilla Developer Network

Pasek społecznościowy

WebRef - kursy webowe

KeyboardEvent#

KeyboardEvent.initKeyboardEvent()#

Składnia#

Interfejs Web IDL#

Specyfikacje i inne materiały#