• Intro
• Downloads
• Community
• Development
• News
• TALK

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

Latest revision as of 09:51, 8 September 2010

[edit] 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.

[edit] 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 at all, on every N900!

[edit] 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.

[edit] Solution 1: Key Mapping UI

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.

[edit] Solution 2: The QWERTY Switch

Another approach that may be appropriate for apps that require very little or no text input (because the user is going to expect the keys to enter the same text as always) 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 <davidfalkayn@gmail.com>  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.

[edit] Documenting the UI

By using this workaround, it is possible to publish a keyboard map for your app that is universal, which greatly improves the user-friendliness of the app.

The UQM keymap

Here is a template to use for your own app keymap. Painting over the keys with GIMP works well.

N900 keyboard template‎