Class: HardwareButtons

HardwareButtons

new HardwareButtons()

After bug 989198 landing, we will be able to listen to KeyboardEvent (e.g.

After bug 989198 landing, we will be able to listen to KeyboardEvent (e.g. keydown and keyup). Also there will be new events called BeforeAfterKeybaordEvent for mozbrowser-embedder iframe, say system app, to control or override the bahavior of keydown/keyup event in mozbrowser-embedded iframes (other apps or homescreen app). These events are:

  • mozbrowserbeforekeydown
  • mozbrowserafterkeydown
  • mozbrowserbeforekeyup
  • mozbrowserafterkeyup

When a key is pressed down, the event sequence would be:

  1. mozbrowserbeforekeydown is dispatched to mozbrowser-embedder iframe
  2. keydown is dispatched to mozbrowser-embedded iframe
  3. mozbrowserkeydown is dispatched to mozbrowser-embedder iframe

For detail, please see https://wiki.mozilla.org/WebAPI/BrowserAPI/KeyboardEvent

This module listens for KeyboardEvent and BeforeAfterKeybaordEvent, processes them (with the help of BrowserKeyEventManager submodule) and generates higher-level events to handle autorepeat on the volume keys, long presses on Home and Sleep, and the Volume Down+Sleep key combination.

Other system app modules should listen for the high-level button events generated by this module.

The high-level events generated by this module are simple Event objects that are not cancelable and do not bubble. They are dispatched at the window object. The type property is set to one of these:

Event Type Meaning
home short press and release of home button
holdhome long press and hold of home button
sleep short press and release of sleep button
wake sleep or home pressed while sleeping
holdsleep long press and hold of sleep button
volumeup volume up pressed and released or autorepeated
volumedown volume down pressed and released or autorepeated
volumedown volume down and sleep pressed at same time (used for
+ sleep screenshots)
volumedown volume up and sleep pressed at same time (used for
+ volumeup systemlog capture)
camera short press and release of camera button
holdcamera long press and hold of camera button

Because these events are fired at the window object, they cannot be captured. Many modules listen for the home event. Those that want to respond to it and prevent others from responding should call stopImmediatePropagation(). Overlays that want to prevent the window manager from showing the homescreen on the home event should call that method. Note, however, that this only works for scripts that run and register their event handlers before AppWindowManager does.

As of the implementation itself, we process events with a finite state machine. Each state object has a process() method for handling events. And optionally has enter() and exit() methods called when the FSM enters and exits that state.

Source:
Requires:
Example
var hardwareButtons = new HardwareButtons();
hardwareButtons.start(); // Attach the event listeners.
hardwareButtons.stop();  // Deattach the event listeners.

Requires