dali/integration-api/events/touch-event-combiner.h

   1 #ifndef __DALI_INTEGRATION_TOUCH_EVENT_COMBINER_H__
   2 #define __DALI_INTEGRATION_TOUCH_EVENT_COMBINER_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/common/vector-wrapper.h>
  23 #include <dali/public-api/events/touch-point.h>
  24 #include <dali/public-api/math/vector2.h>
  25
  26 namespace Dali DALI_IMPORT_API
  27 {
  28
  29 namespace Integration
  30 {
  31
  32 struct TouchEvent;
  33
  34 /**
  35  * Dali::Integration::TouchEventCombiner is a utility class, an instance of which, should be created
  36  * upon initialisation.  It accepts single Point(s) containing information about a touch area and
  37  * creates a TouchEvent combining the latest event's information with previous TouchPoint(s).
  38  *
  39  * The created TouchEvent can then be sent to the Dali Core as indicated by the GetNextTouchEvent()
  40  * method.
  41  *
  42  * The TouchEventCombiner ensures that the following rules are also adhered to:
  43  * - If two Down events are accidentally received, then the second one is ignored.
  44  * - Motion events are not processed if a Down event does not precede it.
  45  * - Motion event throttling is carried out to satisfy the minimum distance and time delta required.
  46  * - If an interrupted event is received, then any stored Point history is cleared.
  47  */
  48 class TouchEventCombiner
  49 {
  50 public:
  51
  52   /**
  53    * Default Constructor.
  54    * @note The default minimum motion time is 1 ms between motion events and the default behaviour
  55    *       is to throttle X and Y movement by 1.
  56    */
  57   TouchEventCombiner();
  58
  59   /**
  60    * Construction with parameters.
  61    * @param[in]  minMotionTime       The minimum time (in ms) that should occur between motion events.
  62    * @param[in]  minMotionXDistance  The minimum distance a finger has to be moved between horizontal motion events.
  63    * @param[in]  minMotionYDistance  The minimum distance a finger has to be moved between vertical motion events.
  64    * @note Will assert if any of the parameters is negative.
  65    */
  66   TouchEventCombiner( unsigned long minMotionTime, float minMotionXDistance, float minMotionYDistance );
  67
  68   /**
  69    * Construction with parameters.
  70    * @param[in]  minMotionTime      The minimum time (in ms) that should occur between motion events.
  71    * @param[in]  minMotionDistance  A Vector2 representing the minimum distance a finger has to be moved between horizontal and vertical motion events.
  72    * @note Will assert if any of the parameters is negative.
  73    */
  74   TouchEventCombiner( unsigned long minMotionTime, Vector2 minMotionDistance );
  75
  76   /**
  77    * Non virtual destructor
  78    */
  79   ~TouchEventCombiner();
  80
  81 public:
  82
  83   /**
  84    * Allows the caller to pass in a point which is processed and the TouchEvent is appropriately filled with the new,
  85    * and previously stored Point information.
  86    *
  87    * @note If the thresholds set have not been passed, then false is returned and the TouchEvent should not be sent
  88    * to Dali Core.
  89    *
  90    * @param[in]   point         The new Point.
  91    * @param[in]   time          The time the event occurred.
  92    * @param[out]  touchEvent    This is populated with the correct Point(s) and time information.
  93    *
  94    * @return true if the point is beyond the different thresholds set thus, should be sent to core, false otherwise.
  95    */
  96   bool GetNextTouchEvent( const TouchPoint& point, unsigned long time, TouchEvent& touchEvent );
  97
  98   /**
  99    * Sets the minimum time (in ms) that should occur between motion events.
 100    * @param[in]  minTime  Minimum time between motion events.
 101    */
 102   void SetMinimumMotionTimeThreshold( unsigned long minTime );
 103
 104   /**
 105    * Sets the minimum distance a finger has to be moved (both X and Y) between motion events.
 106    * @param[in]  minDistance  The minimum distance between motion events.
 107    * @note Will assert if parameter is negative.
 108    */
 109   void SetMinimumMotionDistanceThreshold( float minDistance );
 110
 111   /**
 112    * Sets the minimum distance a finger has to be moved between motion events.
 113    * @param[in]  minXDistance  The minimum X distance between motion events.
 114    * @param[in]  minYDistance  The minimum Y distance between motion events.
 115    * @note Use this method if the X and Y threshold required is different.
 116    * @note Will assert if any of the parameters is negative.
 117    */
 118   void SetMinimumMotionDistanceThreshold( float minXDistance, float minYDistance );
 119
 120   /**
 121    * Sets the minimum distance a finger has to be moved between motion events.
 122    * @param[in]  minDistance  A Vector2 representing the minimum X and Y thresholds.
 123    * @note Use this method if the X and Y threshold required is different.
 124    * @note Will assert if any of the parameters is negative.
 125    */
 126   void SetMinimumMotionDistanceThreshold( Vector2 minDistance );
 127
 128   /**
 129    * Retrieves the minimum motion time threshold.
 130    * @return the minimum time threshold.
 131    */
 132   unsigned long GetMinimumMotionTimeThreshold() const;
 133
 134   /**
 135    * Gets the minimum distance a finger has to be moved (both X and Y) between motion events.
 136    * @return A Vector2 representing the x and y thresholds.
 137    */
 138   Vector2 GetMinimumMotionDistanceThreshold() const;
 139
 140   /**
 141    * This resets any information contained by the TouchEventCombiner.
 142    * This may be required if some platform event has occurred which makes it necessary to reset any
 143    * TouchPoint information that the combiner may store.
 144    */
 145   void Reset();
 146
 147 private:
 148
 149   struct PointInfo;
 150   typedef std::vector< PointInfo > PointInfoContainer;
 151   PointInfoContainer mPressedPoints; ///< A container of point and time.
 152
 153   unsigned long mMinMotionTime; ///< The minimum time that should elapse before considering a new motion event.
 154   Vector2 mMinMotionDistance; ///< The minimum distance in the X and Y direction before considering a new motion event.
 155 };
 156
 157 } // namespace Integration
 158
 159 } // namespace Dali
 160
 161 #endif // __DALI_INTEGRATION_TOUCH_EVENT_COMBINER_H__