Documentation/Maemo 5 Developer Guide/Porting Software/Adapting UI Inputs - Revision history

amigadave: /* N900 Special Considerations */ links

2010-09-08T09:51:05Z

N900 Special Considerations: links

← Older revision		Revision as of 09:51, 8 September 2010
Line 5:		Line 5:
	==N900 Special Considerations==		==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.	+	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:		Some important things to remember:

amigadave: /* Documenting the UI */ reformat images

2010-08-18T09:53:11Z

Documenting the UI: reformat images

← Older revision		Revision as of 09:53, 18 August 2010
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.		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\|frame\|center\|alt=Photo of N900 keyboard with UQM keymap\|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.		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‎~~]]	+	[[Image:N900_keyboard_keymap_template.png\|frame\|center\|alt=Photo of N900 keyboard\|\|N900 keyboard template‎]]

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

amigadave: use and


2010-08-11T20:57:13Z
use <source> and <code>

		
		
		
		
		
		
		← Older revision
		Revision as of 20:57, 11 August 2010
		
		Line 8:
Line 8:
  
 Some important things to remember:  Some important things to remember:
- * The '''Enter''' key on the N900 sends the ''KP_ENTER'' signal, not the ''ENTER'' signal. + * 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.  * 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 layout is locale-specific. ''You cannot rely on any keys being in a given place, or even existing at all, on every N900!''
Line 22:
Line 22:
 ===Solution 2: The QWERTY Switch===  ===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 + 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 on exit
 # Restore the user's original layout when they switch away from the app  # Restore the user's original layout when they switch away from the app
Line 32:
Line 33:
 '''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.  '''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. + <source lang="diff">
-  -- Flandry <davidfalkayn@gmail.com>  20100114 + Maemo-specific patch to work around the Nokia design flaw that left large portions of Europe without up and down arrow keys.
-  --- src/uqm.c   2009-11-07 09:23:35.624611920 -0500 + -- Flandry <davidfalkayn@gmail.com>  20100114
-  +++ src/uqm.c   2010-01-14 22:12:54.972781312 -0500 + --- src/uqm.c   2009-11-07 09:23:35.624611920 -0500
-     TFB_InitInput (TFB_INPUTDRIVER_SDL, 0); + +++ src/uqm.c   2010-01-14 22:12:54.972781312 -0500
-     // Program initiation completed successfully +    TFB_InitInput (TFB_INPUTDRIVER_SDL, 0);
-  +  // MAEMO: Save the user's native keyboard layout and switch to known arrow-key compliant one +    // Program initiation completed successfully
-  +  system("/usr/bin/gconftool-2 -g /apps/osso/inputmethod/int_kb_layout > /home/user/.uqm/int_kb_layout"); + +  // MAEMO: Save the user's native keyboard layout and switch to known arrow-key compliant one
-  +  system("/usr/bin/gconftool-2 -s /apps/osso/inputmethod/int_kb_layout us -t string"); + +  system("/usr/bin/gconftool-2 -g /apps/osso/inputmethod/int_kb_layout > /home/user/.uqm/int_kb_layout");
-     // Start main loop + +  system("/usr/bin/gconftool-2 -s /apps/osso/inputmethod/int_kb_layout us -t string");
-     StartThread (Starcon2Main, NULL, 1024, "Starcon2Main"); +    // 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.  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 @@ + <source lang="diff"> 
-                 mem_uninit (); + @@ -471,6 +478,11 @@
-         } // End program +                mem_uninit ();
-  +  // MAEMO: Reset the user's keyboard layout based on the value recorded at the start +        } // End program
-  +  system("/usr/bin/gconftool-2 -s /apps/osso/inputmethod/int_kb_layout $(cat /home/user/.uqm/int_kb_layout) -t string"); + +  // 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.  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 + <source lang="diff">
-  +++ src/libs/graphics/sdl/sdl_common.c  2010-01-14 22:13:36.531416322 -0500 + --- src/libs/graphics/sdl/sdl_common.c  2009-11-07 10:23:58.974265870 -0500
-      if (Event.active.state & SDL_APPINPUTFOCUS) { + +++ src/libs/graphics/sdl/sdl_common.c  2010-01-14 22:13:36.531416322 -0500
-         GameActive = Event.active.gain; +     if (Event.active.state & SDL_APPINPUTFOCUS) {
-  +      // Switch to english or user's native keyboard layout when gaining/loosing focus +        GameActive = Event.active.gain;
-  +      if (!GameActive) + +      // Switch to english or user's native keyboard layout when gaining/loosing focus
-  +         system("/usr/bin/gconftool-2 -s /apps/osso/inputmethod/int_kb_layout $(cat /home/user/.uqm/int_kb_layout) -t string"); + +      if (!GameActive)
-  +      else + +         system("/usr/bin/gconftool-2 -s /apps/osso/inputmethod/int_kb_layout $(cat /home/user/.uqm/int_kb_layout) -t string");
-  +         system("/usr/bin/gconftool-2 -s /apps/osso/inputmethod/int_kb_layout us -t string"); + +      else
-      } + +         system("/usr/bin/gconftool-2 -s /apps/osso/inputmethod/int_kb_layout us -t string");
  +     }
  + </source>
  
