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 

    19 #ifndef _XNGESTURE_H_

    20 #define _XNGESTURE_H_

    21 

    22 // System includes

    23 #include <e32base.h>

    24 

    25 // User includes

    26 #include "xnpointarray.h"

    27 #include "xngesturerecogniser.h"

    28 

    29 // Namespace declaration

    30 

    31 /**

    32  * XnGestureHelper namespace

    33  * Used for the whole gesture family - Gesture recognizer, gesture helper, 

    34  * Point array

    35  */

    36 namespace XnGestureHelper

    37     {

    38     

    39     /**

    40      * Struct for a point in floating-point represanation 

    41      */

    42     NONSHARABLE_STRUCT( TRealPoint )

    43         {

    44         inline TRealPoint();

    45         inline TRealPoint( const TRealPoint& aPoint );

    46         inline TRealPoint( TReal aX, TReal aY );

    47         inline TBool operator==( const TRealPoint& aPoint ) const;

    48 

    49         TReal32 iX;

    50         TReal32 iY;

    51         };

    52     

    53     // Class declaration

    54 

    55     /**  

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

    57      *  Implements MGestureEvent interface to allow clients to 

    58      *  inspect the gesture

    59      *  

    60      *  @ingroup group_xnlayoutengine 

    61      */

    62     NONSHARABLE_CLASS( CXnGesture ) : public CBase

    63         {

    64     public:

    65         

    66         /** 

    67          * X and Y axes, or both 

    68          */

    69         enum TAxis

    70             {

    71             EAxisBoth, 

    72             EAxisHorizontal, 

    73             EAxisVertical

    74             };

    75 

    76     public:

    77         

    78         /** destructor */

    79         ~CXnGesture();

    80 

    81         /** 

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

    83          * immediately

    84          */

    85         void Reset();

    86 

    87         /** 

    88          * Check the gesture if it is empty

    89          * 

    90          * @return ETrue if the gesture has no points 

    91          */

    92         TBool IsEmpty() const;

    93 

    94         /**

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

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

    97          * 

    98          * @param aPoint the point to add

    99          * @return error code

   100          */

   101         TInt AddPoint( const TPoint& aPoint );

   102 

   103         /** 

   104          * Checks if the point it is close to holding point

   105          * 

   106          * @param aPoint Point to be examined

   107          * @return ETrue if the point is very near the holding point

   108          */

   109         TBool IsNearHoldingPoint( const TPoint& aPoint ) const;

   110 

   111         /** 

   112          * Set the latest point as the holding point

   113          */

   114         void SetHoldingPoint();

   115 

   116         /** 

   117          * Checks if the examined point is at the last point's position

   118          * 

   119          * @param aPoint Point to be examined

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

   121          */

   122         TBool IsLatestPoint( const TPoint& aPoint ) const;

   123 

   124         /** 

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

   126          */

   127         void StartHolding();

   128 

   129         /** 

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

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

   132          */

   133         void ContinueHolding();

   134 

   135         /** 

   136          * Set as stylus released 

   137          */

   138         void SetReleased();

   139 

   140         /** 

   141          * Set the gesture as complete. Gesture is completed at pointer up 

   142          */

   143         void SetComplete();

   144 

   145         /** 

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

   147          */

   148         void SetCancelled();

   149 

   150         /** 

   151          * Checks if the gesture is a tap

   152          * 

   153          * @return Whether the current gesture is a tap 

   154          *         (and hence not a swipe). Does not consider holding or 

   155          *         other state information (such as whether the gesture was 

   156          *         just started or is dragging). Results are based purely on 

   157          *         the current stream of points.

   158          */

   159         TBool IsTap() const;

   160 

   161         /**

   162          * From MGestureEvent

   163          * Checks and return current gesture status at desired axis

   164          * 

   165          * @param aRelevantAxis Axis to be examined

   166          * @return Gesture status

   167          */

   168         TXnGestureCode Code( TAxis aRelevantAxis ) const;

   169 

   170         /**

   171          * From MGestureEvent

   172          * Checks and returns holding status

   173          * 

   174          * @return Return holding

   175          */

   176         TBool IsHolding() const;

   177 

   178         /**

   179          * From MGestureEvent

   180          * Returns first position form iPoints

   181          * 

   182          * @return Returns first point

   183          */

   184         TPoint StartPos() const;

   185 

   186         /**

   187          * From MGestureEvent

   188          * Returns current (last) position from iPoints

   189          * 

   190          * @return Returns last point

   191          */

   192         TPoint CurrentPos() const;

   193 

   194         /**

   195          * From MGestureEvent

   196          * Returns speed of X, Y movement 

   197          * 

   198          * @return Speed in X, Y axis

   199          */

   200         TRealPoint Speed() const;

   201 

   202         /**

   203          * From MGestureEvent

   204          * Scales the speed

   205          * 

   206          * @return Scaled speed

   207          */

   208         TRealPoint SpeedPercent( const TRect& aEdges ) const;

   209 

   210         /**

   211          * From MGestureEvent

   212          * Cheks and returns distance between start and current position

   213          * 

   214          * @return Distance between two points

   215          */

   216         TPoint Distance() const;

   217 

   218     private:

   219         

   220         /** Information of an earlier gesture */

   221         struct TGestureRecord

   222             {

   223             enum TType

   224                 {

   225                 ETypeOther, 

   226                 ETypeTap, 

   227                 ETypeDoubleTap

   228                 };

   229 

   230             TGestureRecord();

   231             TGestureRecord( TType aType, TTime aCompletionTime, TPoint aPos );

   232 

   233             /** type of the gesture */

   234             TType iType;

   235             /** completion time fo the gesture */

   236             TTime iCompletionTime;

   237             /** point of completion */

   238             TPoint iPos;

   239             };

   240 

   241         /**

   242          * Checks and returns gesture

   243          * 

   244          * @param aRelevantAxis See @ref MGestureEvent::Code

   245          * @return gesture code by analysing the sequence of points

   246          */

   247         TXnGestureCode CodeFromPoints( TAxis aRelevantAxis ) const;

   248 

   249         /** 

   250          * Returns elapsed time

   251          *

   252          * @return elapsed time between the latest and previous points 

   253          */

   254         inline TTimeIntervalMicroSeconds32 TimeFromPreviousPoint() const;

   255 

   256         /** 

   257          * Checks whether the movement has stopped

   258          *

   259          * @return ETrue if user has stopped moving the stylus before lifting 

   260          *         it 

   261          */

   262         inline TBool IsMovementStopped() const;

   263 

   264         /** 

   265          * Offset of the last entry

   266          *  

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

   268          */

   269         inline const TXnPointEntry& NthLastEntry( TInt aOffset ) const;

   270 

   271         /** 

   272          * Calles NthLastEntry for previous point

   273          * 

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

   275          */

   276         inline const TXnPointEntry& PreviousEntry() const;

   277 

   278         /** 

   279          * Returns the point before the last one

   280          * 

   281          * @return position of point received just before the latest point 

   282          */

   283         inline TPoint PreviousPos() const;

   284 

   285         /** 

   286          * Return if the tap was a double tap

   287          * 

   288          * @return ETrue if tap should be a double tap 

   289          */

   290         TBool IsTapDoubleTap() const;

   291 

   292         /** 

   293          * Returns current gesture type

   294          * 

   295          * @return the type of the current gesture 

   296          */

   297         TGestureRecord::TType Type() const;

   298 

   299     private:

   300         // Enumerators for holding and completion state

   301         

   302         /**

   303          * the different states that indicate whether user has made a holding 

   304          * gesture

   305          */

   306         enum THoldingState

   307             {

   308             /** before holding activated (i.e., holding not activated) */

   309             ENotHolding = 0,

   310             /** holding activated just now (lasts just one callback round) */

   311             EHoldStarting,

   312             /** holding activated earlier */

   313             EHolding

   314             };

   315 

   316         /**

   317          * Completion states

   318          */                 

   319         enum TCompletionState

   320             {

   321             // Note: implementation assumes this order of enums

   322             ENotComplete = 0, 

   323             ECancelled, 

   324             EComplete, 

   325             EReleased

   326             };

   327     

   328     private:

   329         // Members

   330         

   331         /** 

   332          * sequence of points that make up the gesture, owned. 

   333          */

   334         RArray< TXnPointEntry > iPoints;

   335         

   336         /** 

   337          * index in iPoints of the point in which user started holding 

   338          */

   339         TInt iHoldingPointIndex;     

   340         

   341         /**

   342          * state that indicates is user has held the pointer down in one 

   343          * position for long time to indicate a holding gesture 

   344          */

   345         THoldingState iHoldingState;

   346         

   347         /** 

   348          * gesture only becomes complete when user lifts the pointer 

   349          */ 

   350         TCompletionState iState;

   351         

   352         /** 

   353          * time when the stylus was lifted. 

   354          */

   355         TTime iCompletionTime;

   356         

   357         /** 

   358          * previous gesture information for double tap

   359          */

   360         TGestureRecord iPreviousGesture;

   361         };

   362     } // namespace XnGestureHelper

   363 

   364 // Inline functions

   365 #include "xngesture.inl"

   366 

   367 #endif // _XNGESTURE_H_