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

   1 #ifndef __DALI_PAN_GESTURE_H__
   2 #define __DALI_PAN_GESTURE_H__
   3
   4 /*
   5  * Copyright (c) 2015 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: "Started";
  36  * when the pan gesture is continuing: "Continuing"; and finally, when the pan gesture ends:
  37  * "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  */
  47 struct DALI_IMPORT_API PanGesture: public Gesture
  48 {
  49   // Construction & Destruction
  50
  51   /**
  52    * @brief Default Constructor.
  53    */
  54   PanGesture();
  55
  56   /**
  57    * @brief Constructor.
  58    *
  59    * @param[in]  state  The state of the gesture
  60    */
  61   PanGesture(Gesture::State state);
  62
  63   /**
  64    * @brief Copy constructor.
  65    */
  66   PanGesture( const PanGesture& rhs );
  67
  68   /**
  69    * @brief Assignment operator.
  70    */
  71   PanGesture& operator=( const PanGesture& rhs );
  72
  73   /**
  74    * @brief Virtual destructor.
  75    */
  76   virtual ~PanGesture();
  77
  78   // Data
  79
  80   /**
  81    * @brief The velocity at which the user is moving their fingers.
  82    *
  83    * This is represented as a Vector2 and is the pixel movement per millisecond.
  84    * A positive x value shows that the user is panning to the right, a negative x value means the opposite.
  85    * A positive y value shows that the user is panning downwards, a negative y values means upwards.
  86    * This value represents the local coordinates of the actor attached to the PanGestureDetector.
  87    */
  88   Vector2 velocity;
  89
  90   /**
  91    * @brief This is a Vector2 showing how much the user has panned (dragged) since the last pan gesture or,
  92    * if the gesture has just started, then the amount panned since the user touched the screen.
  93    *
  94    * A positive x value shows that the user is panning to the right, a negative x value means the opposite.
  95    * A positive y value shows that the user is panning downwards, a negative y value means upwards.
  96    * This value is in local actor coordinates, the actor being the one attached to the
  97    * PanGestureDetector.
  98    */
  99   Vector2 displacement;
 100
 101   /**
 102    * @brief This current touch position of the primary touch point in local actor coordinates.
 103    */
 104   Vector2 position;
 105
 106   /**
 107    * @brief The velocity at which the user is moving their fingers.
 108    *
 109    * This is represented as a Vector2 and is the pixel movement per millisecond.
 110    * A positive x value shows that the user is panning to the right, a negative x value means the opposite.
 111    * A positive y value shows that the user is panning downwards, a negative y values means upwards.
 112    * This value represents the screen coordinates.
 113    */
 114   Vector2 screenVelocity;
 115
 116   /**
 117    * @brief This is a Vector2 showing how much the user has panned (dragged) since the last pan gesture or,
 118    * if the gesture has just started, then the amount panned since the user touched the screen.
 119    *
 120    * A positive x value shows that the user is panning to the right, a negative x value means the opposite.
 121    * A positive y value shows that the user is panning downwards, a negative y value means upwards.
 122    * This value is in screen coordinates.
 123    */
 124   Vector2 screenDisplacement;
 125
 126   /**
 127    * @brief This current touch position of the primary touch point in screen coordinates.
 128    */
 129   Vector2 screenPosition;
 130
 131   /**
 132    * @brief The total number of fingers touching the screen in a pan gesture.
 133    */
 134   unsigned int numberOfTouches;
 135
 136   // Convenience Methods
 137
 138   /**
 139    * @brief Returns the speed at which the user is moving their fingers.
 140    *
 141    * This is the pixel movement per millisecond.
 142    * @return The speed of the pan (in pixels per millisecond).
 143    */
 144   float GetSpeed() const;
 145
 146   /**
 147    * @brief This returns the distance the user has panned (dragged) since the last pan gesture or,
 148    * if the gesture has just started, then the distance moved since the user touched the screen.
 149    *
 150    * This is always a positive value.
 151    * @return The distance, as a float, a user's finger has panned.
 152    */
 153   float GetDistance() const;
 154
 155   /**
 156    * @brief Returns the speed at which the user is moving their fingers relative to screen coordinates.
 157    *
 158    * This is the pixel movement per millisecond.
 159    * @return The speed of the pan (in pixels per millisecond).
 160    */
 161   float GetScreenSpeed() const;
 162
 163   /**
 164    * @brief This returns the distance the user has panned (dragged) since the last pan gesture in screen
 165    * coordinates or, if the gesture has just started, then the distance in screen coordinates moved
 166    * since the user touched the screen.
 167    *
 168    * This is always a positive value.
 169    * @return The distance, as a float, a user's finger has panned.
 170    */
 171   float GetScreenDistance() const;
 172 };
 173
 174 /**
 175  * @}
 176  */
 177 } // namespace Dali
 178
 179 #endif // __DALI_PAN_GESTURE_H__