1 #ifndef DALI_INTEGRATION_TOUCH_EVENT_COMBINER_H
2 #define DALI_INTEGRATION_TOUCH_EVENT_COMBINER_H
5 * Copyright (c) 2020 Samsung Electronics Co., Ltd.
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
11 * http://www.apache.org/licenses/LICENSE-2.0
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.
22 #include <dali/integration-api/events/point.h>
23 #include <dali/public-api/common/vector-wrapper.h>
24 #include <dali/public-api/math/vector2.h>
34 * Dali::Integration::TouchEventCombiner is a utility class, an instance of which, should be created
35 * upon initialisation. It accepts single Point(s) containing information about a touch area and
36 * creates a TouchEvent and/or HoverEvent combining the latest event's information with previous Point(s).
38 * The created TouchEvent and/or HoverEvent can then be sent to the Dali Core as indicated by the GetNextTouchEvent()
41 * The TouchEventCombiner ensures that the following rules are also adhered to:
42 * - If two Down events are accidentally received, then the second one is ignored.
43 * - Motion events are not processed if a Down event does not precede it.
44 * - Motion event throttling is carried out to satisfy the minimum distance and time delta required.
45 * - If an interrupted event is received, then any stored Point history is cleared.
47 class DALI_CORE_API TouchEventCombiner
52 enum EventDispatchType
54 DISPATCH_TOUCH, ///< The touch event should be dispatched.
55 DISPATCH_HOVER, ///< The hover event should be dispatched.
56 DISPATCH_BOTH, ///< Both touch event and hover event should be dispatched.
57 DISPATCH_NONE ///< Neither touch event nor hover event should be dispatched.
61 * Default Constructor.
62 * @note The default minimum motion time is 1 ms between motion events and the default behaviour
63 * is to throttle X and Y movement by 1.
68 * Construction with parameters.
69 * @param[in] minMotionTime The minimum time (in ms) that should occur between motion events.
70 * @param[in] minMotionXDistance The minimum distance a finger has to be moved between horizontal motion events.
71 * @param[in] minMotionYDistance The minimum distance a finger has to be moved between vertical motion events.
72 * @note Will assert if any of the parameters is negative.
74 TouchEventCombiner(uint32_t minMotionTime, float minMotionXDistance, float minMotionYDistance);
77 * Construction with parameters.
78 * @param[in] minMotionTime The minimum time (in ms) that should occur between motion events.
79 * @param[in] minMotionDistance A Vector2 representing the minimum distance a finger has to be moved between horizontal and vertical motion events.
80 * @note Will assert if any of the parameters is negative.
82 TouchEventCombiner(uint32_t minMotionTime, Vector2 minMotionDistance);
85 * Non virtual destructor
87 ~TouchEventCombiner();
91 * Allows the caller to pass in a point which is processed and the TouchEvent and/or HoverEvent is appropriately filled with the new,
92 * and previously stored Point information.
94 * @note If the thresholds set have not been passed, then false is returned and the TouchEvent and/or HoverEvent should not be sent
97 * @param[in] point The new Point.
98 * @param[in] time The time the event occurred.
99 * @param[out] touchEvent This is populated with the correct Point(s) and time information.
100 * @param[out] hoverEvent This is populated with the correct Point(s) and time information.
102 * @return true if the point is beyond the different thresholds set thus, should be sent to core, false otherwise.
104 EventDispatchType GetNextTouchEvent(const Point& point, uint32_t time, TouchEvent& touchEvent, HoverEvent& hoverEvent);
107 * Sets the minimum time (in ms) that should occur between motion events.
108 * @param[in] minTime Minimum time between motion events.
110 void SetMinimumMotionTimeThreshold(uint32_t minTime);
113 * Sets the minimum distance a finger has to be moved (both X and Y) between motion events.
114 * @param[in] minDistance The minimum distance between motion events.
115 * @note Will assert if parameter is negative.
117 void SetMinimumMotionDistanceThreshold(float minDistance);
120 * Sets the minimum distance a finger has to be moved between motion events.
121 * @param[in] minXDistance The minimum X distance between motion events.
122 * @param[in] minYDistance The minimum Y distance between motion events.
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.
126 void SetMinimumMotionDistanceThreshold(float minXDistance, float minYDistance);
129 * Sets the minimum distance a finger has to be moved between motion events.
130 * @param[in] minDistance A Vector2 representing the minimum X and Y thresholds.
131 * @note Use this method if the X and Y threshold required is different.
132 * @note Will assert if any of the parameters is negative.
134 void SetMinimumMotionDistanceThreshold(Vector2 minDistance);
137 * Retrieves the minimum motion time threshold.
138 * @return the minimum time threshold.
140 unsigned long GetMinimumMotionTimeThreshold() const;
143 * Gets the minimum distance a finger has to be moved (both X and Y) between motion events.
144 * @return A Vector2 representing the x and y thresholds.
146 Vector2 GetMinimumMotionDistanceThreshold() const;
149 * This resets any information contained by the TouchEventCombiner.
150 * This may be required if some platform event has occurred which makes it necessary to reset any
151 * Point information that the combiner may store.
157 typedef std::vector<PointInfo> PointInfoContainer;
158 PointInfoContainer mPressedPoints; ///< A container of touched point and time.
159 PointInfoContainer mHoveredPoints; ///< A container of hovered point and time.
161 uint32_t mMinMotionTime; ///< The minimum time that should elapse before considering a new motion event.
162 Vector2 mMinMotionDistance; ///< The minimum distance in the X and Y direction before considering a new motion event.
165 } // namespace Integration
169 #endif // DALI_INTEGRATION_TOUCH_EVENT_COMBINER_H