Example - Touchscreen support and last linear movement observation

Touchscreen support is enabled in Widgets by creating the root container, obtaining its IWidget interface and enabling touch on it. Touch observation is required to retrieve flick information in response to user input, and it must be started before use. [TouchTroubleshoot.c]

...
// Enable widget touchscreen support
if (SUCCESS == nErr) nErr = IWidget_EnableTouch(pMe->m_pRootWidget);

// Get the root container's touch observer
if (SUCCESS == nErr) nErr = IWidget_GetTouchObserver(pMe->m_pRootWidget,
            &pMe->m_pRootTouchObs);

// Start last linear movement observation
if (SUCCESS == nErr) nErr = IObserver_StartObservation(pMe->m_pRootTouchObs,
            TOUCHOBSF_LLM);
...

Last linear movement information is obtained from the touch observer. [MainPage.c]

int i;

if (SUCCESS == IObserver_GetLLMAngle(pObs, &i)) {
   pPageData->m_stats.m_nStats[STATS_FLKDIR] = (uint32)i;
}
...

if (SUCCESS == IObserver_GetLLMSpeed(pObs, &i)) {
   pPageData->m_stats.m_nStats[STATS_FLKSPEED] = (uint32)i;
}
...

Multi-touch pointer move events are handled in the pointer event handler. [MainPage.c]

...
int nPtrID = AEE_POINTER_GET_PTRID((const char*)dwParam);

