/*

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

*

*/

#ifndef _XNGESTURE_H_

#define _XNGESTURE_H_

// System includes

#include <e32base.h>

// User includes

#include "xnpointarray.h"

#include "xngesturerecogniser.h"

// Namespace declaration

/**

 * XnGestureHelper namespace

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

 * Point array

 */

namespace XnGestureHelper

    {

    /**

     * Struct for a point in floating-point represanation 

     */

    NONSHARABLE_STRUCT( TRealPoint )

        {

        inline TRealPoint();

        inline TRealPoint( const TRealPoint& aPoint );

        inline TRealPoint( TReal aX, TReal aY );

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

        TReal32 iX;

        TReal32 iY;

        };

    // Class declaration

    /**  

     *  TGesture represents the gesture that the user has made.

     *  Implements MGestureEvent interface to allow clients to 

     *  inspect the gesture

     *  

     *  @ingroup group_xnlayoutengine 

     */

    NONSHARABLE_CLASS( CXnGesture ) : public CBase

        {

    public:

        /** 

         * X and Y axes, or both 

         */

        enum TAxis

            {

            EAxisBoth, 

            EAxisHorizontal, 

            EAxisVertical

            };

    public:

        /** destructor */

        ~CXnGesture();

        /** 

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

         * immediately

         */

        void Reset();

        /** 

         * Check the gesture if it is empty

         * 

         * @return ETrue if the gesture has no points 

         */

        TBool IsEmpty() const;

        /**

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

         * Call Reset() just before adding the first point

         * 

         * @param aPoint the point to add

         * @return error code

         */

        TInt AddPoint( const TPoint& aPoint );

        /** 

         * Checks if the point it is close to holding point

         * 

         * @param aPoint Point to be examined

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

         */

        TBool IsNearHoldingPoint( const TPoint& aPoint ) const;

        /** 

         * Set the latest point as the holding point

         */

        void SetHoldingPoint();

        /** 

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

         * 

         * @param aPoint Point to be examined

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

         */

        TBool IsLatestPoint( const TPoint& aPoint ) const;

        /** 

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

         */

        void StartHolding();

        /** 

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

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

         */

        void ContinueHolding();

        /** 

         * Set as stylus released 

         */

        void SetReleased();

        /** 

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

         */

        void SetComplete();

        /** 

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

         */

        void SetCancelled();

        /** 

         * Checks if the gesture is a tap

         * 

         * @return Whether the current gesture is a tap 

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

         *         other state information (such as whether the gesture was 

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

         *         the current stream of points.

         */

        TBool IsTap() const;

        /**

         * From MGestureEvent

         * Checks and return current gesture status at desired axis

         * 

         * @param aRelevantAxis Axis to be examined

         * @return Gesture status

         */

        TXnGestureCode Code( TAxis aRelevantAxis ) const;

        /**

         * From MGestureEvent

         * Checks and returns holding status

         * 

         * @return Return holding

         */

        TBool IsHolding() const;

        /**

         * From MGestureEvent

         * Returns first position form iPoints

         * 

         * @return Returns first point

         */

        TPoint StartPos() const;

        /**

         * From MGestureEvent

         * Returns current (last) position from iPoints

         * 

         * @return Returns last point

         */

        TPoint CurrentPos() const;

        /**

         * From MGestureEvent

         * Returns speed of X, Y movement 

         * 

         * @return Speed in X, Y axis

         */

        TRealPoint Speed() const;

        /**

         * From MGestureEvent

         * Scales the speed

         * 

         * @return Scaled speed

         */

        TRealPoint SpeedPercent( const TRect& aEdges ) const;

        /**

         * From MGestureEvent

         * Cheks and returns distance between start and current position

         * 

         * @return Distance between two points

         */

        TPoint Distance() const;

    private:

        /** Information of an earlier gesture */

        struct TGestureRecord

            {

            enum TType

                {

                ETypeOther, 

                ETypeTap, 

                ETypeDoubleTap

                };

            TGestureRecord();

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

            /** type of the gesture */

            TType iType;

            /** completion time fo the gesture */

            TTime iCompletionTime;

            /** point of completion */

            TPoint iPos;

            };

        /**

         * Checks and returns gesture

         * 

         * @param aRelevantAxis See @ref MGestureEvent::Code

         * @return gesture code by analysing the sequence of points

         */

        TXnGestureCode CodeFromPoints( TAxis aRelevantAxis ) const;

        /** 

         * Returns elapsed time

         *

         * @return elapsed time between the latest and previous points 

         */

        inline TTimeIntervalMicroSeconds32 TimeFromPreviousPoint() const;

        /** 

         * Checks whether the movement has stopped

         *

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

         *         it 

         */

        inline TBool IsMovementStopped() const;

        /** 

         * Offset of the last entry

         *  

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

         */

        inline const TXnPointEntry& NthLastEntry( TInt aOffset ) const;

        /** 

         * Calles NthLastEntry for previous point

         * 

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

         */

        inline const TXnPointEntry& PreviousEntry() const;

        /** 

         * Returns the point before the last one

         * 

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

         */

        inline TPoint PreviousPos() const;

        /** 

         * Return if the tap was a double tap

         * 

         * @return ETrue if tap should be a double tap 

         */

        TBool IsTapDoubleTap() const;

        /** 

         * Returns current gesture type

         * 

         * @return the type of the current gesture 

         */

        TGestureRecord::TType Type() const;

    private:

        // Enumerators for holding and completion state

        /**

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

         * gesture

         */

        enum THoldingState

            {

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

            ENotHolding = 0,

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

            EHoldStarting,

            /** holding activated earlier */

            EHolding

            };

        /**

         * Completion states

         */                 

        enum TCompletionState

            {

            // Note: implementation assumes this order of enums

            ENotComplete = 0, 

            ECancelled, 

            EComplete, 

            EReleased

            };

    private:

        // Members

        /** 

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

         */

        RArray< TXnPointEntry > iPoints;

        /** 

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

         */

        TInt iHoldingPointIndex;     

        /**

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

         * position for long time to indicate a holding gesture 

         */

        THoldingState iHoldingState;

        /** 

         * gesture only becomes complete when user lifts the pointer 

         */ 

        TCompletionState iState;

        /** 

         * time when the stylus was lifted. 

         */

        TTime iCompletionTime;

        /** 

         * previous gesture information for double tap

         */

        TGestureRecord iPreviousGesture;

        };

    } // namespace XnGestureHelper

// Inline functions

#include "xngesture.inl"

#endif // _XNGESTURE_H_