API Reference | developer.brewmp.com API Reference | developer.brewmp.com

Developer

API Reference

AEEEVENT

Brew Release
Brew MP 1.0.2
See Also
Border Events BTEvent dbg_Event DBGEVENT DBGEVENT_EX Events Model Events ModelEvent ListModelEvent ScrollEvent Widget Events
Description
This topic describes the AEE events that can be received by an applet or control. For each AEEEvent, the wParam and dwParam parameters (if any) that are passed to the applet or control are given.
The following tables list the event codes and key codes supported by Brew MP.

Applet Events


EVT_APP_START_WINDOW:      In response to a request to start an application in the foreground, before the application 
                           is sent EVT_APP_START, the application is sent this event to enable the application 
                           to start as a windowed application. If the application handles this event (returns TRUE), 
                           the application is started in the background as a windowed application, and EVT_APP_START 
                           is not sent.  If the application does not handle this event (returns FALSE), application 
                           startup continues as normal, which typically means that EVT_APP_START will be sent, and 
                           the application will be transitioned to the top-visible state.
EVT_APP_START:             This event is sent in response to a request to start an application in the foreground. 
                           If the application handles this event (returns TRUE), the application is started and 
                           made top visible. If the application does not handle this event (returns FALSE), 
                           application startup is aborted, and the failure to start the application is specified by 
                           asynchronous notifications corresponding to the NMASK_SHELL_START_STATUS and 
                           NMASK_SHELL_SYS_ERROR masks.
EVT_APP_STOP:              App stopped : dwParam = (boolean *).  On return, the application must set *dwParam to FALSE 
                           if it does not want to close and wants to become a background application. EVT_APP_STOP is not 
                           sent if ISHELL_StartApplet is called on an app which is about to close. Note that after an app
			   handles EVT_APP_STOP, its IApplet instance will be released, and can no longer be used by the app.
			   When the IApplet instance of the app is released, IApplet_Release will be called. Depending on how
			   the app has implemented IApplet, the app may be able to get a cleanup callback into it, which will
			   be the last point at which the IApplet can be safely used. For example, the standard AEEAppGen.c
			   implementation of IApplet allows the app to register a cleanup function when calling AEEApplet_New,
			   which will be called when IApplet_Release is called. An app may be invoked into, after its 
			   IApplet is released. This typically happens for app hosted remote objects, for example in the case
			   of windowed apps. It is not safe to use the IApplet at this point.
EVT_APP_SUSPEND:           App suspended:  wParam == AEESuspendReason, dwParam = AEESuspendInfo *
                           If an application refuses to suspend by returning FALSE on this event, the application is
                           closed.
EVT_APP_RESUME:            App resumed: dwParam = ( AEEAppStart * )
                           If an application refuses to resume by returning FALSE on this event, the application 
                           resume is aborted, and the failure to resume the application is specified by asynchronous 
                           notifications corresponding to the NMASK_SHELL_START_STATUS and NMASK_SHELL_SYS_ERROR masks.
EVT_APP_CONFIG:            Alternate App Start: the configuration screen should be shown.
EVT_APP_HIDDEN_CONFIG:     Alternate App Start: hidden configuration screen.
EVT_APP_BROWSE_URL:        Called after EVT_APP_START: dwParam = (const char * pURL)
EVT_APP_BROWSE_FILE:       Called after EVT_APP_START.
EVT_APP_MESSAGE:           Text message: wParam = AEESMSEncoding, dwParam = String format is dependent on the wParam value.
EVT_APP_MESSAGE_EX:        Text message: dwParam = A 32-bit unique message identifier that can be used with ISMS_ReceiveMsg 
                           to get ISMSMsg. 
