/*
* 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 QSTMUIEVENT_IF_H_
#define QSTMUIEVENT_IF_H_
#include <QtCore>
#include "qstmgesturedefs.h"
namespace qstmUiEventEngine
{
static const int KMaxNumberOfPointers(5) ; // How many of these should we have in multi-touch case
enum QStm_UiEventCode
{
ETouch = 0x01,
EHold = 0x02,
EMove = 0x03,
ERelease= 0x04,
ENull = 0x05
};
enum QStm_AreaShape
{
ERectangle = 1,
ECircle,
EEllipse
};
// for testingg/debugging purposes - string name og the code
const char* event_name(QStm_UiEventCode aCode);
struct QStm_PlatformPointerEvent
{
enum PEType
{
EButton1Down,
EButton1Up,
EButton2Down,
EButton2Up,
EButton3Down,
EButton3Up,
EDrag,
EMove,
EButtonRepeat,
ESwitchOn,
};
PEType m_type;
unsigned int m_modifiers;
QPoint m_position;
int m_pointerNumber;
void* m_target;
QTime m_time;
};
class QStm_UiEventSpeedIf
{
public:
QStm_UiEventSpeedIf() {}
virtual float speed() const /*__SOFTFP*/ = 0;
virtual QPointF speedVec() const = 0;
};
/*!
* Utility class to wrap number for (already evaluated) speed values.
*/
class QStm_UiEventSpeed : public QStm_UiEventSpeedIf
{
public:
QStm_UiEventSpeed(): m_speed(0), m_speedVec(QPointF(0.0, 0.0)) {}
QStm_UiEventSpeed(float speed): m_speed(speed), m_speedVec(QPointF(0.0, 0.0)) {}
QStm_UiEventSpeed(float speed, QPointF speedVec): m_speed(speed), m_speedVec(speedVec) {}
virtual float speed() const /*__SOFTFP*/ { return m_speed; }
virtual void setSpeed(float speed) { m_speed = speed; }
virtual QPointF speedVec() const { return m_speedVec; }
virtual void setSpeedVec(QPointF speedVec) { m_speedVec = speedVec; }
float m_speed;
QPointF m_speedVec;
};
/*!
* The UI event interface, UI events are touch, hold, move and release.
* Note that currently the interface is not OS agnostic enough. It is using
* TPoint, TTimeIntervalMicroSeconds etc. types which should be replaced
* with some standard types/classes.
*/
class QStm_UiEventIf : public QStm_UiEventSpeed
{
public:
QStm_UiEventIf() : QStm_UiEventSpeed() {}
/*!
* The starting position of the gesture in _screen_ coordinates
*/
virtual const QPoint& startPos() const = 0;
/*!
* Current position in _screen_ coordinates
*/
virtual const QPoint& currentXY() const = 0 ;
/*!
* Previous position in _screen_ coordinates
*/
virtual const QPoint& previousXY() const = 0 ;
/*!
* Time difference between this and previous UI event
*/
virtual long stateTransition() const = 0 ;
/*!
* true, if the UI event was generated because of timer expiration
*/
virtual bool timerExpired() const = 0;
/*!
* The UI event code
*/
virtual QStm_UiEventCode code() const = 0 ;
/*!
* Target identifier (in practice the CCoeControl* of the window)
*/
virtual void* target() const = 0 ;
/*!
* The index of the UI event. In single touch this is always 0
*/
virtual int index() const = 0 ;
/*!
* Next event in the gesture (with the same index)
*/
virtual QStm_UiEventIf* previousEvent() const = 0 ;
/*!
* Count of events in gesture
*/
virtual int countOfEvents() const = 0 ;
/*!
* Timestamp
*/
virtual QTime timestamp() const = 0 ;
/*!
* Speed. Speed is calculated based on the previous event.
*/
virtual float speed() const /*__SOFTFP */ = 0 ;
virtual void setSpeed(float speed) = 0;
virtual QPointF speedVec() const = 0;
virtual void setSpeedVec(QPointF speedVec) = 0;
virtual QEvent::Type mapToMouseEventType() = 0;
virtual QEvent::Type mapToTouchEventType() = 0;
};
/**
* Observer that will be notified when UI events have been recognised
*/
class QStm_UiEventObserverIf
{
public:
QStm_UiEventObserverIf() {};
/**
* Handle the UI event
* \param aEvent event describing the event
*/
virtual void handleUiEvent( const QStm_UiEventIf& aEvent ) = 0;
};
/*! The state machine interface.
*
* To be OS agnostic TPointerEvent, TRect etc. should be replaced with
* something else.
*/
class QStm_StateMachineIf
{
public:
/*!
* \return the rectangle containing the touch area.
* The shape of the touch area can be either rectangle, circle or ellipse.
* getTouchArea returns the current touch area, so it may be of zero size.
* During touch timer the method will return the TouchTimeArea, after that it
* will return the TouchArea.
*/
virtual QRect getTouchArea(int pointerNumber = 0) = 0 ;
/*!
* \param fingersize_mm defines the width of the rectangle or the diameter of the circle/ellipse
* used for the touch area during touch timer running. If the initial touch is a "sloppy" one,
* there is very easily an extra move event detected during touch time. On the other hand
* after touch has been detected, the touch area should not be too big, just something suitable to
* filter minor movements out. The proposed solution is to define two touch areas: one to be used
* while touch timer is running, and another used after touch has been detected.
* The TouchTimeArea can be a bit larger to allow sloppy touch, then the TouchArea can be smaller to
* filter minor movements out.
*/
virtual void setTouchTimeArea(long fingersize_mm) = 0 ;
/*!
* \param fingersize_mm defines the width of the rectangle or the diameter of the circle/ellipse
* used for the touch area.
*/
virtual void setTouchArea(long fingersize_mm) = 0 ;
/*!
* get the touch area shape, either rectangle, circle or ellipse
*/
virtual QStm_AreaShape getTouchAreaShape() = 0 ;
/*!
* set the touch area shape, either rectangle, circle or ellipse. This is the same for both of
* the touch areas.
*/
virtual void setTouchAreaShape(const QStm_AreaShape shape) = 0 ;
/*!
* get the touch timeout. Touch timeout is the time after the first down event
* until the Touch UI event is generated. Touch timeout makes it possible to
* calculate an average of the first few points detected before generating the Touch UI event.
*/
virtual unsigned int getTouchTimeout() = 0 ;
/*!
* Set the touch timeout.
*/
virtual void setTouchTimeout(unsigned int) = 0 ;
/*!
* \return the rectangle containing the hold area.
* The shape of the hold area can be either rectangle, circle or ellipse.
* getholdArea returns the current hold area, so it may be of zero size.
*/
virtual QRect getHoldArea(int pointerNumber = 0) = 0 ;
/*!
* \param fingersize_mm defines the width of the rectangle or the diameter of the circle/ellipse
* used for the hold area. Hold area defines an area so that if the touch coordinates stay
* inside that area for the duration of hold timeout the Hold UI event is generated.
*/
virtual void setHoldArea(long fingersize_mm) = 0 ;
/*!
* get the hold area shape, either rectangle, circle or ellipse
*/
virtual QStm_AreaShape getHoldAreaShape() = 0 ;
/*!
* set the hold area shape, either rectangle, circle or ellipse
*/
virtual void setHoldAreaShape(const QStm_AreaShape shape) = 0 ;
/*!
* get the hold timeout. The timeout defines how long the touch coordinates need to stay
* inside hold area before Hold UI event is generated.
*/
virtual unsigned int getHoldTimeout() = 0 ;
/*!
* Set the hold timeout.
*/
virtual void setHoldTimeout(unsigned int a) = 0 ;
/*!
* get the touch suppress timeout. This timeout defines how long it will take to generate
* the Release UI event after UP event during the touch timeout. This timeout is rather short
* but will cause the filtering of accidental UP/DOWN events during if they are close together.
*/
virtual unsigned int getTouchSuppressTimeout() = 0 ;
/*!
* Set the touch suppress timeout.
*/
virtual void setTouchSuppressTimeout(unsigned int a) = 0 ;
/*!
* get the move suppress timeout. This timeout is used after Move UI event has been generated to
* filter accidental UP/DOWN events. Using light touch it is possible to cause accidental UP/DOWN
* events with the timespan can be over 120 ms when the direction of movement changes.
*/
virtual unsigned int getMoveSuppressTimeout() = 0 ;
/*!
* set the move suppress timeout.
*/
virtual void setMoveSuppressTimeout(unsigned int a) = 0 ;
/*!
* add UI event observer. The generated UI events will be sent to the observers.
* \return false, if the max number of observers (=5) has been reached.
*/
virtual bool addUiEventObserver(QStm_UiEventObserverIf* observer) = 0 ;
/*!
* remove the UI event observer.
*/
virtual bool removeUiEventObserver(QStm_UiEventObserverIf* observer) = 0 ;
/*!
* \return true, of the message being processed did not generate UI event
*/
virtual bool wasLastMessageFiltered(int pointerNumber = 0) = 0 ;
/*!
* enable capacitive UP message. If it is enabled, UP suppression is not used
* but the UP event causes immediate Release UI event.
*/
virtual void enableCapacitiveUp(bool enable) = 0 ;
/*!
* enable or disable debug logging of the state machine
* \param aEnable : logging enabled
*/
virtual void enableLogging(bool aEnable) = 0 ;
/*!
* add "window handles" to the list of targets which should be included
* in the gesture recognition. This way it is possible to drop the messges
* which are not of interest from the gesture recognition point of view.
* This is used when only the gesture recognition is used so that the UI events are
* not passed to the application.
*/
// virtual void addGestureTarget(void* aTarget) = 0 ;
/*!
* Setting the Y adjustment useful in capacitive touch
* Note that there are problems with the adjustment if done at this level,
* the most proper place would be the window server.
*/
virtual void enableYadjustment(bool aEnable) = 0 ;
// Get the number of supported touch pointers
virtual int getNumberOfPointers() = 0;
/*
virtual void setPointerBuffer(TPoint* aBufferPtr, int aBufSize) = 0;
virtual TPoint* getPointerBuffer() = 0;
virtual int getPointerBufferSize() = 0;
*/
virtual void setMoveTolerance(long fingersize_mm) = 0;
};
} // namespace
#endif /* QSTMUIEVENT_IF_H_ */