1 /*

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

    15 *

    16 */

    17 

    18 #ifndef _GESTUREHELPERIMPL_H_

    19 #define _GESTUREHELPERIMPL_H_

    20 

    21 #include <e32base.h>

    22 

    23 class CAlfEnv;

    24 class CAlfDisplay;

    25 class CAlfVisual;

    26 class TAlfEvent;

    27 struct TPointerEvent;

    28 

    29 namespace GestureHelper

    30 {

    31 

    32 class CCallbackTimer;

    33 class CGesture;

    34 class CPointerCapturer;

    35 class MGestureObserver;

    36 

    37 /**

    38  * Implementation of CGestureHelper interface

    39  */

    40 NONSHARABLE_CLASS( CGestureHelperImpl ) : public CBase

    41     {

    42 public:

    43     /** 2-phase constructor */

    44     static CGestureHelperImpl* NewL( MGestureObserver& aObserver );

    45     

    46     /** Destructor */

    47     ~CGestureHelperImpl();    

    48     

    49     void InitAlfredPointerCaptureL( CAlfEnv& aEnv, CAlfDisplay& aDisplay, 

    50         TInt aFreeControlGroupId );

    51     

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

    53     void SetHoldingEnabled( TBool aEnabled );

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

    55     TBool IsHoldingEnabled() const;

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

    57     void SetDoubleTapEnabled( TBool aEnabled );

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

    59     TBool IsDoubleTapEnabled() const;

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

    61     TBool HandlePointerEventL( const TPointerEvent& aEvent );

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

    63     TBool OfferEventL( const TAlfEvent& aEvent );

    64     /** Reset helper state */

    65     void Reset();

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

    67     void AddObserver(MGestureObserver* aObserver); 

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

    69     TBool StrayEvent( const TPointerEvent& aEvent ) const;

    70     

    71 private:

    72 

    73     /**

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

    75      * notify the observer. 

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

    77      * @return ETrue if the event was consumed

    78      */

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

    80 

    81      /**

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

    83       * notify the observer. 

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

    85       * @return ETrue if the event was consumed

    86       */

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

    88 

    89      /**

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

    91       * notify the observer. 

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

    93       * @return ETrue if the event was consumed

    94       */

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

    96      

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

    98     inline TBool IsIdle( TBool aPointerNumber = 0 ) const;

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

   100     inline void AddPointL( const TPointerEvent& aEvent );    

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

   102     inline TInt AddPoint( const TPointerEvent& aEvent );

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

   104     inline void AddSecondaryPointL( const TPointerEvent& aEvent );    

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

   106     inline TInt AddSecondaryPoint( const TPointerEvent& aEvent );

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

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

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

   110     inline TBool IsMultiTouch() const;

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

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

   113 

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

   115     void StartHoldingL();

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

   117     static void RecyclePreviousTapGesture( TAny* aSelf );

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

   119     void EmitFirstTapEventL();

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

   121     void EmitStartEventL( const CGesture& aGesture );

   122     /** 

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

   124      * Modifies aGesture! 

   125      */

   126     void CompleteAndEmitSingleTouchL( CGesture& aGesture );

   127     /** 

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

   129      * Modifies aGesture! 

   130      */   

   131     void CompleteAndEmitDoubleTouchL( CGesture& aGesture );

   132     /** 

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

   134      * Sets the latest gesture to Cancelled.

   135      */

   136     void EmitCancelEventL();

   137     /** Notify observer of the gesture */

   138     void EmitEventL( const CGesture& aGesture );

   139     /** 

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

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

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

   143      */

   144     void StartHoldingTimer( const TPointerEvent& aNewEvent );

   145 

   146     /** 

   147      * @return a gesture object from the gesture pool 

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

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

   150      * but no more is needed 

   151      */

   152     CGesture* NewGesture();

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

   154     void RecycleGesture( CGesture*& aGesturePointer );

   155     

   156 private:

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

   158     /// at certain times

   159     /// This is the current gesture

   160     CGesture* iGesture;

   161     

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

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

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

   165     /// @see CGestureHelperImpl::iDoubleTapTimer

   166     CGesture* iPreviousTapGesture;

   167 

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

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

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

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

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

   173     CGesture* iUnusedGesture;

   174     

   175     /// When double tap is enabled, a tap

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

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

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

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

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

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

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

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

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

   185     /// Behavior while double tap enabled:

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

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

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

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

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

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

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

   193     CCallbackTimer* iDoubleTapTimer;

   194     

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

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

   197     CCallbackTimer* iHoldingTimer;

   198     

   199     /// observer for gesture events

   200     MGestureObserver* iObserver;

   201     

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

   203     /// until pointer up

   204     CPointerCapturer* iPointerCapturer;

   205     

   206     /// Tells number of pointers pressed down.

   207     TInt iPointerCount;

   208     

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

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

   211     TInt iCurrentPointer;    

   212     

   213     };

   214     

   215 } // GestureHelper

   216 

   217 #endif // _GESTUREHELPERIMPL_H_