dali/public-api/events/pan-gesture.h

   1 #ifndef DALI_PAN_GESTURE_H
   2 #define DALI_PAN_GESTURE_H
   3
   4 /*
   5  * Copyright (c) 2020 Samsung Electronics Co., Ltd.
   6  *
   7  * Licensed under the Apache License, Version 2.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://www.apache.org/licenses/LICENSE-2.0
  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 // INTERNAL INCLUDES
  22 #include <dali/public-api/events/gesture.h>
  23 #include <dali/public-api/math/vector2.h>
  24
  25 namespace Dali
  26 {
  27
  28 namespace Internal DALI_INTERNAL
  29 {
  30 class PanGesture;
  31 }
  32
  33 /**
  34  * @addtogroup dali_core_events
  35  * @{
  36  */
  37
  38 /**
  39  * @brief A PanGesture is emitted when the user moves one or more fingers in a particular direction.
  40  *
  41  * This gesture can be in one of three states, when the pan gesture is first detected: Gesture::Started
  42  * when the pan gesture is continuing: Gesture::Continuing and finally, when the pan gesture ends:
  43  * Gesture::Finished.
  44  *
  45  * A pan gesture will end in the following ways:
  46  * - User releases the primary finger (the first touch).
  47  * - User has more fingers on the screen than the maximum specified.
  48  * - User has less fingers on the screen than the minimum specified.
  49  * - Cancelled by the system.
  50  *
  51  * A pan gesture will continue to be sent to the actor under than initial pan until it ends.
  52  * @SINCE_1_9.28
  53  */
  54 class DALI_CORE_API PanGesture: public Gesture
  55 {
  56 public:
  57
  58   /**
  59    * @brief Creates an uninitialized PanGesture handle.
  60    *
  61    * Calling member functions with an uninitialized Actor handle is not allowed.
  62    * @SINCE_1_9.28
  63    */
  64   PanGesture();
  65
  66   /**
  67    * @brief Copy constructor.
  68    * @SINCE_1_9.28
  69    * @param[in] rhs A reference to the copied handle
  70    */
  71   PanGesture( const PanGesture& rhs );
  72
  73   /**
  74    * @brief Move constructor.
  75    * @SINCE_1_9.28
  76    * @param[in] rhs A reference to the moved handle
  77    */
  78   PanGesture( PanGesture&& rhs );
  79
  80   /**
  81    * @brief Assignment operator.
  82    * @SINCE_1_9.28
  83    * @param[in] rhs A reference to the copied handle
  84    * @return A reference to this
  85    */
  86   PanGesture& operator=( const PanGesture& rhs );
  87
  88   /**
  89    * @brief Move assignment operator.
  90    * @SINCE_1_9.28
  91    * @param[in] rhs A reference to the moved handle
  92    * @return A reference to this
  93    */
  94   PanGesture& operator=( PanGesture&& rhs );
  95
  96   /**
  97    * @brief Non virtual destructor.
  98    * @SINCE_1_9.28
  99    */
 100   ~PanGesture();
 101
 102   /**
 103    * @brief The velocity at which the user is moving their fingers.
 104    *
 105    * This is represented as a Vector2 and is the pixel movement per millisecond.
 106    * A positive x value shows that the user is panning to the right, a negative x value means the opposite.
 107    * A positive y value shows that the user is panning downwards, a negative y values means upwards.
 108    * This value represents the local coordinates of the actor attached to the PanGestureDetector.
 109    * @SINCE_1_9.28
 110    * @return The velocity of the pan
 111    */
 112   const Vector2& GetVelocity() const;
 113
 114   /**
 115    * @brief This is a Vector2 showing how much the user has panned (dragged) since the last pan gesture or,
 116    * if the gesture has just started, then the amount panned since the user touched the screen.
 117    *
 118    * A positive x value shows that the user is panning to the right, a negative x value means the opposite.
 119    * A positive y value shows that the user is panning downwards, a negative y value means upwards.
 120    * This value is in local actor coordinates, the actor being the one attached to the
 121    * PanGestureDetector.
 122    * @SINCE_1_9.28
 123    * @return The displacement of the pan
 124    */
 125   const Vector2& GetDisplacement() const;
 126
 127   /**
 128    * @brief This current touch position of the primary touch point in local actor coordinates.
 129    * @SINCE_1_9.28
 130    * @return The current position of the pan (in local actor coordinates)
 131    */
 132   const Vector2& GetPosition() const;
 133
 134   /**
 135    * @brief The velocity at which the user is moving their fingers.
 136    *
 137    * This is represented as a Vector2 and is the pixel movement per millisecond.
 138    * A positive x value shows that the user is panning to the right, a negative x value means the opposite.
 139    * A positive y value shows that the user is panning downwards, a negative y values means upwards.
 140    * This value represents the screen coordinates.
 141    * @SINCE_1_9.28
 142    * @return The velocity of the pan (in screen coordinates)
 143    */
 144   const Vector2& GetScreenVelocity() const;
 145
 146   /**
 147    * @brief This is a Vector2 showing how much the user has panned (dragged) since the last pan gesture or,
 148    * if the gesture has just started, then the amount panned since the user touched the screen.
 149    *
 150    * A positive x value shows that the user is panning to the right, a negative x value means the opposite.
 151    * A positive y value shows that the user is panning downwards, a negative y value means upwards.
 152    * This value is in screen coordinates.
 153    * @SINCE_1_9.28
 154    * @return The displacement of the pan (in screen coordinates)
 155    */
 156   const Vector2& GetScreenDisplacement() const;
 157
 158   /**
 159    * @brief This current touch position of the primary touch point in screen coordinates.
 160    * @SINCE_1_9.28
 161    * @return The current position of the pan (in screen coordinates)
 162    */
 163   const Vector2& GetScreenPosition() const;
 164
 165   /**
 166    * @brief The total number of fingers touching the screen in a pan gesture.
 167    * @SINCE_1_9.28
 168    * @return The number of touches in the pan
 169    */
 170   uint32_t GetNumberOfTouches() const;
 171
 172   // Convenience Methods
 173
 174   /**
 175    * @brief Returns the speed at which the user is moving their fingers.
 176    *
 177    * This is the pixel movement per millisecond.
 178    * @SINCE_1_9.28
 179    * @return The speed of the pan (in pixels per millisecond)
 180    */
 181   float GetSpeed() const;
 182
 183   /**
 184    * @brief This returns the distance the user has panned (dragged) since the last pan gesture or,
 185    * if the gesture has just started, then the distance moved since the user touched the screen.
 186    *
 187    * This is always a positive value.
 188    * @SINCE_1_9.28
 189    * @return The distance, as a float, a user's finger has panned
 190    */
 191   float GetDistance() const;
 192
 193   /**
 194    * @brief Returns the speed at which the user is moving their fingers relative to screen coordinates.
 195    *
 196    * This is the pixel movement per millisecond.
 197    * @SINCE_1_9.28
 198    * @return The speed of the pan (in pixels per millisecond)
 199    */
 200   float GetScreenSpeed() const;
 201
 202   /**
 203    * @brief This returns the distance the user has panned (dragged) since the last pan gesture in screen
 204    * coordinates or, if the gesture has just started, then the distance in screen coordinates moved
 205    * since the user touched the screen.
 206    *
 207    * This is always a positive value.
 208    * @SINCE_1_9.28
 209    * @return The distance, as a float, a user's finger has panned
 210    */
 211   float GetScreenDistance() const;
 212
 213 public: // Not intended for application developers
 214
 215   /// @cond internal
 216   /**
 217    * @brief This constructor is used internally to Create an initialized PanGesture handle.
 218    *
 219    * @param[in] panGesture A pointer to a newly allocated Dali resource
 220    * @SINCE_1_9.28
 221    */
 222   explicit DALI_INTERNAL PanGesture( Internal::PanGesture* panGesture );
 223   /// @endcond
 224
 225 };
 226
 227 /**
 228  * @}
 229  */
 230 } // namespace Dali
 231
 232 #endif // DALI_PAN_GESTURE_H