Documentation/Maemo 5 Developer Guide/Porting Software/Adapting UI Inputs

Mobile Device Limitations
The Internet Tablets all have limited inputs compared to desktop computers. Some don't have a keyboard, and even those that do provide only a subset of the 101+ keys typical of a PC. Thus the maintainer may need to do some work to adapt the user interface inputs to something more convenient on a handheld device.

N900 Special Considerations
The Maemo 5 device, N900, provides a keyboard with three rows of keys. Applications that require only mouse and text input may work as-ported, but any app that uses shortcuts or special controls mapped to the keyboard (ie games) will need extra attention.

Some important things to remember:
 * The Enter key on the N900 sends the KP_ENTER signal, not the ENTER signal.
 * Numbers have to be entered using the Fn key modifier: they don't work well (or at all) as control keys. Depending on how text input is read, they may also not work for text input.
 * The keyboard layout is locale-specific. You cannot rely on any keys being in a given place, or even existing, on all N900s!

The Keyboard Locale Problem
The localization of N900 keyboards is particularly problematic for apps that use the arrow keys, because up and down arrow keys require a multi-stroke input on French, Finnish and possibly other localizations. This has created a serious problem for maintainers, who have no assurance that all their users will have the same keys available to them. A bug report has been submitted to request a painless and safe workaround, but no standard solution has been offered.

There are a number of ways to get around this limitation. Providing the user a GUI option to remap the controls is ideal, but it may represent a significant amount of extra work for the developer. If that approach is taken, be aware that a menu-driven UI that requires arrow keys will not be operable on the affected devices, so make it mouse-driven.

Another approach that may be appropriate for apps that require very little or no text input is to change the locale of the user's keyboard for the duration of program execution. Special care should be taken to not create side-effects if this is done. In particular, be sure to
 * 1) Restore the user's original layout on exit
 * 2) Restore the user's original layout when they switch away from the app

The first point can be handled by wrapping the app with a script that makes the necessary changes. To handle the second case, the app itself may need to be modified.

Here is an existing dirty hack solution (as implemented in uqm) that handles both case 1 and case 2. It uses gconftool-2, which modifies the linux equivalent of the Windows registry, a trick borrowed from the wrapper script for Duke Nukem. The patch has been commented to describe the important parts.

N.b. This doesn't restore properly custom user layouts set with setxkbmap, and might be improved by using that utility. Please update this portion of the wiki if you adapt this method to work properly with custom user layouts.

Maemo-specific patch to work around the Nokia design flaw that left large portions of Europe without up and down arrow keys. -- Flandry  20100114 --- src/uqm.c  2009-11-07 09:23:35.624611920 -0500 +++ src/uqm.c  2010-01-14 22:12:54.972781312 -0500 TFB_InitInput (TFB_INPUTDRIVER_SDL, 0); // Program initiation completed successfully + // MAEMO: Save the user's native keyboard layout and switch to known arrow-key compliant one + system("/usr/bin/gconftool-2 -g /apps/osso/inputmethod/int_kb_layout > /home/user/.uqm/int_kb_layout"); + system("/usr/bin/gconftool-2 -s /apps/osso/inputmethod/int_kb_layout us -t string"); // Start main loop StartThread (Starcon2Main, NULL, 1024, "Starcon2Main");

This makes two system calls to gconftool-2. The first saves the user's current layout into a file in the app configuration directory. (Be sure to create the user's app configuration directory before this call!) Instead of saving the original value to a file, you might use a different C system call function to enable storing the value in a variable, or read the value directly. The important part is to store initial state. @@ -471,6 +478,11 @@               mem_uninit ; } // End program + // MAEMO: Reset the user's keyboard layout based on the value recorded at the start + system("/usr/bin/gconftool-2 -s /apps/osso/inputmethod/int_kb_layout $(cat /home/user/.uqm/int_kb_layout) -t string");

This undoes the switch with an additional system call to gconftool-2 that uses the value stored at the beginning.

--- src/libs/graphics/sdl/sdl_common.c 2009-11-07 10:23:58.974265870 -0500 +++ src/libs/graphics/sdl/sdl_common.c 2010-01-14 22:13:36.531416322 -0500 if (Event.active.state & SDL_APPINPUTFOCUS) { GameActive = Event.active.gain; +     // Switch to english or user's native keyboard layout when gaining/loosing focus +     if (!GameActive) +        system("/usr/bin/gconftool-2 -s /apps/osso/inputmethod/int_kb_layout $(cat /home/user/.uqm/int_kb_layout) -t string"); +     else +        system("/usr/bin/gconftool-2 -s /apps/osso/inputmethod/int_kb_layout us -t string"); }

The SDL_APPINPUTFOCUS active state changes when an SDL app window is pushed to a thumbnail by the task switcher. When that event is detected, the user's original keyboard layout is restored, and then the qwerty (us) layout is restored when the app regains focus.