inc/FUiTouchGestureDetector.h

   1 //
   2 // Open Service Platform
   3 // Copyright (c) 2012-2013 Samsung Electronics Co., Ltd.
   4 //
   5 // Licensed under the Flora License, Version 1.0 (the License);
   6 // you may not use this file except in compliance with the License.
   7 // You may obtain a copy of the License at
   8 //
   9 //     http://floralicense.org/license/
  10 //
  11 // Unless required by applicable law or agreed to in writing, software
  12 // distributed under the License is distributed on an AS IS BASIS,
  13 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  14 // See the License for the specific language governing permissions and
  15 // limitations under the License.
  16 //
  17
  18 /**
  19  * @file                FUiTouchGestureDetector.h
  20  * @brief               This is the header file for the %TouchGestureDetector class.
  21  *
  22  * This header file contains the declarations of the %TouchGestureDetector class.
  23  *
  24  */
  25 #ifndef _FUI_TOUCH_GESTURE_DETECTOR_H_
  26 #define _FUI_TOUCH_GESTURE_DETECTOR_H_
  27
  28 #include <FBaseObject.h>
  29 #include <FUiTouch.h>
  30
  31 namespace Tizen { namespace Ui
  32 {
  33
  34 /**
  35  * @enum TouchGestureDetectorState
  36  *
  37  * Defines the state of a gesture detector.
  38  *
  39  * @since 2.0
  40  */
  41 enum TouchGestureDetectorState
  42 {
  43         GESTURE_DETECTOR_STATE_READY,                                   /**< The gesture detector is ready to recognize the gesture  */
  44         GESTURE_DETECTOR_STATE_STARTED,                 /**< The gesture detector first recognizes the continuous gesture  */
  45         GESTURE_DETECTOR_STATE_CHANGED,                 /**< A subsequent change happens to the continuous gesture  */
  46         GESTURE_DETECTOR_STATE_FINISHED,                        /**< The discrete gesture is recognized or the continuous gesture ends  */
  47         GESTURE_DETECTOR_STATE_FAILED,                          /**< The gesture detector fails in recognizing the gesture      */
  48 };
  49
  50 class Control;
  51 class ITouchGestureEventListener;
  52 class _TouchGestureDetectorImpl;
  53
  54 /**
  55  * @class               TouchGestureDetector
  56  * @brief               This class stores the information of a gesture detector.
  57  *
  58  * @since 2.0
  59  *
  60  * The %TouchGestureDetector class defines a common behavior for gesture detectors and provides information about gesture detector.
  61  *
  62  */
  63  class _OSP_EXPORT_ TouchGestureDetector
  64         : public Tizen::Base::Object
  65 {
  66 public:
  67         /**
  68         * The object is not fully constructed after this constructor is called. For full construction, the Construct() method must be called right after calling this constructor.
  69         *
  70         * @since 2.0
  71         */
  72         TouchGestureDetector(void);
  73
  74         /**
  75         * This destructor overrides Osp::Base::Object::~Object().
  76         *
  77         * @since 2.0
  78         */
  79         virtual ~TouchGestureDetector(void);
  80
  81 public:
  82         /**
  83         * Initializes this instance of %TouchGestureDetector.
  84         *
  85         * @since 2.0
  86         *
  87         * @exception    E_SUCCESS                       The method is successful.
  88         */
  89         result Construct(void);
  90
  91         /**
  92         * Gets the control which the gesture detector is attached to.
  93         * If an error occurs, this method returns @c null.
  94         *
  95         * @since 2.0
  96         *
  97         * @return                                                       The control which the gesture detector is attached to.
  98         * @exception    E_SUCCESS                       The method is successful.
  99         */
 100          Control* GetControl(void) const;
 101
 102         /**
 103          * Enables or disables delaying touch event on Control.
 104          * The %TouchGestureDetector receives touch events prior to a UI control to which it is added.
 105          * Depending on a gesture that it tries to recognize, it is decided whether touch events need to be delivered to the UI control.
 106          * If touch events must not be delivered to the UI control while gesture recognition is in progress, call this method with @c false argument.
 107          * When the recognition finishes as success, delivering delayed touch events is dependent on IsCancelTouchEventOnSuccessEnabled().
 108          * When the recognition finishes as fail, all delayed touch events are fired sequentially.
 109          * The default value is @c false.
 110          *
 111          * @since 2.0
 112          *
 113          * @return                                                      An error code
 114          * @param[in]   enable                          Whether to delay events
 115          * @exception   E_SUCCESS                       The method is successful.
 116          * @see                                 IsDelayTouchEventEnabled()
 117          * @see                                 SetCancelTouchEventOnSuccessEnabled()
 118          */
 119         result SetDelayTouchEventEnabled(bool enable);
 120
 121         /**
 122         * Checks whether delaying touch event to Control is enabled.
 123         *
 124         * @since 2.0
 125         *
 126         * @return                       @c true if delaying touch event is enabled, @n
 127         *                                       else @c false if delaying touch event is disabled
 128         * @exception    E_SUCCESS                       The method is successful.
 129         * @see                                  SetDelayTouchEventEnabled()
 130         */
 131         bool IsDelayTouchEventEnabled(void) const;
 132
 133         /**
 134         * Enables or disables canceling touch event after a gesture is recognized.
 135         * If canceling touch event is enabled and a gesture is recognized, touch events which have been queued are not delivered to a UI control and discarded.
 136         * The default value is @c false.
 137         *
 138         * @since 2.0
 139         *
 140         * @return                       An error code
 141         * @param[in]    enable          Whether to cancel touch event
 142         * @exception    E_SUCCESS                       The method is successful.
 143         * @see                                  IsCancelTouchEventOnSuccessEnabled()
 144         * @see                                  SetDelayTouchEventEnabled()
 145         */
 146         result SetCancelTouchEventOnSuccessEnabled(bool enable);
 147
 148         /**
 149         * Checks whether touch events are canceled after a gesture is recognized.
 150         *
 151         * @since 2.0
 152         *
 153         * @return                       @c true if canceling touch event is enabled, @n
 154         *                                       else @c false
 155         * @exception    E_SUCCESS                               The method is successful.
 156         * @see                                  SetCancelTouchEventOnSuccessEnabled()
 157         */
 158         bool IsCancelTouchEventOnSuccessEnabled(void) const;
 159
 160         /**
 161         * Sets priority between gesture detectors.
 162         *
 163         * @since 2.0
 164         *
 165         * @return                       An error code
 166         * @param[in]    gestureDetector                 The gesture detector
 167         * @exception    E_SUCCESS                                       The method is successful.
 168         * @exception    E_INVALID_ARG                           The @c gestureDetector is invalid.
 169         * @remarks                      If you want to set relationship between gesture detectors, call this method.
 170         *                                       If @c gestureDetector fails in recognizing a gesture, the gesture detector which waits for it starts the processing of recognizing.
 171         *                                       If @c gestureDetector succeeds in recognizing a gesture,
 172         *                                       the state of the gesture detector which waits for it changes to GESTURE_DETECTOR_STATE_FAIL.
 173         */
 174         result StartOnFailureOf(const TouchGestureDetector& gestureDetector);
 175
 176         /**
 177          * Called when touch is pressed in the Control which the gesture detector is attached to.
 178          *
 179          * @since 2.0
 180          *
 181          * @param[in]   source                                                  The source of the event
 182          * @param[in]           touchInfo                                       The touch event information
 183          */
 184         virtual void OnTouchPressed(Tizen::Ui::Control& source, const Tizen::Ui::TouchEventInfo& touchInfo);
 185
 186         /**
 187          * Called when touch is moved in the Control which the gesture detector is attached to.
 188          *
 189          * @since 2.0
 190          *
 191          * @param[in]           source                                          The source of the event
 192          * @param[in]           touchInfo                                       The touch event information
 193          */
 194         virtual void OnTouchMoved(Tizen::Ui::Control& source, const Tizen::Ui::TouchEventInfo& touchInfo);
 195
 196         /**
 197          * Called when touch is released in the Control which the gesture detector is attached to.
 198          *
 199          * @since 2.0
 200          *
 201          * @param[in]   source                                          The source of the event
 202          * @param[in]   touchInfo                                       The touch event information
 203          */
 204         virtual void OnTouchReleased(Tizen::Ui::Control& source, const Tizen::Ui::TouchEventInfo& touchInfo);
 205
 206         /**
 207          * Called when touch is canceled in the Control which the gesture detector is attached to.
 208          *
 209          * @since 2.0
 210          *
 211          * @param[in]   source                                          The source of the event
 212          * @param[in]   touchInfo                                       The touch event information
 213          */
 214         virtual void OnTouchCanceled(Tizen::Ui::Control& source, const Tizen::Ui::TouchEventInfo& touchInfo);
 215
 216 protected:
 217         /**
 218         * Sets the current state of gesture detector.
 219         * You can call this method only inherit %TouchGestureDetector directly.
 220         *
 221         * @since 2.0
 222         *
 223         * @return                                                       An error code
 224         * @param[in]    state                           Gesture detector state
 225         * @exception    E_SUCCESS                       The method is successful.
 226         * @see                                  GetDetectorState()
 227         */
 228         result SetDetectorState(Tizen::Ui::TouchGestureDetectorState state);
 229
 230         /**
 231         * Gets the current state of gesture detector.
 232         * If an error occurs, this method returns @c GESTURE_DETECTOR_STATE_READY.
 233         *
 234         * @since 2.0
 235         *
 236         * @return                                                       The current state of gesture detector
 237         * @exception    E_SUCCESS                       The method is successful.
 238         * @see                                  SetDetectorState()
 239         */
 240         Tizen::Ui::TouchGestureDetectorState GetDetectorState(void) const;
 241
 242          /**
 243         * Adds the IGestureEventListener instance to the gesture detector instance. @n
 244         * The added listener gets notified when a gesture is recognized.
 245         *
 246         * @since 2.0
 247         *
 248         * @return                                                                       An error code
 249         * @param[in]    listener                                        The event listener to add
 250         * @exception    E_SUCCESS                                       The method is successful.
 251         * @exception    E_OBJ_ALREADY_EXIST     The listener is already added.
 252         * @see                                  RemoveGestureEventListener()
 253         */
 254         result AddGestureEventListener(Tizen::Ui::ITouchGestureEventListener& listener);
 255
 256         /**
 257         * Removes the gesture listener instance.
 258         *
 259         * @since 2.0
 260         *
 261         * @return                                                                       An error code
 262         * @param[in]    listener                                        The listener to remove
 263         * @exception    E_SUCCESS                                       The method is successful.
 264         * @exception    E_OBJ_NOT_FOUND The @c listener is not found.
 265         * @see                                  AddGestureEventListener()
 266         */
 267         result RemoveGestureEventListener(Tizen::Ui::ITouchGestureEventListener& listener);
 268
 269 private:
 270         //
 271         // The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
 272         //
 273         TouchGestureDetector(const TouchGestureDetector& rhs);
 274
 275         //
 276         // The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
 277         //
 278         TouchGestureDetector& operator =(const TouchGestureDetector& rhs);
 279
 280 protected:
 281         friend class _TouchGestureDetectorImpl;
 282
 283         //
 284         // This variable is for internal use only. Using this variable can cause behavioral,
 285         // security-related, and consistency-related issues in the application.
 286         //
 287         _TouchGestureDetectorImpl* __pTouchGestureDetectorImpl;
 288 }; // TouchGestureDetector
 289
 290 }} // Tizen::Ui
 291
 292 #endif  //_FUI_TOUCH_GESTURE_DETECTOR_H_