Resources | developer.brewmp.com Resources | developer.brewmp.com

Developer

resources

Programming for Devices with Extended Keyboard Functionality

Base version:

Brew MP 1.0

Tested version:

Brew MP 1.0

Phone tested:

No

Objective

This topic describes how to create an application for handsets with extended keyboards. The interfaces described were implemented with full support in Brew® 3.1.5 SP01 unless otherwise noted in a handset's device pack. Handsets with earlier Brew versions may have partial or modified support of the interfaces described. Always consult a handset's device pack specification listing to determine handset capabilities.

Requirements

Use the IKeysMapping and IKeysConfig interfaces in applications to decode the key event information. Key events contain extra information to communicate the meaning of key presses to an application.

For handsets with extended keyboards, such as QWERTY, a single key can have multiple input values. For example, an [A] key may also be capable of giving an input of 'a' or a symbol such as '@'. In addition, a combination such as [Function] + [A] can mean an input of '#' on one handset while it means '@' on another.

Device pack requirements

To support IKeysMapping, the device pack must include a map.csv file that provides [key] + [modifier] = [character] mappings. The device pack field IDS_DD_EXTENDED_KEYPAD_SUPPORT indicates whether the device supports an extended keypad using the standard Brew MP behavior described in this topic.

If the device pack contains a map.csv file, IKeysMapping is supported on the Brew MP Simulator, which provides the correct key events as described in this document. When using the Simulator, you can use the PC keyboard to press key combinations, such as [Shift] + [A]. In the Properties tab of the Simulator, a device pack that provides support for IKeysMapping will have a value of Yes for the Extended keypad support field, as shown below.

Event handling

Key events contain the following information:

Primary key The main character that is mapped to a specific hardware key.
Secondary key Additional characters that are mapped to a specific hardware key. A secondary key may be an upper or lower case version of the primary key or a symbol.
Modifiers Flags that communicate to the application which secondary key, if any, has been input from the keypad.
Sticky keys Modifier keys whose state stays constant between key presses, such as a Num Lock or Caps Lock.
Unicode The character encoding specification as described in UCS-2.

There are two types of key events:

  • Primary key events

    • All pressed keys generate the standard key events: EVT_KEY_PRESS, EVT_KEY, and EVT_KEY_RELEASE.
    • For primary keys mapped to a character with a Unicode value, the wParam for the event contains the Unicode value for the character.
    • For primary keys that are alphabetical (A - Z), wParam contains the lower case Unicode value for the letter.
    • The AVK codes, AVK_A through AVK_Z are defined in AEEVCodes.h for convenience, and are equal to the lower case Unicode values for the key press. For example, pressing the [A] key will generate EVT_KEY events with wParam = 97 (the value of AVK_A and the Unicode value for 'a').
  • Secondary key events

    • Secondary key events include one or more modifiers in addition to the primary key information.
    • The combination of the primary key and the modifiers identifies the secondary key.
    • When secondary key events occur, the wParam (primary key code) of an event is the same as it would be for a primary key event and the dwParam value contains the modifiers for the event.
    • The value reported in dwParam is a bitwise OR combination of all currently active modifiers.
    • All keypad event modifiers are defined in AEEVCodes.h. For example, with the [Left Shift] modifier set, pressing [A] will generate an event with the following parameters:
    eCode = EVT_KEY_PRESS (EVT_KEY and EVT_KEY_RELEASE events will
    be received in a similar fashion)
    wParam = AVK_A
    dwParam = KB_LSHIFT

    In the above example, dwParam may be replaced by any combination of modifiers that are valid on the handset, such as KB_SYMBOL, KB_CAPSLOCK, etc., and communicates to the application the modifier(s) that are active when the key is pressed. The possible combinations of modifiers are handset specific. The IKeysMapping interface provides methods to decode overloaded key values. The device pack field IDS_DD_EXTENDED_KEYPAD_SUPPORT specifies the support (YES/NO) of this feature for each specific handset.

Sample code location

ZIP filename

Location

Run app

c_qwertysampleapp

Brew MP Library

  • Download and extract the ZIP file.
  • Compile the app.
  • Run it on the Brew MP Simulator.

