--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/mmuifw_plat/gesturehelper_api/inc/gesturehelper.h Wed Sep 01 12:23:18 2010 +0100
@@ -0,0 +1,158 @@
+/*
+* Copyright (c) 2007 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 _GESTUREHELPER_H_
+#define _GESTUREHELPER_H_
+
+#include <e32base.h>
+#include <gestureobserver.h>
+
+class CAlfEnv;
+class CAlfDisplay;
+class TAlfEvent;
+struct TPointerEvent;
+
+namespace GestureHelper
+{
+
+class CGestureHelperImpl;
+
+/**
+ * Gesture helper provides functionality to convert a stream of pointer events
+ * into a logical gesture, and to assist clients in calculation of gesture
+ * speed and distance.
+ *
+ * Interfaces
+ * - CGestureHelper is a parser of pointer events. Recognises gestures from
+ * a sequence of pointer events, and converts them to gesture commands.
+ * For documentation of callbacks, see @ref MGestureObserver.
+ * - MGestureObserver allows clients to get notified of gestures
+ * - MGestureEvent represents the gesture (event)
+ */
+NONSHARABLE_CLASS( CGestureHelper ) : public CBase
+ {
+public:
+ /**
+ * The helper is expected to be a member variable, hence NewLC is not provided
+ */
+ IMPORT_C static CGestureHelper* NewL( MGestureObserver& aObserver );
+
+ /** Destructor */
+ IMPORT_C ~CGestureHelper();
+
+ /**
+ * Specify whether the helper will send hold events. By default, holding is enabled.
+ * "Hold" means user has held stylus/finger on the same position for a longer duration.
+ *
+ * Clients that require holding to be treated with no special meaning should disable
+ * holding to simplify their event handling.
+ * For example, assume the client uses swipe left/right to control navigation, and
+ * holding is enabled. If user holds, the client gets hold left/right
+ * event, and no swipe event. If user now drags left or right while still pressing
+ * stylus down, the client will not get a swipe event (since it already received a hold
+ * event). Upon release event, the client no reliable way of knowing whether the
+ * user swiped left/right or cancelled the swipe. This problem is removed if the
+ * client simply disables holding. In the above scenario while holding disabled,
+ * the client would get only swipe events (and released event).
+ * (Swipe can be cancelled by dragging towards, but not beyond, the starting position.)
+ */
+ IMPORT_C void SetHoldingEnabled( TBool aEnabled );
+
+ /**
+ * @return whether sending hold events is currently enabled
+ * ("Hold" means user has held stylus/finger on the same position for a longer duration.)
+ */
+ IMPORT_C TBool IsHoldingEnabled() const;
+
+ /**
+ * Enables/disables double tap support. Double tap is disabled by default.
+ * When double tap is disabled, gesture helper emits tap events immediately when
+ * user lifts stylus/finger.
+ * When double tap is enabled, tap events are emitted after the double tap timeout passes.
+ * The timeout is the maximum time within which the second tap will be treated
+ * as a double tap. That is, there is a delay (sluggishness) before client receives
+ * the tap event when double tap is enabled.
+ * tap + timeout => tap event emitted after timeout
+ * tap + tap before timeout => double tap event emitted immediately after the second tap
+ * tap + swipe => tap + swipe events
+ * (tap + timeout + tap + timeout => two tap events)
+ */
+ IMPORT_C void SetDoubleTapEnabled( TBool aEnabled );
+
+ /**
+ * @return whether double tap is currently enabled. See SetDoubleTapEnabled
+ */
+ IMPORT_C TBool IsDoubleTapEnabled() const;
+
+ /**
+ * Initialise pointer capture for Alfred
+ * This means that helper will receive drag events and pointer events that
+ * go outside the original visual area
+ */
+ IMPORT_C void InitAlfredPointerCaptureL( CAlfEnv& aEnv, CAlfDisplay& aDisplay,
+ TInt aFreeControlGroupId );
+
+ /**
+ * Give a pointer event to the helper, to form a part of a gesture
+ * For AVKON-based client, this interface is the only option.
+ * Alfred-based client should use OfferEventL, as it allows gesture events to
+ * provider the visual on which the pointer event started.
+ * @param aEvent pointer event
+ * @return whether event was consumed or not
+ * EFalse the event is not a pointer events and if pointer up/drag
+ * event received without pointer down event
+ * ETrue in all the other cases of pointer event
+ */
+ IMPORT_C TBool HandlePointerEventL( const TPointerEvent& aEvent );
+
+ /**
+ * Offer an Alf event. See HandlePointerEventL.
+ * @return whether event was consumed or not
+ * EFalse the event is not a pointer events and if pointer up/drag
+ * event received without pointer down event
+ * ETrue in all the other cases of pointer event
+ */
+ IMPORT_C TBool OfferEventL( const TAlfEvent& aEvent );
+
+ /**
+ * Cancel ongoing recognision. Purges all pointer events given earlier, and
+ * starts afresh. It is not necessary to call Cancel before deleting the object.
+ */
+ IMPORT_C void Cancel();
+
+ /**
+ * Adds a new observer to gesture helper events. Replaces any earlier observer.
+ * This is to allow sharing of gesture helper between different controls.
+ * The control which is currently shown (control that is on top of the roster)
+ * will add as an observer and the earlier control which is now not in focus will
+ * automatically be removed as an observer.
+ *
+ * This API should be used only when the gesture helper is shared between more
+ * than one control. Gesture helper can be shared only among the controls within the same roster.
+ * Only required for alf based applications, not required for CCoeControl.
+ *
+ */
+ IMPORT_C void AddObserver(MGestureObserver* aObserver);
+
+private:
+ /// interface implementation
+ CGestureHelperImpl* iImpl;
+ };
+
+} // namespace GestureHelper
+
+#endif // _GESTUREHELPER_H_