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


API Reference


Brew Release
Brew MP 1.0.2
See Also
Unique ID that identifies the standard window manager capabilities. An applet should interrogate the window manager for these capabilities using IWindowMgr_CheckCapabilities() before using any of the standard window manager properties

Overview of Standard window manager Capabilities: There are many different classes of windows available: * Fullscreen & Popup Fullscreen and popup windows are the most common and share many window strictly occupies the entire display while a popup window may not.
The window manager maintains a Z-order of all Fullscreen and Popup windows that currently exist, and supplies commands to manipulate the Z-order.
* Softkey (various subclasses) Softkey windows are always "associated" with one or more fullscreen or popup windows. The display of a softkey window is determined by the topmost fullscreen/popup window.
* Icons (various subclasses) Icon windows enable apps to integrate into a task tray and homescreen.
* Annunciator Annunciator windows are typically used by system apps. the display of an annunciator window is determined by the topmost fullscreen window.
A window's class is determined by providing a AEEWindowMgrExt_CLASS property when creating a window using IWindowMgrApp_CreateWindow().
Window State: A window may be in one of several states at any time, as determined by the window manager.
AEEWindowMgrExt_STATE_VISIBLE The window is visible. When the window is not in this state and the window is not drawable (see AEEWindowMgrExt_PROPEX_DRAWABLE) the window manager will never request the window to draw via IWIDGET_Draw().
AEEWindowMgrExt_STATE_OBSCURED The window is not visible because it's obscured by some other window above it.
AEEWindowMgrExt_STATE_SUPPRESSED The window is currently being suppressed (see section on Notification Windows). This state is only possible for fullscreen and popup windows.
AEEWindowMgrExt_STATE_MINIMIZED The window is currently minimized. This state is only possible for fullscreen and popup windows.
The AEEWindowMgrExt_PROPEX_STATE IWidget property is used by the window manager to inform the window of its current state.
Windowed apps event handling: Windowed applications run in the background and export windows to the window manager. Because of that the window manager is the application processing user events like key presses and touch events, the window manager will forward those events to the currently focused window. The window manager doesn't do anything special with key events configured in AEEDeviceInfo fields wKeyCloseApp and wKeyCloseApp (usually AVK_CLR and AVK_END respectively), meaning the window manager by itself doesn't close applications or windows. When the window manager is the top application (always true when windows are showing), it will handle those keys to avoid getting closed by the system.
Fullscreen/Popup Window Class: A fullscreen window is always sized to fit the maximum available display area. Even if the topmost fullscreen window is partially transparent, any fullscreen/popup windows beneath it will not be visible.
A popup window's extent is determined by calling IWIDGET_GetExtent() on the window if the AEEWindowMgrExtProp_EXTENT_HINT property is not supplied, and its position is specified using the AEEWindowMgrExtProp_POSITION_HINT property.
The logical display that the fullscreen/popup window is placed on is specified using the AEEWindowMgrExtProp_DISPLAY property. The window will be closed if the window manager does not support the desired display.
Typically the topmost fullscreen/popup window will received keypad focus. However the window may choose to reject focus, in which case the fullscreen/popup window under it will be given the opportunity to obtain focus. Once a window has rejected focus it may request focus again by activating itself using AEEWindowMgrExtProp_ACTIVATE.
Annunciators: The visibility of annunciators is controlled by the topmost fullscreen window. The desired annunciator style for a window may be specified with the AEEWindowMgrExtProp_ANNUN_STYLE property. If no annunciator style is provided, the parent window's annunciator style is used or AEEWindowMgrExt_ANNUN_STYLE_BAR if the window has no parent. If the parent annunciator style is changed after creation of a child window, the child window's annunciator style is unaffected.
Notification Windows/Window Priority: Notification windows may appear over the topmost window at any time. The AEEWindowMgrExtProp_Z_PRIORITY_ID property can be used to set the priority of a window. Normal application fullscreen/popup windows would typically not use this property.
Suppressing Notification Windows: Notification windows may be suppressed by the topmost parentless fullscreen window with normal priority (AEEWindowMgrExt_Z_PRIORITY_NORMAL) at any time. Suppression only applies to the display that the window is associated with (AEEWindowMgrExtProp_DISPLAY).
The AEEWindowMgrExtProp_Z_PRIORITY_SUPPRESS_LEVEL priority is used to indicate a suppression priority level. All windows with a priority ID that matches will be suppressed (hidden) while that window is topmost.
Unsuppressing Notification Windows: Sending the command AEEWindowMgrExtProp_Z_PRIORITY_SUPPRESS_LEVEL with a payload of AEEWindowMgrExt_SUPPRESS_LEVEL_NONE removes suppression for the window.
Window Families: Fullscreen/popup windows may have zero or more fullscreen/popup child windows (which may come from the same applet or another applet).
A child window is created by supplying the AEEWindowMgrExtProp_PARENTID property during window creation. Child windows always have the same window priority as their parent window, are always located over their parent in the window stack (on the same display). It's not possible to interleave other windows between a window and its descendants.
When a new child window is created it is placed above its parent and all sibling windows. If the AEEWindowMgrExtProp_ACTIVATE property is supplied to the creation of a child window, the entire window family to be activated.
Window rotation: A fullscreen window may request the display be rotated, while it's the topmost fullscreen window, using the AEEWindowMgrExtProp_PREFERRED_ROTATION property. All popup windows shown over the topmost fullscreen window will also be rotated to the requested angle (and possibly resized accordingly), regardless of which applet the popup windows originate from. Not all displays support rotation.
A child fullscreen window does not automatically inherit the display rotation of its parent. If there are no non-minimized fullscreen windows on the display, the display rotation reverts back to 0.
All visible fullscreen/popup windows are informed of screen rotation changes via the AEEWindowMgrExt_PROPEX_ROTATION IWidget property. A window should assume the display rotation is 0 until it receives this event.
Closing Windows: Calling IWindowMgr_CloseWindow() will cause that window and all its children to be closed.
Affecting the Z-Order: Several primitives are provided to affect the ordering of fullscreen/popup windows.
Activating a Window: The AEEWindowMgrExtProp_ACTIVATE property can be used to move the specified window and all other windows in its family to the top of the Z-order for its given AEEWindowMgrExtProp_Z_PRIORITY_ID value. The relative order of child windows is maintained. If a child window is activated the entire window family is moved as high as possible on the stack.
Minimizing a Window: The AEEWindowMgrExtProp_MINIMIZE property can be sent to minimize a window and all other windows in it's family. The intrafamily Z order of the windows is preserved. Note that the window should not consider itself truly minimized until it receives the AEEWindowMgrExt_PROPEX_MINIMIZED=TRUE property. A window may also decide to be created in a minimized state by supplying the AEEWindowMgrExtProp_MINIMIZE at creation time.
Minimizing All Windows: The AEEWindowMgrExtProp_MINIMIZEALL property may be sent to minimize all windows.
Closing All Windows: The AEEWindowMgrExtProp_CLOSEALL property may be sent to close all windows. The invoking app must have a special privilege since this operation is typically only required by system applications. Windows with the AEEWindowMgrExtProp_NO_CLOSEALL property are not closed by this property.
Softkey Window Class: An application creates a softkey window using the AEEWindowMgrExt_CLASS_Softkey or AEEWindowMgrExt_CLASS_OverlaySoftkey window class. Softkey windows will never receive focus.
The display that the softkey window is placed on is specified using the AEEWindowMgrExtProp_DISPLAY property. The softkey window can only be used by fullscreen/popup windows from the same app of the softkey window, on the same display as the softkey window.
The softkey window is selected for a fullscreen/popup window using the following steps:
1) If the window has provided the AEEWindowMgrExt_SOFTKEYID property, and the softkey window with that ID exists then use it. 2) Otherwise if the window has provided the AEEWindowMgrExt_SOFTKEYID property and the softkey window with that ID does not exist then display no softkey. 3) Otherwise if the softkey window is not found at this point, steps #1 and #2 are repeated using the window's parent/grandparent/great-grandparent until the topmost window for the family is found. 4) Otherwise the window will be given the first softkey window that's found from the same application/display as the window. If the application has created multiple softkey windows, the softkey window that's used is window manager implementation specific.
The height of a softkey window is determined by calling IWIDGET_GetExtent() on the window (possibly subject to a reasonable height maximum), however the width of the window is coerced to the maximum available space.
A AEEWindowMgrExt_CLASS_Softkey softkey window for a fullscreen window will be placed at the bottom of the display (taking into account the current rotation of the display) and the main window will be resized vertically to make room for it. However if the softkey window was created using the AEEWindowMgrExt_CLASS_OverlaySoftkey window class, the softkey window will be placed over the bottom portion of the window (rather than resizing the window vertically to "make room" for the softkey window beneath it). Therefore if the softkey window is partially transparent, the fullscreen window will be visible underneath it.
If a popup window's softkey window will always be placed over the bottom portion of the screen (which may overlap the window itself if the window is large enough). If the softkey window is partially transparent, the window(s) underneath it will be visible.

