inc/FUiTouchGestureDetector.h

   1 //
   2 // Open Service Platform
   3 // Copyright (c) 2012-2013 Samsung Electronics Co., Ltd.
   4 //
   5 // Licensed under the Apache License, Version 2.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://www.apache.org/licenses/LICENSE-2.0/
  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 Tizen::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 to which the gesture detector is attached. @n
  93         * If an error occurs, this method returns @c null.
  94         *
  95         * @since 2.0
  96         *
  97         * @return                                                       The control to which the gesture detector is attached
  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. @n
 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. @n
 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         * @brief       <i> [Deprecated] </i>
 164         * @deprecated  This method is deprecated.
 165         * @since 2.0
 166         *
 167         * @return                       An error code
 168         * @param[in]    gestureDetector                 The gesture detector
 169         * @exception    E_SUCCESS                                       The method is successful.
 170         * @exception    E_INVALID_ARG                           The specified @c gestureDetector is invalid.
 171         * @remarks                      If you want to set relationship between gesture detectors, call this method.
 172         *                                       If @c gestureDetector fails in recognizing a gesture, the gesture detector which waits for it starts the processing of recognizing.
 173         *                                       If @c gestureDetector succeeds in recognizing a gesture,
 174         *                                       the state of the gesture detector which waits for it changes to @c GESTURE_DETECTOR_STATE_FAIL.
 175         */
 176         result StartOnFailureOf(const TouchGestureDetector& gestureDetector);
 177
 178         /**
 179          * Sets priority between gesture detectors.
 180          *
 181          * @since 2.1
 182          *
 183          * @return      An error code
 184          * @param[in]   pGestureDetector       A pointer of gesture detector
 185          * @exception   E_SUCCESS              The method is successful.
 186          * @exception   E_INVALID_ARG          The @c pGestureDetector is null.
 187          * @remarks                            If you want to set relationship between gesture detectors, call this method.
 188          *                                     If @c gestureDetector fails in recognizing a gesture, the gesture detector which waits for it starts the processing of recognizing.
 189          *                                     If @c gestureDetector succeeds in recognizing a gesture,
 190          *                                     the state of the gesture detector which waits for it changes to @c GESTURE_DETECTOR_STATE_FAIL.
 191          */
 192         result StartOnFailureOf(TouchGestureDetector* pGestureDetector);
 193
 194         /**
 195          * Called when touch is pressed in the Control to which the gesture detector is attached.
 196          *
 197          * @since 2.0
 198          *
 199          * @param[in]   source                                                  The source of the event
 200          * @param[in]           touchInfo                                       The touch event information
 201          */
 202         virtual void OnTouchPressed(Tizen::Ui::Control& source, const Tizen::Ui::TouchEventInfo& touchInfo);
 203
 204         /**
 205          * Called when touch is moved in the Control to which the gesture detector is attached.
 206          *
 207          * @since 2.0
 208          *
 209          * @param[in]           source                                          The source of the event
 210          * @param[in]           touchInfo                                       The touch event information
 211          */
 212         virtual void OnTouchMoved(Tizen::Ui::Control& source, const Tizen::Ui::TouchEventInfo& touchInfo);
 213
 214         /**
 215          * Called when touch is released in the Control to which the gesture detector is attached.
 216          *
 217          * @since 2.0
 218          *
 219          * @param[in]   source                                          The source of the event
 220          * @param[in]   touchInfo                                       The touch event information
 221          */
 222         virtual void OnTouchReleased(Tizen::Ui::Control& source, const Tizen::Ui::TouchEventInfo& touchInfo);
 223
 224         /**
 225          * Called when touch is canceled in the Control to which the gesture detector is attached.
 226          *
 227          * @since 2.0
 228          *
 229          * @param[in]   source                                          The source of the event
 230          * @param[in]   touchInfo                                       The touch event information
 231          */
 232         virtual void OnTouchCanceled(Tizen::Ui::Control& source, const Tizen::Ui::TouchEventInfo& touchInfo);
 233
 234 protected:
 235         /**
 236         * Sets the current state of gesture detector. @n
 237         * You can call this method only inherit %TouchGestureDetector directly.
 238         *
 239         * @since 2.0
 240         *
 241         * @return                                                       An error code
 242         * @param[in]    state                           Gesture detector state
 243         * @exception    E_SUCCESS                       The method is successful.
 244         * @see                                  GetDetectorState()
 245         */
 246         result SetDetectorState(Tizen::Ui::TouchGestureDetectorState state);
 247
 248         /**
 249         * Gets the current state of gesture detector. @n
 250         * If an error occurs, this method returns @c GESTURE_DETECTOR_STATE_READY.
 251         *
 252         * @since 2.0
 253         *
 254         * @return                                                       The current state of gesture detector
 255         * @exception    E_SUCCESS                       The method is successful.
 256         * @see                                  SetDetectorState()
 257         */
 258         Tizen::Ui::TouchGestureDetectorState GetDetectorState(void) const;
 259
 260          /**
 261         * Adds the IGestureEventListener instance to the gesture detector instance. @n
 262         * The added listener gets notified when a gesture is recognized.
 263         *
 264         * @since 2.0
 265         *
 266         * @return                                                                       An error code
 267         * @param[in]    listener                                        The event listener to add
 268         * @exception    E_SUCCESS                                       The method is successful.
 269         * @exception    E_OBJ_ALREADY_EXIST     The listener is already added.
 270         * @see                                  RemoveGestureEventListener()
 271         */
 272         result AddGestureEventListener(Tizen::Ui::ITouchGestureEventListener& listener);
 273
 274         /**
 275         * Removes the gesture listener instance.
 276         *
 277         * @since 2.0
 278         *
 279         * @return                                                                       An error code
 280         * @param[in]    listener                                        The listener to remove
 281         * @exception    E_SUCCESS                                       The method is successful.
 282         * @exception    E_OBJ_NOT_FOUND The @c listener is not found.
 283         * @see                                  AddGestureEventListener()
 284         */
 285         result RemoveGestureEventListener(Tizen::Ui::ITouchGestureEventListener& listener);
 286
 287 private:
 288         //
 289         // The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
 290         //
 291         TouchGestureDetector(const TouchGestureDetector& rhs);
 292
 293         //
 294         // The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
 295         //
 296         TouchGestureDetector& operator =(const TouchGestureDetector& rhs);
 297
 298 protected:
 299         friend class _TouchGestureDetectorImpl;
 300
 301         //
 302         // This variable is for internal use only. Using this variable can cause behavioral,
 303         // security-related, and consistency-related issues in the application.
 304         //
 305         _TouchGestureDetectorImpl* __pTouchGestureDetectorImpl;
 306 }; // TouchGestureDetector
 307
 308 }} // Tizen::Ui
 309
 310 #endif  //_FUI_TOUCH_GESTURE_DETECTOR_H_