inc/FUiTouchLongPressGestureDetector.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                        FUiTouchLongPressGestureDetector.h
  20  * @brief               This is the header file for the %TouchLongPressGestureDetector class.
  21  *
  22  * This header file contains the declarations of the %TouchLongPressGestureDetector class.
  23  *
  24  */
  25
  26 #ifndef _FUI_TOUCH_LONG_PRESS_GESTURE_DETECTOR_H_
  27 #define _FUI_TOUCH_LONG_PRESS_GESTURE_DETECTOR_H_
  28
  29 #include <FUiTouchGestureDetector.h>
  30
  31 namespace Tizen { namespace Ui
  32 {
  33
  34 class ITouchLongPressGestureEventListener;
  35
  36 /**
  37  * @class               TouchLongPressGestureDetector
  38  * @brief               This class stores the information of a long press gesture detector.
  39  *
  40  * @since 2.0
  41  *
  42  * @final        This class is not intended for extension.
  43  *
  44  * The %TouchLongPressGestureDetector class supports changing conditions of long press gesture, and provides information about long press gesture detector.
  45  *
  46  */
  47 class _OSP_EXPORT_ TouchLongPressGestureDetector
  48         : public Tizen::Ui::TouchGestureDetector
  49 {
  50 public:
  51         /**
  52          * 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.
  53          *
  54          * @since 2.0
  55          */
  56         TouchLongPressGestureDetector(void);
  57
  58         /**
  59          * This destructor overrides Tizen::Base::Object::~Object().
  60          *
  61          * @since 2.0
  62          */
  63         virtual ~TouchLongPressGestureDetector(void);
  64
  65         /**
  66          * Initializes this instance of %TouchLongPressGestureDetector.
  67          *
  68          * @since 2.0
  69          * @exception   E_SUCCESS                                       The method is successful.
  70          * @exception   E_OUT_OF_MEMORY         The memory is insufficient.
  71          */
  72         result Construct(void);
  73
  74         /**
  75         * Adds the ITouchLongPressGestureEventListener instance to the long press gesture detector instance. @n
  76         * The added listener gets notified when a gesture is recognized.
  77         *
  78         * @since 2.0
  79         *
  80         * @return                       An error code
  81         * @param[in]    listener                                                The event listener to add
  82         * @exception    E_SUCCESS                                       The method is successful.
  83         * @exception    E_OBJ_ALREADY_EXIST     The listener is already added.
  84         * @see                                  RemoveLongPressGestureEventListener()
  85         */
  86         result AddLongPressGestureEventListener(Tizen::Ui::ITouchLongPressGestureEventListener& listener);
  87
  88         /**
  89         * Removes the ITouchLongPressGestureEventListener instance from the long press gesture detector instance.
  90         *
  91         * @since 2.0
  92         *
  93         * @return                       An error code
  94         * @param[in]    listener                                                The listener to remove
  95         * @exception    E_SUCCESS                                       The method is successful.
  96         * @exception    E_OBJ_NOT_FOUND The specified @c listener is not found.
  97         * @see                                  AddLongPressGestureEventListener()
  98         */
  99         result RemoveLongPressGestureEventListener(Tizen::Ui::ITouchLongPressGestureEventListener& listener);
 100
 101         /**
 102         * Sets the duration needed for the recognition of long press gesture.
 103         *
 104         * @since 2.0
 105         *
 106         * @param[in]            duration                                                        The time duration
 107         * @exception            E_SUCCESS                                       The method is successful.
 108         * @exception            E_INVALID_ARG                           The specified @c duration is less than @c 0.
 109         * @remarks              The default value is @c 500 milliseconds.
 110         * @see                          GetDuration()
 111         *
 112         */
 113         result SetDuration(int duration);
 114
 115         /**
 116          * Gets the duration needed for the recognition of long press gesture.
 117          *
 118          * @since 2.0
 119          *
 120          * @return                      The time duration
 121          * @exception   E_SUCCESS                                       The method is successful.
 122          * @remarks             If an error occurs, this method returns @c -1.
 123          * @see                 SetDuration()
 124          */
 125         int GetDuration(void) const;
 126
 127         /**
 128         * Sets the allowed displacement of touch move for the recognition of long press gesture.
 129         *
 130         * @since 2.0
 131         *
 132         * @param[in]            allowance                                               The allowed move displacement
 133         * @exception            E_SUCCESS                                       The method is successful.
 134         * @exception            E_INVALID_ARG                           The specified @c allowance is less than @c 0.
 135         * @remarks              The long press gesture is recognized when touch is pressed and moved within the given allowed displacement from the first touch point for the given duration.
 136         *                                               The default allowance is @c 10.
 137         * @see                          GetMoveAllowance()
 138         *
 139         */
 140         result SetMoveAllowance(int allowance);
 141
 142         /**
 143         * Sets the allowed displacement of touch move for the recognition of long press gesture.
 144         *
 145         * @since 2.1
 146         *
 147         * @param[in]            allowance                                               The allowed move displacement
 148         * @exception            E_SUCCESS                                       The method is successful.
 149         * @exception            E_INVALID_ARG                           The specified @c allowance is less than @c 0.
 150         * @remarks              The long press gesture is recognized when touch is pressed and moved within the given allowed displacement from the first touch point for the given duration.
 151         *                                               The default allowance is @c 10.
 152         * @see                          GetMoveAllowance()
 153         *
 154         */
 155         result SetMoveAllowance(float allowance);
 156
 157         /**
 158         * Gets the allowed move bounds.
 159         *
 160         * @since 2.0
 161         *
 162         * @return                       The allowed move bounds
 163         * @exception            E_SUCCESS                                       The method is successful.
 164         * @remarks              If an error occurs, this method returns @c -1.
 165         * @see                          SetMoveAllowance()
 166         *
 167         */
 168         int GetMoveAllowance(void) const;
 169
 170         /**
 171         * Gets the allowed move bounds.
 172         *
 173         * @since 2.1
 174         *
 175         * @return                       The allowed move bounds
 176         * @exception            E_SUCCESS                                       The method is successful.
 177         * @remarks              If an error occurs, this method returns @c -1.
 178         * @see                          SetMoveAllowance()
 179         *
 180         */
 181         float GetMoveAllowanceF(void) const;
 182
 183         /**
 184         * Sets the finger count for the recognition of long press gesture at the same time.
 185         *
 186         * @since 2.0
 187         *
 188         * @param[in]            count                                                           The finger count for long press gesture
 189         * @exception            E_SUCCESS                                       The method is successful.
 190         * @exception            E_INVALID_ARG                           The specified @c count is less than @c 0.
 191         * @remarks              The default value is @c 1.
 192         *                               It is recommended to check the maximum touch count of a device before changing the touch count of a gesture detector.
 193         *                               You can set the gesture touch count to more than the maximum device touch count, but the gesture recognition may not work as you expected.
 194         * @see                          GetTouchCount()
 195         *
 196         */
 197         result SetTouchCount(int count);
 198
 199         /**
 200         * Gets the finger count for the recognition of long press gesture at the same time.
 201         *
 202         * @since 2.0
 203         *
 204         * @return                       The finger count for long press gesture
 205         * @exception            E_SUCCESS                                       The method is successful.
 206         * @remarks              If an error occurs, this method returns @c -1.
 207         * @see                          GetTouchCount()
 208         *
 209         */
 210         int GetTouchCount(void) const;
 211
 212 private:
 213         //
 214         // This is the copy constructor for this class.
 215         //
 216         TouchLongPressGestureDetector(const TouchLongPressGestureDetector& rhs);
 217
 218         //
 219         // Assigns the value of the specified instance to the current instance of %TouchLongPressGestureDetector.
 220         //
 221         TouchLongPressGestureDetector& operator =(const TouchLongPressGestureDetector& rhs);
 222
 223 protected:
 224         friend class _TouchLongPressGestureDetectorImpl;
 225 }; // TouchLongPressGestureDetector
 226
 227 }} // Tizen::Ui
 228
 229 #endif  //_FUI_TOUCH_LONG_PRESS_GESTURE_DETECTOR_H_