mozilla-b2g/gaia — pull request #1744 by lodr (2012-06-15 15:49:28+00:00)
Title: Keyboard refactor

# Overview

The keyboard has been split into 4 files:

* keyboard.js with IMEManager
* controller.js with IMEController
* render.js with IMERender
* feedback.js with IMEFeedback

Main tasks were to split responsabilities and fit them into each component;
rearrange the code; encapsulate it; improve the commentaries and rewrite some
little parts. Mostly all effort of the Mozilla team has been preserved or taken
in count while refactoring.

Layout specification **has not change at all**.

## Responsabilities

Now the keyboard follows a sort of **MVC pattern** where the model is the
layout. The summary of responsabilities is:

* IMEController is in charge of listen to the user events and translate them
into keyboard interactions as well as orchestrate the rendering process
through IMERender.
* IMERender is in charge of build HTML layout for the keyboard. In order
to keep encapsulation, IMERender is not allowed to communicate with
IMEController but in order to improve performance it is allowed to access
directly to the layout.
* IMEManager is in charge to listen to settings events, load new IMEs and
initializate IMEController.
* IMEFeedback is in charge to provide the feedback (sound and haptic response).

# Main changes

## General considerations

* Some keyboard-related system stuff has been changed to include a hide
attribute (in order to avoid unnecessary redraws).
* show-ime and hide-ime events replaced in favor of the new **onfocuschange** event.
* Due to a lot of object properties has been changed by private variables, a lot
of 'delete property' have been changed to 'property = false'

## The IMEFeedback component

* It needs no commentaries. It just a separation of responsabilities.

## The IMEController component

* **Specially important** is the fact that now, IMEngines must register themselves
by using 'IMEController.IMEngines.name = engine_object' and no more
'IMEManager.IMEngines.jskanji = jskanji' (note how IMEManager has been replaced
by IMEController).
* During initialization, it registers the events using a map. The event on
mouse move has been added. Look for LOCKED_AREA commentaries for further info.
* Redraw is avoided when possible. Now it is only triggered when changing
the layout (alternate, symbols or uppercase; or uner requeriment of the IME).
* Changes on the interface to post the system that the keyboard has changed are
centralized by using a mutation observer. Just changing orientation needs
special considerations.
* Redirection of the mouse over events when alternative menu is beeing displayed
is now performed in a more naive way but this will probably change in order to
improve performance (despite it performs very well at the moment).

## The IMERender component

* During initialization, it is passed some code to determine when a key is a
special key and how to get the uppercase variation of a key.
* The draw method is very naive. It just is able to render layouts. All
complementary information should be provided by the controller.
* The resizeUI method allows to adapt the currently rendered layout without
re-drawing. **In addition to the current CSS**, the keyboard is able to adapt
itself to any resolution without media nor JS hacks.

## The IMEManager component

* Just hold the setting listeners and enabling / disabling routines.

# Flaws and future work

* We need to tweak the CSS flex model to let more control over the size that
keys should have via ratio property.
* It is neccesary to tweak the style to improve response (i.e. convert effects
to images).
* The language selection will include scroll areas to scroll between the
different options.
* We would provide a mechanism to register IMEngines.
Some like 'IMEManager.registerEngine(name, engine)'
* As soon as [https://bugzilla.mozilla.org/show_bug.cgi?id=754083#c7] is solved,
we will be able to use the active state of buttons in order to stylish them by
pure CSS, without any JS.

## Recommendations

* It would be great to have a formal specification document of the layout.
* The layout should let rewrite the .com key and offer alternatives for it.
* It would be great to have a formal specification document of the IMEInterface
and glue.