View source for User:Timdream/InputMethod API with hardware keyboard

== Proposed API addition w/ hardware keyboard ==

''This is not planned in Firefox OS v1.2.'' See [https://bugzilla.mozilla.org/show_bug.cgi?id=??? Bug ????].

=== Idea ===

The previous iteration of IM API (See [[WebAPI/KeboardIME]]) enables the keyboard apps to interact with the targeted input field. We would like it to handle the connected hardware keyboard as well.

The API is designed to be compatible with previous iteration: if the hardware key is not <code>block()</code>'ed, Gecko would simply do it's usual things (sending the keydown/keypress/keyup events). If the keyboard app decide to <code>block()</code> the key, it would be responsible to come up with appropriate interaction, and do the desired mutation to the input field (if it decide to further swallow the original key events with <code>unblock(true);</code>.

'''Why not use <code>evt.perventDefault()</code>?''' The default action of an event is evaluated as soon as all event listeners are executed. The keyboard app might not be able to decide whether or not to suppress the usual key events at that point (if the decision is based on, say, an IndexedDB async query). So we opt to <code>block()</code> and <code>unblock(handled)</code>.

* kanru
** Q: What about <code>interface HardwareKeyboardEvent : KeyboardEvent</code> so you don't have to copy the attributes?
*** A: [Tim] If that's the case we would be sending three <code>HardwareKeyboardEvent</code> events to represent 3 keyboard events. Which is good if the keyboard app requires finer control (Luke mentioned that possibility to me).
** Q: What should <code>unblock(false)</code> do? Send the queued events to content? Could it queue more than one key events?
*** A: implementation should send the event, previous blocked, to content. When an event is blocked, all the follow-up events should be queued and be handled in sequence when the event is eventually unblocked.

*janjongboom
** Q: apc.io already is working on this and they have made gonk changes to facilitate this stuff. See the discussion in https://github.com/apc-io/apc-firefox-os/issues/8. Are we talking to them?

=== API addition ===

 partial interface InputMethod {
   /*
    * Indicate the presence of a external/hardware keyboard. In response, the virtual keyboard app, for example,
    * could remove the virtual keyboard part of it's UI and only show the suggestions/candidates UI.
    * [Tim] Need a better abstracted name like "external input source" or something...
    * [JJ] I argued the other way around in the bug I worked on: softkeyboardEnabled as property name. I'm trying to think of other times you'd want to disable soft keyboard but I can't really think of one. Other than that I think these methods should be in mozInputMethod.mgmt rather than in InputMethod. Shouldn't they?
    */
   readonly boolean hardwarekeyboard;
 
   /*
    * Fires when the above attribute changes.
    * [Tim] Need a better abstracted name like "external input source" or something...
    */
   attribute EventHandler onhardwarekeyboard;
 }

 partial interface InputContext {
   /*
    * The "hardwarekey" event will be dispatched when the user press a key.
    * See HardwareKeyEventDetail for what could the keyboard app do to this key event in it's "evt.datail"
    * [Tim] Need a better abstracted name like "external key event" or something...
    * [JJ] Why a separate event for hardware keys? We already have surroundingtextchange event... Can't really think of a use case.
    */
    attribute EventHandler onhardwarekey;
 };

 /*
  * The interface here is inspired by mozbrowsershowmodalprompt event.
  */
 interface HardwareKeyEventDetail {
   /*
    * These values are simply copied from KeyboardEvent so keyboard app gets to decide whether or not to handle the key.
    * See https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent
    */
   readonly number keyCode;
   readonly number charCode;
   readonly DOMString key;
   readonly DOMString char;
   readonly boolean shiftKey;
   readonly boolean metaKey;
   readonly boolean ctrlKey;
   readonly boolean altKey;
 
   /*
    * Block this hardware key event and all the key events follows.
    * The key event should be unblock()'d as soon as the keyboard app has handled it.
    */
   void block();
 
   /*
    * Unblock this hardware key.
    * If "handled" is set to true, the usual key* events will not be sent.
    */
   void unblock(boolean handled);
 }