EVT_ASYNC_ERROR:           Async error notification - dwParam = AEEAsyncError *
EVT_APP_TERMINATE:         Forced version of EVT_APP_STOP.  The application will be released.
EVT_EXIT:                  Sent to any loaded apps when Brew MP terminates.
EVT_APP_RESTART:           Sent to background applications after upgrades.
EVT_EXT_STOP:              Sent to all open applications - dwParam == a zero-terminated list of AEECLSIDs of extensions.
                           This event is sent when Brew MP is about to upgrade extensions from the ADS catalog. A 
						   zero-terminated list of extension classIDs is supplied in dwParam. If the application is using 
						   any of these extentions, it must release it in order for upgrade to finish successfully.
EVT_EXT_CREATE:            Extension class created.
EVT_EXT_RELEASE :          Extension class released.
EVT_APP_NO_CLOSE :         This event is sent to the top-visible application, if the screen saver application is attempting 
                           to become top-visible. By returning TRUE, the application is prevented from being closed.
EVT_APP_NO_SLEEP :         This event notifies the running application to determine if the device may be put into sleep mode or not. 
                           By returning TRUE, the application prevents the device from being put into sleep mode.
EVT_APP_START_BACKGROUND:  The application started in the background.
EVT_APP_WOULD_START:       Sent when ISHELL_StartApplet() is called on the currently top-visible application.
EVT_APP_POST_URL:          Event which copies the URL, located inside dwParam, before sending it to the handler application.

Key Events


Key Codes are received with EVT_KEY, EVT_KEY_PRESS and EVT_KEY_RELEASE.
EVT_KEY:                   App keyup: wParam = KEYCODE, dwParam = Bitflags for modifier keys
EVT_KEY_PRESS:             App keydown: wParam = KEYCODE, dwParam = Bitflags for modifier keys
EVT_KEY_RELEASE:           App keyrelease: wParam = KEYCODE, dwParam = Bitflags for modifier keys
EVT_CHAR:                  This event is now deprecated. Applications will receive EVT_KEY events
                           for character keys as well.
EVT_UPDATECHAR:            This event is now deprecated. Applications will receive EVT_KEY events
                           for character keys as well.

Key Filtering/Hook Events


These events are sent to running applications with AFLAG_PHONE set. If any of these applications handles the event, then the event isn't cascaded further, and the corresponding key event is not sent to the current top-visible application. This provides a way for privileged applications to provide custom handling for specific key events such as AVK_END. There should be a very small number of applications on the device (preferably just one) that have AFLAG_PHONE set. If not, it can cause slowness on the device because, corresponding to every key event, Brew MP will first send key hook events to the currently running AFLAG_PHONE apps.
EVT_KEY_HOOK:             hook key: wParam = KEYCODE, dwParam = Bitflags for modifier keys
EVT_KEY_HOOK_PRESS:       hook keydown: wParam = KEYCODE, dwParam = Bitflags for modifier keys
EVT_KEY_HOOK_RELEASE:     hook keyrelease: wParam = KEYCODE, dwParam = Bitflags for modifier keys

Control Events


EVT_COMMAND:               Application custom control.
EVT_CTL_TAB:               Application TAB event sent by controls: dwParam = control, wParam = 0-left,
                           1-right
EVT_CTL_SET_TITLE:         Message interface to set the title: wParam = ID, dwParam = res file
                           (if ID != 0) or text.
EVT_CTL_SET_TEXT:          Message interface to set text: wParam = ID, dwParam = res file (if ID
                           != 0) or text.
EVT_CTL_ADD_ITEM:          Message interface to add an item: dwParam = CtlAddItem
EVT_CTL_CHANGING:          App dwParam = CtlValChange
EVT_CTL_CHANGING:          App dwParam = CtlValChange
EVT_CTL_MENU_OPEN:         Sent by text controls before their associated softkey menus are activated.
EVT_CTL_SKMENU_PAGE_FULL:  Sent by IMenuCtl when the SK menu page is full.
EVT_CTL_SEL_CHANGED:       Sent by IMenuCtl when the selection has changed.
EVT_CTL_TEXT_MODECHANGED:  Sent by ITextCtl when the input mode has changed.

Dialog Events


