diff -r 4ea6f81c838a -r 0e9bb658ef58 mmuifw_plat/gesturehelper_api/inc/gesturehelper.h --- /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 +#include + +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_