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

Developer

resources

Keypad support

Brew MP provides events and notifications that represent the user's interaction with the keypad. In addition, Brew MP provides two interfaces that support extended keypads (such as QWERTY): IKeysMapping and IKeysConfig.

When the user interacts with the keypad, the OEM layer sends events into Brew MP. Brew MP will, in turn, send events and notifications to certain applets on the device, allowing them to take action based on the user's input.

Terminology

Key events are sent by Brew MP whenever a key is pressed, held, or released. Key hook events provide a way for an application to receive key events before they are sent to other applications, including the top-visible application. To create a privileged Brew MP application that receives key hook events, refer to the Capturing all keypress events topic. Applications can also register to receive notifications.

Events

It is extremely important that the OEM layer send key events to Brew MP at all times. Although Brew MP key events are sent with AEE_Event(), they are handled asynchronously. The return value of the AEE_Event() function called with EVT_KEY, EVT_KEY_PRESS or EVT_KEY_RELEASE indicates whether the key event has been queued.

Much of this Keypad support section explains keypad-related events in Brew MP: how they are sent, captured, and handled; and how Brew MP uses events to support extended keypads.

Notifications

Brew MP applications must register to receive notifications, even when they are running in the background. To register for a notification, call ISHELL_RegisterNotify() with NMASK_SHELL_KEY as the lower 16bits and the AEE Virtual Key (AVK) code of the desired key as the upper 16bits of dwMask parameter.

To register for all notifications, NOTIFIER_VAL_ANY should be used for the AVK code. An application can also register for specific notifications in the MIF of the application instead of using the ISHELL_RegisterNotify() API. For each registered key, the application receives the EVT_NOTIFY event in its event handler with wParam as the AVK code and dwParam of the type AEENotify.

The pData member inside this AEENotify structure is of type NotifyKeyEvent. For more information on AEENotify and NotifyKeyEvent, refer to the Brew MP OEM API Reference Online Help.

Key event notifications are always first sent to any privileged applications that have registered for key hook events. If any of these privileged applications handle the key event but do not consume it, the clsHandled member of NotifyKeyEvent received on EVT_NOTIFY is set to the class of the privileged application. If none of the applications that have registered for key hook events handle the key event, then the key event is sent to the current top-visible application. If that top-visible application handles the key event, then clsHandled is set to the class ID of the top-visible application. The top-visible application cannot prevent the key event from being delivered to registered applications.

An application that has registered for key notification events can prevent the notification from going to other applications by consuming the notification. To consume the notification, the application needs to set the “st” field of dwParam to NSTAT_STOP before returning from the EVT_NOTIFY handler.

case EVT_NOTIFY:
  (AEENotify *)wp = (AEENotify *)dwParam;
  wp->st = NSTAT_STOP;
  return TRUE;

If multiple applications have registered for key press notifications using ISHELL_RegisterNotify(), the order in which notifications are sent depends on the order in which the applications registered with Brew MP. The notification delivery order is the reverse of the registration order. If A1 registered first and then A2, the notification is first sent to A2 and then to A1. However, if registering for notifications is done through the MIF file, the registration order cannot be guaranteed.