EVT_DIALOG_INIT:           Dialog Event: Controls created, pre-init values, flags, and other items.
EVT_DIALOG_START:          Dialog Event: Dialog opening, wParam = ID, dwParam = IDialog *
EVT_DIALOG_END:            Dialog Event: Dialog completed normally, wParam = ID, dwParam = IDialog *
EVT_COPYRIGHT_END:         Dialog Event: Copyright dialog ended.

AEE Shell Events


EVT_ALARM:                 App wParam = uCode
EVT_NOTIFY:                dwParam = AEENotify *
EVT_NOTIFY_FAILURE         Notification registration failed - dwParam = AEENotifyFailure *
EVT_BUSY:                  Sent to app to determine if app can be suspended or stopped

Device Events


EVT_FLIP:                  wParam = TRUE if open, FALSE if closed 
                           EVT_FLIP indicates that the availability of a device's physical 
                           display has changed.  This event is sent when hardware is closed/moved 
                           blocking a physical display and also when hardware is opened/moved 
                           reexposing the physical display.  Applications can use IFlip to determine 
                           which displays are available upon receiving this event.
                           dwParam = AEEFlipInfo (see AEEDeviceNotifier.h)
EVT_LOCKED:                Deprecated from BREW 3.1
EVT_KEYGUARD:              wParam = TRUE if keyguard is on
                           EVT_KEYGUARD indicates the availability of some keys has changed.  
                           The availability of a key is determined by the ability on the part 
                           of the user to trigger a corresponding key event.  This key event 
                           is then delivered to the top-visible app, or is sent as a notification 
                           to apps that have registered for this key event.  Keys can be blocked 
                           or unblocked by either hardware or software.  For example, a flip can 
                           cover or uncover certain keys.  In software, a key lock application can 
                           block or unblock some or all keys from Brew.  Applications can use IFlip 
                           to determine which keys are available upon receiving this event.
                           dwParam = AEEFlipInfo (see AEEDeviceNotifier.h)
EVT_HEADSET                wParam = TRUE if headset is plugged in, FALSE if otherwise
EVT_SCR_ROTATE             wParam = AEEScrOrientation (Portrait or Landscape)
                           dwParam = screen ID

Pen and Pointer Events


To support existing applications, Brew MP will still generate EVT_PEN_XXX events if the application doesn't handle EVT_POINTER_XXX event. EVT_PEN_XXX events are however considered deprecated and newer applications should handle EVT_POINTER_XXX events instead of EVT_PEN_XXX events.
EVT_JOYSTICK_POS           dwParam = position: signed x in upper 16 bits, y in lower
                           wParam = 15 most significant bits of the wParam represent
                           15 least significant bits of GETUPTIMEMS() and thus can be 
                           used to calculate the time lag between events.
                           The LSB in wParam is 1 if an EVT_JOYSTICK_POS event was 
                           dropped before the current EVT_JOYSTICK_POS event. If the 
                           previous joystick event is in the event queue, then 
                           the LSB of wParam will be 0.
EVT_JOYSTICK_STALE_POS     dwParam = position: signed x in upper 16 bits, y in lower
                           Stale move events are reported when the event queue contains
                           additional moves
                           AEE_GET_X() and AEE_GET_Y() macros may be used to extract
                           the position from dwParam
EVT_PEN_DOWN               Deprecated, see EVT_POINTER_DOWN. dwParam = position: signed x in upper 16 bits, y in lower
EVT_PEN_MOVE               Deprecated, see EVT_POINTER_MOVE. dwParam = position: signed x in upper 16 bits, y in lower
EVT_PEN_UP                 Deprecated, see EVT_POINTER_UP. dwParam = position: signed x in upper 16 bits, y in lower
EVT_PEN_STALE_MOVE         Deprecated, see EVT_POINTER_STALE_MOVE. dwParam = position: signed x in upper 16 bits, y in lower
                           Stale move events are reported when the event queue contains
                           additional unprocessed moves
                           For pen positions, 0,0 is the upper left corner of the active frame
                           AEE_GET_X() and AEE_GET_Y() macros may be used to extract
                           the position from dwParam
