/*

* 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_