/*

* 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 helper interface

*

*/

#ifndef _GESTUREOBSERVER_H_

#define _GESTUREOBSERVER_H_

#include <e32std.h>

class CAlfControl;

class CAlfVisual;

namespace GestureHelper

{

/// flag that indicates gesture code is a holding code

/// clients should use MGestureEvent::IsHolding

const TInt EFlagHold       = 0x10000000;

enum TGestureCode

    {

    // states

    EGestureStart          			= 0x00000001, // gesture just started (user pressed stylus down)

    EGestureDrag           			= 0x00000002, // user moved stylus (may be holding or not holding)

    EGestureReleased      		  = 0x00000003, // user lifted stylus while user was holding

    // gestures

    EGestureUnknown             = 0x00000005, // gesture was not recognised

    // these codes are sent when user lifts stylus (if holding not started)

    EGestureTap                 = 0x00000006,

    EGestureDoubleTap           = 0x00000007, // only if double tap is enabled 

                                         // (via CGestureHelper::SetDoubleTapEnabled or

                                         // CGestureControl::SetDoubleTapEnabled)

    EGestureSwipeLeft           = 0x00000008,

    EGestureSwipeRight          = 0x00000009,

    EGestureSwipeUp             = 0x0000000A,

    EGestureSwipeDown           = 0x0000000B,

    // gestures related to advanced pointer events. These codes are sent if the platform supports advanced pointer events.

    // states

    EGestureMultiTouchStart     = 0x0000000C, // multitouch gesture just started (user touched 2nd finger down)

    EGestureMultiTouchReleased  = 0x0000000D, // user released 2nd touch point while still holding the first touch point

	  // gestures

    EGesturePinch         		  = 0x0000000E, // This event is sent when the pinch is recognised for 

    																		 // the first time or when the pinch distance is changing.

    // these codes are sent when user initiates holding by keeping stylus in

    // same place for a longer duration

    EGestureHoldLeft       = EGestureSwipeLeft  | EFlagHold,

    EGestureHoldRight      = EGestureSwipeRight | EFlagHold,

    EGestureHoldUp         = EGestureSwipeUp    | EFlagHold,

    EGestureHoldDown       = EGestureSwipeDown  | EFlagHold

    };

/**

 * Point of float accuracy

 */

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;

    };

/**

 * a gesture event

 */

class MGestureEvent

    {

public:

    /** X and Y axes, or both */

    enum TAxis

        {

        EAxisBoth,

        EAxisHorizontal,

        EAxisVertical

        };

public:

    /**

     * @param aRelevantAxis indicates whether only x, y or both coordinates 

     *        should be considered when determining the code. For example,

     *        if client specifies EAxisVertical as relevant axis, a swipe

     *        to left and slightly up would result in an "swipe up" code,

     *        and not "swipe left" code. If client specifies EAxisHorizontal

     *        or EAxisBoth, "swipe left" code is returned.

     * @return gesture code

     */

    virtual TGestureCode Code( TAxis aRelevantAxis ) const = 0;

    /** 

     * @return ETrue if user has activated holding 

     *         (by keeping stylus in the same position for longer time)

     *         EFalse if holding has not been activated

     */

    virtual TBool IsHolding() const = 0;

    /** 

     * @return position where gesture started, i.e., where stulys 

     * was pressed down 

     */

    virtual TPoint StartPos() const = 0;

    /** 

     * @return current position of the stylus

     */

    virtual TPoint CurrentPos() const = 0; 

    /** 

     * @return speed of a swipe. unit is pixels per second.

     */

    virtual TRealPoint Speed() const = 0;

    /**

     * Abstracts the algorithm to calculate speed during swipe and hold. This

     * algorithm (currently) assumes that max speed is achieved at the edges of an

     * area.

     * @param aEdges represents the coordinates of the rectange on which speed is 

     *               calculated. Speed will reach maximum if stylus is on the edge 

     *               or beyond the rect. In practise, the value should match the

     *               area of the layout that contains the scrollable visuals.

     *               For example, if the control area is the whole screen, the

     *               rect should be the screen rect.

     * @returns the speed as a percentage between -100% and 100%

     */

    virtual TRealPoint SpeedPercent( const TRect& aEdges ) const = 0;

    /** 

     * @return Length of gesture from starting position

     *         (start pos - current pos)

     */

    virtual TPoint Distance() const = 0; 

    /**

     * @return visual on which the gesture started

     *         NULL if not known (e.g., AVKON-based client 

     */

    virtual CAlfVisual* Visual() const = 0;

    /**

     * Pinch distance

     *

     * Used only for pinch. Returns 0 for other gestures. 

     *

     * @return The ratio of pinch end distance to pinch start distance * 100

     * 				PinchPercent above 100 for zooming out and below hundred for zooming in

     */

    virtual TInt PinchPercent() const = 0;    

    /**

     * Centre point of the two touch points

     *

     * Used only for pinch. Returns TPoint(0,0) for other gestures. 

     *

     * @return the centre point calculated using teh two touch down points

     * This point will remian the same for one multitouch gesture start to end.

     * This doesnt vary as the two points move away or closer.

     */

    virtual TPoint PinchCentrePoint() const = 0;   

    };

/** 

 * Observer that will be notified when user makes gestures

 */

class MGestureObserver

    {

public:

    /**

     * Handle the gesture event

     * @param aEvent event describing the gesture 

     */

    virtual void HandleGestureL( const MGestureEvent& aEvent ) = 0;

    };

/** 

 * static class for finding a visual from a visual tree

 */

class HitTest

    {

public:

    /** 

     * @return the leaf-most visual is under aPos, or NULL if not found

     */

    IMPORT_C static CAlfVisual* VisualByCoordinates( const CAlfControl& aControl, 

        const TPoint& aPos );

    };

// ----------------------------------------------------------------------------

// Default constructor for real point

// ----------------------------------------------------------------------------

//

inline TRealPoint::TRealPoint()

        : iX( 0 ), iY( 0 )

    {    

    }

// ----------------------------------------------------------------------------

// Copy constructor for real point

// ----------------------------------------------------------------------------

//

inline TRealPoint::TRealPoint( const TRealPoint& aPoint )

        : iX( aPoint.iX ), iY( aPoint.iY )

    {    

    }

// ----------------------------------------------------------------------------

// Copy constructor for real point

// ----------------------------------------------------------------------------

//

inline TRealPoint::TRealPoint( TReal aX, TReal aY )

        : iX( aX ), iY( aY )

    {    

    }

// ----------------------------------------------------------------------------

// Default constructor for real point

// ----------------------------------------------------------------------------

//

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

    {    

    return iX == aPoint.iX && iY == aPoint.iY;

    }

} // namespace GestureHelper

#endif // _GESTUREOBSERVER_H_