Gaia/System/Keyboard/Layout: Difference between revisions
Jump to navigation
Jump to search
No edit summary |
|||
| Line 1: | Line 1: | ||
This document explains how to add custom keyboard layouts containing their own languages/scripts to '''Firefox OS v1.2''' and up. | |||
== Status of the Gaia Keyboard app & system architecture == | == Status of the Gaia Keyboard app & system architecture == | ||
Two major features have been implemented in Firefox OS, as of October 2013. | |||
* A build flag | * A build flag to turn keyboard/spellcheck dictionaries to include in the build in the default Gaia Keyboard app on and off (see {{Bug|884752}}). | ||
* An OS-level feature that | * An OS-level feature that allows users to install 3rd-party keyboard apps from the Firefox Marketplace. See {{Bug|816869}}. | ||
To come up with a new keyboard layout, you | To come up with a new keyboard layout, you can put a layout file in Gaia, build the keyboard app using a build config, or come up with your own keyboard app and install it on the phone. | ||
== How | == How to make a keyboard app == | ||
You | You can use Gaia's built-in keyboard app as a template, or fork it. The basic ideas are: | ||
* In the manifest, declare | * In the manifest file, declare your keyboard in the <code>role</code> property. | ||
* Make sure you have the <code>input</code> permission. | * Make sure you have the <code>input</code> permission specified. | ||
After that, | After that, you can install your keyboard, and it will show up on the bottom half of the screen whenever the user is focused to a input field. The space issues that arise from this can be dealt with by: | ||
* | * Using the old, classic <code>window.resize</code> to update the area of your app should occupy. | ||
* | * Using the new, shiny <code>navigator.mozInputMethod</code> API to mutate the content of the input given, see [[WebAPI/KeboardIME|API page]] for detail. | ||
TBD: provide sample code and/or a small template app | |||
== How | == How to add a custom layout to your template in the Gaia keyboard app == | ||
See [https://github.com/mozilla-b2g/gaia/blob/master/apps/keyboard/CONFIGURE apps/keyboard/CONFIGURE] for | See [https://github.com/mozilla-b2g/gaia/blob/master/apps/keyboard/CONFIGURE apps/keyboard/CONFIGURE] for details. Depending on the language you might want to add a dictionary, or include an interactive IME (for Asian languages). | ||
=== Spell check / word suggestion dictionary === | === Spell check / word suggestion dictionary === | ||
| Line 36: | Line 36: | ||
==== Introduction ==== | ==== Introduction ==== | ||
East Asian languages (Chinese, Japanese, and Korean) use [https://en.wikipedia.org/wiki/CJK a fairly complex script] that involves thousands of characters. As there is no way to put thousands of keys on a hardware | East Asian languages (Chinese, Japanese, and Korean) use [https://en.wikipedia.org/wiki/CJK a fairly complex script] that involves thousands of characters. As there is no way to put thousands of keys on a hardware or software keyboard, users rely on an indexing program called [https://en.wikipedia.org/wiki/Input_method input method], or IME for short, to convert series of symbols into selections of characters. | ||
How symbols should be converted and how "smart" the IME should be depends on the method chosen, implementation itself, and often [https://en.wikipedia.org/wiki/Natural_language_processing NLP] science, which is outside the scope of this document. One thing to note is that it is highly recommended to put the database part into IndexedDB, in order to conserve memory on a mobile device. | How symbols should be converted and how "smart" the IME should be depends on the method chosen, implementation itself, and often [https://en.wikipedia.org/wiki/Natural_language_processing NLP] science, which is outside the scope of this document. One thing to note is that it is highly recommended to put the database part into IndexedDB, in order to conserve memory on a mobile device. | ||
| Line 42: | Line 42: | ||
==== IM Engine interface in Gaia keyboard app ==== | ==== IM Engine interface in Gaia keyboard app ==== | ||
Assuming you have an IME library readily available for converting symbols into characters (''IM Engine'' in our terminology), you would need to use the defined interface within Gaia Keyboard app | Assuming you have an IME library readily available for converting symbols into characters (''IM Engine'' in our terminology), you would need to use the defined interface within the Gaia Keyboard app to receive symbols from the layout and output the characters. The [https://github.com/mozilla-b2g/gaia/blob/master/apps/keyboard/js/keyboard.js#L32-L115 current API is documented on Github]. | ||
We invite implementations in order to further refine this API within Gaia. | |||
==== Make your IM engine work with your layout ==== | ==== Make your IM engine work with your layout ==== | ||
# Put a new layout in layout.js as the previous section | To get your IM engine working with your keyboard layout: | ||
# Reference the IM engine with <code>imEngine</code> property. When your layout is enabled, the keyboard app | |||
# APIs to receive and send the keys/characters | # Put a new layout in layout.js as described in the previous section. | ||
# When the user | # Reference the IM engine with the <code>imEngine</code> property. When your layout is enabled, the keyboard app will start loading the script located at <code>keyboard/js/imes/<imEngine>/<imEngine>.js</code>. | ||
# Set up the APIs to receive and send the keys/characters when the script is loaded and <code>init</code>'d. | |||
# Do whatever you want in response to the user input. When the user taps any keys on the keyboard, it would typically get sent to the IM engine. | |||
==== Known implementations ==== | ==== Known implementations ==== | ||
* [https://github.com/timdream/jszhuyin JSZhuyin] is the first implementation of Gaia Keyboard Asian IM engine, for Zhuyin IME | * [https://github.com/timdream/jszhuyin JSZhuyin] is the first implementation of Gaia Keyboard Asian IM engine, for Traditional Chinese incorporating Zhuyin IME. | ||
* [https://github.com/mozilla-b2g/gaia/tree/master/apps/keyboard/js/imes/jskanji JSKanji] is a prototype IM engine written for Japanese. | * [https://github.com/mozilla-b2g/gaia/tree/master/apps/keyboard/js/imes/jskanji JSKanji] is a prototype IM engine written for Japanese. | ||
* [https://github.com/mozilla-b2g/gaia/tree/master/apps/keyboard/js/imes/jspinyin JSPinyin] is a written for Simplified Chinese and works by tapping Pinyin symbols. | * [https://github.com/mozilla-b2g/gaia/tree/master/apps/keyboard/js/imes/jspinyin JSPinyin] is a written for Simplified Chinese and works by tapping Pinyin symbols. | ||
* As a demonstration, [http://chewing.csie.net/ Chewing], an C/C++ open-source Zhuyin IME for Traditional Chinese, was [https://bugzilla.mozilla.org/show_bug.cgi?id=845685 cross-compiled with emscripten] and linked with Gaia keyboard. | * As a demonstration, [http://chewing.csie.net/ Chewing], an C/C++ open-source Zhuyin IME for Traditional Chinese, was [https://bugzilla.mozilla.org/show_bug.cgi?id=845685 cross-compiled with emscripten] and linked with the Gaia keyboard. | ||
* [https://bugzilla.mozilla.org/show_bug.cgi?id=835261 JSHangul] | * [https://bugzilla.mozilla.org/show_bug.cgi?id=835261 JSHangul] is a prototype IM engine for Korean, and is currently in development. | ||
== Discussion, Q&A, etc == | == Discussion, Q&A, etc == | ||
Please come to [https://lists.mozilla.org/listinfo/dev-gaia dev-gaia] mailing list or the <code>#gaia</code> channel on irc.mozilla.org. <code>#mozilla-taiwan</code> is the de-facto Chinese-language channel for this topic. | Please come to the [https://lists.mozilla.org/listinfo/dev-gaia dev-gaia] mailing list or the <code>#gaia</code> channel on irc.mozilla.org. <code>#mozilla-taiwan</code> is the de-facto Chinese-language channel for this topic. | ||
Revision as of 13:55, 5 November 2013
This document explains how to add custom keyboard layouts containing their own languages/scripts to Firefox OS v1.2 and up.
Status of the Gaia Keyboard app & system architecture
Two major features have been implemented in Firefox OS, as of October 2013.
- A build flag to turn keyboard/spellcheck dictionaries to include in the build in the default Gaia Keyboard app on and off (see bug 884752).
- An OS-level feature that allows users to install 3rd-party keyboard apps from the Firefox Marketplace. See bug 816869.
To come up with a new keyboard layout, you can put a layout file in Gaia, build the keyboard app using a build config, or come up with your own keyboard app and install it on the phone.
How to make a keyboard app
You can use Gaia's built-in keyboard app as a template, or fork it. The basic ideas are:
- In the manifest file, declare your keyboard in the
roleproperty. - Make sure you have the
inputpermission specified.
After that, you can install your keyboard, and it will show up on the bottom half of the screen whenever the user is focused to a input field. The space issues that arise from this can be dealt with by:
- Using the old, classic
window.resizeto update the area of your app should occupy. - Using the new, shiny
navigator.mozInputMethodAPI to mutate the content of the input given, see API page for detail.
TBD: provide sample code and/or a small template app
How to add a custom layout to your template in the Gaia keyboard app
See apps/keyboard/CONFIGURE for details. Depending on the language you might want to add a dictionary, or include an interactive IME (for Asian languages).
Spell check / word suggestion dictionary
(TBA)
Asian IME
Introduction
East Asian languages (Chinese, Japanese, and Korean) use a fairly complex script that involves thousands of characters. As there is no way to put thousands of keys on a hardware or software keyboard, users rely on an indexing program called input method, or IME for short, to convert series of symbols into selections of characters.
How symbols should be converted and how "smart" the IME should be depends on the method chosen, implementation itself, and often NLP science, which is outside the scope of this document. One thing to note is that it is highly recommended to put the database part into IndexedDB, in order to conserve memory on a mobile device.
IM Engine interface in Gaia keyboard app
Assuming you have an IME library readily available for converting symbols into characters (IM Engine in our terminology), you would need to use the defined interface within the Gaia Keyboard app to receive symbols from the layout and output the characters. The current API is documented on Github.
We invite implementations in order to further refine this API within Gaia.
Make your IM engine work with your layout
To get your IM engine working with your keyboard layout:
- Put a new layout in layout.js as described in the previous section.
- Reference the IM engine with the
imEngineproperty. When your layout is enabled, the keyboard app will start loading the script located atkeyboard/js/imes/<imEngine>/<imEngine>.js. - Set up the APIs to receive and send the keys/characters when the script is loaded and
init'd. - Do whatever you want in response to the user input. When the user taps any keys on the keyboard, it would typically get sent to the IM engine.
Known implementations
- JSZhuyin is the first implementation of Gaia Keyboard Asian IM engine, for Traditional Chinese incorporating Zhuyin IME.
- JSKanji is a prototype IM engine written for Japanese.
- JSPinyin is a written for Simplified Chinese and works by tapping Pinyin symbols.
- As a demonstration, Chewing, an C/C++ open-source Zhuyin IME for Traditional Chinese, was cross-compiled with emscripten and linked with the Gaia keyboard.
- JSHangul is a prototype IM engine for Korean, and is currently in development.
Discussion, Q&A, etc
Please come to the dev-gaia mailing list or the #gaia channel on irc.mozilla.org. #mozilla-taiwan is the de-facto Chinese-language channel for this topic.