/*

* Copyright (c) 2007 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:  Gesture helper implementation

*

*/

#ifndef _GESTUREHELPERIMPL_H_

#define _GESTUREHELPERIMPL_H_

#include <e32base.h>

class CAlfEnv;

class CAlfDisplay;

class CAlfVisual;

class TAlfEvent;

struct TPointerEvent;

namespace GestureHelper

{

class CCallbackTimer;

class CGesture;

class CPointerCapturer;

class MGestureObserver;

/**

 * Implementation of CGestureHelper interface

 */

NONSHARABLE_CLASS( CGestureHelperImpl ) : public CBase

    {

public:

    /** 2-phase constructor */

    static CGestureHelperImpl* NewL( MGestureObserver& aObserver );

    /** Destructor */

    ~CGestureHelperImpl();    

    void InitAlfredPointerCaptureL( CAlfEnv& aEnv, CAlfDisplay& aDisplay, 

        TInt aFreeControlGroupId );

    /** See @ref CGestureHelper::SetHoldingEnabled */

    void SetHoldingEnabled( TBool aEnabled );

    /** See @ref CGestureHelper::IsHoldingEnabled */

    TBool IsHoldingEnabled() const;

    /** See @ref CGestureHelper::SetDoubleTapEnabled */

    void SetDoubleTapEnabled( TBool aEnabled );

    /** See @ref CGestureHelper::IsDoubleTapEnabled */

    TBool IsDoubleTapEnabled() const;

    /** See @ref CGestureHelper::HandlePointerEventL */

    TBool HandlePointerEventL( const TPointerEvent& aEvent );

    /** See @ref CGestureHelper::OfferEventL */

    TBool OfferEventL( const TAlfEvent& aEvent );

    /** Reset helper state */

    void Reset();

    /** See @ref CGestureHelper::AddObserver */

    void AddObserver(MGestureObserver* aObserver); 

    /** Returns true the current event is a stray event form another visual */

    TBool StrayEvent( const TPointerEvent& aEvent ) const;

private:

    /**

     * Analyse how the pointer event affects the current gesture, and potentially

     * notify the observer. 

     * @param aVisual visual on which the event fell on or NULL if not known

     * @return ETrue if the event was consumed

     */

    TBool HandlePointerEventL( const TPointerEvent& aEvent, CAlfVisual* aVisual );

     /**

      * Analyse how the pointer event affects the current gesture, and potentially

      * notify the observer. 

      * @param aVisual visual on which the event fell on or NULL if not known

      * @return ETrue if the event was consumed

      */

     TBool HandleSinglePointerEventL( const TPointerEvent& aEvent, CAlfVisual* aVisual );

     /**

      * Analyse how the pointer event affects the current gesture, and potentially

      * notify the observer. 

      * @param aVisual visual on which the event fell on or NULL if not known

      * @return ETrue if the event was consumed

      */

     TBool HandleMultiplePointerEventL( const TPointerEvent& aEvent, const TInt aPointerNumber );

    /** @return ETrue if the helper has not started processing a gesture */

    inline TBool IsIdle( TBool aPointerNumber = 0 ) const;

    /** Add a point to the sequence of points that make up the gesture */

    inline void AddPointL( const TPointerEvent& aEvent );    

    /** Add a point to the sequence of points that make up the gesture */

    inline TInt AddPoint( const TPointerEvent& aEvent );

    /** Add a point to the sequence of points that make up the gesture */

    inline void AddSecondaryPointL( const TPointerEvent& aEvent );    

    /** Add a point to the sequence of points that make up the gesture */

    inline TInt AddSecondaryPoint( const TPointerEvent& aEvent );

    /** Verify if the currnet pointer event recived is valid and expected */

    inline TBool ValidatePointer( const TPointerEvent& aEvent, const TInt aPointerNumber) const;

    /** return if there is a second pointer held down */

    inline TBool IsMultiTouch() const;

    /** Add points to corresponding array depending on aPointerNumber, return whether the point is added or not */   

    inline TBool AddMultiTouchPointsL( const TPointerEvent& aEvent, const TInt aPointerNumber);

    /** Activates holding and notifies observer that holding has been started */

    void StartHoldingL();

    /* Set previous tag gesture to null (and recycle the gesture object) */

    static void RecyclePreviousTapGesture( TAny* aSelf );

    /** Emits a tap event since second tap of a double tap was not received within timeout */

    void EmitFirstTapEventL();

    /** Emit the start gesture event that aGesture would have produced */

    void EmitStartEventL( const CGesture& aGesture );

    /** 

     * Send code event if not holding. Also sets the event to released and emits again.

     * Modifies aGesture! 

     */

    void CompleteAndEmitSingleTouchL( CGesture& aGesture );

    /** 

     * Send code event if pinch. Also sets the event to released and emits again.

     * Modifies aGesture! 

     */   

    void CompleteAndEmitDoubleTouchL( CGesture& aGesture );

    /** 

     * Send cancel event about the latest gesture client was notified about 

     * Sets the latest gesture to Cancelled.

     */

    void EmitCancelEventL();

    /** Notify observer of the gesture */

    void EmitEventL( const CGesture& aGesture );

    /** 

     * (re)start holding timer at the current point.

     * Does not restart holding if the point (in aEvent) is near enough to where holding 

     * was started earlier. (Allows small movement but still starting holding.

     */

    void StartHoldingTimer( const TPointerEvent& aNewEvent );

    /** 

     * @return a gesture object from the gesture pool 

     * Getting gestures from the gesture pool avoids the need to create gestures

     * after construction. There is max only one gesture object in the pool, 

     * but no more is needed 

     */

    CGesture* NewGesture();

    /** Move the gesture into the gesture pool, and set aGesturePointer to null */

    void RecycleGesture( CGesture*& aGesturePointer );

private:

    /// Gesture is the logical representation of a sequence of points arriving

    /// at certain times

    /// This is the current gesture

    CGesture* iGesture;

    /// Tap gesture of the previous gesture. Used when double tap is enabled.

    /// The gesture is cached, since it cannot be emitted until gesture helper

    /// knows whether the next gesture forms a double tap

    /// @see CGestureHelperImpl::iDoubleTapTimer

    CGesture* iPreviousTapGesture;

    /// This is a recyclable object pool with just one object.

    /// This class needs one or two gesture objects at any one time. There is one

    /// less error condition to handle if gesture objects are not created after

    /// construction. Therefore, if only one gesture object is needed at a specific,

    /// point in time, the unused gesture object is stored here.

    CGesture* iUnusedGesture;

    /// When double tap is enabled, a tap

    /// event (and it's released event) is only emitted after the double tap timeout

    /// passes. If user taps again before the timeout (in the same position),

    /// this gesture is emitted as a double tap (followed by the released event, 

    /// and the second tap is not emitted at all.

    /// If user taps, and then swipes before the double tap timeout, this tap

    /// event (and it's released event) event is emitted, and only then the swipe's

    /// down and drag events are emitted. In other words, if user presses down

    /// during the timeout, the down event it not emitted until the gesture

    /// helper knows that the gesture is not another tap.

    /// Behavior while double tap enabled:

    /// Swipe: Down + drag + up => emits down + swipe/cancel + released

    /// Tap: Down + up => emits down ... timeout ... + tap + released

    /// Double tap: Down + up + down + up => emits down ... double tap + released

    /// Tap + quick swipe: Down + up + down + drag + ... => emits down ... tap + up (for tap) + down (for swipe ) + drag + ...

    /// Double tap timer is cancelled when the second pointer down event is received,

    /// i.e., it does not matter if user does this: 

    /// down + up + down ... long wait ... + up. It's still a double tap.

    CCallbackTimer* iDoubleTapTimer;

    /// holding is activated when user keeps pointer down in the same place for 

    /// a longer period. the holding timer activates off when enough time has passed.

    CCallbackTimer* iHoldingTimer;

    /// observer for gesture events

    MGestureObserver* iObserver;

    /// captures subsequent pointer events after pointer down received,

    /// until pointer up

    CPointerCapturer* iPointerCapturer;

    /// Tells number of pointers pressed down.

    TInt iPointerCount;

    /// Tells the pointer number of the current pointers pressed down.

    /// Valid only when single pointer is touched down.

    TInt iCurrentPointer;    

    };

} // GestureHelper

#endif // _GESTUREHELPERIMPL_H_