1 /*

     2 * Copyright (c) 2009 Nokia Corporation and/or its subsidiary(-ies).

     3 * All rights reserved.

     4 * This component and the accompanying materials are made available

     5 * under the terms of "Eclipse Public License v1.0"

     6 * which accompanies this distribution, and is available

     7 * at the URL "http://www.eclipse.org/legal/epl-v10.html".

     8 *

     9 * Initial Contributors:

    10 * Nokia Corporation - initial contribution.

    11 *

    12 * Contributors:

    13 *

    14 * Description:  Flick touch gesture recognizer.

    15 *

    16 */

    17 

    18 #ifndef C_AKNTOUCHGESTUREFWFLICKRECOGNIZER_H

    19 #define C_AKNTOUCHGESTUREFWFLICKRECOGNIZER_H

    20 

    21 #include "akntouchgesturefwbaserecognizer.h"

    22 

    23 namespace AknTouchGestureFw {

    24 

    25 class CAknTouchGestureFwDragTracer;

    26 

    27 /**

    28  *  Flick touch gesture recognizer.

    29  *

    30  *  @lib akntouchgesturefw

    31  *  @since S60 v5.2

    32  */

    33 NONSHARABLE_CLASS( CAknTouchGestureFwFlickRecognizer )

    34     : public CAknTouchGestureFwBaseRecognizer

    35     {

    36 

    37 public:

    38 

    39     /**

    40      * Two-phased constructor.

    41      *

    42      * @param  aEngine  The gesture recognition engine.

    43      */

    44     static CAknTouchGestureFwFlickRecognizer* NewL(

    45             CAknTouchGestureFwRecognitionEngine& aEngine );

    46 

    47     /**

    48      * Two-phased constructor.

    49      *

    50      * @param  aEngine  The gesture recognition engine.

    51      */

    52     static CAknTouchGestureFwFlickRecognizer* NewLC(

    53             CAknTouchGestureFwRecognitionEngine& aEngine );

    54 

    55     /**

    56      * Destructor.

    57      */

    58     virtual ~CAknTouchGestureFwFlickRecognizer();

    59 

    60 public: // From base class CAknTouchGestureFwBaseRecognizer.

    61 

    62     /**

    63      * Returns recognizer gesture group.

    64      *

    65      * @return EAknTouchGestureFwGroupFlick

    66      */

    67     TAknTouchGestureFwGroup GestureGroup() const;

    68 

    69     /**

    70      * Cancels gesture recognition.

    71      */

    72     void CancelRecognizing();

    73 

    74     /**

    75      * Handles single pointer event.

    76      *

    77      * @param  aPointerData  Pointer event related data.

    78      */

    79     void HandleSinglePointerEventL( const TPointerEventData& aPointerData );

    80 

    81     /**

    82      * Handles multi pointer event.

    83      *

    84      * @param  aPointerData            Pointer event related data.

    85      * @param  aFirstPointerPosition   First pointer position.

    86      * @param  aSecondPointerPosition  Second pointer position.

    87      */

    88     void HandleMultiPointerEventL( const TPointerEventData& aPointerData,

    89 	                               const TPoint& aFirstPointerPosition,

    90                                    const TPoint& aSecondPointerPosition );

    91 

    92 private:

    93 

    94     /**

    95      * C++ constructor.

    96      *

    97      * @param  aEngine  The gesture recognition engine.

    98      */

    99     CAknTouchGestureFwFlickRecognizer(

   100             CAknTouchGestureFwRecognitionEngine& aEngine );

   101 

   102     /**

   103      * Symbian second-phase constructor.

   104      */

   105     void ConstructL();

   106 

   107     /**

   108      * Starts single-touch recognition.

   109      *

   110      * @param  aPointerPos  Current pointer position.

   111      * @param  aTimeStamp   Pointer event time stamp.

   112      */

   113     void StartSingleRecognizing( const TPoint& aPointerPos,

   114                                  const TTime& aTimeStamp );

   115 

   116     /**

   117      * Handles single-touch recognition cycle.

   118      * Called for every drag event when one pointer is down.

   119      *

   120      * @param  aPointerPos  New position of pointer.

   121      * @param  aTimeStamp   Pointer event time stamp.

   122      */

   123     void SingleRecognizeL( const TPoint& aPointerPos,

   124                            const TTime& aTimeStamp);

   125 

   126     /**

   127      * Completes single-touch recognition.

   128      *

   129      * @param  aPointerPos       New position of pointer, valid only if

   130      *                           parameter @c aStartMultiTouch is @c EFalse.

   131      * @param  aTimeStamp        Pointer event time stamp.                           

   132      * @param  aStartMultiTouch  If @c ETrue, recognition was cancelled

   133      *                           by multitouch.

   134      */

   135     void CompleteSingleRecognizingL( const TPoint& aPointerPos,

   136                                      const TTime& aTimeStamp,

   137                                      TBool aStartMultiTouch );

   138 

   139     /**

   140      * Asks engine to send flick event to observer.

   141      *

   142      * @param  aGestureType    Flick gesture type.

   143      * @param  aPosition       Flick position.

   144      * @param  aSpeed          Flick speed.

   145      */

   146     void SendFlickEventL( TAknTouchGestureFwType aGestureType,

   147                           const TPoint& aPosition,

   148                           const TPoint& aSpeed );

   149 

   150     /**

   151      * Resets recognizer.

   152      */

   153     void Reset();

   154 

   155     /**

   156      * Adds a point to the sequences of points that forms the gesture.

   157      *

   158      * @param  aPoint      The point to add.

   159      * @param  aTimeStamp  Pointer event time stamp.

   160      */

   161     void AddPoint( const TPoint& aPoint,

   162                    const TTime& aTimeStamp );

   163 

   164     /**

   165      * Returns @c ETrue if the gesture has no points.

   166      *

   167      * @return @c ETrue if the gesture has no points.

   168      */

   169     TBool IsEmpty() const;

   170 

   171     /**

   172      * Checks if flick is recognised. Determines its direction and speed.

   173      *

   174      * @param  aFlickGestureType  On return type of flick gesture.

   175      * @param  aSpeed             On return the speed of the flick.

   176      *

   177      * @return ETrue if flick is recognized (speed is over threshold).

   178      */

   179     TBool DetermineFlickTypeAndSpeed(

   180             TAknTouchGestureFwType& aFlickGestureType,

   181             TPoint& aSpeed );

   182 

   183     /**

   184      * Calculates distance and speed for flick.

   185      *

   186      * @param  aDistance  In return distance of flick.

   187      * @param  aSpeed     In return speed of flick is pixels per seconds.

   188      *

   189      * @return @c ETrue if there was enought information to calculate values.

   190      */

   191     TBool CalculateFlickParameters( TPoint& aDistance, TPoint& aSpeed );

   192 

   193     /**

   194      * Handles direction changes in drag.

   195      * If direction changes removes unnecessary points before

   196      * direction change point.

   197      *

   198      * @param  aPosition  New position.

   199      */

   200     void HandleDirectionChanges( const TPoint& aPosition );

   201 

   202     /**

   203      * Returns elapsed time.

   204      *

   205      * @param  aStartTime  Time of start point.

   206      * @param  aEndTime    Time of end point.

   207      *

   208      * @return Elapsed time between @c aStartTime and @c aEndTime.

   209      */

   210     static TTimeIntervalMicroSeconds32 Elapsed( const TTime& aStartTime,

   211                                                 const TTime& aEndTime );

   212 

   213     /**

   214      * Removes unnecessary (oldest) points before direction change point.

   215      *

   216      * @param  aNumberOfPoints  Number of points to leave.

   217      */

   218     void RemovePreviousPoints( TInt aNumberOfPoints );

   219 

   220     /**

   221      * Returns maximum flick buffer length.

   222      *

   223      * @return Maximum flick buffer length.

   224      */

   225     TInt MaximumBufferLength() const;

   226 

   227     /**

   228      * Returns flick speed threshold.

   229      *

   230      * @return Flick speed threshold.

   231      */

   232     TInt FlickSpeedThreshold() const;

   233 

   234     /**

   235      * Returns flick detection time.

   236      *

   237      * @return Flick detection time.

   238      */

   239     TInt FlickDetectionTime() const;

   240 

   241     /**

   242      * Returns flick direction change sensitivity.

   243      *

   244      * @return Flick direction change sensitivity.

   245      */

   246     TInt DirectionChangeSensitivity() const;

   247 

   248 private: // data

   249 

   250     /**

   251      * Sequence of points that make up the gesture.

   252      * Used only for single-touch gesture.

   253      */

   254     RArray<TPointEntry> iPoints;

   255 

   256     /**

   257      * Drag tracer instance to detect changes in drag direction

   258      * and remove unnecessary points.

   259      * Own.

   260      */

   261     CAknTouchGestureFwDragTracer* iDragTracer;

   262 

   263     /**

   264      * Is the drag threshold exceeded or not.

   265      */

   266     TBool iThresholdExceeded;

   267 

   268     /**

   269      * Drag threshold area.

   270      */

   271     TThresholdArea iDragArea;

   272 

   273     /**

   274      * Flick speed.

   275      */

   276     TPoint iFlickSpeed;

   277     

   278     /**

   279      * Boolean flag to indicate if drag recognition

   280      * should be started upon single touch drag.

   281      * This flag may be set when multi touch changes to

   282      * single (i.e. another pointer was released). 

   283      */

   284     TBool iStartOnSingleTouchDrag;

   285     };

   286 

   287 } // namespace AknTouchGestureFw

   288 

   289 #endif // C_AKNTOUCHGESTUREFWFLICKRECOGNIZER_H