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

Developer

resources

Handling tap, double tap, and hold

Tap, double tap, and tap and hold are some of the basic gestures supported by the touch observer. The touch observer analyzes pointer events to detect if a pointer's movement and sequence duration were within the allowed position and time thresholds. Based on the gesture type, either a gesture model notification is issued, or an option is provided to the application to query the touch observer if a gesture is detected.

These gestures are defined as follows:

  • Tap - occurs when a complete pointer sequence (tap and release) occurs in a short duration of time covering a small portion of the screen. If the pointer sequence goes beyond the allowed distance, it usually becomes a drag or scroll. If the pointer sequence goes beyond the allowed time limit, it becomes a tap and hold.

  • Double tap - occurs when a pointer down event follows a tap gesture within a short duration and distance.

  • Tap and hold - occurs when the screen is touched and not released within a given time period. In addition, any moves observed within this time threshold should be within a limited distance (to avoid conflict with a pan or scroll action).

This topic explains how an application can listen for tap, double tap, tap and hold gestures and how to query touch observer for information about these gestures. The example code shown in this topic is from c_gestures_app.

Tap and double tap

When touch observer detects tap or double tap, it propagates a pointer event through the widget tree. One of the parameters of the pointer event is the tap or double tap information. To handle tap or double tap gestures, an application needs to do following:

  1. Include files for widgets and touch observer.
  2. Enable touch and start tap gesture observation on touch observer.
  3. Hook an application-specific event handler into the widget.
  4. Handle the pointer up event. Query touch observer if tap or double tap is detected and take appropriate action.
  5. Stop observation on touch observer.

These steps are described in more detail in the example sections below.

Tap and hold

When a tap and hold gesture is detected by touch observer, it sends a notification to the application through a gesture model. To handle the tap and hold gesture, an application needs to do following.

  1. Enable touch and start tap and hold gesture observation on touch observer.
  2. Retrieve the gesture model from touch observer.
  3. Add a listener to the gesture model.
  4. Take appropriate action upon receiving tap and hold notification.
  5. Stop observation on touch observer
  6. Cancel listener on gesture model.

These steps are described in more detail in the example sections below.

Example: tap and double tap include files

To handle tap and double tap in an application, additional include files are needed. The example below is from the c_gestures_app sample.

// Widget related includes  
#include "AEEIHandler.h"  
#include "AEEIWidget.h"  
#include "AEEIRootContainer.h"  
#include "AEEWProperties.h"  
#include "AEEWidgetProperties.h"  
#include "AEEPointerObserver.h"  
#include "AEEPointerHelpers.h"

Example: enabling touch, starting gesture observation for tap and double tap

After the Root container has been created, the application can enable touch on it, which causes touch observer to observe and analyze pointer events and store gesture information. Pointer events will be passed down the widget tree.

// Enable touch.  
ERR_TRY( IWidget_EnableTouch(pMe->piwRoot) );

Start tap and double tap observation on touch observer. For example:

// Query Touch Observer   
ERR_TRY( IWidget_GetTouchObserver(pMe->piwRoot, &pMe->piTO));  
    
// Start Observation on Single Tap  
ERR_TRY( IObserver_StartObservation(pMe->piTO, TOUCHOBSF_TAP));  
  
// Start Observation on Double Tap  
ERR_TRY( IObserver_StartObservation(pMe->piTO, TOUCHOBSF_DBLTAP));

Example: overriding a widget's event handler for gesture handling

In this example, a rounded border static widget is used to create the desired widget on which gestures have to be handled.

// Create rounded border static widget  
ERR_TRY( c_gestures_app_ISHELL_CreateLabelWidget(pMe->a.m_pIShell, &piws1,   
                                                     awchLabel4, 220));

The application should override the static widget's event handler to handle tap and double tap gestures on this widget. For more information on how to override an event handler, refer to Overriding Widget's Event Handler.

// Override static widget event handler  
HANDLERDESC_INIT(&pMe->hdStatic, c_gestures_app_StaticHandler, (void*) pMe, NULL);  
IWidget_SetHandler(piws1, &pMe->hdStatic);

Example: handling gestures

This example shows how to handle pointer events in the custom event handler and how to query touch observer for tap and double tap detection.

The tap and double tap gestures are detected on EVT_POINTER_UP. In this example, when the application detects a tap or double tap gesture, it updates the static widget's text to "Tap Detected" or "Double Tap Detected". The custom event handler should pass unhandled events to the widget's default handler.

Refer to the http://developer.brewmp.com/reference/api-all for widget element related helper methods.

