/*

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

* All rights reserved.

* This component and the accompanying materials are made available

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

* which accompanies this distribution, and is available

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

*

* Initial Contributors:

* Nokia Corporation - initial contribution.

*

* Contributors:

*

* Description:  Flick touch gesture recognizer.

*

*/

#ifndef C_AKNTOUCHGESTUREFWFLICKRECOGNIZER_H

#define C_AKNTOUCHGESTUREFWFLICKRECOGNIZER_H

#include "akntouchgesturefwbaserecognizer.h"

namespace AknTouchGestureFw {

class CAknTouchGestureFwDragTracer;

/**

 *  Flick touch gesture recognizer.

 *

 *  @lib akntouchgesturefw

 *  @since S60 v5.2

 */

NONSHARABLE_CLASS( CAknTouchGestureFwFlickRecognizer )

    : public CAknTouchGestureFwBaseRecognizer

    {

public:

    /**

     * Two-phased constructor.

     *

     * @param  aEngine  The gesture recognition engine.

     */

    static CAknTouchGestureFwFlickRecognizer* NewL(

            CAknTouchGestureFwRecognitionEngine& aEngine );

    /**

     * Two-phased constructor.

     *

     * @param  aEngine  The gesture recognition engine.

     */

    static CAknTouchGestureFwFlickRecognizer* NewLC(

            CAknTouchGestureFwRecognitionEngine& aEngine );

    /**

     * Destructor.

     */

    virtual ~CAknTouchGestureFwFlickRecognizer();

public: // From base class CAknTouchGestureFwBaseRecognizer.

    /**

     * Returns recognizer gesture group.

     *

     * @return EAknTouchGestureFwGroupFlick

     */

    TAknTouchGestureFwGroup GestureGroup() const;

    /**

     * Cancels gesture recognition.

     */

    void CancelRecognizing();

    /**

     * Handles single pointer event.

     *

     * @param  aPointerData  Pointer event related data.

     */

    void HandleSinglePointerEventL( const TPointerEventData& aPointerData );

    /**

     * Handles multi pointer event.

     *

     * @param  aPointerData            Pointer event related data.

     * @param  aFirstPointerPosition   First pointer position.

     * @param  aSecondPointerPosition  Second pointer position.

     */

    void HandleMultiPointerEventL( const TPointerEventData& aPointerData,

	                               const TPoint& aFirstPointerPosition,

                                   const TPoint& aSecondPointerPosition );

private:

    /**

     * C++ constructor.

     *

     * @param  aEngine  The gesture recognition engine.

     */

    CAknTouchGestureFwFlickRecognizer(

            CAknTouchGestureFwRecognitionEngine& aEngine );

    /**

     * Symbian second-phase constructor.

     */

    void ConstructL();

    /**

     * Starts single-touch recognition.

     *

     * @param  aPointerPos  Current pointer position.

     * @param  aTimeStamp   Pointer event time stamp.

     */

    void StartSingleRecognizing( const TPoint& aPointerPos,

                                 const TTime& aTimeStamp );

    /**

     * Handles single-touch recognition cycle.

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

     *

     * @param  aPointerPos  New position of pointer.

     * @param  aTimeStamp   Pointer event time stamp.

     */

    void SingleRecognizeL( const TPoint& aPointerPos,

                           const TTime& aTimeStamp);

    /**

     * Completes single-touch recognition.

     *

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

     *                           parameter @c aStartMultiTouch is @c EFalse.

     * @param  aTimeStamp        Pointer event time stamp.                           

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

     *                           by multitouch.

     */

    void CompleteSingleRecognizingL( const TPoint& aPointerPos,

                                     const TTime& aTimeStamp,

                                     TBool aStartMultiTouch );

    /**

     * Asks engine to send flick event to observer.

     *

     * @param  aGestureType    Flick gesture type.

     * @param  aPosition       Flick position.

     * @param  aSpeed          Flick speed.

     */

    void SendFlickEventL( TAknTouchGestureFwType aGestureType,

                          const TPoint& aPosition,

                          const TPoint& aSpeed );

    /**

     * Resets recognizer.

     */

    void Reset();

    /**

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

     *

     * @param  aPoint      The point to add.

     * @param  aTimeStamp  Pointer event time stamp.

     */

    void AddPoint( const TPoint& aPoint,

                   const TTime& aTimeStamp );

    /**

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

     *

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

     */

    TBool IsEmpty() const;

    /**

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

     *

     * @param  aFlickGestureType  On return type of flick gesture.

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

     *

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

     */

    TBool DetermineFlickTypeAndSpeed(

            TAknTouchGestureFwType& aFlickGestureType,

            TPoint& aSpeed );

    /**

     * Calculates distance and speed for flick.

     *

     * @param  aDistance  In return distance of flick.

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

     *

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

     */

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

    /**

     * Handles direction changes in drag.

     * If direction changes removes unnecessary points before

     * direction change point.

     *

     * @param  aPosition  New position.

     */

    void HandleDirectionChanges( const TPoint& aPosition );

    /**

     * Returns elapsed time.

     *

     * @param  aStartTime  Time of start point.

     * @param  aEndTime    Time of end point.

     *

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

     */

    static TTimeIntervalMicroSeconds32 Elapsed( const TTime& aStartTime,

                                                const TTime& aEndTime );

    /**

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

     *

     * @param  aNumberOfPoints  Number of points to leave.

     */

    void RemovePreviousPoints( TInt aNumberOfPoints );

    /**

     * Returns maximum flick buffer length.

     *

     * @return Maximum flick buffer length.

     */

    TInt MaximumBufferLength() const;

    /**

     * Returns flick speed threshold.

     *

     * @return Flick speed threshold.

     */

    TInt FlickSpeedThreshold() const;

    /**

     * Returns flick detection time.

     *

     * @return Flick detection time.

     */

    TInt FlickDetectionTime() const;

    /**

     * Returns flick direction change sensitivity.

     *

     * @return Flick direction change sensitivity.

     */

    TInt DirectionChangeSensitivity() const;

private: // data

    /**

     * Sequence of points that make up the gesture.

     * Used only for single-touch gesture.

     */

    RArray<TPointEntry> iPoints;

    /**

     * Drag tracer instance to detect changes in drag direction

     * and remove unnecessary points.

     * Own.

     */

    CAknTouchGestureFwDragTracer* iDragTracer;

    /**

     * Is the drag threshold exceeded or not.

     */

    TBool iThresholdExceeded;

    /**

     * Drag threshold area.

     */

    TThresholdArea iDragArea;

    /**

     * Flick speed.

     */

    TPoint iFlickSpeed;

    /**

     * Boolean flag to indicate if drag recognition

     * should be started upon single touch drag.

     * This flag may be set when multi touch changes to

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

     */

    TBool iStartOnSingleTouchDrag;

    };

} // namespace AknTouchGestureFw

#endif // C_AKNTOUCHGESTUREFWFLICKRECOGNIZER_H