Work In Progress

This guide is an early work in progress, some information is incomplete and may change in the future.

Creating new keyboard layouts

This tutorial will take you through the steps required to create a new keyboard layout for the Ubuntu keyboard. To illustrate this we'll create a brand new layout for the Welsh language. This will include defining the layout itself, setting the dictionary used for spell checking and training the prediction module on our new language.

Welsh has the language code "cy", for your own layout you'll need to replace any instances of "cy" with your own layout's language code.

Checking out the keyboard

All keyboard layouts live inside the ubuntu-keyboard project on launchpad, so we'll create a new branch of ubuntu-keyboard and add our layout to this.To create a new branch of the keyboard simply run:

bzr branch lp:ubuntu-keyboard add-welsh-layout

Where "add-welsh-layout" is the name of the directory you wish to create the branch in.

Template

To simplify the creation of new layouts you can use the layout generation tool -- The template generation tool isn't complete yet, instead we recommend looking at a the changes made in a recent branch which adds the Catalan layout: https://code.launchpad.net/~dpm/ubuntu-keyboard/add-catalan/+merge/238368

Layout Files

There are typically four different layouts specified for each language, the default layout (in our case "Keyboard_cy.qml"), the URL layout ("Keyboard_cy_url.qml"), the search URL layout ("Keyboard_cy_url_search.qml") and the email layout ("Keyboard_cy_email.qml").

The keyboard layouts are implemented as QML files, which make use of a number of custom components common to all layouts:

* BackspaceKey - Triggers the deletion of characters, this should typically be placed at the end of the third row.

* CharKey - This is used for all normal character keys. The character it inputs can be set via the "label" property, the character that should be input when the keyboard is in a shifted state can be set via the "shifted" property. CharKeys can also provide access to an extended set of characters that the user accesses by holding down the key for a short time, these are set via the "extended" and "extendedShifted" properties. The first row of characters should typically have the numbers 0-9 as the first entries for the extended and extendedShifted on the top row of the keyboard.

* LanguageKey - Provides access to the language switcher menu, this key is only visible if the user has more than one keyboard layout enabled and should be the second key on the bottom row of the keyboard.

* ReturnKey - This should be placed on the end of the bottom row.

* ShiftKey - This causes the CharKeys to toggle between their normal and their shifted states. It should be the first key on the third row.

* SpaceKey - The space key dynamically expands its width to fill in any spare space and should be placed roughly in the middle of the bottom row. The exact positioning will typically vary between layouts as additional keys may be present (such as the UrlKey, or the '@' key for email layouts)

* SymbolShiftKey - This toggles switching between the character layout and the symbol layout, and should be the first key on the bottom row.

* UrlKey - This key displays common URL endings specific to your locale's layout (e.g. ".se" for Swedish layouts, ".de" for German). This key should only appear on the email, url and url_search layouts and should be displayed on the bottom row to the right of the space key. The UrlKey can also display extended keys, which can be used to provide any additional domains common to your locale.

If you used the template to create your keyboard then most of the special keys should be setup in their correct positions already, you'll just need to add entries for all of the CharKeys and modify the UrlKey to match your language.

Letting the keyboard know about our plugin

Predictions

Keyboard predictions are based around the presage prediction engine. Presage can learn from user input, however to bootstrap the learning so that predictions are available when the user first starts using the keyboard, we train presage using an appropriately licensed ebook for that language (typically we've been selecting ebooks from Project Gutenburg).

If you used the template you'll find an empty file called "free_ebook.txt" in your layout plugin's src/ directory. Simply replace this file with appropriate sample text and then run "qmake && make lang_db_cy" (replacing "cy" with the language code of the layout you're creating).

Packaging

Uploading