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

Developer

resources

Device integration

This section describes how pointer events are generated and sent.

In Brew MP, pen events (EVT_PEN_DOWN, EVT_PEN_MOVE, EVT_PEN_UP and EVT_PEN_STALE_MOVE) are deprecated in favor of more generic pointer events. Brew MP supports EVT_POINTER_DOWN, EVT_POINTER_MOVE, EVT_POINTER_UP, and EVT_POINTER_STALE_MOVE events generated by pointing devices such as a stylus, touch-screen, mouse, and so forth. These events allow the OEM layer to notify Brew MP and Brew MP applications about pointing device activity such as putting the pointer down or lifting it up on a capable screen, or moving the pointing device across the screen.

The new events and their parameters are listed below.

Pointer events generated by OEMs

The EVT_POINTER_DOWN event is sent when the pointing device is put down on the capable screen.

The EVT_POINTER_MOVE event is sent when the pointing device is moved across the capable screen while remaining in touch with the screen.

The EVT_POINTER_UP event is sent when the pointing device is lifted up from the capable screen.

Pointer events generated by Brew MP

The EVT_POINTER_STALE_MOVE event must not be sent by OEMs. Brew MP sends this event to the applets when it sees an EVT_POINTER_MOVE event, and if there is a move near a pending EVT_POINTER_MOVE event in the event queue.

IF there are 50 pointer move events already in the queue and more move events are received, the events already in the queue are trimmed starting with the second event and increasing up to the 50 in order to create equally spaced move events. This cycles until the Brew MP applet starts consuming events from the queue. This way Brew MP can accept the newer move events,while still maintaining a fairly accurate trace of the older move event.

The table below contains the pointer event parameters to be passed to AEE_Event():
Parameter Value Description
AEEEvent evt

EVT_POINTER_DOWN

EVT_POINTER_MOVE

EVT_POINTER_UP

Pointer events.
uint16 wparam Unsigned 16-bit value The size of single-byte character string pointed to by dwparam, including the terminating NULL character, in bytes.
uint32 dwparam Pointer to a NULL-terminated single-byte-character string.

dwParam is a pointer to a NULL-terminated single-byte-character string containing pointing device information in the form of delimiter-based “name=value” pairs for x-coordinate, y-coordinate, time, click count, modifiers, ptrID, displayID, etc.

e.g.: x=00000017,y=FFFFFFFB, time=00003456,clkcnt=2,” where x=+23 and y=-5 in decimal.”

x and y are mandatory parameters that need to be set by OEMs. ptrID and displayID are optional parameters that may be generated by OEMs if the device supports only one pointing device or only one display. However ptrID is mandatory if there is more than one pointing device and displayID is mandatory if there is more than one display. Brew MP calculates the time and click count and insert it into the dwParam string before sending the event to the app. See the section below for a detailed description of each parameter.

Generating pointer events

OEMs must send pointer events using the AEE_Event() function if their device has a pointing component (stylus, mouse, touch-screen and so on). The event codes can be one of the following:

  • AEE_Event (EVT_POINTER_DOWN, wParam, dwParam): This event is sent when the pointing device comes in contact with the screen.
  • AEE_Event (EVT_POINTER_MOVE, wParam, dwParam): This event is sent when the pointing device moves on the screen while maintaining contact with the screen.
  • AEE_Event (EVT_POINTER_UP, wParam, dwParam): This event is sent when the pointing device loses contact with the screen.

    Where dwParam is a pointer to a NULL-terminated single-byte-character string containing delimiter-based name=value pairs; and wParam is the length of the single-byte-character string pointed to by dwparam, in bytes, including the terminating NULL character.

