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

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