Objective
This topic describes how to create a windowed application that will share the display with other applications.
Requirements
Brew® MP windowed applications need to be written differently than traditional Brew MP applications. Traditional Brew MP applications, when running in the foreground, occupy full screen space and can modify the display at any time. In the windowing framework, multiple applications share the display at the same time and are not allowed to modify the display arbitrarily. A windowed application also needs to create one or more widgets to be used to create the windows.
A windowed application needs to:
·                  Create and initialize one or more widgets to be passed to IWindowMgr_CreateWindow().
The application can implement its own IWidget, or it can make use of an existing IWidget.
·                  Handle the EVT_APP_START_WINDOW event (and create a window).
·                  Implement handlers for visibility changes, focus changes, and extent changes. The implementation of these handlers is dependent on the details of the application.
·                  Draw in two stages:
·                                  Tell the container that drawing is necessary (ICONTAINER_Invalidate()).
·                                  Draw only when told to draw by the container (IWIDGET_Draw()).
Note: A windowed application should not call any functions that modify IDisplay directly. This includes explicit IDisplay function calls or implicit updates, such as calls to IIMAGE_Draw() or ICONTROL_Redraw(). Drawing should happen only on demand, for example, when IWIDGET_Draw() is called for the widget used to create the window. Existing Widget based applications follow these guidelines and, with minor modifications, can be ported to the windowing framework.
Event handling
A windowed application must respond to these events:
EVT_APP_START_WINDOW and EVT_APP_START
A window-based application receives EVT_APP_START_WINDOW first. If the application returns TRUE for this event, the application does not receive EVT_APP_START. If an application needs to support both the environments (window based and non-window based), it should handle both events.
When the application receives EVT_APP_START_WINDOW, it should create one or more windows.
If creation of IWindowMgr0 fails while handling EVT_APP_START_WINDOW, the application should assume that the platform does not support window-based applications. In this case, the application should return FALSE and continue the application logic in the code for EVT_APP_START.
EVT_APP_SUSPEND and EVT_APP_RESUME
After an application returns TRUE for EVT_APP_START_WINDOW, it will not receive EVT_APP_SUSPEND and EVT_APP_RESUME as non-windowed Brew MP applications do. Instead, the application must check for window status events that are sent to the widget through EVT_WDG_SETPROPERTY events. For EVT_WDG_SETPROPERTY events, wParam indicates which property was set, and dwParam specifies the value of the property. When the AEEWindowMgrExt_PROPEX_STATE property has a value of AEEWindowMgrExt_STATE_VISIBLE, the window is visible.
EVT_WDG_WINDOWSTATUS
The EVT_WDG_WINDOWSTATUS event is sent to a widget to notify it about various window related status messages. AEEWindowStatus.h contains information on the meaning of various status messages.
Sample code location


　　
　　　　
　　　　　　
　　　　　　ZIP filename
　　　　　　
　　　　　　
　　　　　　Location
　　　　　　
　　　　　　
　　　　　　Run app
　　　　　　
　　　　
　　
　　
　　　　
　　　　　　
　　　　　　hellowindowapp
　　　　　　
　　　　　　
　　　　　　Brew MP Library
　　　　　　
　　　　　　
　　　　　　·                       Download and extract the ZIP file.
　　　　　　·                       Compile the app.
　　　　　　·                       Run it on the Brew MP Simulator.
　　　　　　
　　　　
　　


Example of a windowed application
In the hellowindowapp sample, HelloWindowApp_HandleEvent handles the EVT_APP_START_WINDOW event and creates soft key and pop-up windows:
   case EVT_APP_START_WINDOW:   
      DBGPRINTF("EVT_APP_START_WINDOW");
 
      // Create the softkey and popup windows
      HelloWindowApp_CreateSoftkey(pMe);
      HelloWindowApp_CreateOrActivatePopup(pMe);
 
      // Handling this event tells Brew that we are a windowing
      // application.
      return TRUE;  
