1 #ifndef DALI_TOOLKIT_SCROLL_VIEW_H
2 #define DALI_TOOLKIT_SCROLL_VIEW_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/public-api/animation/alpha-function.h>
25 #include <dali-toolkit/public-api/controls/scrollable/scrollable.h>
31 namespace Internal DALI_INTERNAL
36 * @addtogroup dali_toolkit_controls_scroll_view
41 * @brief Enumeration for how axes/rotation or scale are clamped.
46 NOT_CLAMPED, ///< The quantity isn't clamped @SINCE_1_9.28
47 CLAMPED_TO_MIN, ///< The quantity is clamped to the min value @SINCE_1_9.28
48 CLAMPED_TO_MAX ///< The quantity is clamped to the max value @SINCE_1_9.28
52 * @brief A 2 dimensional clamp.
57 ClampState x; ///< The clamp state of the x axis
58 ClampState y; ///< The clamp state of the y axis
62 * @brief Enumeration for the snap type.
67 SNAP, ///< SNAP @SINCE_1_9.28
68 FLICK ///< FLICK @SINCE_1_9.28
72 * @brief Enumeration for DirectionBias types.
77 DIRECTION_BIAS_LEFT = -1, ///< Bias scroll snap to Left @SINCE_1_9.28
78 DIRECTION_BIAS_NONE = 0, ///< Don't bias scroll snap @SINCE_1_9.28
79 DIRECTION_BIAS_RIGHT = 1 ///< Bias scroll snap to Right @SINCE_1_9.28
83 * @brief Used for specifying minimum/maximum extents of a ruler.
86 class DALI_TOOLKIT_API RulerDomain
90 * @brief Creates Ruler domain allowing a point to traverse between min and max extents.
93 * @param[in] min Minimum extent (point cannot traverse less than this)
94 * @param[in] max Maximum extent (point cannot traverse greater than this)
95 * @param[in] enabled Whether domain has been enabled or not
97 explicit RulerDomain(float min, float max, bool enabled = true);
100 float min; ///< Minimum extent (point cannot traverse less than this)
101 float max; ///< Maximum extent (point cannot traverse greater than this)
102 bool enabled; ///< Whether domain has been enabled or not.
105 * @brief Clamps value (x) from (min) to (max).
107 * An optional length parameter can be specified to suggest that the
108 * subject is not a point but a line to that should be clamped.
111 * @param[in] x X point to be clamped between (min) and (max) extents
112 * @param[in] length (optional) The Length of the line from (x) to (x + length) to be clamped
113 * @param[in] scale Scaling parameter which treats domain as scaled in calculations
114 * @return The clamped value
116 float Clamp(float x, float length = 0.0f, float scale = 1.0f) const;
119 * @brief Clamps value (x) from (min) to (max).
121 * An optional length parameter can be specified to suggest that the
122 * subject is not a point but a line to that should be clamped.
125 * @param[in] x X point to be clamped between (min) and (max) extents
126 * @param[in] length (optional) The Length of the line from (x) to (x + length) to be clamped
127 * @param[in] scale Scaling parameter which treats domain as scaled in calculations
128 * @param[out] clamped Whether clamping occurred and which size (None, Min or Max)
129 * @return The clamped value
131 float Clamp(float x, float length, float scale, ClampState& clamped) const;
134 * @brief Returns (max-min) size of ruler.
137 * @return The size of the ruler from min to max
139 float GetSize() const;
142 // Forward declare future extension interface
143 class RulerExtension;
146 * @brief Abstracts class to define scroll axes.
148 * It can specify whether they are traversable,
149 * where their snap points are and their domain.
152 class DALI_TOOLKIT_API Ruler : public RefObject
156 * @brief Enumeration for the type of the ruler.
161 FIXED, ///< A fixed ruler @SINCE_1_9.28
162 FREE ///< A free ruler @SINCE_1_9.28
167 * @brief Constructs ruler, enabled by default, with limitless domain.
173 * @brief Snaps (x) in accordance to the ruler settings.
176 * @param[in] x The input value on the ruler to be snapped
177 * @param[in] bias (optional) The biasing employed for snapping
178 * 0 floor input (floor x) "Used for Flick Left"
179 * 0.5 round input (floor x + 0.5) "Used for Release"
180 * 1 ceil input (floor x + 1.0) "Used for Flick Right"
181 * @return The position of the one dimensional point passed in once snapped.
183 virtual float Snap(float x, float bias = 0.5f) const = 0;
186 * @brief Returns position from page, based on whatever the ruler
189 * If (wrap) is true, then will set volume to the number of
190 * times page has exceeded the domain's volume (volume being the
191 * number of pages within the domain), while wrapping the position
195 * @param[in] page The page index
196 * @param[out] volume The overflow volume when the page exceeds the domain (wrap must be enabled)
197 * @param[in] wrap Enable wrap mode
198 * @return The position representing this page point
200 virtual float GetPositionFromPage(unsigned int page, unsigned int& volume, bool wrap) const = 0;
203 * @brief Returns page from position, based on whatever the ruler
206 * If (wrap) is true, then will return a page wrapped within the domain.
209 * @param[in] position The position on the domain
210 * @param[in] wrap Enable wrap mode
211 * @return The page where this position resides
213 virtual unsigned int GetPageFromPosition(float position, bool wrap) const = 0;
216 * @brief Returns the total number of pages within this Ruler.
219 * @return The number of pages in the Ruler
221 virtual unsigned int GetTotalPages() const = 0;
224 * @brief Gets the extension interface of the Ruler.
227 * @return The extension interface of the Ruler
229 virtual RulerExtension* GetExtension()
236 * @brief Gets the ruler type.
239 * @return The ruler type
241 Ruler::RulerType GetType() const;
244 * @brief Returns whether this axis has been enabled or not.
247 * @return true if axis is enabled
249 bool IsEnabled() const;
252 * @brief Enables ruler (ruler must be enabled in order to traverse along it).
258 * @brief Disables ruler.
264 * @brief Sets the Domain.
267 * @param[in] domain Ruler domain object
269 void SetDomain(RulerDomain domain);
272 * @brief Gets the Domain.
277 const RulerDomain& GetDomain() const;
280 * @brief Disables Domain (minimum/maximum extents for this axis).
283 void DisableDomain();
286 * @brief Clamps value (x) from (min) to (max).
288 * An optional length parameter can be specified to suggest that the
289 * subject is not a point but a line that should be clamped.
292 * @param[in] x X point to be clamped between (min) and (max) extents
293 * @param[in] length (optional) The Length of the line from (x) to (x + length) to be clamped
294 * @param[in] scale Scaling parameter which treats domain as scaled in calculations
295 * @return The clamped value
297 float Clamp(float x, float length = 0.0f, float scale = 1.0f) const;
300 * @brief Clamps value (x) from (min) to (max).
302 * An optional length parameter can be specified to suggest that the
303 * subject is not a point but a line to that should be clamped.
306 * @param[in] x X point to be clamped between (min) and (max) extents
307 * @param[in] length (optional) The Length of the line from (x) to (x + length) to be clamped
308 * @param[in] scale Scaling parameter which treats domain as scaled in calculations
309 * @param[out] clamped Whether clamping occurred and which size (None, Min or Max)
310 * @return The clamped value
312 float Clamp(float x, float length, float scale, ClampState& clamped) const;
315 * @brief Snaps and Clamps (x) in accordance to ruler settings.
318 * @param[in] x X value to be snapped in accordance to ruler snap value,
319 * and clamped in accordance to the ruler's domain (if set)
320 * @param[in] bias (optional) The biasing employed for snapping
321 * 0 floor input (floor x) "Used for Flick Left"
322 * 0.5 round input (floor x + 0.5) "Used for Release"
323 * 1 ceil input (floor x + 1.0) "Used for Flick Right"
324 * @param[in] length (optional) The Length of the line from (x) to (x + length)
326 * @param[in] scale Scaling parameter which treats domain as scaled in calculations
327 * @return The clamped value after snapping
329 float SnapAndClamp(float x, float bias = 0.5f, float length = 0.0f, float scale = 1.0f) const;
332 * @brief Snaps and Clamps (x) in accordance to ruler settings.
335 * @param[in] x X value to be snapped in accordance to ruler snap value,
336 * and clamped in accordance to the ruler's domain (if set)
337 * @param[in] bias (optional) The biasing employed for snapping
338 * 0 floor input (floor x) "Used for Flick Left"
339 * 0.5 round input (floor x + 0.5) "Used for Release"
340 * 1 ceil input (floor x + 1.0) "Used for Flick Right"
341 * @param[in] length (optional) The Length of the line from (x) to (x + length)
343 * @param[in] scale Scaling parameter which treats domain as scaled in calculations
344 * @param[out] clamped Whether clamping occurred and which size (None, Min or Max)
345 * @return The clamped value after snapping
347 float SnapAndClamp(float x, float bias, float length, float scale, ClampState& clamped) const;
351 * @brief Destructor - A reference counted object may only be deleted by calling Unreference().
357 RulerType mType; ///< Type of Ruler (FIXED or FREE).
358 bool mEnabled; ///< If the ruler is enabled.
359 RulerDomain mDomain; ///< The domain of the ruler.
362 typedef IntrusivePtr<Ruler> RulerPtr; ///< Pointer to Dali::Toolkit::Ruler object @SINCE_1_0.0
365 * @brief Concrete implementation of Ruler that has no snapping and has one single page.
368 class DALI_TOOLKIT_API DefaultRuler : public Ruler
372 * @brief DefaultRuler constructor.
378 * @copydoc Toolkit::Ruler::Snap
380 float Snap(float x, float bias) const override;
383 * @copydoc Toolkit::Ruler::GetPositionFromPage
385 float GetPositionFromPage(unsigned int page, unsigned int& volume, bool wrap) const override;
388 * @copydoc Toolkit::Ruler::GetPageFromPosition
390 unsigned int GetPageFromPosition(float position, bool wrap) const override;
393 * @copydoc Toolkit::Ruler::GetTotalPages
395 unsigned int GetTotalPages() const override;
399 * @brief Concrete implementation of Ruler that has fixed snapping.
402 class DALI_TOOLKIT_API FixedRuler : public Ruler
406 * @brief Constructor.
409 * @param[in] spacing The spacing between each interval on this ruler
411 FixedRuler(float spacing = 1.0f);
414 * @copydoc Toolkit::Ruler::Snap
416 float Snap(float x, float bias) const override;
419 * @copydoc Toolkit::Ruler::GetPositionFromPage
421 float GetPositionFromPage(unsigned int page, unsigned int& volume, bool wrap) const override;
424 * @copydoc Toolkit::Ruler::GetPageFromPosition
426 unsigned int GetPageFromPosition(float position, bool wrap) const override;
429 * @copydoc Toolkit::Ruler::GetTotalPages
431 unsigned int GetTotalPages() const override;
434 float mSpacing; ///< The spacing between each interval
437 class ScrollViewEffect;
441 * @brief ScrollView contains actors that can be scrolled manually (via touch)
445 * | %Signal Name | Method |
446 * |-------------------|----------------------------|
447 * | snap-started | @ref SnapStartedSignal() |
450 class DALI_TOOLKIT_API ScrollView : public Scrollable
454 * @brief Clamps signal event's data.
459 ClampState2D scale; ///< Clamp information for scale axes
460 ClampState2D position; ///< Clamp information for position axes
461 ClampState rotation; ///< Clamp information for rotation
465 * @brief Snaps signal event's data.
470 SnapType type; ///< Current snap commencing
471 Vector2 position; ///< Target snap position
472 float duration; ///< Duration of snap animation.
476 * @brief Enumeration for the start and end property ranges for this control.
481 PROPERTY_START_INDEX = Toolkit::Scrollable::PROPERTY_END_INDEX + 1, ///< @SINCE_1_1.18
482 PROPERTY_END_INDEX = PROPERTY_START_INDEX + 1000, ///< Reserve property indices, @SINCE_1_1.18
484 ANIMATABLE_PROPERTY_START_INDEX = Toolkit::Scrollable::ANIMATABLE_PROPERTY_END_INDEX + 1,
485 ANIMATABLE_PROPERTY_END_INDEX = ANIMATABLE_PROPERTY_START_INDEX + 1000 ///< Reserve animatable property indices @SINCE_1_0.0
489 * @brief Enumeration for the instance of properties belonging to the ScrollView class.
495 * @brief Enumeration for the instance of properties belonging to the ScrollView class.
500 ///////////////////////////////////////////////////////////////////////////////
501 // Event side (non-animatable) properties
502 ///////////////////////////////////////////////////////////////////////////////
505 * @brief Whether wrapping is enabled.
506 * @details Name "wrapEnabled", type Property::BOOLEAN.
510 WRAP_ENABLED = PROPERTY_START_INDEX,
513 * @brief Whether panning is enabled.
514 * @details Name "panningEnabled", type Property::BOOLEAN.
516 * @see SetScrollSensitive()
521 * @brief Whether the Axis Auto Lock mode for panning within the ScrollView is enabled.
522 * @details Name "axisAutoLockEnabled", type Property::BOOLEAN.
524 * @see SetAxisAutoLock()
526 AXIS_AUTO_LOCK_ENABLED,
529 * @brief The step of scroll distance in actor coordinates for each wheel event received in free panning mode.
530 * @details Name "wheelScrollDistanceStep", type Property::VECTOR2.
532 * @see SetWheelScrollDistanceStep()
534 WHEEL_SCROLL_DISTANCE_STEP,
537 * @brief The scroll mode.
538 * @details Name "scrollMode", type Property::MAP.
539 * The scroll mode map is a frontend for the Ruler helper class, containing the following keys:
541 * | %Property Name | Type | Required | Description |
542 * |----------------------|----------|----------|---------------------------------------------------------------------------------------------------------------------------------------|
543 * | xAxisScrollEnabled | BOOLEAN | No | True if the content can be scrolled in X axis or false if not. |
544 * | xAxisSnapToInterval | FLOAT | No | When set, causes scroll view to snap to multiples of the value of the interval in the X axis while flicking. (by default no snapping) |
545 * | xAxisScrollBoundary | FLOAT | No | When set, causes scroll view unable to scroll beyond the value of the boundary in the X axis (by default no boundary) |
546 * | yAxisScrollEnabled | BOOLEAN | No | True if the content can be scrolled in Y axis or false if not. |
547 * | yAxisSnapToInterval | FLOAT | No | When set, causes scroll view to snap to multiples of the value of the interval in the Y axis while flicking. (by default no snapping) |
548 * | yAxisScrollBoundary | FLOAT | No | When set, causes scroll view unable to scroll beyond the value of the boundary in the Y axis (by default no boundary) |
550 * Alternatively, one can use the keys defined in the Dali::Toolkit::ScrollMode::Type enumeration.
555 ///////////////////////////////////////////////////////////////////////////////
556 // Animatable Properties
557 ///////////////////////////////////////////////////////////////////////////////
560 * @brief The current scroll position.
561 * @details Name "scrollPosition", type Property::VECTOR2.
564 SCROLL_POSITION = ANIMATABLE_PROPERTY_START_INDEX,
567 * @brief The position before we set the clamp at scroll boundaries.
568 * @details Name "scrollPrePosition", type Property::VECTOR2.
574 * @brief The X component of SCROLL_PRE_POSITION.
575 * @details Name "scrollPrePositionX", type Property::FLOAT.
578 SCROLL_PRE_POSITION_X,
581 * @brief The Y component of SCROLL_PRE_POSITION.
582 * @details Name "scrollPrePositionY", type Property::VECTOR2.
585 SCROLL_PRE_POSITION_Y,
588 * @brief The maximum value that SCROLL_PRE_POSITION can be.
589 * @details Name "scrollPrePositionMax", type Property::VECTOR2.
592 SCROLL_PRE_POSITION_MAX,
595 * @brief The X component of SCROLL_PRE_POSITION_MAX.
596 * @details Name "scrollPrePositionMaxX", type Property::FLOAT.
599 SCROLL_PRE_POSITION_MAX_X,
602 * @brief The Y component of SCROLL_PRE_POSITION_MAX.
603 * @details Name "scrollPrePositionMaxY", type Property::FLOAT.
606 SCROLL_PRE_POSITION_MAX_Y,
609 * @brief The amount that we can scroll beyond the boundary along the X axis.
610 * @details Name "overshootX", type Property::FLOAT.
616 * @brief The amount that we can scroll beyond the boundary along the Y axis.
617 * @details Name "overshootY", type Property::FLOAT.
623 * @brief The position after the overshoot value has been considered in the calculation.
624 * @details Name "scrollFinal", type Property::VECTOR2.
630 * @brief The X component of SCROLL_FINAL.
631 * @details Name "scrollFinalX", type Property::FLOAT.
637 * @brief The Y component of SCROLL_FINAL.
638 * @details Name "scrollFinalY", type Property::FLOAT.
644 * @brief Whether scrolling wraps.
645 * @details Name "wrap", type Property::BOOLEAN.
651 * @brief Whether we are currently panning.
652 * @details Name "panning", type Property::BOOLEAN.
658 * @brief Whether we are currently scrolling.
659 * @details Name "scrolling", type Property::BOOLEAN.
665 * @brief The size of the scrolling domain.
666 * @details Name "scrollDomainSize", type Property::VECTOR2.
672 * @brief The X component of SCROLL_DOMAIN_SIZE.
673 * @details Name "scrollDomainSizeX", type Property::FLOAT.
676 SCROLL_DOMAIN_SIZE_X,
679 * @brief The Y component of SCROLL_DOMAIN_SIZE.
680 * @details Name "scrollDomainSizeY", type Property::FLOAT.
683 SCROLL_DOMAIN_SIZE_Y,
686 * @brief The offset of the scroll domain.
687 * @details Name "scrollDomainOffset", type Property::VECTOR2.
690 SCROLL_DOMAIN_OFFSET,
693 * @brief The delta in the position when scrolling.
694 * @details Name "scrollPositionDelta", type Property::VECTOR2.
697 SCROLL_POSITION_DELTA,
700 * @brief The starting page position.
701 * @details Name "startPagePosition", type Property::VECTOR3.
710 typedef Signal<void(const SnapEvent&)> SnapStartedSignalType; ///< SnapStarted signal type @SINCE_1_0.0
714 * @brief Creates an empty ScrollView handle.
720 * @brief Copy constructor.
722 * Creates another handle that points to the same real object.
725 * @param[in] handle Handle to copy from
727 ScrollView(const ScrollView& handle);
730 * @brief Move constructor
733 * @param[in] rhs A reference to the moved handle
735 ScrollView(ScrollView&& rhs) noexcept;
738 * @brief Assignment operator.
740 * Changes this handle to point to another real object.
742 * @param[in] handle The handle to copy from
743 * @return A reference to this
745 ScrollView& operator=(const ScrollView& handle);
748 * @brief Move assignment
751 * @param[in] rhs A reference to the moved handle
752 * @return A reference to this
754 ScrollView& operator=(ScrollView&& rhs) noexcept;
759 * This is non-virtual since derived Handle types must not contain data or virtual methods.
765 * @brief Creates an initialized ScrollView.
768 * @return A handle to a newly allocated Dali resource
770 static ScrollView New();
773 * @brief Downcasts a handle to ScrollView handle.
775 * If handle points to a ScrollView, the downcast produces valid handle.
776 * If not, the returned handle is left uninitialized.
779 * @param[in] handle Handle to an object
780 * @return A handle to a ScrollView or an uninitialized handle
782 static ScrollView DownCast(BaseHandle handle);
786 * @brief Gets snap-animation's AlphaFunction.
789 * @return Current easing alpha function of the snap animation
791 AlphaFunction GetScrollSnapAlphaFunction() const;
794 * @brief Sets snap-animation's AlphaFunction.
797 * @param[in] alpha Easing alpha function of the snap animation
799 void SetScrollSnapAlphaFunction(AlphaFunction alpha);
802 * @brief Gets flick-animation's AlphaFunction.
805 * @return Current easing alpha function of the flick animation
807 AlphaFunction GetScrollFlickAlphaFunction() const;
810 * @brief Sets flick-animation's AlphaFunction.
813 * @param[in] alpha Easing alpha function of the flick animation
815 void SetScrollFlickAlphaFunction(AlphaFunction alpha);
818 * @brief Gets the time for the scroll snap-animation.
820 * This animation occurs when the user drags, and releases.
823 * @return The time in seconds for the animation to take
825 float GetScrollSnapDuration() const;
828 * @brief Sets the time for the scroll snap-animation.
830 * This animation occurs when the user drags, and releases.
833 * @param[in] time The time in seconds for the animation to take
835 void SetScrollSnapDuration(float time);
838 * @brief Gets the time for the scroll flick-animation.
840 * This animation occurs when the user flicks scroll view.
843 * @return The time in seconds for the animation to take
845 float GetScrollFlickDuration() const;
848 * @brief Sets the time for the scroll flick-animation.
850 * This animation occurs when the user flicks scroll view.
853 * @param[in] time The time in seconds for the animation to take
855 void SetScrollFlickDuration(float time);
858 * @brief Sets X axis ruler.
860 * Defines how scrolling horizontally is snapped, and
861 * the boundary (domain) in which the ScrollView can pan.
864 * @param[in] ruler The ruler to be used for the X axis
866 void SetRulerX(RulerPtr ruler);
869 * @brief Sets Y axis ruler.
871 * Defines how scrolling vertically is snapped, and the boundary
872 * (domain) in which the ScrollView can pan.
875 * @param[in] ruler The ruler to be used for the Y axis
877 void SetRulerY(RulerPtr ruler);
880 * @brief Sets scroll sensitivity of pan gesture.
883 * @param[in] sensitive @c true to enable scroll, @c false to disable scrolling
884 * @note Unlike Actor::Property::SENSITIVE, this determines whether this ScrollView
885 * should react (e.g. pan), without disrupting the sensitivity of its children.
888 void SetScrollSensitive(bool sensitive);
891 * @brief Sets maximum overshoot amount.
893 * The final overshoot value is within 0.0f to 1.0f, but the maximum
894 * overshoot is in pixels (e.g. if you scroll 75 pixels beyond the
895 * edge of a scrollable area and the maximum overshoot is 100 then
896 * the final overshoot value will be 0.75f).
899 * @param[in] overshootX The maximum number of horizontally scrolled pixels before overshoot X reaches 1.0f
900 * @param[in] overshootY The maximum number of vertically scrolled pixels before overshoot Y reaches 1.0f
902 void SetMaxOvershoot(float overshootX, float overshootY);
905 * @brief Sets Snap Overshoot animation's AlphaFunction.
908 * @param[in] alpha Easing alpha function of the overshoot snap animation
910 void SetSnapOvershootAlphaFunction(AlphaFunction alpha);
913 * @brief Sets Snap Overshoot animation's Duration.
916 * @param[in] duration The duration of the overshoot snap animation
917 * @note Set duration to 0 seconds to disable Animation.
920 void SetSnapOvershootDuration(float duration);
923 * @brief Enables or Disables Actor Auto-Snap mode.
925 * When Actor Auto-Snap mode has been enabled, ScrollView will automatically
926 * snap to the closest actor (The closest actor will appear in the center of
930 * @param[in] enable Enables (true), or disables (false) Actor AutoSnap
932 void SetActorAutoSnap(bool enable);
935 * @brief Enables or Disables Wrap mode for ScrollView contents.
937 * When enabled, the ScrollView contents are wrapped over the X/Y Domain.
940 * @param[in] enable Enables (true), or disables (false) Wrap Mode
941 * @note You must apply a position constraint that causes Wrapping
945 void SetWrapMode(bool enable);
948 * @brief Gets the current distance needed to scroll for ScrollUpdatedSignal to be emitted.
951 * @return Current scroll update distance
953 int GetScrollUpdateDistance() const;
956 * @brief Sets the distance needed to scroll for ScrollUpdatedSignal to be emitted.
958 * The scroll update distance tells ScrollView how far to move before ScrollUpdatedSignal the informs application.
959 * Each time the ScrollView crosses this distance the signal will be emitted.
962 * @param[in] distance The distance for ScrollView to move before emitting update signal
964 void SetScrollUpdateDistance(int distance);
967 * @brief Returns state of Axis Auto Lock mode.
970 * @return Whether Axis Auto Lock mode has been enabled or not
972 bool GetAxisAutoLock() const;
975 * @brief Enables or Disables Axis Auto Lock mode for panning within the ScrollView.
977 * When enabled, any pan gesture that appears mostly horizontal or mostly
978 * vertical, will be automatically restricted to horizontal only or vertical
979 * only panning, until the pan gesture has completed.
982 * @param[in] enable Enables (true), or disables (false) AxisAutoLock mode
984 void SetAxisAutoLock(bool enable);
987 * @brief Gets the gradient threshold at which a panning gesture
988 * should be locked to the Horizontal or Vertical axis.
991 * @return The gradient, a value between 0.0 and 1.0f
993 float GetAxisAutoLockGradient() const;
996 * @brief Sets the gradient threshold at which a panning gesture should be locked to the
997 * Horizontal or Vertical axis.
999 * By default, this is 0.36 (0.36:1) which means angles less than 20
1000 * degrees to an axis will lock to that axis.
1003 * @param[in] gradient A value between 0.0 and 1.0 (auto-lock for all angles)
1004 * @note Specifying a value of 1.0 (the maximum value accepted) indicates that
1005 * all panning gestures will auto-lock either to the horizontal or vertical axis.
1008 void SetAxisAutoLockGradient(float gradient);
1011 * @brief Gets the friction coefficient setting for ScrollView when
1012 * flicking in free panning mode.
1014 * This is a value in stage-diagonals per second^2.
1015 * stage-diagonal = Length( stage.width, stage.height )
1017 * @return Friction coefficient is returned
1019 float GetFrictionCoefficient() const;
1022 * @brief Sets the friction coefficient for ScrollView when flicking
1023 * in free panning mode.
1025 * This is a value in stage-diagonals per second^2.
1026 * stage-diagonal = Length( stage.width, stage.height ).
1028 * A stage 480x800 in size has a diagonal length of 933.
1029 * Friction coefficient of 1.0 means the swipe velocity will
1030 * reduce by 1.0 * 933 pixels/sec^2.
1032 * @param[in] friction Friction coefficient must be greater than 0.0 (default = 1.0)
1034 void SetFrictionCoefficient(float friction);
1037 * @brief Gets the flick speed coefficient for ScrollView when
1038 * flicking in free panning mode.
1040 * This is a constant which multiplies the input touch
1041 * flick velocity to determine the actual velocity at
1042 * which to move the scrolling area.
1044 * @return The flick speed coefficient is returned
1046 float GetFlickSpeedCoefficient() const;
1049 * @brief Sets the flick speed coefficient for ScrollView when
1050 * flicking in free panning mode.
1052 * This is a constant which multiplies the input touch
1053 * flick velocity to determine the actual velocity at
1054 * which to move the scrolling area.
1056 * @param[in] speed The flick speed coefficient (default = 1.0)
1058 void SetFlickSpeedCoefficient(float speed);
1061 * @brief Returns the minimum pan distance required for a flick gesture in pixels.
1064 * @return Minimum pan distance vector with separate x and y distance
1066 Vector2 GetMinimumDistanceForFlick() const;
1069 * @brief Sets the minimum pan distance required for a flick in pixels.
1071 * Takes a Vector2 containing separate x and y values. As long as the pan distance exceeds one of these axes, a flick will be allowed.
1074 * @param[in] distance The minimum pan distance for a flick
1076 void SetMinimumDistanceForFlick(const Vector2& distance);
1079 * @brief Returns the minimum pan speed required for a flick gesture in pixels per second.
1082 * @return Minimum pan speed
1084 float GetMinimumSpeedForFlick() const;
1087 * @brief Sets the minimum pan speed required for a flick in pixels per second.
1090 * @param[in] speed The minimum pan speed for a flick
1092 void SetMinimumSpeedForFlick(float speed);
1095 * @brief Gets the maximum flick speed setting for ScrollView when
1096 * flicking in free panning mode.
1098 * This is a value in stage-diagonals per second.
1099 * stage-diagonal = Length( stage.width, stage.height )
1101 * @return Maximum flick speed is returned
1103 float GetMaxFlickSpeed() const;
1106 * @brief Sets the maximum flick speed for the ScrollView when
1107 * flicking in free panning mode.
1109 * This is a value in stage-diagonals per second.
1110 * stage-diagonal = Length( stage.width, stage.height )
1112 * A stage 480x800 in size has a diagonal length of 933.
1113 * Max Flick speed of 1.0 means the maximum velocity of
1114 * a swipe can be 1.0 * 933 pixels/sec.
1116 * @param[in] speed Maximum flick speed (default = 3.0)
1118 void SetMaxFlickSpeed(float speed);
1121 * @brief Gets the step of scroll distance in actor coordinates for
1122 * each wheel event received in free panning mode.
1125 * @return The step of scroll distance(pixel) in X and Y axes
1127 Vector2 GetWheelScrollDistanceStep() const;
1130 * @brief Sets the step of scroll distance in actor coordinates for
1131 * each wheel event received in free panning mode.
1134 * @param[in] step The step of scroll distance(pixel) in X and Y axes
1136 * @note If snap points are defined in the rulers, it will always
1137 * scroll to the next snap point towards the scroll direction while
1138 * receiving the wheel events.
1141 void SetWheelScrollDistanceStep(Vector2 step);
1144 * @brief Retrieves current scroll position.
1147 * @return The current scroll position
1149 Vector2 GetCurrentScrollPosition() const;
1152 * @brief Retrieves current scroll page based on ScrollView
1153 * dimensions being the size of one page, and all pages laid out in
1154 * a grid fashion, increasing from left to right until the end of
1158 * @note Pages start from 0 as the first page, not 1.
1160 * @return The Current page
1162 unsigned int GetCurrentPage() const;
1165 * @brief Scrolls View to position specified (contents will scroll to this position).
1167 * Position 0,0 is the origin. Increasing X scrolls contents left, while
1168 * increasing Y scrolls contents up.
1169 * - If Rulers have been applied to the axes, then the contents will scroll until
1170 * reaching the domain boundary.
1172 * @param[in] position The position to scroll to
1173 * @note Contents will not snap to ruler snap points.
1176 void ScrollTo(const Vector2& position);
1179 * @brief Scrolls View to position specified (contents will scroll to this position).
1181 * Position 0,0 is the origin. Increasing X scrolls contents left, while
1182 * increasing Y scrolls contents up.
1183 * - If Rulers have been applied to the axes, then the contents will scroll until
1184 * reaching the domain boundary.
1186 * @param[in] position The position to scroll to
1187 * @param[in] duration The duration of the animation in seconds
1188 * @note Contents will not snap to ruler snap points.
1191 void ScrollTo(const Vector2& position, float duration);
1194 * @brief Scrolls View to position specified (contents will scroll to this position).
1196 * Position 0,0 is the origin. Increasing X scrolls contents left, while
1197 * increasing Y scrolls contents up.
1198 * - If Rulers have been applied to the axes, then the contents will scroll until
1199 * reaching the domain boundary.
1201 * @param[in] position The position to scroll to
1202 * @param[in] duration The duration of the animation in seconds
1203 * @param[in] alpha The alpha function to use
1204 * @note Contents will not snap to ruler snap points.
1207 void ScrollTo(const Vector2& position, float duration, AlphaFunction alpha);
1210 * @brief Scrolls View to position specified (contents will scroll to this position).
1212 * Position 0,0 is the origin. Increasing X scrolls contents left, while
1213 * increasing Y scrolls contents up.
1214 * - If Rulers have been applied to the axes, then the contents will scroll until
1215 * reaching the domain boundary.
1217 * @param[in] position The position to scroll to
1218 * @param[in] duration The duration of the animation in seconds
1219 * @param[in] horizontalBias Whether to bias scrolling to left or right
1220 * @param[in] verticalBias Whether to bias scrolling to top or bottom
1221 * @note Contents will not snap to ruler snap points.
1222 * Biasing parameters are provided such that in scenarios with 2 or 2x2 pages in
1223 * wrap mode, the application developer can decide whether to scroll left or right
1224 * to get to the target page.
1227 void ScrollTo(const Vector2& position, float duration, DirectionBias horizontalBias, DirectionBias verticalBias);
1230 * @brief Scrolls View to position specified (contents will scroll to this position).
1232 * Position 0,0 is the origin. Increasing X scrolls contents left, while
1233 * increasing Y scrolls contents up.
1234 * - If Rulers have been applied to the axes, then the contents will scroll until
1235 * reaching the domain boundary.
1237 * @param[in] position The position to scroll to
1238 * @param[in] duration The duration of the animation in seconds
1239 * @param[in] horizontalBias Whether to bias scrolling to left or right
1240 * @param[in] verticalBias Whether to bias scrolling to top or bottom
1241 * @param[in] alpha Alpha function to use
1242 * @note Contents will not snap to ruler snap points.
1243 * Biasing parameters are provided such that in scenarios with 2 or 2x2 pages in
1244 * wrap mode, the application developer can decide whether to scroll left or right
1245 * to get to the target page.
1248 void ScrollTo(const Vector2& position, float duration, AlphaFunction alpha, DirectionBias horizontalBias, DirectionBias verticalBias);
1251 * @brief Scrolls View to page currently based on assumption that each page is
1252 * "(page) * ScrollViewSize.width, 0".
1255 * @param[in] page The page to scroll to
1256 * @note Should probably be upgraded so that page is an abstract class, that can be
1257 * a function of ScrollViewSize, ruler domain, ruler snap points etc. as pages may be
1258 * orchestrated in a 2D grid fashion, or variable width.
1261 void ScrollTo(unsigned int page);
1264 * @brief Scrolls View to page currently based on assumption that each page is
1265 * "(page) * ScrollViewSize.width, 0".
1268 * @param[in] page The page to scroll to
1269 * @param[in] duration The duration of the animation in seconds
1270 * @note Should probably be upgraded so that page is an abstract class, that can be
1271 * a function of ScrollViewSize, ruler domain, ruler snap points etc. as pages may be
1272 * orchestrated in a 2D grid fashion, or variable width.
1275 void ScrollTo(unsigned int page, float duration);
1278 * @brief Scrolls View to page currently based on assumption that each page is
1279 * "(page) * ScrollViewSize.width, 0".
1282 * @param[in] page The page to scroll to
1283 * @param[in] duration The duration of the animation in seconds
1284 * @param[in] bias Whether to bias scrolling to left or right
1285 * @note Should probably be upgraded so that page is an abstract class, that can be
1286 * a function of ScrollViewSize, ruler domain, ruler snap points etc. as pages may be
1287 * orchestrated in a 2D grid fashion, or variable width.
1288 * A biasing parameter is provided such that in scenarios with 2 pages in wrap mode,
1289 * the application developer can decide whether to scroll left or right to get to
1293 void ScrollTo(unsigned int page, float duration, DirectionBias bias);
1296 * @brief Scrolls View such that actor appears in the center of the ScrollView.
1299 * @param[in] actor The actor to center in on (via Scrolling)
1300 * @note Actor must be a direct child of ScrollView, otherwise will
1301 * cause an assertion failure.
1303 void ScrollTo(Actor& actor);
1306 * @brief Scrolls View such that actor appears in the center of the ScrollView.
1309 * @param[in] actor The actor to center in on (via Scrolling)
1310 * @param[in] duration The duration of the animation in seconds
1311 * @note Actor must be a direct child of ScrollView, otherwise will
1312 * cause an assertion failure.
1314 void ScrollTo(Actor& actor, float duration);
1317 * @brief Scrolls View to the nearest snap points as specified by the Rulers.
1319 * If already at snap points, then will return false, and not scroll.
1322 * @return True if Snapping necessary
1324 bool ScrollToSnapPoint();
1327 * @brief Applies a constraint that will affect the children of ScrollView.
1330 * @param[in] constraint The constraint to apply
1331 * @note This affects all existing and future Actors that are added to scrollview.
1333 void ApplyConstraintToChildren(Constraint constraint);
1336 * @brief Removes all constraints that will affect the children of ScrollView.
1339 * @note This removes all constraints from actors that have been added
1342 void RemoveConstraintsFromChildren();
1345 * @brief Applies Effect to ScrollView.
1348 * @param[in] effect The effect to apply to scroll view
1350 void ApplyEffect(ScrollViewEffect effect);
1353 * @brief Removes Effect from ScrollView.
1356 * @param[in] effect The effect to remove
1358 void RemoveEffect(ScrollViewEffect effect);
1361 * @brief Remove All Effects from ScrollView.
1364 void RemoveAllEffects();
1367 * @brief Binds actor to this ScrollView.
1369 * Once an actor is bound to a ScrollView, it will be subject to
1370 * that ScrollView's properties.
1373 * @param[in] child The actor to add to this ScrollView
1375 void BindActor(Actor child);
1378 * @brief Unbinds Actor from this ScrollView.
1380 * Once Unbound, this ScrollView will not affect the actor.
1382 * @param[in] child The actor to be unbound
1383 * @note This does not remove the child from the ScrollView container
1386 void UnbindActor(Actor child);
1389 * @brief Allows the user to constrain the scroll view in a particular direction.
1392 * @param[in] direction The axis to constrain the scroll-view to.
1393 * Usually set to PanGestureDetector::DIRECTION_VERTICAL or PanGestureDetector::DIRECTION_HORIZONTAL (but can be any other angle if desired).
1394 * @param[in] threshold The threshold to apply around the axis
1395 * @note If no threshold is specified, then the default threshold of PI * 0.25 radians (or 45 degrees) is used.
1397 void SetScrollingDirection(Radian direction, Radian threshold = PanGestureDetector::DEFAULT_THRESHOLD);
1400 * @brief Removes a direction constraint from the scroll view.
1403 * @param[in] direction The axis to stop constraining to.
1404 * Usually will be PanGestureDetector::DIRECTION_VERTICAL or PanGestureDetector::DIRECTION_HORIZONTAL (but can be any other angle if desired).
1406 void RemoveScrollingDirection(Radian direction);
1410 * @brief Signal emitted when the ScrollView has started to snap or flick (it tells the target
1411 * position, scale, rotation for the snap or flick).
1413 * A callback of the following type may be connected:
1415 * void YourCallbackName(const SnapEvent& event);
1418 * @return The signal to connect to
1419 * @pre The Object has been initialized.
1421 SnapStartedSignalType& SnapStartedSignal();
1423 public: // Not intended for application developers
1426 * @brief Creates a handle using the Toolkit::Internal implementation.
1429 * @param[in] implementation The Control implementation
1431 DALI_INTERNAL ScrollView(Internal::ScrollView& implementation);
1434 * @brief Allows the creation of this Control from an Internal::CustomActor pointer.
1437 * @param[in] internal A pointer to the internal CustomActor
1439 explicit DALI_INTERNAL ScrollView(Dali::Internal::CustomActor* internal);
1446 } // namespace Toolkit
1450 #endif // DALI_TOOLKIT_SCROLL_VIEW_H