EVT_POINTER_DOWN           Sent when the pointing device is put down on the
                           capable screen.
                           dwParam = NUL-terminated single-byte-character string
                           with delimiter-based name=hex value pair representing
                           information about pointing device.
                           e.g.:"x=00000017,y=FFFFFFFB,time=00003456,clkcnt=2", where
                           the decimal equivalents being x = 23 & y = -5.
                           Helper functions defined in AEEPointerHelpers.h can be
                           used to obtain the name-value pairs. See AEE_POINTER_GET_XY()
                           for more details and references to other similar
                           helper functions.
                           wParam = size of dwParam string in bytes including
                           terminating NUL-character.
EVT_POINTER_MOVE           Sent when the pointing device is moved across the capable
                           screen while remaining in contact with the screen. This
                           is equivalent to dragging the pointing device.
                           dwParam = NUL-terminated single-byte-character string
                           with delimiter-based name=hex value pair representing
                           information about pointing device.
                           e.g.:"x=00000017,y=FFFFFFFB,time=00003456,clkcnt=2", where
                           the decimal equivalents being x = 23 & y = -5.
                           Helper functions defined in AEEPointerHelpers.h can be
                           used to obtain the name-value pairs. See AEE_POINTER_GET_XY()
                           for more details and references to other similar
                           helper functions.
                           wParam = size of dwParam string in bytes including
                           terminating NUL-character.
EVT_POINTER_UP             Sent when the pointing device is lifted up from the
                           capable screen.
                           dwParam = NUL-terminated single-byte-character string
                           with delimiter-based name=hex value pair representing
                           information about pointing device.
                           e.g.:"x=00000017,y=FFFFFFFB,time=03456,clkcnt=2", where
                           the decimal equivalents being x = 23 & y = -5.
                           Helper functions defined in AEEPointerHelpers.h can be
                           used to obtain the name-value pairs. See AEE_POINTER_GET_XY()
                           for more details and references to other similar
                           helper functions.
                           wParam = size of dwParam string in bytes including
                           terminating NUL-character.
EVT_POINTER_MT_DOWN        Multitouch down event. This event is the same format as
                           EVT_POINTER_DOWN, but will be used when the down event is 
                           for any pointer ID other than 1.
EVT_POINTER_MT_MOVE        Multitouch move event. This event is the same format as
                           EVT_POINTER_MOVE, but will be used when the move event 
                           does not contain pointer ID 1.
EVT_POINTER_MT_UP          Multitouch up event. This event is the same format as
                           EVT_POINTER_UP, but will be used when the up event is 
                           for any pointer ID other than 1.
EVT_POINTER_STALE_MOVE     Stale move events are reported when the event queue
                           contains additional unprocessed moves.
                           dwParam = NUL-terminated single-byte-character string
                           with delimiter-based name=hex value pair representing
                           information about pointing device.
                           e.g.:"x=00000017,y=FFFFFFFB,time=00003456,clkcnt=2".
                           Helper functions defined in AEEPointerHelpers.h can be
                           used to obtain the name-value pairs. See AEE_POINTER_GET_XY()
                           for more details and references to other similar
                           helper functions.
                           wParam = size of dwParam string in bytes including
                           terminating NUL-character.
EVT_JOGDIAL_POS            dwParam = The 32-bit parameter takes either +1 or -1 values. 
                           A positive value (+1) indicates that the wheel was rotated 
                           anti-clockwise and a negative value (-1) indicates that the wheel 
                           was rotated clockwise. dwParam is uint32.
                           dwParam is uint32. After receiving this event,
                           Brew applications need to type cast dwParam to int32 variable. 
                           wParam = Represents 16 least significant bits of GETUPTIMEMS() and 
                           thus can be used to calculate the time lag between events.

 
