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

Warning: You are not logged in. Your IP address will be recorded in this page's edit history.

The edit can be undone. Please check the comparison below to verify that this is what you want to do, and then save the changes below to finish undoing the edit.

Learn more about Contributing to the wiki.

==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 [[Open development/Maemo roadmap/Fremantle|Maemo 5]] device, [[Nokia N900|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 <code>KP_ENTER</code> signal, not the <code>ENTER</code> 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!''

==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 [http://bugs.maemo.org/show_bug.cgi?id=7695 bug report] has been submitted to request a painless and safe workaround, but no standard solution has been offered.

===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.

===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:

# Restore the user's original layout on exit
# 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 <strike>dirty hack</strike> 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.

<source lang="diff">
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");
</source>

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.

<source lang="diff"> 
@@ -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");
</source>

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

<source lang="diff">
--- 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");
    }
</source>

The <code>SDL_APPINPUTFOCUS</code> 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.

==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.

Example: The UQM keymap

[[Image:Uqm-keymap.jpg]]

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

[[Image:N900_keyboard_keymap_template.png‎]]

[[Category:Development]]
[[Category:Documentation]]
[[Category:Fremantle]]

Please note that all contributions to maemo.org wiki may be edited, altered, or removed by other contributors. If you do not want your writing to be edited mercilessly, then do not submit it here.
You are also promising us that you wrote this yourself, or copied it from a public domain or similar free resource (see maemo.org wiki:Copyrights for details). Do not submit copyrighted work without permission!

Summary:

Cancel | Editing help (opens in new window)

Retrieved from "http://wiki.maemo.org/Documentation/Maemo_5_Developer_Guide/Porting_Software/Adapting_UI_Inputs"

Personal tools

Navigation

Views

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

@@ Line 78: / Line 78: @@
 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.
-[[Image:Uqm-keymap.jpg|frame|center|alt=Photo of N900 keyboard with UQM keymap|The UQM keymap]]
+Example: The UQM keymap
+[[Image:Uqm-keymap.jpg]]
 Here is a template to use for your own app keymap. Painting over the keys with GIMP works well.
-[[Image:N900_keyboard_keymap_template.png|frame|center|alt=Photo of N900 keyboard||N900 keyboard template‎]]
+[[Image:N900_keyboard_keymap_template.png‎]]
 [[Category:Development]]
 [[Category:Documentation]]
 [[Category:Fremantle]]