Note: To use IKeysMapping on the Simulator, you must copy the map.csv file to the tools\simulation directory in the Brew MP SDK. Make sure to turn off Numlock, Capslock, and Scrolllock on the PC keyboard to avoid interference with keys mapping.

Example - IKeysMapping

Note: This sample code requires the AEEIKeysMapping.h and AEEIKeysConfig.h header files, located in the platform\hardware\inc directory of the Brew MP SDK.

In the following example, IKeysMapping_GetMapping() is called to get the AVK code and modifier for the character, then TextEntry_FindModifier() determines which key was pressed.

   
      if(dwParam) {
         nRetval = IKeysMapping_GetMapping(pMe->m_pIKeysMapping,
                  wParam, dwParam, &mapping);
         TextEntry_FindModifier(pMe, dwParam);
      }
      else {
         mapping = wParam;
      }      

Example - IKeysConfig

Note: Changing sticky key states is a global operation that can affect other applications that are executing concurrently or execute after the change has occurred. It is recommended that applications refrain from modifying sticky key states when they are operating as either a background or a non-top-visible application.

The IKeysConfig interface allows an application to control sticky modifier keys. An application can use the IKeysConfig_GetStickyKeys() interface to determine which sticky keys are present on the handset. An application can also read and modify sticky key states using IKeysConfig_GetKeyState() and IKeysConfig_SetKeyState(), respectively. The IKeysConfig API is available as a QueryInterface on IKeysMapping.

//Exercise IKeysConfig interface
   IKeysConfig_GetStickyKeys(pMe->m_pIKeysConfig, &dwStickyKeys);
   switch(wParam)
   {
      case IDC_CAPS:
         {
            if (pMe->m_dwStickyKeys & KB_CAPSLOCK)
            {
               //If caps lock is present, read its state
               IKeysConfig_GetKeyState(pMe->m_pIKeysConfig, KB_CAPSLOCK,
                        &bKeystate);
               /* Logic to handle Caps Lock state */
               IKeysConfig_SetKeyState(pMe->m_pIKeysConfig, KB_CAPSLOCK,
                        !bKeystate);
	
            }
         }
         break;

      case IDC_NUMLOCK:
         {
            if (pMe->m_dwStickyKeys & KB_NUMLOCK)
            {
               //If caps lock is present, read its state
               IKeysConfig_GetKeyState(pMe->m_pIKeysConfig, KB_NUMLOCK,
                        &bKeystate);
               /* Logic to handle Caps Lock state */
               IKeysConfig_SetKeyState(pMe->m_pIKeysConfig, KB_NUMLOCK,
                        !bKeystate);
            }
         }
      break; 
  
   default:
      break;
   }

It is recommended that applications that are impacted by sticky keys use the IKeysConfig_GetStickyKeys() and IKeysConfig_GetKeyState() interfaces to ascertain sticky key states upon startup and resume instead of assuming a default launching condition. This will prevent incorrect performance caused by differences between handset input state and an application's operational state.

ITextCtl Support for extended keyboard functionality

If your application is using ITextCtl to receive text input from the the user, a new input mode, AEE_TM_EXTENDED_KEYS, was added to the ITextCtl interface in Brew 3.1.5 SP01. (Earlier Brew versions that use extended keypads may have partial support or no support for ITextCtl and may require application support to operate correctly.)

In the AEE_TM_EXTENDED_KEYS mode, ITextCtl automatically decodes key events by internally calling IKeysMapping and displays the correct character in the text box for the current sticky key state. For handsets supporting this input mode, an application should make the following call at the beginning of execution:

ITEXTCTL_SetInputMode(pMe->pITextCtl, AEE_TM_EXTENDED_KEYS);

Applications do not need to modify further the input mode of ITextCtl to properly display key events that are passed using the ITEXTCTL_HandleEvent() interface. Because ITextCtl is internally calling IKeysMapping on events it receives, the application should only pass in the raw key event values sent to the application by Brew MP, without any modification to these values.

Comments

deepak4bin 13 Jun 2011 11:53am

where can I find c_qwertysampleapp?