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

   1 #ifndef DALI_PAN_GESTURE_H
   2 #define DALI_PAN_GESTURE_H
   3
   4 /*
   5  * Copyright (c) 2019 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  * @addtogroup dali_core_events
  29  * @{
  30  */
  31
  32 /**
  33  * @brief A PanGesture is emitted when the user moves one or more fingers in a particular direction.
  34  *
  35  * This gesture can be in one of three states, when the pan gesture is first detected: Gesture::Started
  36  * when the pan gesture is continuing: Gesture::Continuing and finally, when the pan gesture ends:
  37  * Gesture::Finished.
  38  *
  39  * A pan gesture will end in the following ways:
  40  * - User releases the primary finger (the first touch).
  41  * - User has more fingers on the screen than the maximum specified.
  42  * - User has less fingers on the screen than the minimum specified.
  43  * - Cancelled by the system.
  44  *
  45  * A pan gesture will continue to be sent to the actor under than initial pan until it ends.
  46  * @SINCE_1_0.0
  47  */
  48 struct DALI_CORE_API PanGesture: public Gesture
  49 {
  50   // Construction & Destruction
  51
  52   /**
  53    * @brief Default Constructor.
  54    * @SINCE_1_0.0
  55    */
  56   PanGesture();
  57
  58   /**
  59    * @brief Constructor.
  60    *
  61    * @SINCE_1_0.0
  62    * @param[in] state The state of the gesture
  63    */
  64   PanGesture(Gesture::State state);
  65
  66   /**
  67    * @brief Copy constructor.
  68    * @SINCE_1_0.0
  69    * @param[in] rhs A reference to the copied handle
  70    */
  71   PanGesture( const PanGesture& rhs );
  72
  73   /**
  74    * @brief Assignment operator.
  75    * @SINCE_1_0.0
  76    * @param[in] rhs A reference to the copied handle
  77    * @return A reference to this
  78    */
  79   PanGesture& operator=( const PanGesture& rhs );
  80
  81   /**
  82    * @brief Virtual destructor.
  83    * @SINCE_1_0.0
  84    */
  85   virtual ~PanGesture();
  86
  87   // Data
  88
  89   /**
  90    * @brief The velocity at which the user is moving their fingers.
  91    *
  92    * This is represented as a Vector2 and is the pixel movement per millisecond.
  93    * A positive x value shows that the user is panning to the right, a negative x value means the opposite.
  94    * A positive y value shows that the user is panning downwards, a negative y values means upwards.
  95    * This value represents the local coordinates of the actor attached to the PanGestureDetector.
  96    */
  97   Vector2 velocity;
  98
  99   /**
 100    * @brief This is a Vector2 showing how much the user has panned (dragged) since the last pan gesture or,
 101    * if the gesture has just started, then the amount panned since the user touched the screen.
 102    *
 103    * A positive x value shows that the user is panning to the right, a negative x value means the opposite.
 104    * A positive y value shows that the user is panning downwards, a negative y value means upwards.
 105    * This value is in local actor coordinates, the actor being the one attached to the
 106    * PanGestureDetector.
 107    */
 108   Vector2 displacement;
 109
 110   /**
 111    * @brief This current touch position of the primary touch point in local actor coordinates.
 112    */
 113   Vector2 position;
 114
 115   /**
 116    * @brief The velocity at which the user is moving their fingers.
 117    *
 118    * This is represented as a Vector2 and is the pixel movement per millisecond.
 119    * A positive x value shows that the user is panning to the right, a negative x value means the opposite.
 120    * A positive y value shows that the user is panning downwards, a negative y values means upwards.
 121    * This value represents the screen coordinates.
 122    */
 123   Vector2 screenVelocity;
 124
 125   /**
 126    * @brief This is a Vector2 showing how much the user has panned (dragged) since the last pan gesture or,
 127    * if the gesture has just started, then the amount panned since the user touched the screen.
 128    *
 129    * A positive x value shows that the user is panning to the right, a negative x value means the opposite.
 130    * A positive y value shows that the user is panning downwards, a negative y value means upwards.
 131    * This value is in screen coordinates.
 132    */
 133   Vector2 screenDisplacement;
 134
 135   /**
 136    * @brief This current touch position of the primary touch point in screen coordinates.
 137    */
 138   Vector2 screenPosition;
 139
 140   /**
 141    * @brief The total number of fingers touching the screen in a pan gesture.
 142    */
 143   uint32_t numberOfTouches;
 144
 145   // Convenience Methods
 146
 147   /**
 148    * @brief Returns the speed at which the user is moving their fingers.
 149    *
 150    * This is the pixel movement per millisecond.
 151    * @SINCE_1_0.0
 152    * @return The speed of the pan (in pixels per millisecond)
 153    */
 154   float GetSpeed() const;
 155
 156   /**
 157    * @brief This returns the distance the user has panned (dragged) since the last pan gesture or,
 158    * if the gesture has just started, then the distance moved since the user touched the screen.
 159    *
 160    * This is always a positive value.
 161    * @SINCE_1_0.0
 162    * @return The distance, as a float, a user's finger has panned
 163    */
 164   float GetDistance() const;
 165
 166   /**
 167    * @brief Returns the speed at which the user is moving their fingers relative to screen coordinates.
 168    *
 169    * This is the pixel movement per millisecond.
 170    * @SINCE_1_0.0
 171    * @return The speed of the pan (in pixels per millisecond)
 172    */
 173   float GetScreenSpeed() const;
 174
 175   /**
 176    * @brief This returns the distance the user has panned (dragged) since the last pan gesture in screen
 177    * coordinates or, if the gesture has just started, then the distance in screen coordinates moved
 178    * since the user touched the screen.
 179    *
 180    * This is always a positive value.
 181    * @SINCE_1_0.0
 182    * @return The distance, as a float, a user's finger has panned
 183    */
 184   float GetScreenDistance() const;
 185 };
 186
 187 /**
 188  * @}
 189  */
 190 } // namespace Dali
 191
 192 #endif // DALI_PAN_GESTURE_H