WebAPI/BrowserAPI/KeyboardEvent: Difference between revisions

From MozillaWiki
Jump to navigation Jump to search
Line 48: Line 48:
=== How to Fulfill Scenarios? ===
=== How to Fulfill Scenarios? ===
Here are some examples for each scenario.
Here are some examples for each scenario.
==== Scenario 1. SYSTEM-ONLY ====
 
Let's define some functions first.
 
function handleEvent(event) {
  dump('Receive event \'' + event.type + '\'.');
};
 
function handleEventAndPreventDefault(event) {
  dump('Receive event \'' + event.type + '\'.');
  event.preventDefault();
};
 
function checkAttrAndHandleEvent(event) {
  if (!event.embeddedCancelled) {
    dump('Receive event \'' + event.type + '\'.');
  }
};
 
==== Scenario SYSTEM-ONLY ====
* mozbrowser-embedder iframe
* mozbrowser-embedder iframe
     window.addEventListener('mozbrowserbeforekeydown') = function(evt) {
     window.addEventListener('mozbrowserbeforekeydown', handleEventAndPreventDefault);
      evt.preventDefault();
    window.addEventListener('mozbrowserbeforekeyup', handleEventAndPreventDefault);
     };
     window.addEventListener('mozbrowserkeydown', function() { });
     window.addEventListener('mozbrowserbeforekeyup') = function(evt) {
     window.addEventListener('mozbrowserkeyup', function() { });
      evt.preventDefault();
* mozbrowser-embedded iframe
     };
    window.addEventListener('keydown', handleEvent);
     window.addEventListener('keyup', handleEvent);


  {| border="0" align="left"
  {| border="0" align="left"
  ! Order !! mozbrowser-embedder iframe !! mozbrowser-embedded iframe
  ! width="80px" | Order !! width="200px" | mozbrowser-embedder iframe !! width="200px" | mozbrowser-embedded iframe !! Output
|-
| 1 || mozbrowserbeforekeydown || || Receive event 'mozbrowserbeforekeydown'.
  |-
  |-
  | style="border-right: 50px solid white" | 1 || style="border-right: 50px solid white" | mozbrowserbeforekeydown ||
  | 2 || mozbrowserkeydown || ||
  |-
  |-
  | 2 || mozbrowserbeforekeyup ||
  | 3 || mozbrowserbeforekeyup || || Receive event 'mozbrowserbeforekeyup'.
|-
| 4 || mozbrowserkeyup || ||
  |}
  |}


==== Scenario 2. SYSTEM-FIRST ====
==== Scenario SYSTEM-FIRST ====
* mozbrowser-embedder iframe
* mozbrowser-embedder iframe
     window.addEventListener('mozbrowserbeforekeydown') = function(evt) {
     window.addEventListener('mozbrowserbeforekeydown', handleEvent);
      // do something
    window.addEventListener('mozbrowserbeforekeyup', handleEvent);
    };
    window.addEventListener('mozbrowserkeydown', function() { });
     window.addEventListener('mozbrowserbeforekeyup') = function(evt) {
     window.addEventListener('mozbrowserkeyup', function() { });
      // do something
    };
* mozbrowser-embedded iframe
* mozbrowser-embedded iframe
     window.addEventListener('keydown') = function(evt) {
     window.addEventListener('keydown', handleEvent);
      // do something
     window.addEventListener('keyup', handleEvent);
    };
     window.addEventListener('keyup') = function(evt) {
      // do something
    };


  {| border="0" align="left"
  {| border="0" align="left"
  ! Order !! mozbrowser-embedder iframe !! mozbrowser-embedded iframe
  ! width="80px" | Order !! width="200px" | mozbrowser-embedder iframe !! width="200px" | mozbrowser-embedded iframe !! Output
  |-
  |-
  | style="border-right: 50px solid white" | 1 || style="border-right: 50px solid white" | mozbrowserbeforekeydown ||
  | 1 || mozbrowserbeforekeydown || || Receive event 'mozbrowserbeforekeydown'.
  |-
  |-
  | 2 || || keydown
  | 2 || || keydown || Receive event 'keydown'.
  |-
  |-
  | 3 || mozbrowserbeforekeyup ||
  | 3 || mozbrowserkeydown || ||
  |-
  |-
  | 4 || || keyup
  | 4 || mozbrowserbeforekeyup || || Receive event 'mozbrowserbeforekeyup'.
|-
| 5 || || keyup || Receive event 'keyup'.
|-
| 6 || mozbrowserkeyup || ||
  |}
  |}


==== APP-ONLY ====
==== Scenario APP-ONLY ====
* mozbrowser-embedder iframe
* mozbrowser-embedder iframe
     window.addEventListener('mozbrowserkeydown') = function(evt) {
     window.addEventListener('mozbrowserbeforekeydown', function() { });
      // evt.embeddedcancelled = true;
     window.addEventListener('mozbrowserbeforekeyup', function() { });
    };
    window.addEventListener('mozbrowserkeydown', checkAttrAndHandleEvent);
     window.addEventListener('mozbrowserkeyup') = function(evt) {
     window.addEventListener('mozbrowserkeyup', checkAttrAndHandleEvent);
      // evt.embeddedcancelled = true;
     };