switch (evt) {
   case EVT_POINTER_MT_MOVE:
   case EVT_POINTER_MOVE:
   case EVT_POINTER_MT_STALE_MOVE:  //lint -fallthrough
   case EVT_POINTER_STALE_MOVE:
      {
         ...
         if (SUCCESS == AEE_POINTER_GET_XY(pszPointer, &x, &y)) {
            ...
         }
         else {
            DBGPRINTF("Fail: get pointer XY");
         }

         pszPointer = AEE_POINTER_GET_NEXT_POINTER(pszPointer);

         while (pszPointer) {
            if (SUCCESS == AEE_POINTER_GET_MT_XY_PTRID(pszPointer, &x, &y, &nPtrID)) {
               ...
            }
            else {
               DBGPRINTF("Fail: get MT pointer XY PTRID");
            }

            pszPointer = AEE_POINTER_GET_MT_NEXT_POINTER(pszPointer);
         }
      }
      break;

When no longer needed, the applet stops touch observation. [TouchTroubleshoot.c]

...
// Stop observation and release the root touch observer
if (pMe->m_pRootTouchObs) {
   (void)IObserver_StopObservation(pMe->m_pRootTouchObs, TOUCHOBSF_LLM);
   (void)IObserver_Release(pMe->m_pRootTouchObs);
}
...

Example - Creating an instance of wlan_IConnMgr

Use the IShell create instance function to create a wlan_IConnMgr object.

nResult = ISHELL_CreateInstance(pMe->piShell, wlan_AEECLSID_ConnMgr,
                               (void**)(&pMe->piConnMgr));
if( SUCCESS != nResult) 
{
   DBGPRINTF("Create instance of wlan_IConnMgr failed Return Value %d",
              nResult);
   pMe->piConnMgr = NULL;
}

Example - Starting a scan

Before starting a scan, you must create a signal and set up the signal with the wlan_IConnMgr object. Then you call wlan_IConnMgr_StartScan() to start the scan.

nErr = WCM_CreateSignal(pMe->piShell, WCM_StartScanCB, pMe,
   &pMe->piSignal, &pMe->piSignalCtl);
if (AEE_SUCCESS != nErr) 
{
   goto bail;
}

nErr = wlan_IConnMgr_OnScanEnd(pMe->piConnMgr, pMe->piSignal);
if (AEE_SUCCESS != nErr) 
{
   goto bail;
}

nErr = wlan_IConnMgr_StartScan(pMe->piConnMgr);
if (AEE_SUCCESS != nErr) 
{
   goto bail;
}

Example - Retrieving the network list

When the wlan_IConnMgr is done finding the available networks, it generates the callback signal. In the callback function, you must call wlan_IConnMgr_GetNetworks() to determine if any networks were found and the buffer size needed.

nErr = wlan_IConnMgr_GetNetworks(pMe->piConnMgr, 
                               &bScanInProgress, 
                               pMe->pNet, pMe->nNetCount, 
                               &nNetworksLenReq);

After allocating the space defined in nNetworksLenReq, call wlan_IConnMgr_GetNetworks() to get the network list.

// allocate space
pMe->pNet = REALLOC(pMe->pNet, sizeof(wlan_Network) 
                            * nNetworksLenReq);
// Get the network string
nErr = wlan_IConnMgr_GetNetworks(pMe->piConnMgr, &bScanInProgress, 
                                       pMe->pNet, pMe->nNetCount, 
                                       NULL);

Example - Connecting to an access point

To connect to a WLAN access point, you must create and set up a callback function, and then try to connect.

nErr = WCM_CreateSignal(pMe->piShell, WCM_ConnectCB, pMe,
                       &pMe->piSignal, &pMe->piSignalCtl);
if (AEE_SUCCESS != nErr) 
{
   goto bail;
}

nErr = wlan_IConnMgr_OnConnectStatusChange(pMe->piConnMgr, 
                         pMe->piSignal);
if (AEE_SUCCESS != nErr) 
{
   goto bail;
}
     
nErr = wlan_IConnMgr_Connect(pMe->piConnMgr, pNet, 
                         wlan_SCAN_AUTO, enc, pAuthInfo);
if (AEE_SUCCESS != nErr) 
{
   WCM_DisplayMsg(pMe, "Connect failed %d \n", nErr );
   goto bail;
}

Example - Retrieving network information

To get the status of the network connection, you call wlan_IConnMgr_GetConnectStatus(). This function can be used at any time.

wlan_IConnMgr_GetConnectStatus( pMe->piConnMgr,&status, &reason, 
                                &bInfoAvail, &net);

Example - Disconnecting from an access point

To disconnect from a WLAN access point, you must create and set up a callback function, and then try and disconnect.

nErr = WCM_CreateSignal(pMe->piShell, WCM_DisconnectCB, pMe,
                       &pMe->piSignal, &pMe->piSignalCtl);
if (AEE_SUCCESS != nErr) 
{
    goto bail;
}

nErr = wlan_IConnMgr_OnConnectStatusChange(pMe->piConnMgr, pMe->piSignal);
if (AEE_SUCCESS != nErr) 
{
    goto bail;
}

nErr = wlan_IConnMgr_Disconnect(pMe->piConnMgr);
if (AEE_SUCCESS != nErr) 
{
   goto bail;
}

Example - initialization

The code examples in this section are from the c_drawTriangle sample. InitGLSurface(), which is called from c_drawTriangle_InitAppData(), calls EGL_Init() and GLES_Init() before calling EGL functions to setup the EGL display and EGL surface.

   if (EGL_Init( pMe->a.m_pIShell ) != SUCCESS)   
   {   
      return FALSE;   
   }   
   
   if (GLES_Init( pMe->a.m_pIShell ) != SUCCESS)   
   {   
      return FALSE;   
   }

Example - rendering

After c_drawTriangle_InitAppData() is called, the application sets a timer. When the timer expires, the RenderLoopTimerNotify() callback function is called, which draws the triangles and resets the timer. RenderLoopTimerNotify() calls Render(), which calls drawTriAngle() to draw the 3D geometry, then calls eglSwapBuffers() to swap the front buffer and back buffer, as shown in the following example:

void Render(c_drawTriangle* pMe, uint32 currTime) 
{ 
   drawTriAngle(pMe,currTime); 
   eglSwapBuffers(pMe->eglDisplay, pMe->eglSurface); 
} 
 
//------------------------------------------------------------------ 
void RenderLoopTimerNotify(void* pi) 
//------------------------------------------------------------------ 
{ 
   c_drawTriangle* pMe = (c_drawTriangle*)pi; 
   uint32 currTimeMs = ISHELL_GetUpTimeMS(pMe->a.m_pIShell); 
 
   Render(pMe, currTimeMs);   
   ISHELL_SetTimer(pMe->a.m_pIShell, REFRESH_IN_MS,
               (PFNNOTIFY)RenderLoopTimerNotify, pMe); 
}

Example - freeing resources

The FreeGLSurface() function, which is called from c_drawTriangle_FreeAppData() and DisplayErrorMsg(), calls a number of EGL functions to free resources, then calls GLES_Release() and EGL_Release():

   if (pMe->eglDisplay != EGL_NO_DISPLAY)   
   {   
      eglMakeCurrent( EGL_NO_DISPLAY, EGL_NO_SURFACE, EGL_NO_SURFACE,
                  EGL_NO_CONTEXT );   
      eglDestroyContext( pMe->eglDisplay, pMe->eglContext );   
      eglDestroySurface( pMe->eglDisplay, pMe->eglSurface );   
      eglTerminate( pMe->eglDisplay );   
      pMe->eglDisplay = EGL_NO_DISPLAY;   
   
      GLES_Release();   
      EGL_Release();   
   }

Initialization

This include is needed to create a touch controller that uses virtual input.

#include "AEEVirtualInputHelpers.h"

The PROPEX_VIRTUALINPUT_ENABLE property must be handled by the touch controller, which is sent to enable/disable virtual input automatically when the widget is inserted within a virtual input-enabled root container.

When disabling virtual input, all listeners must be properly cancelled, and any state enabled during initialization must be reset.

static boolean VirtualInputDateTimeTC_HandleSetPropEx(VirtualInputDateTimeTC *pMe,
            ControllerPropEx* pPropEx )   
{   
...   
      case PROPEX_VIRTUALINPUT_ENABLE:   
         if (pPropEx->nSize == (int)sizeof(boolean)) {   
            if (TRUE == *(boolean*)pPropEx->pUser) {   
               VirtualInputDateTimeTC_InitVirtualInputMgr(pMe);   
            }   
            else{   
               LISTENER_Cancel(&pMe->mlRCViewModel);   
               VirtualInputDateTimeTC_Detach(pMe);   
               RELEASEIF(pMe->picVirtualInputMgr);   
            }   
            bHandled = TRUE;   
         }   
         break;   
...   
}

The following function is used when virtual input is first initialized for the DateTimeWidget.

static __inline void VirtualInputDateTimeTC_InitVirtualInputMgr(VirtualInputDateTimeTC *pMe){   
...

A listener must be attached to the root container's view model to receive notifications in case the current Virtual Input Manager is changed.

...   
   //Attach listener to the RC's view model   
   ERR_TRY( IWIDGET_GetRootContainer(pMe->piwChild, &piwRoot) );   
   ERR_TRY( IWidget_GetViewModel(piwRoot, &pimRCViewModel) );   
      
   LISTENER_Cancel(&pMe->mlRCViewModel);   
   ERR_TRY( IModel_AddListenerEx((IModel*)pimRCViewModel, &pMe->mlRCViewModel,  
   (PFNLISTENER)VirtualInputDateTimeTC_RootViewModelListener, pMe) );   

To ensure no orphans, all references to the previous Virtual Input Manager are released and the listeners are cancelled.

   //Detach previous virtual input manager, if set   
   if (pMe->bVirtualInputMode && pMe->picVirtualInputMgr) {   
      LISTENER_Cancel(&pMe->mlVirtualInputStatus);   
      (void)IController_SetVirtualInputTargetWidget(pMe->picVirtualInputMgr, NULL);   
   }   
   RELEASEIF(pMe->picVirtualInputMgr);

Retrieve the current Virtual Input Manager from the root container for future reference.

   //Grab the virtual input manager   
   ERR_TRY(IWidget_GetVirtualInputMgr(piwRoot, &pMe->picVirtualInputMgr) );   
...   
}

Showing the Virtual Keypad

Initiate a virtual input request on pointer events, namely EVT_POINTER_UP.

static boolean VirtualInputDateTimeTC_HandleEvent(void *pCxt, AEEEvent eCode,
            uint16 wParam, uint32 dwParam){   
...   
   case EVT_POINTER_UP:   
      //If we're virtual input enabled and we're not currently already   
      //awaiting input from the virtual keypad, initiate a virtual input query   
      if (NULL != pMe->picVirtualInputMgr && !pMe->bVirtualInputMode) {   
         VirtualInputDateTimeTC_StartVirtualInputRequest(pMe);   
      }   
      bHandled = TRUE;   
      break;   
...

The following function is called to set up and display the virtual keypad.

static __inline void VirtualInputDateTimeTC_StartVirtualInputRequest(VirtualInputDateTimeTC *pMe) {   
...   
   //Set self as target   
   ERR_TRY( IController_SetVirtualInputTargetWidget(pMe->picVirtualInputMgr,
               pMe->piwChild) );   
      
   //Attach model   
   ERR_TRY( IController_GetVirtualInputStatusModel(pMe->picVirtualInputMgr,
               &pimStatusModel) );   
   ERR_TRY( IModel_AddListenerEx(pimStatusModel, &pMe->mlVirtualInputStatus,  
   (PFNLISTENER)VirtualInputDateTimeTC_VirtualInputStatusListener, (void*)pMe) );   
   //Update input mode of keypad widget to give us numbers.   
   ERR_TRY( IController_SetVirtualInputLayoutMode(pMe->picVirtualInputMgr, FALSE,
               AEE_TLANG_NUMBERS) );   
      
   //Update virtual input flag to active   
   pMe->bVirtualInputMode = TRUE;   
   ERR_TRY( IController_ShowVirtualInputFrame(pMe->picVirtualInputMgr) );   
...

Closing the Virtual Keypad

When the user presses the finish button, dismiss button, or clicks on a different widget, the status model of the Virtual Input Manager will send a notification. The touch controller must deal appropriately with each notification to ensure a proper and constant behavior.

static void VirtualInputDateTimeTC_VirtualInputStatusListener(VirtualInputDateTimeTC *pMe,
            ModelEvent *pe)   
{   
...      
   //If we're not currently waiting for input data and we get this notification,   
   //we should detach ourselves.   
   if (!pMe->bVirtualInputMode) {   
      LISTENER_Cancel(&pMe->mlVirtualInputStatus);   
      return;   
   }   
   
   //We only care out status changes   
   if (EVT_MDL_VIRTUALINPUT_STATUS_CHANGE != pe->evCode) {   
      return;   
   }   
      
   //Disable listener if we are not the current target for the virtual input   
   nErr = IController_GetVirtualInputTargetWidget(pMe->picVirtualInputMgr, &piwTarget);   
   if (SUCCESS != nErr || pMe->piwChild != piwTarget) {   
      LISTENER_Cancel(&pMe->mlVirtualInputStatus);   
      pMe->bVirtualInputMode = FALSE;   
      RELEASEIF(piwTarget);   
      return;   
   }   
   RELEASEIF(piwTarget);

The touch controller must take different actions based on which status is received.

If VIRTUALINPUT_STATUS_ACCEPT is received, it means the user is finished entering data, and the keypad should be hidden.

   switch (ev->nStatus) {   
      case VIRTUALINPUT_STATUS_ACCEPT:   
         //On accept close the window.   
         VirtualInputDateTimeTC_Detach(pMe);   
         break;   
            

The status VIRTUALINPUT_STATUS_MOVE is sent when another widget initiates a virtual input request due to user interaction. The touch controller must respond by cancelling the listener but should not try to hide the keypad since another widget requires it.

      case VIRTUALINPUT_STATUS_MOVE:   
         //On move, only cancel the listener.   
         LISTENER_Cancel(&pMe->mlVirtualInputStatus);   
         pMe->bVirtualInputMode = FALSE;   
         break;

When a VIRTUALINPUT_STATUS_CANCEL status is received, the virtual keypad is dismissed. If a buffer is available, the touch controller ignores it's content.

      case VIRTUALINPUT_STATUS_CANCEL:   
         //On cacel, close the window   
         VirtualInputDateTimeTC_Detach(pMe);   
         break;   
...   

Dtor

Dtor is called when the base DateTimeTouchController reaches a reference count of zero. All references are released and listeners canceled.

static void VirtualInputDateTimeTC_Dtor(void *pCxt)   
{   
   VirtualInputDateTimeTC* pMe = (VirtualInputDateTimeTC*) pCxt;   
      
   //Relase all references, cancel all listeners   
   VirtualInputDateTimeTC_Detach(pMe);   
   LISTENER_Cancel(&pMe->mlRCViewModel);   
   HANDLERDESC_FREE(&pMe->hdBase);   
   RELEASEIF(pMe->picVirtualInputMgr);   
   RELEASEIF(pMe->piEnv);   
}