com.smartgwt.client.docs

Interface KeyboardEvents

public interface KeyboardEvents

Keyboard Events

Smart GWT allows keyboard events to be captured at the page level via Page.registerKey() or at the widget level via Canvas.keyDown(), Canvas.keyPress(), and Canvas.keyUp().

Details about the key events can be retrieved via static methods on the EventHandler class. See the following APIs:

• EventHandler.getKey() - name of the pressed key. (Note this may differ from the native event.key)
• EventHandler.getKeyEventCharacter() - the character that was typed. This is derived from the reported characterValue and will only be populated for keyPress events on character keys.
• EventHandler.getKeyEventCharacterValue() - the characterValue from the event. This is populated for keyPress events on character keys.
• EventHandler.getKeyEventKey() - the reported event.key from the native browser event.
• EventHandler.getKeyEventCode() - the reported event.code from the native browser event.

Developers may also check for modifier keys via EventHandler.shiftKeyDown(), EventHandler.altKeyDown() and EventHandler.ctrlKeyDown().

As with other Smart GWT event handling code, returning false will suppress the default native browser behavior.
Note: browsers do not allow cancellation of some keys' default behaviors. These cases vary by browser, and wherever native cancellation is supported, returning false from your event handler should be sufficient to suppress the behavior.
Some specific cases where default behavior cancellation is not always possible include:

• Some function keys (f1, f3, f5, etc) which trigger native browser behavior. [These can be suppressed in Internet Explorer and Mozilla Firefox but not in some other browsers such as Safari / Chrome, etc]
• Some accelerator key combos such as Alt+f3
• The "Meta" key (the Windows / Apple key to show OS level menu)

If you do want to include functionality for these keys in your application, we'd recommend testing against your expected users' browser types. It is also worth considering whether by changing the functionality of these standard browser keys you may provide an unexpected user experience (for example a user may press "f5" in an attempt to reload the application and be surprised by this triggering some alternative functionality in your application).

See Also:

EventHandler.getKeyEventCharacterValue(), EventHandler.getKeyEventCharacter(), EventHandler.getKey(), EventHandler.getKeyEventKey(), EventHandler.getReportedKey(), EventHandler.getKeyEventCode(), EventHandler.shiftKeyDown(), EventHandler.ctrlKeyDown(), EventHandler.altKeyDown()