/*

* Copyright (c) 2010 Nokia Corporation and/or its subsidiary(-ies).

* All rights reserved.

*

* This program is free software: you can redistribute it and/or modify

* it under the terms of the GNU Lesser General Public License as published by

* the Free Software Foundation, version 2.1 of the License.

* 

* This program is distributed in the hope that it will be useful,

* but WITHOUT ANY WARRANTY; without even the implied warranty of

* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the

* GNU Lesser General Public License for more details.

*

* You should have received a copy of the GNU Lesser General Public License

* along with this program.  If not, 

* see "http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html/".

*

* Description:

*

*/

#ifndef QSTMGESTURELISTENER_IF_H_

#define QSTMGESTURELISTENER_IF_H_

#include "qstmgesturelistener_if.h"

#include "qstmgesture_if.h"

namespace qstmUiEventEngine

{

    class QStm_UiEventIf ;

}

namespace qstmGesture

{

// Forward declarations

class QStm_GestureRecogniserIf ;

/*!

 *  QStm_GestureRecogniserIf defines the methods for the gesture recognisers

 *  to be added to the gesture engine.

 *  TODO: add rule based settings to position the gesture recognisers to the list.

 *  The gesture recogniser order rules would be defined how?

 *  - defining the order inside the application

 *  - defining the order in some configuration file (maybe not)

 *

 *  This requires:

 *  - the gesture recognisers need to have an ID

 *  - a type can also be defined if the rules can be set based on types.

 *

 *  The gesture recognisers are arranged in a list so that the correct gesture recogniser

 *  gets the opportunity to detect the gesture in time.  An axample of a set of gesture recognisers

 *  could be e.g.

 *

 *  |---------------------------------------------|

 *  |  scrolling stop by tap -gesture recogniser  | A is enabled only when needed, when enabled must precede all others

 *  |                                             |   (note that locking partly can be used to achieve the same)

 *  |---------------------------------------------|

 *  | location specific: zoom + button tap gesture| B these must detect the location first

 *  |---------------------------------------------|

 *  | location specific: zoom - button tap gesture| B these must detect the location first

 *  |---------------------------------------------|

 *  | location specific: edge scroll gesture      | B these must detect the location first

 *  |---------------------------------------------|

 *  | pinch zoom gesture                          |   standard gesture, but application wide (spans windows)

 *  |                                             | C another requirement: disable all but me/restore state

 *  |                                             |   so that other gestures will not meddle in while pinching

 *  |---------------------------------------------|

 *  | hover gesture                               | C standard gesture, needs to detect the EMove speed

 *  |---------------------------------------------|

 *  | pan gesture                                 | C standard gesture, but must be after hover

 *  |---------------------------------------------|

 *  | tap/doubletap gesture                       | C standard gesture, order not that important, since

 *  |                                             |   needs just to see certain events in history: touch/release

 *  |---------------------------------------------|

 *

 *  The order of gesture recognisers determine how the system behaves, so there must be an easy way

 *  to define the order.  The order could be defined either by specifying the IDs or just their types, if then the

 *  order is not that important.  TODO to study whether it would be a good idea to implement this so that

 *  there are separate lists for the three different classes of gesture recognisers A, B and C; this might

 *  make the implementation simpler.

 */

class QStm_GestureEngineIf

{

public:

	QStm_GestureEngineIf() {}

    /*!

     *  add gesture to the end of the list of gestures

     */

    virtual bool addGesture(const QStm_GestureRecogniserIf* newGesture) = 0 ;

    /*!

     * inset a gesture to specific position

     */

    virtual bool insertGesture(const QStm_GestureRecogniserIf* newGesture, int position) = 0 ;

    virtual int findGesture(const QStm_GestureRecogniserIf* newGesture, int startPos = 0) const = 0;

    virtual int findGestureReverse(const QStm_GestureRecogniserIf* gesture, int astartPos) const = 0;

    virtual int findGesture(QStm_GestureUid uid, int startPos = 0) const = 0;

    virtual int findGestureReverse(QStm_GestureUid uid, int startPos) const = 0;

    virtual int gestureCount() const = 0;

    virtual QStm_GestureRecogniserIf* gestureAt(int idx) = 0;

    /*!

     * remove a gesture from the list

     */

    virtual bool removeGesture(const QStm_GestureRecogniserIf* oldGesture) = 0 ;

    /*!

     * get the number of non-empty event streams.

     * Event streams correspond UI events generated by one touch pointer (=finger).

     * The low level state machine handles the necessary filtering etc.

     * so that it is safe to remove the event stream after UI Release event has been processed.

     */

    virtual int activeStreamCount() const = 0 ;

    /*!

     * get the UI events of stream X

     * \param indexOfActiveStream defines which active stream is used.

     * Note that QStm_UiEventIf contains all the events from down up to the current event.

     * Assumption: the UI events contain the target "window handle", i.e.

     * the gesture recognition needs to be aware of all possible windows of the application.

     */

    virtual const qstmUiEventEngine::QStm_UiEventIf* getUiEvents(int indexOfActiveStream) const = 0 ;

    /*!

     * Enable/disable logging

     */

