mmuifw_plat/gesturehelper_api/inc/gestureobserver.h
changeset 0 e83bab7cf002
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/mmuifw_plat/gesturehelper_api/inc/gestureobserver.h	Thu Dec 17 08:56:02 2009 +0200
@@ -0,0 +1,244 @@
+/*
+* 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_