S60 Touch Gesture Framework API
Changes in the Touch Gesture Framework API documentation
| Version |
Date |
Status |
Description |
|
1.0
|
08.03.2010
|
Approved
|
|
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:
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.
|
Related APIs
CAknTouchGestureFwMAknTouchGestureFwObserver
Related APIs
CAknTouchGestureFwCCoeControlEAknTouchGestureFwAllEAknTouchGestureFwGroupDragEAknTouchGestureFwGroupFlickEAknTouchGestureFwGroupPinchEAknTouchGestureFwGroupTapEAknTouchGestureFwNoGroup
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
CAknTouchGestureFWCAknTouchGestureFwCAknTouchGestureFw::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
CAknTouchGestureFwCGesObserver::HandleTouchGestureL()MAknTouchGestureFwEvent
Extensions to the API
There is no explicit support for extensions to the Touch Gesture Framework
API.
Limitations of the API
None.