1 #ifndef __DALI_INTEGRATION_TOUCH_EVENT_COMBINER_H__
2 #define __DALI_INTEGRATION_TOUCH_EVENT_COMBINER_H__
5 * Copyright (c) 2014 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/public-api/common/vector-wrapper.h>
23 #include <dali/public-api/math/vector2.h>
24 #include <dali/integration-api/events/point.h>
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).
40 * The created TouchEvent and/or HoverEvent can then be sent to the Dali Core as indicated by the GetNextTouchEvent()
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.
49 class DALI_IMPORT_API TouchEventCombiner
55 enum EventDispatchType
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.
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.
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.
77 TouchEventCombiner( unsigned long minMotionTime, float minMotionXDistance, float minMotionYDistance );
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.
85 TouchEventCombiner( unsigned long minMotionTime, Vector2 minMotionDistance );
88 * Non virtual destructor
90 ~TouchEventCombiner();
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.
98 * @note If the thresholds set have not been passed, then false is returned and the TouchEvent and/or HoverEvent should not be sent
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.
106 * @return true if the point is beyond the different thresholds set thus, should be sent to core, false otherwise.
108 EventDispatchType GetNextTouchEvent( const Point& point, unsigned long time, TouchEvent& touchEvent, HoverEvent& hoverEvent );
111 * Sets the minimum time (in ms) that should occur between motion events.
112 * @param[in] minTime Minimum time between motion events.
114 void SetMinimumMotionTimeThreshold( unsigned long minTime );
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.
121 void SetMinimumMotionDistanceThreshold( float minDistance );
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.
130 void SetMinimumMotionDistanceThreshold( float minXDistance, float minYDistance );
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.
138 void SetMinimumMotionDistanceThreshold( Vector2 minDistance );
141 * Retrieves the minimum motion time threshold.
142 * @return the minimum time threshold.
144 unsigned long GetMinimumMotionTimeThreshold() const;
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.
150 Vector2 GetMinimumMotionDistanceThreshold() const;
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.
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.
166 unsigned long 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.
170 } // namespace Integration
174 #endif // __DALI_INTEGRATION_TOUCH_EVENT_COMBINER_H__