Class Guacamole.Keyboard

Defined in: Keyboard.js.

Class Summary
Constructor Attributes	Constructor Name and Description
	Guacamole.Keyboard(element) Provides cross-browser and cross-keyboard keyboard for a specific element.

Field Summary
Field Attributes	Field Name and Description
<inner>	eventLog An array of recorded events, which can be instances of the private KeydownEvent, KeypressEvent, and KeyupEvent classes.
<inner>	last_keydown_result The last result of calling the onkeydown handler for each key, indexed by keysym.
	modifiers All modifiers and their states.
	pressed The state of every key, indexed by keysym.

Method Summary
Method Attributes	Method Name and Description
<inner>	get_keysym(keysyms, location) Given an array of keysyms indexed by location, returns the keysym for the given location, or the keysym for the standard location if undefined.
<inner>	getEventLocation(e) Returns the keyboard location of the key associated with the given keyboard event.
<inner>	interpret_event() Reads through the event log, interpreting the first event, if possible, and returning that event.
<inner>	interpret_events() Reads through the event log, removing events from the head of the log when the corresponding true key presses are known (or as known as they can be).
<inner>	key_identifier_sane(keyCode, keyIdentifier) Heuristically detects if the legacy keyIdentifier property of a keydown/keyup event looks incorrectly derived.
	press(keysym) Marks a key as pressed, firing the keydown event if registered.
	release(keysym) Marks a key as released, firing the keyup event if registered.
<inner>	release_simulated_altgr(keysym) Releases Ctrl+Alt, if both are currently pressed and the given keysym looks like a key that may require AltGr.
	reset() Resets the state of this keyboard, releasing all keys, and firing keyup events for each released key.
<inner>	update_modifier_state(e) Given a keyboard event, updates the local modifier state and remote key state based on the modifier flags within the event.

Event Summary
Event Attributes	Event Name and Description
	onkeydown(keysym) Fired whenever the user presses a key with the element associated with this Guacamole.Keyboard in focus.
	onkeyup(keysym) Fired whenever the user releases a key with the element associated with this Guacamole.Keyboard in focus.

Class Detail

Guacamole.Keyboard(element)

Provides cross-browser and cross-keyboard keyboard for a specific element. Browser and keyboard layout variation is abstracted away, providing events which represent keys as their corresponding X11 keysym.

Parameters:
{Element} element: The Element to use to provide keyboard events.

Field Detail

<inner> {(KeydownEvent|KeypressEvent|KeyupEvent)[]} eventLog

An array of recorded events, which can be instances of the private KeydownEvent, KeypressEvent, and KeyupEvent classes.

<inner> last_keydown_result

The last result of calling the onkeydown handler for each key, indexed by keysym. This is used to prevent/allow default actions for key events, even when the onkeydown handler cannot be called again because the key is (theoretically) still pressed.

modifiers

All modifiers and their states.

pressed

The state of every key, indexed by keysym. If a particular key is pressed, the value of pressed for that keysym will be true. If a key is not currently pressed, it will not be defined.

Method Detail

<inner> get_keysym(keysyms, location)

Given an array of keysyms indexed by location, returns the keysym for the given location, or the keysym for the standard location if undefined.

Parameters:
{Array} keysyms: An array of keysyms, where the index of the keysym in the array is the location value.
{Number} location: The location on the keyboard corresponding to the key pressed, as defined at: http://www.w3.org/TR/DOM-Level-3-Events/#events-KeyboardEvent

<inner> {Number} getEventLocation(e)

Returns the keyboard location of the key associated with the given keyboard event. The location differentiates key events which otherwise have the same keycode, such as left shift vs. right shift.

Parameters:
{KeyboardEvent} e: A JavaScript keyboard event, as received through the DOM via a "keydown", "keyup", or "keypress" handler.

Returns:: {Number} The location of the key event on the keyboard, as defined at: http://www.w3.org/TR/DOM-Level-3-Events/#events-KeyboardEvent

<inner> {KeyEvent} interpret_event()

Reads through the event log, interpreting the first event, if possible, and returning that event. If no events can be interpreted, due to a total lack of events or the need for more events, null is returned. Any interpreted events are automatically removed from the log.

Returns:: {KeyEvent} The first key event in the log, if it can be interpreted, or null otherwise.

<inner> {Boolean} interpret_events()

Reads through the event log, removing events from the head of the log when the corresponding true key presses are known (or as known as they can be).

Returns:: {Boolean} Whether the default action of the latest event should be prevented.

<inner> {Boolean} key_identifier_sane(keyCode, keyIdentifier)

Heuristically detects if the legacy keyIdentifier property of a keydown/keyup event looks incorrectly derived. Chrome, and presumably others, will produce the keyIdentifier by assuming the keyCode is the Unicode codepoint for that key. This is not correct in all cases.

Parameters:
{Number} keyCode: The keyCode from a browser keydown/keyup event.
{String} keyIdentifier: The legacy keyIdentifier from a browser keydown/keyup event.

Returns:: {Boolean} true if the keyIdentifier looks sane, false if the keyIdentifier appears incorrectly derived or is missing entirely.

{Boolean} press(keysym)

Marks a key as pressed, firing the keydown event if registered. Key repeat for the pressed key will start after a delay if that key is not a modifier. The return value of this function depends on the return value of the keydown event handler, if any.

Parameters:
{Number} keysym: The keysym of the key to press.

Returns:: {Boolean} true if event should NOT be canceled, false otherwise.

release(keysym)

Marks a key as released, firing the keyup event if registered.

Parameters:
{Number} keysym: The keysym of the key to release.

<inner> release_simulated_altgr(keysym)

Releases Ctrl+Alt, if both are currently pressed and the given keysym looks like a key that may require AltGr.

Parameters:
{Number} keysym: The key that was just pressed.

reset()

Resets the state of this keyboard, releasing all keys, and firing keyup events for each released key.

<inner> update_modifier_state(e)

Given a keyboard event, updates the local modifier state and remote key state based on the modifier flags within the event. This function pays no attention to keycodes.

Parameters:
{KeyboardEvent} e: The keyboard event containing the flags to update.

Event Detail

{Boolean} onkeydown(keysym)

Fired whenever the user presses a key with the element associated with this Guacamole.Keyboard in focus.

Parameters:
{Number} keysym: The keysym of the key being pressed.

Returns:: {Boolean} true if the key event should be allowed through to the browser, false otherwise.

onkeyup(keysym)

Fired whenever the user releases a key with the element associated with this Guacamole.Keyboard in focus.

Parameters:
{Number} keysym: The keysym of the key being released.

Classes

Class Guacamole.Keyboard