HelloWindowApp_CreateSoftkey() creates the soft key widget, sets the color text of the widget, then calls HelloWindowApp_CreateWindow() to create the window.
   WidgetWindow *pWindow = &pMe->softkeyWindow;
  
   if (pWindow->piWindowWidget != NULL) return;
   pWindow->pszDbgName = "Softkey";
   pWindow->pMe = pMe;
  
   (void) ISHELL_CreateInstance(pMe->applet.m_pIShell, AEECLSID_SoftkeyWidget,
            (void **) &pWindow->piWindowWidget);
   if (pWindow->piWindowWidget == NULL) return;
 
   {
      WidgetExtent extent = {0, HWA_SOFTKEY_HEIGHT};
      IWidget_SetExtent(pWindow->piWindowWidget, &extent);
   }
  
   (void) IWidget_SetBGColor(pWindow->piWindowWidget, MAKE_RGBA(200,200,200,255));
  
   // Now set the softkeys text
   {
      IWidget *piTextWidget = NULL;
      (void) IWidget_GetSoftkey(pWindow->piWindowWidget, PROP_SOFTKEY1, &piTextWidget);
     
      if (piTextWidget != NULL) {
         (void) IWidget_SetText(piTextWidget, L"Hover", TRUE);
      }
      RELEASEIF(piTextWidget);
 
      (void) IWidget_GetSoftkey(pWindow->piWindowWidget, PROP_SOFTKEY2, &piTextWidget);
      if (piTextWidget != NULL) {
         (void) IWidget_SetText(piTextWidget, L"Close", TRUE);
      }
      RELEASEIF(piTextWidget);
   }
 
   HelloWindowApp_CreateWindow(pMe, pWindow, AEEWindowMgrExt_CLASS_Softkey);  
HelloWindowApp_CreateWindow() creates the soft key window, as follows:
   int result;
   uint32 winId;
   AEEWindowProp propList[1];
  
   // Set custom window handler
   HANDLERDESC_Init(&pWindow->hdHandler, HelloWindowApp_WindowHandler, pWindow, NULL);
   IWIDGET_SetHandler(pWindow->piWindowWidget, &pWindow->hdHandler);
        
   propList[0].id = AEEWindowMgrExtProp_CLASS;
   propList[0].pbyLen = sizeof(winClass);
   propList[0].pby = (void *) &winClass;
     
   result = IWindowMgr_CreateWindow(pMe->piWindowMgr, (IQI*) (void *) pWindow->piWindowWidget,
      propList, ARR_SIZE(propList), &winId);
 
   if (result != SUCCESS) {
      DBGPRINTF("Window creation failed for %s: %d", pWindow->pszDbgName, result);
      HelloWindowApp_DestroyWindow(pWindow);
   } else {
      DBGPRINTF("Window %s created: id=%d", pWindow->pszDbgName, winId);
   }
HelloWindowApp_CreateOrActivatePopup() creates the widget for the pop-up window, then calls HelloWindowApp_CreateWindow() to create the pop-up window.
   pWindow->piWindowWidget = HelloWindowApp_CreateAndInitImageWidget(
                                pMe,
                                "popups.main" // Image as defined in appinfo.ini
                             );
 
   if (pWindow->piWindowWidget == NULL) return;
 
   {
      WExtent extent = {HWA_POPUP_WIDTH, HWA_POPUP_HEIGHT};
      IWIDGET_SetExtent(pWindow->piWindowWidget, &extent);
   }
 
   HelloWindowApp_CreateWindow(pMe, pWindow, AEEWindowMgrExt_CLASS_Popup);
Related information
·                  See Brew MP Widgets Technology Guide: Creating a Widgets application
·                  See Brew MP API Reference


　　
　　　　
　　　　　　
　　　　　　Base version:
　　　　　　
　　　　　　
　　　　　　Brew MP 1.0
　　　　　　
　　　　
　　　　
　　　　　　
　　　　　　Tested version:
　　　　　　
　　　　　　
　　　　　　Brew MP 1.0
　　　　　　
　　　　
　　　　
　　　　　　
　　　　　　Phone tested:
　　　　　　
　　　　　　
　　　　　　No