Class pwlib.dom.KeyboardEventListener

A complete keyboard events cross-browser compatibility layer.
Defined in: lib.js.

Class Summary
Constructor Attributes	Constructor Name and Description
	pwlib.dom.KeyboardEventListener(elem_, handlers_) A complete keyboard events cross-browser compatibility layer.

Field Summary
Field Attributes	Field Name and Description
<private> <inner>	char_ During a keyboard event flow, this holds the current character, starting from the `keypress` event.
<private> <inner>	charCode_ During a keyboard event flow, this holds the current character code, starting from the `keypress` event.
<private> <inner>	key_ During a keyboard event flow, this holds the current key, starting from the `keydown` event.
<private> <inner>	keyCode_ During a keyboard event flow, this holds the current key code, starting from the `keydown` event.
<private> <inner>	repeat_ True if the current keyboard event is repeating.

Method Summary
Method Attributes	Method Name and Description
	attach() Attach the keyboard event listeners to the current DOM element.
	detach() Detach the keyboard event listeners from the current DOM element.
<private> <inner>	dispatch(type, ev) Dispatch an event.
<private> <inner>	findCharCode(ev) Determine the character and the character code for the current DOM Event object.
<private> <inner>	findKeyCode(ev) Determine the key and the key code for the current DOM Event object.
<private> <inner>	firesKeyPress(ev) Tells if the current Web browser will fire the `keypress` event for the current `keydown` event object.
<private> <inner>	isModifierKey(key) Tells if the `key` is a modifier or not.
<private> <inner>	keydown(ev) The `keydown` event handler.
<private> <inner>	keypress(ev) The `keypress` event handler.
<private> <inner>	keyup(ev) The `keyup` event handler.

Class Detail

pwlib.dom.KeyboardEventListener(elem_, handlers_)

A complete keyboard events cross-browser compatibility layer.

Unfortunately, due to the important differences across Web browsers, simply using the available properties in a single keyboard event is not enough to accurately determine the key the user pressed. Thus, one needs to have event handlers for all keyboard-related events keydown, keypress and keyup.

This class provides a complete keyboard event compatibility layer. For any new instance you provide the DOM element you want to listen events for, and the event handlers for any of the three events keydown / keypress / keyup.

Your event handlers will receive the original DOM Event object, with several new properties defined:

event.keyCode_ holds the correct code for event key.
event.key_ holds the key the user pressed. It can be either a key name like "PageDown", "Delete", "Enter", or it is a character like "A", "1", or "[".
event.charCode_ holds the Unicode character decimal code.
event.char_ holds the character generated by the event.
event.repeat_ is a boolean property telling if the keypress event is repeated - the user is holding down the key for a long-enough period of time to generate multiple events.

The character-related properties, charCode_ and char_ are only available in the keypress and keyup event objects.

This class will ensure that the keypress event is always fired in Webkit and MSIE for all keys, except modifiers. For modifier keys like Shift, Control, and Alt, the keypress event will not be fired, even if the Web browser does it.

Some user agents like Webkit repeat the keydown event while the user holds down a key. This class will ensure that only the keypress event is repeated.

If you want to prevent the default action for an event, you should prevent it on keypress. This class will prevent the default action for keydown if need (in MSIE).

var klogger = function (ev) {
  console.log(ev.type +
    ' keyCode_ ' + ev.keyCode_ +
    ' key_ ' + ev.key_ +
    ' charCode_ ' + ev.charCode_ +
    ' char_ ' + ev.char_ +
    ' repeat_ ' + ev.repeat_);
};

var kbListener = new pwlib.dom.KeyboardEventListener(window,
              {keydown: klogger,
               keypress: klogger,
               keyup: klogger});

// later when you're done...
kbListener.detach();

Parameters:
{Element} elem_: The DOM Element you want to listen events for.
{Object} handlers_: The object holding the list of event handlers associated to the name of each keyboard event you want to listen. To listen for all the three keyboard events use {keydown: fn1, keypress: fn2, keyup: fn3}.

Throws:
{TypeError}: If the handlers_ object does not contain any event handler.

Field Detail

<private> <inner> {String} char_

During a keyboard event flow, this holds the current character, starting from the keypress event.

<private> <inner> {Number} charCode_

During a keyboard event flow, this holds the current character code, starting from the keypress event.

<private> <inner> {String} key_

During a keyboard event flow, this holds the current key, starting from the keydown event.

<private> <inner> {Number} keyCode_

During a keyboard event flow, this holds the current key code, starting from the keydown event.

<private> <inner> {Boolean} repeat_

True if the current keyboard event is repeating. This happens when the user holds down a key for longer periods of time.

Method Detail

attach()

Attach the keyboard event listeners to the current DOM element.

detach()

Detach the keyboard event listeners from the current DOM element.

<private> <inner> dispatch(type, ev)

Dispatch an event.

This function simply invokes the handler for the event of the given type. The handler receives the ev event.

Parameters:
{String} type: The event type to dispatch.
{Event} ev: The DOM Event object to dispatch to the handler.

<private> <inner> findCharCode(ev)

Determine the character and the character code for the current DOM Event object. This function updates the charCode_ and the char_ variables to hold the result.

Parameters:
{Event} ev: The DOM Event object.

<private> <inner> findKeyCode(ev)

Determine the key and the key code for the current DOM Event object. This function updates the keyCode_ and the key_ variables to hold the result.

Parameters:
{Event} ev: The DOM Event object.

<private> <inner> {Boolean} firesKeyPress(ev)

Tells if the current Web browser will fire the keypress event for the current keydown event object.

Parameters:
{Event} ev: The DOM Event object.

Returns:: {Boolean} True if the Web browser will fire a keypress event, or false if not.

<private> <inner> {Boolean} isModifierKey(key)

Tells if the key is a modifier or not.

Parameters:
{String} key: The key name.

Returns:: {Boolean} True if the key is a modifier, or false if not.

<private> <inner> keydown(ev)

The keydown event handler. This function determines the key pressed by the user, and checks if the keypress event will fire in the current Web browser, or not. If it does not, a synthetic keypress event will be fired.

Parameters:
{Event} ev: The DOM Event object.

<private> <inner> keypress(ev)

The keypress event handler. This function determines the character generated by the keyboard event.

Parameters:
{Event} ev: The DOM Event object.

<private> <inner> keyup(ev)

The keyup event handler.

Parameters:
{Event} ev: The DOM Event object.

Classes

Class pwlib.dom.KeyboardEventListener