diff -r 000000000000 -r 1450b09d0cfd qstmgesturelib/qstmgestureapi.h --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/qstmgesturelib/qstmgestureapi.h Tue May 04 12:39:35 2010 +0300 @@ -0,0 +1,322 @@ +/* +* Copyright (c) 2010 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: +* +*/ + + +#ifndef QSTMGESTUREAPI_H__ +#define QSTMGESTUREAPI_H__ + +#include +#include +#include +#include +#include + +#if !defined(Q_WS_X11) +#define XEvent void +#endif + +namespace qstmGesture +{ + class QStm_GestureRecogniserIf; + class QStm_GestureEngine; +} + + +namespace qstmUiEventEngine +{ + class QStm_StateMachine; +} + +class QStm_GestureContext; +class QGestureEvent; +class QSymbianEvent; +class QStm_Gesture; + +class QStm_GestureListenerApiIf +{ +public: + enum QStm_ProcessingResult + { + // Normally listeners return this code + EContinue = 0, + // Prevents any other listeners to get this event + EConsume = 1, + // continue and disable recognizer till explicitly re-enabled + ESuspend = 1<<1, + }; + + enum QStm_GestureContextEvent + { + EContextActivated, + EContextDeactivated + }; + + // Gesture handling callback. + // @param aUid Type of gesture (actually, UID of gesture recognizer implementation) + // @param aGesture Geture data; if it's NULL then event is Exit (end of gesture) + // @note Some gestures issue more then one calls and then, typically Exit call. + virtual QStm_ProcessingResult handleGestureEvent(qstmGesture::QStm_GestureUid /*aUid*/, qstmGesture::QStm_GestureIf* /*aGesture*/) + { + return QStm_GestureListenerApiIf::EContinue; + } + + // This method is called instead of HandleGestureEventL if prevous listener locked itself + // onto gesture handling by returning TProcessingResult::EConsume. + // @see HandleGestureEventL + // Default implementation does nothing. + virtual void handleGestureListenerSuppressed(qstmGesture::QStm_GestureUid /*aUid*/, qstmGesture::QStm_GestureIf* /*aGesture*/) + { + + } + + // Called by framework when listener is removed from a listener set. + // It can be used for application-specific action, i.e. desturction of the listener. + // Default implementation does nothing. + virtual void handleGestureContextEvent(QStm_GestureContextEvent /*aEvent*/) + { + + } + + // Called by framework when listener is removed from a listener set. + // It can be used for application-specific action, i.e. destruction of the listener. + // Default implementation does nothing. + virtual void handleGestureListenerRemoved() + { + + } +}; + + + + + + + +//================================================================== + +class QStm_GestureParametersApiIf +{ +public: + virtual qstmGesture::QStm_GestureArea* area(qstmGesture::QStm_GestureAreaSettings aArea) = 0; + virtual int param(qstmGesture::QStm_GestureSettings aParam) const = 0; + virtual uint enabled(qstmGesture::QStm_GestureUid gestureUid) const = 0; +}; + +//================================================================== + +class QStm_GestureParameters: public QObject, public QStm_GestureParametersApiIf +{ +public: + + QStm_GestureParameters(); + + QStm_GestureParameters(const QStm_GestureParameters& aParams); + +public: // getters from QStm_GestureParametersApiIf + + qstmGesture::QStm_GestureArea* area(qstmGesture::QStm_GestureAreaSettings aArea) + { + return &m_areaSettings[aArea]; + } + + int param(qstmGesture::QStm_GestureSettings param) const + { + return m_param[param]; + } + + uint enabled(qstmGesture::QStm_GestureUid gestureUid) const + { + return m_enabled[gestureUid] != 0; + } + + void setParam(qstmGesture::QStm_GestureSettings param, int value) + { + m_param[param] = value; + } + + void setEnabled(qstmGesture::QStm_GestureUid gestureUid, uint param) + { + m_enabled[gestureUid] = param; + } + + int& operator[](qstmGesture::QStm_GestureSettings param) + { + return m_param[param]; + } + +private: + int m_param[qstmGesture::EGestureSettingsCount]; + qstmGesture::QStm_GestureArea m_areaSettings[qstmGesture::EGestureAreaSettingsCount]; + int m_modified; + uint m_enabled[qstmGesture::EStmGestureUid_Count]; +}; + +//================================================================== + +class QStm_GestureEngineApi : public QObject +{ + Q_OBJECT +public: + ~QStm_GestureEngineApi(); + + QSTMGESTURELIB_EXPORT QStm_GestureContext* createContext(int aId); + + QStm_GestureContext* context(int aId); + + QSTMGESTURELIB_EXPORT QStm_GestureEngineApi(); + + qstmGesture::QStm_GestureEngine* getGestureEngine() { return m_gestureEngine; } + qstmUiEventEngine::QStm_StateMachine* getStateMachine() { return m_statemachine; } + + +private: // used by friend class QStm_GestureContext + void init(); + void enableContext(QStm_GestureContext& ctx); + + void disableContext(QStm_GestureContext& ctx); + + template + void initRecognizer( + T*& gesture, + QStm_GestureContext& ctx, + bool isNewCtx); + + void setupRecognizers(QStm_GestureContext& ctx, bool isNewCtx); + +private: + friend class QStm_GestureContext; + + // Registered/owned contexts + QList m_contexts; + // Active set of contexts; latest added defines parameters + QList m_ctxtStack; + + // Global/default parameters + QStm_GestureParameters* m_config; + bool m_dtorPhase; + + qstmGesture::QStm_GestureEngine* m_gestureEngine; + qstmUiEventEngine::QStm_StateMachine* m_statemachine; +}; + + +// Gesture context represents a certain configuration of gesture parameters +// (including what gestures are enabled) and gesture listeners. +// Context can be created beforehand and reused later. +// The assumed use of a context is to have rough correspondence between +// UI view and enabled gestures. +// +// @note Gesture contexts are created by an instance of QStm_GestureEngineApi. +class QStm_GestureContext: public QObject, + public qstmGesture::QStm_GestureListenerIf, + public qstmUiEventEngine::QStm_UiEventObserverIf +{ + Q_OBJECT +public: + QSTMGESTURELIB_EXPORT QStm_GestureContext(QStm_GestureEngineApi& engine); + + QSTMGESTURELIB_EXPORT ~QStm_GestureContext(); + +public: // Gesture listeners + + // Add listener to the gesture processing context. + // @param aListener Listener object + // @param aPos Position of inserted listener which determines order + // in which it receives gesture events (0 == first, before existing) + QSTMGESTURELIB_EXPORT void addListener(QStm_GestureListenerApiIf* listener, int pos = 0); + + QSTMGESTURELIB_EXPORT int removeListener(QStm_GestureListenerApiIf* listener); + + const QList& listeners() const { return m_listeners; } + + QSTMGESTURELIB_EXPORT QStm_GestureParameters& config() { return *m_config; } + + QSTMGESTURELIB_EXPORT void setContext(void* control); + + QSTMGESTURELIB_EXPORT void setLogging(int enabled) { m_logging = enabled; } + + QSTMGESTURELIB_EXPORT void* contextControl() { return m_ownerControl; } + + QSTMGESTURELIB_EXPORT void activate(); + + QSTMGESTURELIB_EXPORT void activate(void* control); + + QSTMGESTURELIB_EXPORT bool isActive() { return m_isActivated; } + + QSTMGESTURELIB_EXPORT void deactivate(); + + QSTMGESTURELIB_EXPORT int id() const { return m_ctxtId; } + + // TODO: hide implementation, check boundaries + QSTMGESTURELIB_EXPORT qstmGesture::QStm_GestureRecogniserIf* recognizer(qstmGesture::QStm_GestureUid aUid) + { + return m_recognizers[aUid]; + } + +// from qstmGesture::QStm_GestureListenerIf + + void gestureEnter(qstmGesture::QStm_GestureIf& aGesture); + + void gestureExit(qstmGesture::QStm_GestureIf& aGesture); + + QSTMGESTURELIB_EXPORT void* getOwner(); + + +//from qstmUiEventEngine::QStm_UiEventObserverIf + QSTMGESTURELIB_EXPORT void handleUiEvent( const qstmUiEventEngine::QStm_UiEventIf& event ); + + QSTMGESTURELIB_EXPORT bool handleSymbianPlatformEvent(const QSymbianEvent* platEvent); + + QSTMGESTURELIB_EXPORT bool handleX11PlatformEvent(const XEvent* platEvent); + + +signals: + void uiEvent(const qstmUiEventEngine::QStm_UiEventIf& event); + +private: + friend class QStm_GestureEngineApi; + + QStm_Gesture* createQStmGesture(qstmGesture::QStm_GestureUid uid, + qstmGesture::QStm_GestureIf* gesture); + void init(); + + void dispatchGestureEvent(qstmGesture::QStm_GestureUid aUid, qstmGesture::QStm_GestureIf* aGesture); + + void suspendRecognizer(qstmGesture::QStm_GestureUid aUid); + void enableRecognizers(); + void enableRecognizer(qstmGesture::QStm_GestureUid aUid); + +private: + QStm_GestureEngineApi& m_engine; + // Application-specific ID for finding context + int m_ctxtId; + bool m_isActivated; + QStm_GestureParameters* m_config; + void* m_ownerControl; + + //TBool iPinchUsed; + QList m_listeners; + // for simplicity of addressing recognizers, we'll use fixed array + // with UID-based index (range 0..N is assumed for UIDs) + // @note Tap recognizer actually produces Tap and DoubleTap gesture, + // so should be handled carefully -- only Tap position is set + qstmGesture::QStm_GestureRecogniserIf* m_recognizers[qstmGesture::EStmGestureUid_Count]; + int m_logging; +}; + + +#endif // QSTMGESTUREAPI_H__