capi/dali/public-api/events/long-press-gesture-detector.h

   1 #ifndef __DALI_LONG_PRESS_GESTURE_DETECTOR_H__
   2 #define __DALI_LONG_PRESS_GESTURE_DETECTOR_H__
   3
   4 //
   5 // Copyright (c) 2014 Samsung Electronics Co., Ltd.
   6 //
   7 // Licensed under the Flora License, Version 1.0 (the License);
   8 // you may not use this file except in compliance with the License.
   9 // You may obtain a copy of the License at
  10 //
  11 //     http://floralicense.org/license/
  12 //
  13 // Unless required by applicable law or agreed to in writing, software
  14 // distributed under the License is distributed on an AS IS BASIS,
  15 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  16 // See the License for the specific language governing permissions and
  17 // limitations under the License.
  18 //
  19
  20 /**
  21  * @addtogroup CAPI_DALI_EVENTS_MODULE
  22  * @{
  23  */
  24
  25 // INTERNAL INCLUDES
  26 #include <dali/public-api/events/gesture-detector.h>
  27 #include <dali/public-api/signals/dali-signal-v2.h>
  28
  29 namespace Dali DALI_IMPORT_API
  30 {
  31
  32 namespace Internal DALI_INTERNAL
  33 {
  34 class LongPressGestureDetector;
  35 }
  36
  37 struct LongPressGesture;
  38
  39 /**
  40  * @brief This class emits a signals when a long press gesture occurs that meets the requirements set by the application.
  41  * @see LongPressGestureDetector::SetTouchesRequired.
  42  *
  43  * For any valid long press, two signals will be emitted:
  44  * - First identifying the beginning (state = Started) i.e. when fingers held down for the required time.
  45  * - Second identifying the ending (state = Finished) i.e. when fingers are released.
  46  *
  47  * The application programmer can use this gesture detector as follows:
  48  * @code
  49  * LongPressGestureDetector detector = LongPressGestureDetector::New();
  50  * detector.Attach(myActor);
  51  * detector.SignalDetected().Connect(this, &MyApplication::OnLongPress);
  52  * @endcode
  53  *
  54  * @see LongPressGesture
  55  */
  56 class LongPressGestureDetector : public GestureDetector
  57 {
  58 public: // Typedefs
  59
  60   typedef SignalV2< void (Actor, LongPressGesture) > DetectedSignalV2; ///< Gesture detected signal type
  61
  62   //Signal Names
  63   static const char* const SIGNAL_LONG_PRESS_DETECTED; ///< name "long-press-detected"
  64
  65 public: // Creation & Destruction
  66
  67   /**
  68    * @brief Create an uninitialized LongPressGestureDetector; this can be initialized with LongPressGestureDetector::New().
  69    *
  70    * Calling member functions with an uninitialized Dali::Object is not allowed.
  71    */
  72   LongPressGestureDetector();
  73
  74   /**
  75    * @brief Create an initialized LongPressGestureDetector.
  76    *
  77    * By default, this would create a gesture detector that requires only one touch.
  78    * @return A handle to a newly allocated Dali resource.
  79    */
  80   static LongPressGestureDetector New();
  81
  82   /**
  83    * @brief Create an initialized LongPressGestureDetector with the number of touches required.
  84    *
  85    * A long press gesture will be emitted from this detector if the number of fingers touching the
  86    * screen is equal to the touches required.
  87    * @param[in]  touchesRequired  The number of touches required.
  88    * @return A handle to a newly allocated Dali resource.
  89    */
  90   static LongPressGestureDetector New(unsigned int touchesRequired);
  91
  92   /**
  93    * @brief Create an initialized LongPressGestureDetector with the minimum and maximum number of touches required.
  94    *
  95    * A long press gesture will be emitted from this detector if the number of fingers touching the screen
  96    * falls between the minimum and maximum touches set.
  97    * @param[in]  minTouches  The minimum number of touches required.
  98    * @param[in]  maxTouches  The maximum number of touches required.
  99    * @return A handle to a newly allocated Dali resource.
 100    */
 101   static LongPressGestureDetector New(unsigned int minTouches, unsigned int maxTouches);
 102
 103   /**
 104    * @brief Downcast an Object handle to LongPressGestureDetector handle.
 105    *
 106    * If handle points to a LongPressGestureDetector object the
 107    * downcast produces valid handle. If not the returned handle is left uninitialized.
 108    * @param[in] handle to An object
 109    * @return handle to a LongPressGestureDetector object or an uninitialized handle
 110    */
 111   static LongPressGestureDetector DownCast( BaseHandle handle );
 112
 113   /**
 114    * @brief Virtual destructor.
 115    *
 116    * Dali::Object derived classes typically do not contain member data.
 117    */
 118   virtual ~LongPressGestureDetector();
 119
 120   /**
 121    * @copydoc Dali::BaseHandle::operator=
 122    */
 123   using BaseHandle::operator=;
 124
 125 public: // Setters
 126
 127   /**
 128    * @brief Set the number of touches required.
 129    *
 130    * The number of touches corresponds to the number of fingers a user
 131    * has on the screen.  This sets the minimum and maximum touches to
 132    * the input parameter.
 133    *
 134    * @param[in]  touches  Touches required.
 135    * @pre The gesture detector has been initialized.
 136    * @note The default is '1'.
 137    */
 138   void SetTouchesRequired(unsigned int touches);
 139
 140   /**
 141    * @brief Sets the minimum and maximum touches required.
 142    *
 143    * The number of touches corresponds to the number of fingers a user
 144    * has on the screen.
 145    *
 146    * @param[in]  minTouches  Minimum Touches required.
 147    * @param[in]  maxTouches  Maximum Touches required.
 148    * @pre The gesture detector has been initialized.
 149    * @note The default is '1'.
 150    */
 151   void SetTouchesRequired(unsigned int minTouches, unsigned int maxTouches);
 152
 153 public: // Getters
 154
 155   /**
 156    * @brief Retrieves the minimum number of touches required.
 157    *
 158    * @return The minimum number of touches required.
 159    * @pre The gesture detector has been initialized.
 160    */
 161   unsigned int GetMinimumTouchesRequired() const;
 162
 163   /**
 164    * @brief Retrieves the maximum number of touches required.
 165    *
 166    * @return The maximum number of touches required.
 167    * @pre The gesture detector has been initialized.
 168    */
 169   unsigned int GetMaximumTouchesRequired() const;
 170
 171 public: // Signals
 172
 173   /**
 174    * @brief  This signal is emitted when the specified long press is detected on the attached actor.
 175    *
 176    * A callback of the following type may be connected:
 177    * @code
 178    *   void YourCallbackName(Actor actor, LongPressGesture gesture);
 179    * @endcode
 180    * @pre The gesture detector has been initialized.
 181    * @return The signal to connect to.
 182    */
 183   DetectedSignalV2& DetectedSignal();
 184
 185 public: // Not intended for Application developers
 186
 187   /**
 188    * @brief This constructor is used by Dali New() methods.
 189    *
 190    * @param [in]  internal  A pointer to a newly allocated Dali resource.
 191    */
 192   explicit DALI_INTERNAL LongPressGestureDetector(Internal::LongPressGestureDetector* internal);
 193
 194 };
 195
 196 } // namespace Dali
 197
 198 /**
 199  * @}
 200  */
 201 #endif // __DALI_LONG_PRESS_GESTURE_DETECTOR_H__