1 /*

     2 * Copyright (c) 2008-2008 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 class

    15 *

    16 */

    17 

    18 #ifndef _GESTURE_H_

    19 #define _GESTURE_H_

    20 

    21 #include <e32base.h>

    22 

    23 #include "gestureobserver.h"

    24 #include "gesturerecogniser.h"

    25 #include "pointarray.h"

    26 

    27 namespace GestureHelper

    28 {

    29 

    30 /**  

    31  * TGesture represents the gesture that the user has made.

    32  * Implements MGestureEvent interface to allow clients to 

    33  * inspect the gesture

    34  */

    35 NONSHARABLE_CLASS( CGesture ) : public CBase, public MGestureEvent

    36     {

    37 public:

    38     /** constructor */

    39      CGesture();

    40     /** destructor */

    41     ~CGesture();

    42     

    43     /** 

    44      * @return a new gesture that will have only the first point

    45      * of this gesture. Can be used to create gesture's a "start" event

    46      * after some other points have been received. 

    47      */ 

    48     CGesture* AsStartEventLC() const;

    49     

    50     /** 

    51      * Sets the gesture as empty. resets timers to receive points

    52      * immediately

    53      */

    54     void Reset();

    55     

    56     /** @return ETrue if the gesture has no points */

    57     TBool IsEmpty() const;

    58     

    59     /** @return ETrue if there are no points in the second array */

    60     TBool IsMultiTouch() const;

    61     

    62     /**

    63      * Add a point to the sequence of points that forms the gesture

    64      * Call Reset() just before adding the first point

    65      * @param aPoint the point to add

    66      * @return error code

    67      */

    68     TInt AddPoint( const TPoint& aPoint );

    69  

    70     /**

    71      * Add a point to the sequence of points that forms the gesture

    72      * Adds the point to the secondray pointer array.

    73      * Used to add second pointer movement in case of multi touch

    74      * Call Reset() just before adding the first point

    75      * @param aPoint the point to add

    76      * @return error code

    77      */

    78     TInt AddSecondaryPoint( const TPoint& aPoint );

    79     

    80     /** Set the visual of this gesture. Should be called when gesture starts */

    81     void SetVisual( CAlfVisual* aVisual );

    82     

    83     /** @return ETrue if the point is very near the holding point */

    84     TBool IsNearHoldingPoint( const TPoint& aPoint ) const;

    85     /** Set the latest point as the holding point */

    86     void SetHoldingPoint();

    87     /** @return ETrue if aPoint is the same as point added last */

    88     TBool IsLatestPoint( const TPoint& aPoint ) const;

    89     /** @return ETrue if aPoint is the same as point added last in the secondary array */

    90     TBool IsLatestSecondaryPoint( const TPoint& aPoint ) const;

    91     

    92     /** 

    93      * After call, Code(...) will return appropriate holding gesture code.

    94      */

    95     void StartHolding();

    96     /** 

    97      * After call, Code(...) will return a "hold released" gesture code when

    98      * the gesture is completed. Meanwhile, code will be drag.

    99      */

   100     void ContinueHolding(); 

   101     /** Set as single touch gesture started */

   102     void SetSingleTouchActive();

   103     /** Set as multitouch gesture started */

   104     void SetMultiTouchActive();    

   105 	/** Set as stylus released when there was only one stylus pressed */

   106     void SetSingleTouchReleased();

   107     /** Set as stylus released when there were two pointers, one pointer is still pressed down */

   108     void SetMultiTouchReleased();

   109     /** Set the single touch gesture as complete. Gesture is completed at pointer up */

   110     void SetSingleTouchComplete();

   111     /** Set the multitouch gesture as complete. Single touch still continues */

   112     void SetMultiTouchComplete();    

   113     /** After call, Code(...) will return a "cancelled" gesture code */

   114     void SetCancelled();

   115     

   116     /** force returning a code as double tap when gesture is complete */

   117     void SetDoubleTap();

   118     

   119     /** 

   120      * @return Whether the current gesture is a tap (and hence not a swipe)

   121      *         Does not consider holding or other state information (such as

   122      *         whether the gesture was just started or is dragging).  

   123      *         Results are based purely on the current stream of points.

   124      */ 

   125     TBool IsTap() const;

   126  

   127     /** 

   128      * Checks if the current points in primary and secondary pointer array results in

   129      * a pinch gesture. If yes updates the previous distance.

   130      * @return Whether the current gesture is a pinch

   131      *         Returns EFalse if multitouch is not active currently.  

   132      *         Results are based purely on the current stream of points.

   133      */ 

   134     TBool IsPinch();

   135     

   136     /** 

   137      * Reset all the events recieved in the current gesture.

   138      * Calls Reset() internally.

   139      * create a new points starting from the last point of the

   140      * earlier gesture

   141      * Used when the multitouch point is released to start the 

   142      * single touch operations.

   143      * @param aFirstPointer, Should reset to the first pointers last point or to the 2d pointers.

   144      *          false (2nd pointers last point) when multitouch is going on and user releases the first point and

   145      *          continues to hold the second point

   146      */ 

   147     void ResetToLastPoint(TBool aSetPointerZero,TBool aSetToZero); 

   148   

   149 // From MGestureEvent

   150     TGestureCode Code( TAxis aRelevantAxis ) const;

   151     TBool IsHolding() const;

   152     TPoint StartPos() const;

   153     TPoint CurrentPos() const; 

   154     TRealPoint Speed() const;

   155     TRealPoint SpeedPercent( const TRect& aEdges ) const;

   156     TPoint Distance() const; 

   157     CAlfVisual* Visual() const;

   158     TInt PinchPercent() const;

   159     TPoint PinchCentrePoint()const;

   160     

   161 private:

   162     /** @return elapsed time between the latest and previous points */

   163     inline TTimeIntervalMicroSeconds32 TimeFromPreviousPoint() const; 

   164     

   165     /** @return elapsed time between the latest and first points */

   166     inline TTimeIntervalMicroSeconds32 TimeFromStart() const; 

   167     

   168     /** @return ETrue if user has stopped moving the stylus before lifting it */

   169     inline TBool IsMovementStopped() const;

   170     

   171     /** @return aOffset'th last entry in the list of points */

   172     inline const TPointEntry& NthLastEntry( TInt aOffset ) const;

   173     

   174     /** @return previous point (may not be exactly the point before last) */

   175     inline const TPointEntry& PreviousEntry() const;

   176     

   177     /** @return position of point received just before the latest point */

   178     inline TPoint PreviousPos() const;

   179     

   180     /** @return the last point in the given pointer array */

   181     inline const TPointEntry LastPoint( const RArray< TPointEntry >& aPoints ) const;

   182     

   183     /** @return whether a slightly higher tolarence needs to be used for pinch or not*/

   184     inline TBool IsHighPinchTolerance() const;

   185     

   186 private: 

   187 

   188     /// sequence of points that make up the gesture. own.

   189     /// Single touch pointer variations.

   190     RArray< TPointEntry > iPoints;

   191 	

   192     /// sequence of points that make up the gesture. own.

   193     /// Second touch pointer variations.

   194     RArray< TPointEntry > iSecondaryPoints;

   195     

   196     /// index in iPoints of the point in which user started holding

   197     TInt iHoldingPointIndex;

   198 

   199     /// the different states that indicate whether user has made a holding gesture 

   200     enum THoldingState

   201         {

   202         ENotHolding = 0, // before holding activated (i.e., holding not activated)

   203         EHoldStarting,   // holding activated just now (lasts just one callback round)

   204         EHolding         // holding activated earlier 

   205         };

   206   

   207     /// state that indicates is user has held the pointer down in one position 

   208     /// for long time to indicate a holding gesture    

   209     THoldingState iHoldingState;

   210     

   211     /// Whether the gesture completion code will be forcefully overridden to be double tap,

   212     /// regardless of what the points are

   213     TBool iIsDoubleTap;

   214     

   215     /// If in the current gesture, there was a multi touch at any in between point.

   216     /// This is required, if after doing a multitouch, release one pointer and do some 

   217     /// operation with the other pointer still touched down. Though the new variations

   218     /// of pointer results in a tap, tap is not possible after a multitouch.

   219     TBool iIsMultiTouched;

   220         

   221     enum TCompletionState 

   222         {

   223         ENotActive = 0,

   224         ESingleTouchActive,

   225         EMultiTouchActive,

   226         ECancelled,

   227         EMultiTouchComplete,

   228         EMultiTouchReleased,

   229         ESingleTouchComplete,        

   230         ESingleTouchReleased       

   231         };

   232       

   233     /// gesture only becomes complete when user lifts the pointer

   234     TCompletionState iState;

   235 

   236     /// time when the stylus was lifted.

   237     TTime iCompletionTime;

   238     

   239     /// visual relevant to this gesture. null if not known.

   240     CAlfVisual* iVisual;

   241     

   242     /// The distance between the two points, at the time of last identified pinch gesture

   243     /// This will also be the start distance for next pinch. At start it will

   244     /// be the distance between touch down points

   245     TInt iPinchStartDistance;

   246 

   247     /// The distance between the two points, at the time of pinch identified

   248     TInt iPinchEndDistance;

   249     

   250     /// Pinch detcted, true for one cycle,untill a new point is recieved.

   251     TBool iPinchDetected;

   252  

   253     enum TZoomState 

   254         {

   255         ENoZoom = 0,

   256         EZoomOut,

   257         EZoomIn    

   258         };

   259   

   260     /// gesture only becomes complete when user lifts the pointer

   261     TZoomState iZoomState;

   262     

   263     };

   264 

   265 } // namespace GestureHelper

   266 

   267 #endif // _GESTURE_H_