* mozbrowser-embedded iframe
* mozbrowser-embedded iframe
     window.addEventListener('keydown') = function(evt) {
     window.addEventListener('keydown', handleEventAndPreventDefault);
      evt.preventDefault();
     window.addEventListener('keyup', handleEventAndPreventDefault);
    };
     window.addEventListener('keyup') = function(evt) {
      evt.preventDefault();
    };


  {| border="0" align="left"
  {| border="0" align="left"
  ! Order !! mozbrowser-embedder iframe !! mozbrowser-embedded iframe
  ! width="80px" | Order !! width="200px" | mozbrowser-embedder iframe !! width="200px" | mozbrowser-embedded iframe !! Output
|-
| 1 || mozbrowserbeforekeydown || ||
  |-
  |-
  | style="border-right: 50px solid white" | 1 || || style="border-right: 50px solid white" |keydown
  | 2 || || keydown || Receive event 'keydown'.
  |-
  |-
  | 2 || mozbrowserkeydown ||
  | 3 || mozbrowserkeydown || ||
  |-
  |-
  | 3 || || keyup
  | 4 || mozbrowserbeforekeyup || ||
  |-
  |-
  | 4 || mozbrowserkeyup ||
  | 5 || || keyup || Receive event 'keyup'.
|-
| 6 || mozbrowserup || ||
  |}
  |}
==== APP-FIRST ====
 
==== Scenario APP-FIRST ====
* mozbrowser-embedder iframe
* mozbrowser-embedder iframe
     window.addEventListener('mozbrowserkeydown') = function(evt) {
     window.addEventListener('mozbrowserbeforekeydown', function() { });
      // evt.embeddedcancelled = false;
     window.addEventListener('mozbrowserbeforekeyup', function() { });
    };
    window.addEventListener('mozbrowserkeydown', checkAttrAndHandleEvent);
     window.addEventListener('mozbrowserkeyup') = function(evt) {
     window.addEventListener('mozbrowserkeyup', checkAttrAndHandleEvent);
      // evt.embeddedcancelled = false;
     };
* mozbrowser-embedded iframe
* mozbrowser-embedded iframe
     window.addEventListener('keydown') = function(evt) {
     window.addEventListener('keydown', handleEvent);
      // do something
     window.addEventListener('keyup', handleEvent);
    };
     window.addEventListener('keyup') = function(evt) {
      // do something
    };


  {| border="0" align="left"
  {| border="0" align="left"
  ! Order !! mozbrowser-embedder iframe !! mozbrowser-embedded iframe
  ! width="80px" | Order !! width="200px" | mozbrowser-embedder iframe !! width="200px" | mozbrowser-embedded iframe !! Output
|-
| 1 || mozbrowserbeforekeydown || ||
|-
| 2 || || keydown || Receive event 'keydown'.
  |-
  |-
  | style="border-right: 50px solid white" | 1 || || style="border-right: 50px solid white" | keydown
  | 3 || mozbrowserkeydown || || Receive event 'mozbrowserkeydown'.
  |-
  |-
  | 2 || mozbrowserkeydown ||
  | 4 || mozbrowserbeforekeyup || ||
  |-
  |-
  | 3 || || keyup
  | 5 || || keyup || Receive event 'keyup'.
  |-
  |-
  | 4 || mozbrowserkeyup ||
  | 6 || mozbrowserkeyup || || Receive event 'mozbrowserkeyup'.
  |}
  |}


Revision as of 09:33, 7 May 2014

Dispatch KeyboardEvent across BrowserElements

This is a proposal to enable applications to handle/override the behavior of certain KeyboardEvent.

There are four scenarios which should be fulfilled:

Scenario Description Example Keys
SYSTEM-ONLY For keys which should be handled by mozbrowser embedder iframe only. 'Power', 'VolumeUp', 'VolumeDown', 'VolumeMute', 'DisplaySwap'
SYSTEM-FIRST For keys which can be handled by mozbrowser embedder iframe first and can also be handled by mozbrowser embedded iframe then. 'Info', 'Settings'
APP-ONLY For keys which should be handled by mozbrowser embedded iframe only. 'ColorF0Red', 'ColorF1Green', 'ColorF2Yellow', 'ColorF3Blue', 'ColorF4Grey'
APP-FIRST For keys which keys can be handled by mozbrowser embedded iframe first and can also be handled by mozbrowser embedder iframe then. 'Info', 'Settings'


Note that some keys could be either SYSTEM-FIRST or APP-FIRST. The behavior is decided by the author of applications.

Proposal Concept

Concept diagram

Four new events are proposed:

  • mozbrowserbeforekeydown
  • mozbrowserkeydown
  • mozbrowserbeforekeyup
  • mozbrowserkeyup


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


Similarly, when a key is released, the event sequence would be:

  1. 'mozbrowserbeforekeyup' is dispatched to mozbrowser-embedder iframe
  2. 'keyup' is dispatched to mozbrowser-embedded iframe
  3. 'mozbrowserkeyup' is dispatched to mozbrowser-embedder iframe


