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