The pointer events can be generated using one of two options:

  • If you need to send only the mandatory x and y coordinates for the pointer event and do not have any additional optional parameters, use the helper function AEE_POINTER_SEND_XY(, x, y) defined in OEMPointerHelpers.h. The helper function takes care of generating the dwparam single-byte-character string in the proper format and uses AEE_Event to dispatch the pointer event to Brew MP.
  • If you need to send additional optional parameters along with the mandatory x and y coordinates for the pointer events, use the helper function AEE_POINTER_SET_XY(, , x, y) or AEE_POINTER_SET_XY_OFFSET((, , offset for x, offset for y) to format the x and y name-value pairs and then append the optional parameters to the single-byte-character string. The latter function uses offsets on top of existing coordinate values. The x-coordinate string should be at AEE_POINTER_XSTR_OFFSET and the y-coordinate string should be at AEE_POINTER_YSTR_OFFSET. After generating the entire single-byte-character string, use AEE_Event to send the pointer event to Brew MP with the parameters as described in the table above. Make sure to NULL-terminate the buffer before sending it using AEE_Event. Brew MP duplicates the string and you can deallocate or remove any references to the char string after AEE_Event returns. The size of the single-byte-character string pointed to by dwParam needs to be at least as big as AEE_POINTER_X_SIZE + AEE_POINTER_Y_SIZE + AEE_POINTER_DISPID_SIZE + 1.

The string composed by OEMs (or auto-generated using the AEE_POINTER_SEND_XY helper function) should contain the following name-value pairs separated by the comma (,) delimiter:
Name Value Description Helper function(s) Example
x (mandatory) signed integer in decimal X-coordinate of the pointer relative to the top-left location (0,0) of the display screen. The numeric string should contain 8 characters representing the hexadecimal value of the x-coordinate for the pointer event. . Example: ‘x=00000017,’ for a total length of 11 single-byte characters (AEE_POINTER_X_SIZE). The x-coordinate string in the dwParam should be at AEE_POINTER_XSTR_OFFSET. AEE_POINTER_SEND_XY

Or

AEE_POINTER_SET_XY

Or

AEE_POINTER_SET_XY_OFFSET

Or

AEE_POINTER_SEND_XY_DISPID

Or

AEE_POINTER_SET_XY_DISPID
“x=00000017,” where x = +23 in decimal
y (mandatory) signed integer in decimal Y-coordinate of the pointer relative to the top-left location (0,0) of the display screen. The string should contain 8 characters representing the hexadecimal value of the sign representing the y-coordinate for the pointer event. Example: “y=FFFFFFFB,” for a total length of 11 single-byte characters (AEE_POINTER_Y_SIZE). The y-coordinate string in the dwParam should be at AEE_POINTER_YSTR_OFFSET. AEE_POINTER_SEND_XY

Or

AEE_POINTER_SET_XY

Or

AEE_POINTER_SET_XY_OFFSET

Or

AEE_POINTER_SEND_XY_DISPID

Or

AEE_POINTER_SET_XY_DISPID
“y=FFFFFFFB,” where y = (-5) in decimal
ptrID (optional if only one pointing device is supported, mandatory otherwise) unsigned integer in decimal The ID of the pointing device. The numeric string should contain 2 characters representing the hexadecimal value of the pointing device’s ID. . Example: “ptrID=01,”, for a total length of 9 single-byte characters “ptrID=01,”
dispID (optional if only one display screen is supported, mandatory otherwise) unsigned integer in decimal representing the AEECLSID of the display screen The AEECLSID of the display screen on which pointer event occurred. The numeric string should contain 8 characters representing the hexadecimal value of the AEECLSID of the screen on which the event occurred. Example: "dispID=010127d4,", for a total of 16 single-byte characters (AEE_POIN TER_DISPID_SIZE). AEE_POINTER_SEND_XY_DISPID

Or

AEE_POINTER_SET_XY_DISPID
“dispID=010127D4," for AEECLSID_DISPLAY1
mousebtn (optional if the device doesn’t support mouse) unsigned integer in decimal representing the mouse modifier bit-mask. Mouse-button modifiers to be sent for EVT_POINTER_DOWN to notify BREW which mouse button (defined in AEEPointerHelpers.h) is pressed. The numeric string should contain 8 characters representing the hexadecimal value of the AEECLSID of the screen on which the event occurred. Example: "dispID=010127d4,", for a total of 16 single-byte characters (AEE_POINTER_DISPID_SIZE). Example, if AEE_POINTER_MOUSE_LBUTTON is pressed, “mousebtn=00001,” for a total of 14 single-byte characters. "mousebtn=00001,”

Note: The OEMBitmap implementation should take into consideration display rotation in the functions, OEMBitmap_AppToScreen() and OEMBitmap_ScreenToApp(). (The rotation information will be stored in pMe->m_nRotation if the directions from the Display Rotation OEM Note have been followed.)

When the screen is rotated on a device, OEMs should send an EVT_SCR_ROTATE event to Brew MP using the following macro: AEE_SEND_SCRROTATE_EVT (pAEEDeviceNotify). These functions are used by Brew MP to translate pointer coordinates before they are passed along to applets.

Example

Assume that:

  • Upright portrait mode is the default display mode.
  • x and y were the coordinates of the touch.
  • W and H are the width and height of the touchscreen.

For a 90 clockwise rotation, x, y must be adjusted as follows:

  • xNew = H - y;
  • yNew = x;

For a 180 clockwise rotation, x, y must be adjusted as follows:

  • xNew = W - x;
  • yNew = H - y;

For a 270 clockwise rotation, x, y must be adjusted as follows:

  • xNew = y;
  • yNew = W - x;

Any custom parameters that OEMs send along with the pre-defined parameters should be contained in a case-sensitive MIME-style namespace. The name value pair for custom parameters should have the following format: “x--=value”. Example, hypothetically if the Brew MP Simulator generates a pressure name-value pair, it would append the following string to the dwParam: “x-BREWSimulator-pressure=100,”. Always ensure that the single-byte-character string pointed to by dwParam is NULL-terminated.

For the above example where x = 23 and y = 10 and generating only the mandatory parameters, the single-byte-character string pointed to by dwparam will look like “x=+0000023, y=-0000005,” with a total size of 23 bytes including the terminating NULL-character.

Brew MP appensd the timestamp, clickcount, and modifiers to the dwparam and passes it along to the applet. OEMs should not generate the following parameters.
Name Value Description Example
time (generated by Brew MP) unsigned integer in decimal Time-stamp of pointer event in milliseconds. The unsigned numeric string should contain 8 single-byte hexadecimal characters representing the 32-bit time value as returned by GETUPTIMEMS() -- used to calculate the time lag between events. Example: “time=003684F9,” for a total length of 14 single-byte characters (AEE_POINTER_TIME_SIZE).

“time=003684F9,”

clkcnt (generated by Brew MP) unsigned integer in decimal Click count. The unsigned numeric string should contain 1 single-byte hexadecimal character representing the click count. The click count is a running count of the number of pointer clicks received during the OEM-specified duration. For example, if the timeout duration is 500 milliseconds and two EVT_POINTER_DOWN events are received within 500 milliseconds of each other, then AEE_ POINTER_GET_CLICKCOUNT will return 2 for the second EVT_POINTER_DOWN event. This is typically used to identify double-click events. Example: “clkcnt=2,” for a total length of 9 single-byte characters (AEE_POINTER_CLKCNT_SIZE). “clkcnt=2,”
modifiers (generated by Brew MP) A bit-mask represented as a single-byte character string. Modifiers can be for:
  • Keyboard keys like Shift, Alt, Control, etc. (see EVT_KEY dwParam bits defined in AEEVCodes.h)
  • Mouse buttons like Middle, Left, Right
  • Additional pointing-device-specific flags, described below

Keyboard modifiers are represented by 8 single-byte hexadecimal characters corresponding to the 32-bit key modifier state. For example, if KB_RSHIFT, KB_RCTRL, KB_RALT and KB_NUMLOCK are set, the key modifier string consists of the following substring in the modifier string: "0004002A".

Mouse modifiers are represented in the same way as keyboard modifiers and are appended to the keyboard modifier substring to generate the "modifiers" string. The only difference is that the mouse modifiers are 16-bit values and are represented by 4 single-byte hexadecimal characters in the modifier string. For example, if AEE_POINTER_MOUSE_LBUTTON is pressed, the mouse modifier substring is "0001".

The additional pointing device modifier flags provide additional information specific to the pointer events. These are 16-bit values represented by 4 single-byte hexadecimal characters in the modifier string. For example, if a pointer move event is dropped, the AEE_POINTER_EVENT_DROPPED flag is set and the additional modifiers string is "0001".

For example: "modifiers=0004002a00010001," for a total length of 27 single-byte characters (AEE_POINTER_MODIFIERS_SIZE).

The modifiers string in the dwParam is at AEE_POINTER_MODIFIERS_OFFSET.

Use AEE_POINTER_GET_KEY_MODIFIERS() or AEE_POINTER_GET_MOUSE_MODIFIERS() to obtain the values.

AEE_POINTER_IS_EVENT_DROPPED() returns TRUE if a move event was dropped and FALSE otherwise.