This proposal can be extended to nested mozbrowser iframes. The four new events will be dispatched to all mozbrowser-embedder iframes.

Concept diagram for nested mozbrowser iframes

How to Fulfill Scenarios?

Here are some examples for each scenario.

Let's define some functions first. 

function handleEvent(event) {
  dump('Receive event \ + event.type + '\'.');
};

function handleEventAndPreventDefault(event) {
  dump('Receive event \ + event.type + '\'.');
  event.preventDefault();
};

function checkAttrAndHandleEvent(event) {
  if (!event.embeddedCancelled) {
    dump('Receive event \ + event.type + '\'.');
  }
};

Scenario SYSTEM-ONLY

  • mozbrowser-embedder iframe
   window.addEventListener('mozbrowserbeforekeydown', handleEventAndPreventDefault);
   window.addEventListener('mozbrowserbeforekeyup', handleEventAndPreventDefault);
   window.addEventListener('mozbrowserkeydown', function() { });
   window.addEventListener('mozbrowserkeyup', function() { });
  • mozbrowser-embedded iframe
   window.addEventListener('keydown', handleEvent);
   window.addEventListener('keyup', handleEvent);
Order mozbrowser-embedder iframe mozbrowser-embedded iframe Output
1 mozbrowserbeforekeydown Receive event 'mozbrowserbeforekeydown'.
2 mozbrowserkeydown
3 mozbrowserbeforekeyup Receive event 'mozbrowserbeforekeyup'.
4 mozbrowserkeyup

Scenario SYSTEM-FIRST

  • mozbrowser-embedder iframe
   window.addEventListener('mozbrowserbeforekeydown', handleEvent);
   window.addEventListener('mozbrowserbeforekeyup', handleEvent);
   window.addEventListener('mozbrowserkeydown', function() { });
   window.addEventListener('mozbrowserkeyup', function() { });
  • mozbrowser-embedded iframe
   window.addEventListener('keydown', handleEvent);
   window.addEventListener('keyup', handleEvent);
Order mozbrowser-embedder iframe mozbrowser-embedded iframe Output
1 mozbrowserbeforekeydown Receive event 'mozbrowserbeforekeydown'.
2 keydown Receive event 'keydown'.
3 mozbrowserkeydown
4 mozbrowserbeforekeyup Receive event 'mozbrowserbeforekeyup'.
5 keyup Receive event 'keyup'.
6 mozbrowserkeyup

Scenario APP-ONLY

  • mozbrowser-embedder iframe
   window.addEventListener('mozbrowserbeforekeydown', function() { });
   window.addEventListener('mozbrowserbeforekeyup', function() { });
   window.addEventListener('mozbrowserkeydown', checkAttrAndHandleEvent);
   window.addEventListener('mozbrowserkeyup', checkAttrAndHandleEvent);
  • mozbrowser-embedded iframe
   window.addEventListener('keydown', handleEventAndPreventDefault);
   window.addEventListener('keyup', handleEventAndPreventDefault);
Order mozbrowser-embedder iframe mozbrowser-embedded iframe Output
1 mozbrowserbeforekeydown
2 keydown Receive event 'keydown'.
3 mozbrowserkeydown
4 mozbrowserbeforekeyup
5 keyup Receive event 'keyup'.
6 mozbrowserup

Scenario APP-FIRST

  • mozbrowser-embedder iframe
   window.addEventListener('mozbrowserbeforekeydown', function() { });
   window.addEventListener('mozbrowserbeforekeyup', function() { });
   window.addEventListener('mozbrowserkeydown', checkAttrAndHandleEvent);
   window.addEventListener('mozbrowserkeyup', checkAttrAndHandleEvent);
  • mozbrowser-embedded iframe
   window.addEventListener('keydown', handleEvent);
   window.addEventListener('keyup', handleEvent);
Order mozbrowser-embedder iframe mozbrowser-embedded iframe Output
1 mozbrowserbeforekeydown
2 keydown Receive event 'keydown'.
3 mozbrowserkeydown Receive event 'mozbrowserkeydown'.
4 mozbrowserbeforekeyup
5 keyup Receive event 'keyup'.
6 mozbrowserkeyup Receive event 'mozbrowserkeyup'.

Proposal Details

mozbrowserbeforekeydown

Type mozbrowserbeforekeydown
Interface KeyboardEvent
Sync/Async Sync
Bubbles Yes
Target Document, Element
Cancelable Yes
Default action keydown event

mozbrowserkeydown

Type mozbrowserkeydown
Interface KeyboardEvent
Sync/Async Sync
Bubbles Yes
Target Document, Element
Cancelable Yes
Default action None

mozbrowserbeforekeyup

Type mozbrowserbeforekeyup
Interface KeyboardEvent
Sync/Async Sync
Bubbles Yes
Target Document, Element
Cancelable Yes
Default action keyup event

mozbrowserkeyup

Type mozbrowserkeyup
Interface KeyboardEvent
Sync/Async Sync
Bubbles Yes
Target Document, Element
Cancelable Yes
Default action None
Retrieved from "https://wiki.allizom.org/index.php?title=WebAPI/BrowserAPI/KeyboardEvent&oldid=974261"