Icon Window Classes: There are a couple different types of icon windows.
Task Tray Icon Windows: Windowed apps may choose to participate in the task tray by creating a icon window with a window class of AEEWindowMgrExt_CLASS_TaskTrayIcon. Note that some window managers may not support a task tray so the application should be prepared to gracefully deal with failure to create a task tray window.
Home Screen Icon Windows: Home Screen icon windows are displayed on the idle/homescreen of the device, and are identified from other icon windows by the AEEWindowMgrExt_CLASS_HomeScreenIcon window class. Note that some window managers may not support Home Screen icons so the application should be prepared to gracefully deal with failure to create these windows.

Legacy applications: The window manager fully supports legacy (fullscreen IDisplay-based) applets. A legacy applet behaves similarly to fullscreen window using the default AEEWindowMgrExtProp_Z_PRIORITY_ID value. If another app creates or activates a window while a legacy app is top visible, the window manager suspends the legacy application and shows the new window. When the new window closes, the window manager resumes the legacy application.

Annunciator Window Class: The window manager itself provides no annunciators internally (not even AEEWindowMgrExt_ANNUN_STYLE_BAR). Annunciators are just another type of window created using AEEWindowMgrExt_CLASS_Annunciator. The following properties are required at annunciator window creation time:
* AEEWindowMgrExtProp_ANNUN_POSITION_HINT: describes how the annunciator window should be placed on the screen.
* AEEWindowMgrExtProp_ANNUN_STYLE: Used to map the annunciator window to fullscreen windows. Up to 4 windows can be created with the same AEEWindowMgrExtProp_ANNUN_STYLE value, one for each edge (see AEEWindowMgrExtProp_ANNUN_POSITION_HINT).
If annunciator windows collide and they have an AEEWindowMgrExt_ANNUNPOS_OUTSIDE position, the windows are drawn in the order they were created. For example, the first annunciator window created is on top, and the second annunciator window is on the right. They both collide on the right-top corner. The first window will get the entire display width and the height specified. The second window will get the screen height minus the height specified by the first window.
The applet hosting an annunciator window must be a member of the group identified by the AEEWindowMgrExtProp_ANNUN_STYLE property (by importing the classID contained in this property in its .MIF file)
Annunciator windows will never receive focus.
The logical display that the annunciator window is placed on is specified using the AEEWindowMgrExtProp_DISPLAY property. The annunciator window can only be used by fullscreen on the same display.
User defined window properties: Users can define their own properties. The window manager will not do anything with properties it doesn't know about, the window manager will simply store these properties. These properties can then be retrieved by the user or another party using IWindowHistory. User defined properties must have a unique id generated using the BREWMP classid generator. The payload of such properties is a sequence of bytes which structure is known by the user. The window manager will simply cache the sequence. To set a user defined property on a window, the owner of the window must have a privilege which is the same class id used to define the property. If a property is set and it already exists it will overwrite the previous property payload. The window manager will enforce a reasonable quota for the size of the payload and the number of properties stored per window. These quotas are configured by the OEM. See AEEIWindowHistory.idl and AEEWindowHistory.bid
Low Memory Conditions: Reclaiming memory in low memory conditions is complicated by the fact that windows may be running in a different environment than the window manager itself. Therefore each application must be a good citizen and handle low memory conditions in its environment as appropriate. The window manager application does not force windows to close when it detects a low memory condition in its environment.
An application whose window is obscured (AEEWindowMgrExt_PROPEX_OBSCURED) cannot simply exit on low memory because it will lose its position in the window stack. Instead it should unload any internal structures and maintain a skeleton window until it becomes unobscured.

Unexpected Window Properties: All windows should be prepared to deal with unexpected IWidget PROP_EX events. These could be sent as result of a window manager extension that was not known to the application during build time. The window should always return FALSE (unhandled) for these properties.
  •   const AEEUID AEEWindowMgrExt_CapabilityID = 0x01073d57;