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