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