    virtual void enableLogging(bool aLoggingEnabled) = 0 ;

};

/*!

 * Enumerated values for the gesture recogniser

 */

enum QStm_GestureRecognitionState

{

    EGestureActive,     /*! < gesture recognised and gesture notification sent */

    ELockToThisGesture, /*! < gesture recognised, and only this recogniser called until release/this returns something else */

    ENotMyGesture       /*! < not this gesture, try the next one in the list  */

};

/*!

 * The types of gesture recognisers. TODO to implement rule based gesture engine

 * where the recognisers can be added in any order, and the rules define the order of them.

 * The rules may define

 */

enum QStm_GestureRecogniserType

{

    ECriticalGestureRecogniser,           /*! < This kind of gestures should be at the beginning of the list */

    ELocationSpecificGestureRecogniser,   /*! < This kind of gestures should be at the next in the list */

    EGenericGestureRecogniser             /*! < This kind of gestures should be at the next in the list */

};

/*!

 * QStm_GestureRecogniserIf defines the interface needed to be implemented by every gesture recognition element.

 * The gesture recogniser gets the UI events and needs to determine whether they define the expected gesture.

 *

 */

class QStm_GestureRecogniserIf

{

public:

	QStm_GestureRecogniserIf() {}

    /*!

     *  Virtual destuructor.

     */

    virtual ~QStm_GestureRecogniserIf() {}

    /*!

     * Process the UI event.

     * \param numOfActiveStreams : indicates how many pointers are currently active.

     * \param ge the gesture engine.  The Gesture recogniser uses this to get the current active events.

     *

     * \return EMaybeGesture    if gesture was not yet recognised but can be possible (e.g. after first touch everyone returns this)

     * \return EGestureActive   if gesture was recognised and a gesture notification was sent; this is then the active gesture

     * \return ENotMygesture    if gesture can not be this one, e.g. TAP gesture after receiving Move UI event.

     *

     * Note that a gesture may take control only if it sends out a gesture notification. (or is it so?)

     * Until no gesture recogniser has sent a gesture notification, all recognisers who have not returned

     * ENotMyGesture are eligible, based on the order they are in the list.

     *

     * The gesture engine may be either in dynamic gestures mode or fixed gestures mode.

     * In dynamic gestures mode each time an UI event is processed, engine will call each

     * gesture recogniser until one of the recognisers returns EGestureActive.

     *

     * In fixed gestures mode the index of the gesture recogniser first returning EGestureActive is stored

     * and the subsequent UI events are processed so that only that recogniser is allowed to send gesture

     * notification.  If it returns !=EGestureActive, it relinguishes the control.

     *

     */

    virtual QStm_GestureRecognitionState recognise(int numOfActiveStreams, QStm_GestureEngineIf* ge) = 0 ;

    /*!

     * In dynamic gestures mode the gesture engine will call release of the recogniser

     * who lost activation status because a preceding recogniser in the list took control.

     *

     * Note that the recogniser must then do whatever (if anything) is needed to cancel the gesture.

     */

    virtual void release(QStm_GestureEngineIf* ge) = 0  ;

    /*!

     * Enable or disable recogniser.  E.g. if two gestures are related so that

     * a gesture ending recogniser needs to be activated to stop a t5imer driven

     * behaviour it is useful to add the recogniser to the top of the list

     * and then disable it until needed.

     */

    virtual void enable(bool enableRecogniser) = 0 ;

    /*!

     * Get the state of the gesture recogniser, whether it is enabled or not

     * \return true, if the recogniser is enabled.

     */

    virtual bool isEnabled() = 0 ;

    /*!

     * Return the type of the gesture recogniser

     */

    virtual QStm_GestureUid gestureUid() const = 0;

    /*!

     * for testing purposes

     */

    virtual void enableLogging(bool loggingEnabled) = 0 ;

    virtual void setOwner(void* owner) = 0;

    virtual QStm_GestureRecognitionState state() = 0;

};

class QStm_GestureRecogniser : public QObject, public QStm_GestureRecogniserIf

{

public:

    virtual ~QStm_GestureRecogniser()

    {

    }

    /*!

     * MGestureRecogniserIf methods; partial implementation

     */

    virtual void enable(bool enabled)

    {

        m_gestureEnabled = enabled ;

    }

    virtual bool isEnabled()

    {

        return m_gestureEnabled ;

    }

    virtual void enableLogging(bool loggingOn)

    {

        m_loggingenabled = loggingOn;

    }

    virtual void setOwner(void* owner)

    {

        m_powner = owner;

    }

    virtual QStm_GestureRecognitionState state()

    {

        return m_state;

    }

protected:

    QStm_GestureRecogniser(QStm_GestureListenerIf* listener) : QStm_GestureRecogniserIf(),

                           m_powner(listener->getOwner()), 

                           m_listener(listener), 

                           m_gestureEnabled(false), 

                           m_loggingenabled(false),

                           m_state(ENotMyGesture)

    {

    }

protected:

    void*                    m_powner ; // The owning control for this gesture

    QStm_GestureListenerIf*  m_listener ;

    bool                     m_gestureEnabled ;

    bool                     m_loggingenabled ;

    QStm_GestureRecognitionState m_state;

};

} // namespace

#endif /* QSTMGESTURELISTENER_IF_H_ */