EVT_POINTER_XXX parameters:
   EVT_POINTER_DOWN, EVT_POINTER_UP, EVT_POINTER_MOVE and EVT_POINTER_STALE_MOVE.
   These events are generated when the phone device detects actions like touching
   or clicking, lifting, or moving pointing devices on capable display screens.
   The following name-value pairs are possible for the dwParam parameter for
   these events. Helper functions in AEEPointerHelpers.h provide easy and efficient
   access to these values. Example: AEE_POINTER_GET_XY().

   Mandatory name-value pairs:
      X co-ordinate: Name: "x"; Value: X-coordinate of the pointer relative to the
         top-left location (0,0) of the display screen. The single-byte-character string
         contains the hex value representing the signed x-coordinate for the pointer
         event. Example: "x=00000017," (i.e +23 decimal) for a total length of 11
         single-byte characters (AEE_POINTER_X_SIZE). The x-coordinate string in
         the dwParam will be at AEE_POINTER_XSTR_OFFSET.
         Use AEE_POINTER_GET_X() or AEE_PPOINTER_GET_XY() to obtain the value.
      Y co-ordinate: Name: "y"; Value: Y-coordinate of the pointer relative to the
         top-left location (0,0) of the display screen. The single-byte-character string
         contains the hex value representing the signed y-coordinate for the pointer
         event. Example: "y=FFFFFFFB," (i.e. -5 decimal) 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. Use AEE_POINTER_GET_Y() or AEE_PPOINTER_GET_XY()
         to obtain the value.
      Timestamp: Name: "time"; Value: Time-stamp of pointer event in milliseconds.
         The unsigned numeric string contains 8 hexadecimal single-byte-characters
         representing a 32-bit time value.
         Example: "time=00003456," for a total length of 14 single-byte
         characters (AEE_POINTER_TIME_SIZE).
         The time string in the dwParam will be at AEE_POINTER_TIME_OFFSET.
         Use AEE_POINTER_GET_TIME() to obtain the value.
      Click Count: Name: "clkcnt"; Value: Click count. The unsigned numeric string
         contains 1 hexadecimal single-byte-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 can be typically used to identify double-click events. Example:
         "clkcnt=2," for a total length of 9 single-byte characters (AEE_POINTER_CLKCNT_SIZE).
         The click count string in the dwParam will be at AEE_POINTER_CLKCNT_OFFSET.
         Use AEE_POINTER_GET_CLICKCOUNT() to obtain the value.
      Modifiers: "modifiers", Value: 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 a single-byte character
         corresponding to a hexadecimal value for each nibble (4-bits) in the
         32-bit key modifier state. For example, if KB_RSHIFT, KB_RCTRL,
         KB_RALT and KB_NUMLOCK are set, the key modifier string will consist of
         the following substring in the modifier string: "0004002a".
         Mouse modifiers are represented in the same way as the 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 characters in the
         modifier string. For example, if AEE_POINTER_MOUSE_LBUTTON is pressed,
         the mouse modifier substring will be "0001".
         The additional pointing device modifier flags will provide additional
         information specific to the pointer events. These are 16-bit values
         represented by 4 single-byte characters in the modifier string. For
         example, if a pointer move event is dropped, the AEE_POINTER_EVENT_DROPPED
         flag is set the additional modifiers string will be "0001".
         Example: "modifiers=0004002a00010001," for a total length of 27 single-byte
         characters (AEE_POINTER_MODIFIERS_SIZE).
         The modifiers string in the dwParam will be at AEE_POINTER_MODIFIERS_OFFSET.
         Use AEE_POINTER_GET_KEY_MODIFIERS() or AEE_POINTER_GET_MOUSE_MODIFIERS() to
         obtain the values.
      DisplayID Index: "dispID"; Value: The AEECLSID of the display screen on which
         pointer event occurred. The numeric string contains 8 hexadecimal single-byte-characters.
         Example: "dispID=010127d4,", for a total of 16
         single-byte characters (AEE_POINTER_DISPID_SIZE). The dispID string is
         not at a pre-defined offset. Use AEE_POINTER_GET_DISPID_EX() to retrieve this.
      ptrID: Index: "ptrID"; Value: The ID of the pointing device. The string contains 2 single-byte-characters.
         Example: "ptrID=01,", for a total length of
         9 single-byte characters (AEE_POINTER_PTRID_SIZE). The ptrID string is
         not at a pre-defined offset. Use AEE_POINTER_GET_PTRID() to retrieve this.
      Next Pointer Offset: Index: "nextptr", Value: The offset to the next pointer sub string from the beginning of this one.
         This is used to support multitouch events. In this case you will get a string as follows.
         "x=00000017,y=FFFFFFFB,time=00003456,clkcnt=2,modifiers=0000000000000000,dispID=010127D4,ptrID=01,nextptr=0000007E,
         x_02=00000022,y_02=00000001,nextptr_02=00000030,"
         x_04=00000087,y_04=00000023,nextptr_04=00000000,"
         Use AEE_POINTER_GET_NEXT_POINTER() and AEE_POINTER_GET_MT_NEXT_POINTER() to get the next pointer to the string for 
         the next pointer ID.
   Optional name-value pairs:
      Mouse Buttons (Optional; doesn't apply to devices that do not support mouse
         device): "mousebtn", Value: Mouse-button modifiers to be sent for
         EVT_POINTER_DOWN to notify Brew MP which mouse button (defined in
         AEEPointerHelpers.h) is pressed. The numeric string contains 5 digits
         (zero-padded on the left). Example, if AEE_POINTER_MOUSE_LBUTTON is
         pressed, "mousebtn=00001," for a total of 15 single-byte characters.
      Any additional device-specific extended name-value pairs: Certain devices
         may have additional custom name-value pairs. They would typically be
         in the format "x--=value,". As a hypothetical example,
         if the Brew MP Simulator were to generate a pressure value, it would look
         similar to "x-BREWSimulator-pressure=100,". AEE_POINTER_GET_VALUE() can
         be used to retrive the values of these non-standard name-value pairs.

