forms.js requirements

About

This document is a draft and an attempt to reconcile between the mash currently in forms.js and the newly implemented, D3E-aware nsITextInputProcessor. The outcome of this document is to find out the requirements of the current implementation and what are the new C-based interface it should rely on, instead of legacy nsIDOMWindowUtils.

Ideally we should document not only the current implementation, but also the requirements to make this fully D3E compatible.

The related work is bug 1137557.

What is forms.js

forms.js is the remote end of the Input Method API, responsible of handling input fields for the active API user (the keyboard app).

It is loaded by browser-element exactly once on every content/chrome process, on the topmost widget.

Requirements

Focus management

1. Send an async message when any of the text inputs (input/textarea/contenteditable) receives focus
2. Send an async message when any of the select element receives focus
3. Send an async message when any of the text inputs (input/textarea/contenteditable) lost focus
4. Send an async message when any of the select element lost focus
5. (To be removed in bug 1162360) When the focus move from one input to another input in the same widget, don't send two blur/focus events but reduce to one focus event only.
6. (Unimplemented) Detect input properties change (type/inputmode/readonly/etc.)
7. Send an async message when the page submit/pagehide/beforeunload; also trigger blur to keep the state consistent.

(1)(2) Focus are currently detected by listen to DOM events L193. Valid elements are currently filter in JS logic L362-L391.

(3)(4) Blur can happen not only the real blur (detected by DOM event L194) but also removal from DOM tree (detected by mutation observer L298.

(5) The way to reduce blur-then-focus events to one focus event is implemented by schedule the event sending function to the end of the event queue L685 and L700. We should be able to safely remove this feature since System app and Keyboard app has the safeguard in place anyway, as we did not reduce two events when focus moved between processes.

(6) Is never implemented, but we should issue a new InputContext when this happens (or dispatch *change event and keep the same InputContext?)

(7) Has caused issue like bug 1122463 (combine w/ (5)).

Issues

1. Can we use one nsITextInputProcessor instance for the entire lifecycle of forms.js?
2. Can we use nsITextInputProcessor to detect focus instead? Select elements however should be handled separately.
3. Would it be possible even moving this global focused element detection to the chrome process, not forms.js in every process? We had some async message ordering issue before, see Keyboard.jsm#L286.

Input handling

1. Scroll the focused element into view the size of the window/widget/frame changes.
2. Send an message when the content of the currently focused input element changes
3. (Unimplemented) Send an message when the content of the currently focused select element changes
4. Send an message when the position of the carets (selections) changes.

Issues

Text input

1. Handle the sendKey() call to InputMethod API, which inputs one character (and generate keyboard events)
2. (New) Provide user finer control on virtual keyboard emulation by offering keydown() and keyup() methods and allow specify keyboard event properties within.
3. Handle the setComposition() call to InputMethod API, which create visible composition on the input (and generate compositionstart/compositionupdate events), used by Asian IME.
4. (New) Allow caller to specify the key event triggers the composition to start/update in setComposition()
5. Handle the endComposition() call to InputMethod API, which create visible composition on the input (and generate compositionstart/compositionupdate events), used by Asian IME.
6. (New) Allow caller to specify the key event triggers the composition to end in endComposition()

Issues

Select

1. Handle the setSelectionRange() call to InputMethod API, which changes the selection range/position of the input.
2. Handle the replaceSurroundingText() call to InputMethod API, which changes the text around the caret(s), used by auto correction.
3. Handle the deleteSurroundingText() call to InputMethod API, which changes the text around the caret(s), used by auto correction.

Issues