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

Developer

resources

Sending and handling keypress events

To send key events to Brew MP at all times:

  1. In scenarios where it is not possible to send key events to Brew MP, you must call the function AEE_Active() whenever a key is pressed. This allows Brew MP to deal with the screen saver correctly.
  2. For each key pressed and released, you must translate key input into an AEE Virtual Key (AVK) code and send an event via each of the following functions:

Event When to send
AEE_KeyPress() (EVT_KEY_PRESS) Send as soon as the key is pressed.
AEE_KeyRelease() (EVT_KEY_RELEASE) Send as soon as the key is released.
AEE_Key() (EVT_KEY) Send immediately after EVT_KEY_PRESS.

Note: The three functions listed above take one input parameter, which is the translated AEE Virtual Key code of the AVKType enumeration type defined in the AEEVCodes.h header file.

Sending key repeat events

While a key is held, Brew MP sends key repeat events to Brew MP applications.

Brew MP starts an internal timer as soon as it receives the first EVT_KEY following an EVT_KEY_PRESS. This timer triggers repeated EVT_KEY events to the Brew MP application while the key is held, and continues to repeat until Brew MP receives EVT_KEY_RELEASE from the OEM. Because of this repeat function, it is extremely important to send EVT_KEY_RELEASE to Brew MP as soon as the key is released. Sending EVT_KEY without EVT_KEY_RELEASE results in repeated EVT_KEY events being sent to the Brew MP application.

Note: Previous BREW versions supported an EVT_KEY_HELD event to indicate that a key was held. This event is now deprecated. Instead, repeated EVT_KEY events are sent to the Brew MP application to indicate that a key is being held.

Example scenario

The following example shows an event flow from the perspective of a Brew MP application and steps for handling key events from an OEM perspective:

Scenario:

  1. Press key AVK_1.
  2. Hold key AVK_1 for 1 minute.
  3. Release key AVK_1.

Event flow from a Brew MP application perspective:

  1. EVT_KEY_PRESS (wParam = AVK_1)
  2. EVT_KEY (wParam=AVK_1, dwParam=0)
  3. EVT_KEY (wParam=AVK_1, dwParam=KB_AUTOREPEAT)

    Note: The KB_AUTOREPEAT indicates to the application that this is a repeat of the same key.

  4. EVT_KEY (wParam=AVK_1, dwParam=KB_AUTOREPEAT)
  5. EVT_KEY_RELEASE (wParam=AVK_1)

To handle key events from an OEM perspective:

  1. Call AEE_KeyPress (AVK_1) when AVK_1 is pressed.
  2. Call AEE_Key (AVK_1) for EVT_KEY event.
  3. Call AEE_KeyRelease (AVK_1) when AVK_1 is released.

Note: The following basic requirements apply for Brew devices with physical keys:

  • The END or HOME key on the device must send the AVK_END keycode. This is required in order for Brew to apply default processing for END key handling.
  • If the device has a Clear or Back key, this key must send the AVK_CLR keycode. This is required in order to ensure uniform key codes are sent to applications.
  • If the device has physical Volume Up and Volume Down keys, they must send the AVK_VOLUME_UP and AVK_VOLUME_DOWN key codes, respectively.

Configurable timers for key repeat events

The OEM may configure the key repeat timers by customizing the KBAutoRepeatGet() function in OEMBREWSettings.c (platform\brewmp\system\brewcore\src\OEM\ishellbased\msm). This function writes a string to the pszValue parameter that contains two numbers. The first number is the initial timeout, after which Brew starts sending the auto-repeated key events. The second number is the delay between subsequent auto-repeated key events. For example, a string such as "1000 200" means that after a key is held for 1000ms, Brew starts sending auto-repeated key events every 100ms while that key is held. Brew's defaults are:

  • KB_AUTOREPEAT_START (1500ms)
  • KB_AUTOREPEAT_RATE (100ms)

Application behavior

Keypad auto-repeat keys are transmitted to the application as follows:

  • EVT_KEY_PRESS
  • EVT_KEY (wParam = Key, dwParam = 0)
    • Brew MP sets a timer to KB_AUTOREPEAT_START or the OEM-defined value if it is non-zero.
    • Brew MP does not auto-repeat if you indicate that auto-repeat is off (OEMKBAutoRepeat.dwStart = 0).
    • When the timer expires, the following logic repeats while the key is held.
  • EVT_KEY (wParam = key, dwParam = KB_AUTOREPEAT)
    • The timer sets to KB_AUTOREPEAT_RATE or the OEM-defined value if it is nonzero.
    • Events do not repeat if the OEM sets OEMKBAutoRepeat.dwRate to 0.
  • EVT_KEY_RELEASE

The following diagram shows a simple case in which a single key is pressed at one time:

Key modifiers

There are several key modifiers defined for Brew MP, in AEEVCodes.h, which must be passed along with the Brew MP AEE Virtual Key codes. This value is passed as the dwParam value (the third parameter of the type uint32) in the AEE_Event() function. For every key modifier you detect, you need to perform a bit-wise OR operation to send multiple key modifiers if there is more than one.

Note: When there are key modifiers, you cannot use the AEE_Key() macro. Instead, you must use AEE_Event(). For example, if the 1 key was pressed along with the Left Shift key and the Left Alt key, you must make sure the two modifiers are included in the key event as shown below:

AEE_Event(EVT_KEY, AVK_1, (KB_LSHIFT | KB_LALT));

Note: When key modifiers are used, you still must generate key events, for example, AEE_Key, AEE_KeyPressed and AEE_KeyReleased for each of the modifier keys.