static boolean c_gestures_app_StaticHandler(c_gestures_app *pMe, AEEEvent evt,   
                                               uint16 wParam, uint32 dwParam)  
{      
   int nErr = 0;  
   boolean result = HANDLERDESC_CALL(&pMe->hdStatic, evt, wParam, dwParam);        
   if(evt == EVT_POINTER_DOWN) {            
      int x, y;        
      // this code is added here to show how to get x and y from  
      // pointer event string  
      x = (int16) AEE_POINTER_GET_X((const char*) dwParam);  
      y = (int16) AEE_POINTER_GET_Y((const char*) dwParam);  
      // check if this was a double tap  
      ERR_TRY( IObserver_GetDoubleTap(pMe->piTO, &pMe->bDoubleTap));  
      if (pMe->bDoubleTap){  
         DBGPRINTF("StaticHandler: Double Tap Detected");  
         ERR_TRY(IWidget_SetText(pMe->piwTarget, awchLabel2, 0));    
      }  
   }  
   else if(evt == EVT_POINTER_UP) {  
      boolean bTap = FALSE;        
      // check if this was a single tap  
      ERR_TRY(IObserver_GetSingleTap(pMe->piTO, &bTap));  
      if (bTap){  
         DBGPRINTF("StaticHandler: Tap Detected");  
         ERR_TRY(IWidget_SetText(pMe->piwTarget, awchLabel1, 0));    
     }        
  }        
ERR_CATCH:  
     return result;   
}

Example: stop observation

It is recommended that applications stop observation on touch observation when gesture related handling is completed. For example:

void c_gestures_app_FreeAppData(c_gestures_app* pMe)  
{  
  .........   
  (void)IObserver_StopObservation(pMe->piTO, TOUCHOBSF_TAP);     
  (void)IObserver_StopObservation(pMe->piTO, TOUCHOBSF_DBLTAP);     
  .........  
} 

Example: starting gesture observation for tap and hold

The following example shows how to start observation for tap and hold gestures:

static int c_gestures_app_SetupRootContainer(c_gestures_app *pMe)  
{  
 ..........  
  // Start Observation on Tap & Hold   
  ERR_TRY( IObserver_StartObservation(pMe->piTO, TOUCHOBSF_TAPANDHOLD));  
 ..........  
}

Example: retrieving gesture model and attaching listener

An application can retrieve the gesture model from a touch observer, and then attach a listener to the gesture model to receive notification of gesture events. In the following example, the application calls IWidget_GetTouchObserver() to get the touch observer object, then calls IObserver_GetGestureModel() to get the gesture model. It then calls IModel_AddListenerEx() to initialize the model listener and attach it to the model.

static int c_gestures_app_SetupRootContainer(c_gestures_app *pMe)  
{  
   .........  
   // Query Touch Observer   
   ERR_TRY( IWidget_GetTouchObserver(pMe->piwRoot, &pMe->piTO));  
   ..........      
   ERR_TRY( IObserver_GetGestureModel(pMe->piTO, &piGestureModel));  
   ERR_TRY( IModel_AddListenerEx(piGestureModel, &pMe->mlGesturesListener,   
        (PFNLISTENER) c_gestures_app_GesturesModelListener, (void*) pMe));  
   .........     
}

The callback function, c_gestures_app_GesturesModelListener, will be called when gesture events occur.

Example: listening to gesture notification, action

When a tap and hold gesture is detected, touch observer issues a EVT_MDL_GESTURE notification with gesture type TOUCHOBSF_TAPANDHOLD. In this example, the call back function checks for an EVT_MDL_GESTURE event with gesture type TOUCHOBSF_TAPANDHOLD and updates the widget text to "Tap and Hold Detected".

static int c_gestures_app_GesturesModelListener(c_gestures_app *pMe,
            ModelEvent *pEvent)  
{  
   ...........  
   if (EVT_MDL_GESTURE == pEvent->evCode) {  
      ObserverGestureEvent* pwese = (ObserverGestureEvent*)pEvent;  
      if(pwese->nGestureType == TOUCHOBSF_TAPANDHOLD) {  
         DBGPRINTF("GesturesModelListener: Tap and Hold Detected");  
         ERR_TRY(IWIDGET_SetText(pMe->piwTarget, awchLabel3, 0));    
      }  
   }  
   ...........  
}

Example: stop observation

Once gesture related handling is completed, stop observation on touch observer and cancel listener on gesture model.

void c_gestures_app_FreeAppData(c_gestures_app* pMe)  
{  
   .........   
   (void)IObserver_StopObservation(pMe->piTO, TOUCHOBSF_TAPANDHOLD);     
   LISTENER_Cancel(&pMe->mlGesturesListener);  
   .........  
}