- 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. + 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==  ==Documenting the UI==



amigadave: categorise
2010-02-12T12:47:13Z
categorise

		
		
		
		
		
		
		← Older revision
		Revision as of 12:47, 12 February 2010
		
		Line 78:
Line 78:
  
 [[Image:N900_keyboard_keymap_template.png‎]]  [[Image:N900_keyboard_keymap_template.png‎]]
  + 
  + [[Category:Development]]
  + [[Category:Documentation]]
  + [[Category:Fremantle]]




flandry: Added template for keymap image
2010-01-30T16:09:57Z
Added template for keymap image

		
		
		
		
		
		
		← Older revision
		Revision as of 16:09, 30 January 2010
		
		Line 10:
Line 10:
 * The '''Enter''' key on the N900 sends the ''KP_ENTER'' signal, not the ''ENTER'' signal.  * 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.  * 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 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 Keyboard Locale Problem==
Line 66:
Line 66:
  
 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.  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.
  + 
  + ==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.  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  Example: The UQM keymap
  + 
 [[Image:Uqm-keymap.jpg]]  [[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‎]]




flandry: Added example keyboard map
2010-01-30T16:01:18Z
Added example keyboard map

		
		
		
		
		
		
		← Older revision
		Revision as of 16:01, 30 January 2010
		
		Line 15:
Line 15:
  
 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.  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.  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 + ===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 on exit
 # Restore the user's original layout when they switch away from the app  # Restore the user's original layout when they switch away from the app
Line 62:
Line 66:
  
 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.  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.
  + 
  + 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]]




