Purpose

The purpose of the Touch Gesture Framework (FW) API is to convert a stream of pointer events into a logical gesture.

Constraints

This API is valid for all platforms running on Symbian OS v9.5 or later.

Classification and release information

This API is a platform API and was first published in S60 release 5.2. This document is valid from S60 release 5.2 onwards.

Emulator support

This API is supported in the WINS/WINSCW emulator environment.

API description

Touch Gesture Framework contains a pointer to a control (derived from CCoeControl) where gestures are recognized. The recognized gestures are reported to the gesture observer. Based on the gesture interest set by the gesture observer, CAknTouchGestureFw converts the pointer events to the logical gesture.

NOTE: The gesture observer must always set the gesture interest in order to receive gesture events. The events that are sent to the gesture observer vary according to the gesture group.

Each gesture event belongs to a gesture interest group. The default value for the interest is EAknTouchGestureFwNoGroup.

The following table lists the gesture interest groups:

EAknTouchGestureFwGroupTap

Group for tap gestures. It consists of the following:

  • Single tap

  • Double tap

  • Long tap

EAknTouchGestureFwGroupFlick

Group for flick gestures. It consists of the following:

  • Left flick

  • Right flick

  • Up flick

  • Down flick

EAknTouchGestureFwGroupDrag

Group for drag gestures. It consist of drag.

EAknTouchGestureFwGroupPinch

Group for pinch gestures. It consists of pinch.

EAknTouchGestureFwNoGroup

Group for no gestures

EAknTouchGestureFwAll

Group for all gestures

Use cases

The following use cases illustrate the typical use of the Touch Gesture Framework API:

  • Creating gesture framework

  • Handling touch gesture

API class structure

The Touch Gesture Framework API consists of two classes as listed in the following table:

CAknTouchGestureFw

Provides functionality to convert a stream of pointer events into a logical gesture.

MAknTouchGestureFwObserver

Touch gesture FW observer.

The Touch Gesture Framework API class st...


The Touch Gesture Framework API class structure.

Related APIs
  • CAknTouchGestureFw
  • MAknTouchGestureFwObserver
Related APIs
  • CAknTouchGestureFw
  • CCoeControl
  • EAknTouchGestureFwAll
  • EAknTouchGestureFwGroupDrag
  • EAknTouchGestureFwGroupFlick
  • EAknTouchGestureFwGroupPinch
  • EAknTouchGestureFwGroupTap
  • EAknTouchGestureFwNoGroup

Using the Touch Gesture Framework API

Use Case 1: Creating gesture framework

The following steps explain how to create a gesture framework:

  • Create a CAknTouchGestureFw instance using CAknTouchGestureFw::NewL(). Client application can receive gesture events after implementing MAknTouchGestureFwObserver interface and registering to CAknTouchGestureFW.

  • Set the gesture interest by calling CAknTouchGestureFw::SetGestureInterestL();.

The following example code explains how to create a gesture framework:

/*
* CGesObserver is a realization of interface of 
* MAknTouchGestureFwObserver
*/
void CGesObserver::ConstructL( const TRect& aRect )
    {
    ……
    // Create the gestured control
    iGestureControl = new( ELeave ) CEikEdwin();
    iGestureControl ->SetContainerWindowL( *this );
    TInt edwinFlags = CEikEdwin::ENoAutoSelection;
    edwinFlags |= CEikEdwin::EReadOnly;
    iGestureControl ->ConstructL( edwinFlags );
    iGestureControl ->SetAknEditorCurrentInputMode( EAknEditorTextInputMode );
    
    // Create gesture frame work object
    CAknTouchGestureFw* gestureFw = CAknTouchGestureFw::NewL( *this, *iGestureControl );
    // Set gesture interest (drag and flick gestures)
    gestureFw->SetGestureInterestL( EAknTouchGestureFwGroupDrag |                             
                                    EAknTouchGestureFwGroupFlick );
    ……
    }
Related APIs
  • CAknTouchGestureFW
  • CAknTouchGestureFw
  • CAknTouchGestureFw::NewL()
  • CAknTouchGestureFw::SetGestureInterestL();
  • MAknTouchGestureFwObserver

Use Case 2: Handling touch gesture

Touch gesture framework notifies the observer when the user makes gestures in the gesture control area. Observer class must register to CAknTouchGestureFw for receiving gesture events. Set the gesture interest to enable gesture event notifications.

CGesObserver::HandleTouchGestureL() callback receives a general MAknTouchGestureFwEvent type event. To use gesture group-specific methods, theMAknTouchGestureFwEvent event must be casted to the corresponding gesture event type.

The following example code illustrates how to handle touch gesture events.

void CGesObserver::HandleTouchGestureL( MAknTouchGestureFwEvent& aEvent )
    {
    // Handle gestures by group
    switch ( aEvent.Group() )
        {
        case EAknTouchGestureFwGroupDrag:
            {
            // We are interested on drag start position and current position,
            // need to cast to drag event for accessing corresponding methods
            MAknTouchGestureFwDragEvent* dragEvent = AknTouchGestureFwEventDrag( aEvent );
            TPoint startPosition = dragEvent->StartPosition();
            TPoint curPosition = dragEvent->CurrentPosition();
            ...
            break;
            }
        case EAknTouchGestureFwGroupFlick:
            {
            // We want to handle specific flick types
            if ( aEvent.Type() == EAknTouchGestureFwFlickLeft )
                {
                // Flick left received, do something e.g. move content to left            
                ...
                }
            else if ( aEvent.Type() == EAknTouchGestureFwFlickRight )
                {
                // Flick right received, do something, for example, move content to right
                ...
                }
            // Do something on all flick events
            ...
            break;
            }
        default:
            {
            break;
            }
        }
    }
Related APIs
  • CAknTouchGestureFw
  • CGesObserver::HandleTouchGestureL()
  • MAknTouchGestureFwEvent

Extensions to the API

There is no explicit support for extensions to the Touch Gesture Framework API.

Limitations of the API

None.