Multitouch Support:
      For up and down events the events EVT_POINTER_UP/EVT_POINTER_DOWN are still sent for 
      ptrID=1, but for any other pointer up/down EVT_POINTER_MT_UP/EVT_POINTER_MT_DOWN. Up
      and down events will only contain information about one pointer per an event. 
      EVT_POINTER_MOVE will be used for multitouch move events if ptrID=1 is in the multitouch
      event. If ptrID=1 is not present then EVT_POINTER_MT_MOVE will be used instead. Move events
      will contain the information for all pointers that are currently in contact on the display.
      The format of this is an extension of the standard pointer event. For example: 
         "x=00000017,y=FFFFFFFB,time=00003456,clkcnt=2,modifiers=0000000000000000,dispID=010127D4,ptrID=01,nextptr=0000007E,
         x_02=00000022,y_02=00000001,nextptr_02=00000030,"
         x_04=00000087,y_04=00000023,nextptr_04=00000000,"
      The AEE_POINTER_GET_NEXT_POINTER(), AEE_POINTER_GET_MT_NEXT_POINTER(), and AEE_POINTER_GET_MT_XY_PTRID()
      functions can be used to process these events.

      A settings item that can be used to determine if the device supports multitouch is also
      present. The item's name is /BREW/Display//TouchMode. The dispid field is the 
      classID of the display that is being queried. For example, for the primary display the
      item is named /BREW/Display/010127d4/TouchMode.

      Currently defined values for this item are:
      None: Touchscreen is not supported
      Singletouch: Display is capable of 1 touch contact
      Dualtouch: Display is capable of 2 touch contacts
      Multitouch: Display is capable of more than 2 touch contacts

User-defined Events


EVT_USER:                  Start of App/User defined Events (Private to apps)
Comments
The user defined events start from EVT_USER.