diff -r 79859ed3eea9 -r 919f36ff910f web_plat/stmgesturefw_api/inc/rt_uievent.h --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/web_plat/stmgesturefw_api/inc/rt_uievent.h Wed Sep 01 12:28:30 2010 +0100 @@ -0,0 +1,309 @@ +/* +* Copyright (c) 2008 Nokia Corporation and/or its subsidiary(-ies). +* All rights reserved. +* This component and the accompanying materials are made available +* under the terms of the License "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: +* +*/ + +#ifndef RT_UIEVENT_H_ +#define RT_UIEVENT_H_ + +// INCLUDES +#include +#include +#include +#include +#include + +#if defined(BRDO_MULTITOUCH_ENABLED_FF) +#define ADVANCED_POINTER_EVENTS +#endif + +namespace stmUiEventEngine +{ + +#if defined(ADVANCED_POINTER_EVENTS) +static const TInt KMaxNumberOfPointers(2) ; // How many pointer we have in multi-touch case +#else +static const TInt KMaxNumberOfPointers(1) ; // How many pointer we have in single touch case +#endif + +/*! + * Event code generated from the state machine + */ +enum TUiEventCode +{ + ETouch = 0x01, + EHold = 0x02, + EMove = 0x03, + ERelease= 0x04, + ENull = 0x05 +}; + +/*! + * Shape of the Area + */ +enum TAreaShape +{ + ERectangle = 1, + ECircle, + EEllipse +}; + +// for testingg/debugging purposes - string name og the code +const char* EventName(TUiEventCode aCode); + +/*! + * Interface class for Speed in X-Y direction + */ +class MUiEventSpeed +{ +public: + virtual float speedX() const __SOFTFP = 0; + virtual float speedY() const __SOFTFP = 0; +}; + +/*! + * Utility class to wrap number for (already evaluated) speed values. + */ +NONSHARABLE_CLASS(TUiEventSpeed): public MUiEventSpeed +{ +public: + TUiEventSpeed(float speedX, float speedY): m_speedX(speedX),m_speedY(speedY) {} + virtual float speedX() const __SOFTFP { return m_speedX; } + virtual float speedY() const __SOFTFP { return m_speedY; } + float m_speedX; + float m_speedY; +}; + +/*! + * 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 MUiEvent: public MUiEventSpeed +{ +public: + /*! + * The starting position of the gesture in _screen_ coordinates + */ + virtual const TPoint& StartPos() const = 0; + /*! + * Current position in _screen_ coordinates + */ + virtual const TPoint& CurrentXY() const = 0 ; + /*! + * Previous position in _screen_ coordinates + */ + virtual const TPoint& PreviousXY() const = 0 ; + /*! + * Time difference between this and previous UI event + */ + virtual TTimeIntervalMicroSeconds StateTransition() const = 0 ; + /*! + * true, if the UI event was generated because of timer expiration + */ + virtual bool TimerExpired() const = 0; + /*! + * The UI event code + */ + virtual TUiEventCode 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 MUiEvent* previousEvent() const = 0 ; + /*! + * Count of events in gesture + */ + virtual int countOfEvents() const = 0 ; + /*! + * Timestamp + */ + virtual TInt64 timestamp() const = 0 ; + /*! + * Speed. Speed is calculated based on the previous event. + */ + virtual float speedX() const __SOFTFP = 0 ; + /*! + * Speed. Speed is calculated based on the previous event. + */ + virtual float speedY() const __SOFTFP = 0 ; +}; + +/** + * Observer that will be notified when UI events have been recognised + */ +class MUiEventObserver +{ +public: + /** + * Handle the UI event + * \param aEvent event describing the event + */ + virtual void HandleUiEventL( const MUiEvent& aEvent ) = 0; +}; + +/*! The state machine interface. + * + * To be OS agnostic TPointerEvent, TRect etc. should be replaced with + * something else. + */ +class MStateMachine +{ +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 TRect getTouchArea(TInt aPointerNumber = 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 TAreaShape 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 TAreaShape 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 TRect getHoldArea(TInt aPointerNumber = 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 TAreaShape getHoldAreaShape() = 0 ; + /*! + * set the hold area shape, either rectangle, circle or ellipse + */ + virtual void setHoldAreaShape(const TAreaShape 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(MUiEventObserver* observer) = 0 ; + /*! + * remove the UI event observer. + */ + virtual bool removeUiEventObserver(MUiEventObserver* observer) = 0 ; + /*! + * \return true, of the message being processed did not generate UI event + */ + virtual bool wasLastMessageFiltered(TInt aPointerNumber = 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; +}; + +} // namespace +#endif /* RT_UIEVENT_H_ */