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

Developer

resources

Using the Touchscreen Troubleshooting Applet

Base version:

Brew MP 1.0

Tested version:

Brew MP 1.0.3 (device), 1.0.2 (simulator)

Phone tested:

Yes

The Touch Troubleshooting applet is intended to verify the correct operation of a Brew® MP touchscreen device. It is written using Brew MP Widgets.

The applet draws points on the display in response to Brew MP pointer events:

  • green = pointer down
  • black = pointer move
  • yellow = pointer stale move
  • red = pointer up.
Events received from a touchscreen pointer other than pointer 1 (on a multi-touch device) are drawn as numbers corresponding to the pointer ID.

The applet gathers statistics when it receives touchscreen events. When a pointer up event is received, the touch observer is queried for the flick information associated with the gesture just made by the user and then the touchscreen statistics are output to the screen. The touchscreen statistics displayed are:

  • Total number of pointer down events
  • Total number of pointer move events
  • Total number of pointer stale move events
  • Total number of pointer up events
  • Last flick direction
  • Last flick speed

Three touchscreen tests are described for the user to perform in a pop-up message, which is displayed when the Tests... button is clicked. The tests to perform are:

  • Reset the statistics, then draw a circle on the screen with a pointing device.

    Note: The circle is simply a shape for the user to draw to verify that the device generates sufficient pointer events to describe the circle.

    The user should see a green point (pointer down) followed by a series of black (pointer move) or yellow (pointer stale move) points and finally a red (pointer up) point.
  • Reset the statistics, perform a vertical flick, then reset the statistics and perform a horizontal flick. The user should see a vertical or horizontal line of points.
  • If testing a multi-touch device, reset the statistics, perform a vertical pinch, then reset the statistics and perform a horizontal pinch. The user should see two vertical or horizontal lines of points, each of which corresponds to a particular pointer.

Touchscreen statistics are ouput to the screen after each gesture made by the user. These statistics should be used to verify the correct behaviour of the touchscreen device, such as its ability to correctly determine the type and position of various pointer events.

Objective

This document describes how to use the Touch Troubleshooting applet to test the functionality of a touchscreen device.

Requirements

The main functionality of the applet is contained in two files: TouchTroubleshoot.c and MainPage.c. Other files in the project support the applet functionality, such as the generic widget pop-up in WidgetPopUp.c.

At start-up, the applet

  • Creates a root container
  • Enables touch support
  • Gets the root touch observer
  • Starts last linear movement observation
  • Provides the root container with a canvas.

On receipt of the EVT_APP_START event, the main page is created. The main page consists of an XY container, two buttons and static widgets to display strings. An offscreen display is also created.

When touch events are received by the applet's event handler, they are passed to Widgets for handling, before being forwarded to the main page. This ensures the main page of the applet can respond to all pointer events, even if they are processed by Widgets, which allows, for example, the events causing a button click to be displayed on top of the button. Points are drawn on the offscreen display in response to pointer events. When a pointer up event is received, the statistics are updated and the offscreen display bitmap is blitted to the screen.

Sample code location

ZIP filename

Location

Run app

c_touchtroubleshoot

Brew MP Resources

  • Download and extract the ZIP file.

  • Compile the app.

  • Run it on the touchscreen Brew MP device to be tested.

Event handling

As well as handling EVT_APP_START, EVT_APP_STOP, EVT_APP_RESUME and EVT_KEY events, the applet handles touchscreen pointer events after passing them to Widgets for default handling.

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);
}
...

Error handling

When writing a touchscreen applet such as this, ensure that all of the executed APIs have returned SUCCESS in order to proceed with the next step and for correct execution, unless a potential error is of no consequence (for example, this applet ignores any errors that may occur when removing a widget from the root container).

Related information

  • See the Widgets Touchscreen Technology Guide.
  • See the Widgets Technology Guide.
  • See the C/C++ API Reference.