flandry: General suggestions for UI input changes and a hack to fix the Nokia keyboard localization bug.
2010-01-30T15:45:22Z
General suggestions for UI input changes and a hack to fix the Nokia keyboard localization bug.
New page
==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 [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.



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

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



 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.

← Older revision		Revision as of 20:57, 11 August 2010
Line 8:		Line 8:

	Some important things to remember:		Some important things to remember:
-	* The '''Enter''' key on the N900 sends the ''KP_ENTER'' signal, not the ''ENTER'' signal.	+	* 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.		* 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 layout is locale-specific. ''You cannot rely on any keys being in a given place, or even existing at all, on every N900!''
Line 22:		Line 22:
	===Solution 2: The QWERTY Switch===		===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	+	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 on exit
	# Restore the user's original layout when they switch away from the app		# Restore the user's original layout when they switch away from the app
Line 32:		Line 33:
	'''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.		'''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.	+	<source lang="diff">
-	-- Flandry <davidfalkayn@gmail.com> 20100114	+	Maemo-specific patch to work around the Nokia design flaw that left large portions of Europe without up and down arrow keys.
-	--- src/uqm.c 2009-11-07 09:23:35.624611920 -0500	+	-- Flandry <davidfalkayn@gmail.com> 20100114
-	+++ src/uqm.c 2010-01-14 22:12:54.972781312 -0500	+	--- src/uqm.c 2009-11-07 09:23:35.624611920 -0500
-	TFB_InitInput (TFB_INPUTDRIVER_SDL, 0);	+	+++ src/uqm.c 2010-01-14 22:12:54.972781312 -0500
-	// Program initiation completed successfully	+	TFB_InitInput (TFB_INPUTDRIVER_SDL, 0);
-	+ // MAEMO: Save the user's native keyboard layout and switch to known arrow-key compliant one	+	// Program initiation completed successfully
-	+ system("/usr/bin/gconftool-2 -g /apps/osso/inputmethod/int_kb_layout > /home/user/.uqm/int_kb_layout");	+	+ // MAEMO: Save the user's native keyboard layout and switch to known arrow-key compliant one
-	+ system("/usr/bin/gconftool-2 -s /apps/osso/inputmethod/int_kb_layout us -t string");	+	+ system("/usr/bin/gconftool-2 -g /apps/osso/inputmethod/int_kb_layout > /home/user/.uqm/int_kb_layout");
-	// Start main loop	+	+ system("/usr/bin/gconftool-2 -s /apps/osso/inputmethod/int_kb_layout us -t string");
-	StartThread (Starcon2Main, NULL, 1024, "Starcon2Main");	+	// 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.		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 @@	+	<source lang="diff">
-	mem_uninit ();	+	@@ -471,6 +478,11 @@
-	} // End program	+	mem_uninit ();
-	+ // MAEMO: Reset the user's keyboard layout based on the value recorded at the start	+	} // End program
-	+ system("/usr/bin/gconftool-2 -s /apps/osso/inputmethod/int_kb_layout $(cat /home/user/.uqm/int_kb_layout) -t string");	+	+ // 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.		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	+	<source lang="diff">
-	+++ src/libs/graphics/sdl/sdl_common.c 2010-01-14 22:13:36.531416322 -0500	+	--- src/libs/graphics/sdl/sdl_common.c 2009-11-07 10:23:58.974265870 -0500
-	if (Event.active.state & SDL_APPINPUTFOCUS) {	+	+++ src/libs/graphics/sdl/sdl_common.c 2010-01-14 22:13:36.531416322 -0500
-	GameActive = Event.active.gain;	+	if (Event.active.state & SDL_APPINPUTFOCUS) {
-	+ // Switch to english or user's native keyboard layout when gaining/loosing focus	+	GameActive = Event.active.gain;
-	+ if (!GameActive)	+	+ // Switch to english or user's native keyboard layout when gaining/loosing focus
-	+ system("/usr/bin/gconftool-2 -s /apps/osso/inputmethod/int_kb_layout $(cat /home/user/.uqm/int_kb_layout) -t string");	+	+ if (!GameActive)
-	+ else	+	+ system("/usr/bin/gconftool-2 -s /apps/osso/inputmethod/int_kb_layout $(cat /home/user/.uqm/int_kb_layout) -t string");
-	+ system("/usr/bin/gconftool-2 -s /apps/osso/inputmethod/int_kb_layout us -t string");	+	+ else
-	}	+	+ system("/usr/bin/gconftool-2 -s /apps/osso/inputmethod/int_kb_layout us -t string");
		+	}
		+	</source>

-	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.	+	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==		==Documenting the UI==

← Older revision		Revision as of 12:47, 12 February 2010
Line 78:		Line 78:

	[[Image:N900_keyboard_keymap_template.png‎]]		[[Image:N900_keyboard_keymap_template.png‎]]
		+
		+	[[Category:Development]]
		+	[[Category:Documentation]]
		+	[[Category:Fremantle]]

← Older revision		Revision as of 16:09, 30 January 2010
Line 10:		Line 10:
	* The '''Enter''' key on the N900 sends the ''KP_ENTER'' signal, not the ''ENTER'' signal.		* 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.		* 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 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 Keyboard Locale Problem==
Line 66:		Line 66:

	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.		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.
		+
		+	==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.		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		Example: The UQM keymap
		+
	[[Image:Uqm-keymap.jpg]]		[[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‎]]

← Older revision		Revision as of 16:01, 30 January 2010
Line 15:		Line 15:

	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.		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.		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	+	===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 on exit
	# Restore the user's original layout when they switch away from the app		# Restore the user's original layout when they switch away from the app
Line 62:		Line 66:

	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.		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.
		+
		+	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]]