capi/dali/public-api/events/tap-gesture-detector.h

   1 #ifndef __DALI_TAP_GESTURE_DETECTOR_H__
   2 #define __DALI_TAP_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_FRAMEWORK
  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 TapGestureDetector;
  35 }
  36
  37 struct TapGesture;
  38
  39 /**
  40  * This class emits a signal when a tap gesture occurs that meets the requirements set by the
  41  * application. See TapGestureDetector::SetTapsRequired and TapGestureDetector::SetTouchesRequired.
  42  *
  43  * A Tap Gesture is a discrete gesture, which means it does not have any state information attached
  44  * to it.  Please see TapGesture for more information.
  45  *
  46  * The application programmer can use this gesture detector as follows:
  47  * @code
  48  * TapGestureDetector detector = TapGestureDetector::New();
  49  * detector.Attach(myActor);
  50  * detector.SignalDetected().Connect(this, &MyApplication::OnTap);
  51  * @endcode
  52  *
  53  * @see TapGesture
  54  */
  55 class TapGestureDetector : public GestureDetector
  56 {
  57 public: // Typedefs
  58
  59   typedef SignalV2< void (Actor, TapGesture) > DetectedSignalV2;
  60
  61   //Signal Names
  62   static const char* const SIGNAL_TAP_DETECTED;
  63
  64 public: // Creation & Destruction
  65
  66   /**
  67    * Create an uninitialized TapGestureDetector; this can be initialized with TapGestureDetector::New()
  68    * Calling member functions with an uninitialized Dali::Object is not allowed.
  69    */
  70   TapGestureDetector();
  71
  72   /**
  73    * Create an initialized TapGestureDetector.
  74    * By default, this would create a gesture detector which requires one tap with one touch.
  75    * @return A handle to a newly allocated Dali resource.
  76    */
  77   static TapGestureDetector New();
  78
  79   /**
  80    * Create an initialized TapGestureDetector with the specified parameters.
  81    * @param[in]  tapsRequired     The number of taps required.
  82    * @param[in]  touchesRequired  The number of touches required.
  83    * @return A handle to a newly allocated Dali resource.
  84    */
  85   static TapGestureDetector New(unsigned int tapsRequired, unsigned int touchesRequired);
  86
  87   /**
  88    * Downcast an Object handle to TapGestureDetector handle. If handle points to a TapGestureDetector object the
  89    * downcast produces valid handle. If not the returned handle is left uninitialized.
  90    * @param[in] handle to An object
  91    * @return handle to a TapGestureDetector object or an uninitialized handle
  92    */
  93   static TapGestureDetector DownCast( BaseHandle handle );
  94
  95   /**
  96    * Virtual destructor.
  97    * Dali::Object derived classes typically do not contain member data.
  98    */
  99   virtual ~TapGestureDetector();
 100
 101   /**
 102    * @copydoc Dali::BaseHandle::operator=
 103    */
 104   using BaseHandle::operator=;
 105
 106 public: // Setters
 107
 108   /**
 109    * Set the number of taps required.  The tap count is the number of times a user should "tap" the
 110    * screen.
 111    * @param[in]  taps  Taps required.
 112    * @pre The gesture detector has been initialized.
 113    * @note The default is '1'.
 114    */
 115   void SetTapsRequired(unsigned int taps);
 116
 117   /**
 118    * Set the number of touches required. The number of touches corresponds to the number of fingers
 119    * a user has on the screen.
 120    * @param[in]  touches  Touches required.
 121    * @pre The gesture detector has been initialized.
 122    * @note The default is '1'.
 123    */
 124   void SetTouchesRequired(unsigned int touches);
 125
 126 public: // Getters
 127
 128   /**
 129    * Retrieves the number of taps required.
 130    * @return The taps required.
 131    * @pre The gesture detector has been initialized.
 132    */
 133   unsigned int GetTapsRequired() const;
 134
 135   /**
 136    * Retrieves the number of touches required.
 137    * @return The number of touches required.
 138    * @pre The gesture detector has been initialized.
 139    */
 140   unsigned int GetTouchesRequired() const;
 141
 142 public: // Signals
 143
 144   /**
 145    * This signal is emitted when the specified tap is detected on the attached actor.
 146    * A callback of the following type may be connected:
 147    * @code
 148    *   void YourCallbackName(Actor actor, TapGesture gesture);
 149    * @endcode
 150    * @pre The gesture detector has been initialized.
 151    * @return The signal to connect to.
 152    */
 153   DetectedSignalV2& DetectedSignal();
 154
 155 public: // Not intended for Application developers
 156
 157   /**
 158    * This constructor is used by Dali New() methods.
 159    * @param [in]  internal  A pointer to a newly allocated Dali resource.
 160    */
 161   explicit DALI_INTERNAL TapGestureDetector(Internal::TapGestureDetector* internal);
 162 };
 163
 164 } // namespace Dali
 165
 166 /**
 167  * @}
 168  */
 169 #endif // __DALI_TAP_GESTURE_DETECTOR_H__