1 #ifndef __DALI_TOOLKIT_SCROLL_VIEW_H__
2 #define __DALI_TOOLKIT_SCROLL_VIEW_H__
5 * Copyright (c) 2015 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>
33 namespace Internal DALI_INTERNAL
38 * @addtogroup dali_toolkit_controls_scroll_view
43 * @brief How axes/rotation or scale are clamped
47 NotClamped, ///< The quantity isn't clamped
48 ClampedToMin, ///< The quantity is clamped to the min value
49 ClampedToMax ///< The quantity is clamped to the max value
53 * @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 The snap type
71 * @brief DirectionBias types.
75 DirectionBiasLeft = -1, ///< Bias scroll snap to Left
76 DirectionBiasNone = 0, ///< Don't bias scroll snap
77 DirectionBiasRight = 1 ///< Bias scroll snap to Right
81 * @brief Used for specifying minimum/maximum extents of a ruler.
83 class DALI_IMPORT_API RulerDomain
88 * @brief Creates Ruler domain allowing a point to traverse between min and max extents.
90 * @param[in] min Minimum extent (point cannot traverse less than this)
91 * @param[in] max Maximum extent (point cannot traverse greater than this)
92 * @param[in] enabled Whether domain has been enabled or not.
94 explicit RulerDomain(float min, float max, bool enabled = true);
98 float min; ///< Minimum extent (point cannot traverse less than this)
99 float max; ///< Maximum extent (point cannot traverse greater than this)
100 bool enabled; ///< Whether domain has been enabled or not.
103 * @brief Clamps value (x) from (min) to (max).
105 * An optional length parameter can be specified to suggest that the
106 * subject is not a point but a line to that should be clamped.
108 * @param[in] x X point to be clamped between (min) and (max) extents.
109 * @param[in] length (optional) The Length of the line from (x) to (x + length) to be clamped.
110 * @param[in] scale Scaling parameter which treats domain as scaled in calculations.
111 * @return The clamped value.
113 float Clamp(float x, float length = 0.0f, float scale = 1.0f) const;
116 * @brief Clamps value (x) from (min) to (max).
118 * An optional length parameter can be specified to suggest that the
119 * subject is not a point but a line to that should be clamped.
121 * @param[in] x X point to be clamped between (min) and (max) extents.
122 * @param[in] length (optional) The Length of the line from (x) to (x + length) to be clamped.
123 * @param[in] scale Scaling parameter which treats domain as scaled in calculations.
124 * @param[out] clamped Whether clamping occured and which size (None, Min or Max)
125 * @return The clamped value.
127 float Clamp(float x, float length, float scale, ClampState &clamped) const;
130 * @brief Returns (max-min) size of ruler.
132 * @return The size of the ruler from min to max.
134 float GetSize() const;
138 // Forward declare future extension interface
139 class RulerExtension;
142 * @brief Abstract class to define scroll axes.
144 * It can specify whether they are traversable, where their snap
145 * points are and their domain.
147 class DALI_IMPORT_API Ruler : public RefObject
150 /// @brief The type of the ruler
152 Fixed, ///< A fixed ruler
153 Free ///< A free ruler
159 * @brief Constructs ruler, default enabled, with limitless domain.
164 * @brief Snaps (x) in accordance to the ruler settings.
166 * @param[in] x The input value on the ruler to be snapped.
167 * @param[in] bias (optional) The biasing employed for snapping
168 * 0 floor input (floor x) "Used for Flick Left"
169 * 0.5 round input (floor x + 0.5) "Used for Release"
170 * 1 ceil input (floor x + 1.0) "Used for Flick Right"
171 * @return The position of the one dimensional point passed in once snapped.
173 virtual float Snap(float x, float bias = 0.5f) const = 0;
176 * @brief Returns position from page, based on whatever the ruler
179 * If (wrap) is true, then will set volume to the number of
180 * times page has exceeded the domain's volume (volume being the
181 * number of pages within the domain), while wrapping the position
184 * @param[in] page The page index
185 * @param[out] volume The overflow volume when the page exceeds the domain (wrap must be enabled)
186 * @param[in] wrap Enable wrap mode
187 * @return The position representing this page point.
189 virtual float GetPositionFromPage(unsigned int page, unsigned int &volume, bool wrap) const = 0;
192 * @brief Returns page from position, based on whatever the ruler
195 * If (wrap) is true, then will return a page wrapped within the domain.
197 * @param[in] position The position on the domain
198 * @param[in] wrap Enable wrap mode
199 * @return The page where this position resides.
201 virtual unsigned int GetPageFromPosition(float position, bool wrap) const = 0;
204 * @brief Returns the total number of pages within this Ruler.
206 * @return The number of pages in the Ruler.
208 virtual unsigned int GetTotalPages() const = 0;
211 * @brief Gets the extension interface of the Ruler.
213 * @return The extension interface of the Ruler
215 virtual RulerExtension* GetExtension() { return NULL; }
220 * @brief Gets the ruler type.
222 * @return The ruler type.
224 Ruler::RulerType GetType() const;
227 * @brief Returns whether this axis has been enabled or not.
229 * @return true if axis is enabled
231 bool IsEnabled() const;
234 * @brief Enables ruler (ruler must be enabled in order to traverse along it).
239 * @brief Disables ruler.
244 * @brief Sets Domain.
246 * @param[in] domain Ruler domain object.
248 void SetDomain(RulerDomain domain);
251 * @brief Gets Domain.
255 const RulerDomain &GetDomain() const;
258 * @brief Disables Domain (minimum/maximum extents for this axis).
260 void DisableDomain();
263 * @brief Clamps value (x) from (min) to (max).
265 * An optional length parameter can be specified to suggest that the
266 * subject is not a point but a line that should be clamped.
268 * @param[in] x X point to be clamped between (min) and (max) extents.
269 * @param[in] length (optional) The Length of the line from (x) to (x + length) to be clamped.
270 * @param[in] scale Scaling parameter which treats domain as scaled in calculations.
271 * @return The clamped value.
273 float Clamp(float x, float length = 0.0f, float scale = 1.0f) const;
277 * @brief Clamps value (x) from (min) to (max).
279 * An optional length parameter can be specified to suggest that the
280 * subject is not a point but a line to that should be clamped.
282 * @param[in] x X point to be clamped between (min) and (max) extents.
283 * @param[in] length (optional) The Length of the line from (x) to (x + length) to be clamped.
284 * @param[in] scale Scaling parameter which treats domain as scaled in calculations.
285 * @param[out] clamped Whether clamping occured and which size (None, Min or Max)
286 * @return The clamped value.
288 float Clamp(float x, float length, float scale, ClampState &clamped) const;
291 * @brief Snaps and Clamps (x) in accordance to ruler settings.
293 * @param[in] x value to be snapped in accordance to ruler snap value,
294 * and clamped in accordance to the ruler's domain (if set).
295 * @param[in] bias (optional) The biasing employed for snapping
296 * 0 floor input (floor x) "Used for Flick Left"
297 * 0.5 round input (floor x + 0.5) "Used for Release"
298 * 1 ceil input (floor x + 1.0) "Used for Flick Right"
299 * @param[in] length (optional) The Length of the line from (x) to (x + length)
301 * @param[in] scale Scaling parameter which treats domain as scaled in calculations.
302 * @return the clamped value after snapping
304 float SnapAndClamp(float x, float bias = 0.5f, float length = 0.0f, float scale = 1.0f) const;
307 * @brief Snaps and Clamps (x) in accordance to ruler settings.
309 * @param[in] x value to be snapped in accordance to ruler snap value,
310 * and clamped in accordance to the ruler's domain (if set).
311 * @param[in] bias (optional) The biasing employed for snapping
312 * 0 floor input (floor x) "Used for Flick Left"
313 * 0.5 round input (floor x + 0.5) "Used for Release"
314 * 1 ceil input (floor x + 1.0) "Used for Flick Right"
315 * @param[in] length (optional) The Length of the line from (x) to (x + length)
317 * @param[in] scale Scaling parameter which treats domain as scaled in calculations.
318 * @param[out] clamped Whether clamping occured and which size (None, Min or Max)
319 * @return The clamped value after snapping
321 float SnapAndClamp(float x, float bias, float length, float scale, ClampState &clamped) const;
326 * @brief Destructor - A reference counted object may only be deleted by calling Unreference().
332 RulerType mType; ///< Type of Ruler (Fixed or Free).
333 bool mEnabled; ///< If the ruler is enabled.
334 RulerDomain mDomain; ///< The domain of the ruler.
338 typedef IntrusivePtr<Ruler> RulerPtr; ///< Pointer to Dali::Toolkit::Ruler object
341 * @brief Concrete implementation of Ruler that has no snapping and has one single page.
343 class DALI_IMPORT_API DefaultRuler : public Ruler
347 * @brief DefaultRuler constructor.
352 * @copydoc Toolkit::Ruler::Snap
354 virtual float Snap(float x, float bias) const;
357 * @copydoc Toolkit::Ruler::GetPositionFromPage
359 virtual float GetPositionFromPage(unsigned int page, unsigned int &volume, bool wrap) const;
362 * @copydoc Toolkit::Ruler::GetPageFromPosition
364 virtual unsigned int GetPageFromPosition(float position, bool wrap) const;
367 * @copydoc Toolkit::Ruler::GetTotalPages
369 virtual unsigned int GetTotalPages() const;
373 * @brief Concrete implementation of Ruler that has fixed snapping.
375 class DALI_IMPORT_API FixedRuler : public Ruler
381 * @param[in] spacing The spacing between each interval on this ruler.
383 FixedRuler(float spacing = 1.0f);
386 * @copydoc Toolkit::Ruler::Snap
388 virtual float Snap(float x, float bias) const;
391 * @copydoc Toolkit::Ruler::GetPositionFromPage
393 virtual float GetPositionFromPage(unsigned int page, unsigned int &volume, bool wrap) const;
396 * @copydoc Toolkit::Ruler::GetPageFromPosition
398 virtual unsigned int GetPageFromPosition(float position, bool wrap) const;
401 * @copydoc Toolkit::Ruler::GetTotalPages
403 virtual unsigned int GetTotalPages() const;
406 float mSpacing; ///< The spacing between each interval
409 class ScrollViewEffect;
413 * @brief ScrollView contains actors that can be scrolled manually (via touch)
417 * | %Signal Name | Method |
418 * |-------------------|----------------------------|
419 * | snap-started | @ref SnapStartedSignal() |
421 class DALI_IMPORT_API ScrollView : public Scrollable
427 * @brief Clamp signal event's data
431 ClampState2D scale; ///< Clamp information for scale axes
432 ClampState2D position; ///< Clamp information for position axes
433 ClampState rotation; ///< Clamp information for rotation
437 * @brief Snap signal event's data.
441 SnapType type; ///< Current snap commencing
442 Vector2 position; ///< Target snap position
443 float duration; ///< Duration of snap animation.
447 * @brief The start and end property ranges for this control.
451 ANIMATABLE_PROPERTY_START_INDEX = Toolkit::Scrollable::ANIMATABLE_PROPERTY_END_INDEX + 1,
452 ANIMATABLE_PROPERTY_END_INDEX = ANIMATABLE_PROPERTY_START_INDEX + 1000 ///< Reserve animatable property indices
456 * @brief An enumeration of properties belonging to the ScrollView class.
462 SCROLL_POSITION = ANIMATABLE_PROPERTY_START_INDEX, ///< Property, name "scrollPosition", type Vector2
463 SCROLL_PRE_POSITION, ///< Property, name "scrollPrePosition", type Vector2
464 SCROLL_PRE_POSITION_X, ///< Property, name "scrollPrePositionX", type float
465 SCROLL_PRE_POSITION_Y, ///< Property, name "scrollPrePositionY", type float
466 SCROLL_PRE_POSITION_MAX, ///< Property, name "scrollPrePositionMax", type Vector2
467 SCROLL_PRE_POSITION_MAX_X, ///< Property, name "scrollPrePositionMaxX", type float
468 SCROLL_PRE_POSITION_MAX_Y, ///< Property, name "scrollPrePositionMaxY", type float
469 OVERSHOOT_X, ///< Property, name "overshootX", type float
470 OVERSHOOT_Y, ///< Property, name "overshootY", type float
471 SCROLL_FINAL, ///< Property, name "scrollFinal", type Vector2
472 SCROLL_FINAL_X, ///< Property, name "scrollFinalX", type float
473 SCROLL_FINAL_Y, ///< Property, name "scrollFinalY", type float
474 WRAP, ///< Property, name "wrap", type bool
475 PANNING, ///< Property, name "panning", type bool
476 SCROLLING, ///< Property, name "scrolling", type bool
477 SCROLL_DOMAIN_SIZE, ///< Property, name "scrollDomainSize", type Vector2
478 SCROLL_DOMAIN_SIZE_X, ///< Property, name "scrollDomainSizeX", type float
479 SCROLL_DOMAIN_SIZE_Y, ///< Property, name "scrollDomainSizeY", type float
480 SCROLL_DOMAIN_OFFSET, ///< Property, name "scrollDomainOffset", type Vector2
481 SCROLL_POSITION_DELTA, ///< Property, name "scrollPositionDelta", type Vector2
482 START_PAGE_POSITION ///< Property, name "startPagePosition", type Vector3
488 typedef Signal< void ( const SnapEvent& ) > SnapStartedSignalType; ///< SnapStarted signal type
493 * @brief Creates an empty ScrollView handle.
498 * @brief Copy constructor.
500 * Creates another handle that points to the same real object
502 * @param[in] handle to copy from
504 ScrollView( const ScrollView& handle );
507 * @brief Assignment operator.
509 * Changes this handle to point to another real object
510 * @param[in] handle The handle to copy from
511 * @return A reference to this
513 ScrollView& operator=( const ScrollView& handle );
518 * This is non-virtual since derived Handle types must not contain data or virtual methods.
523 * @brief Create an initialized ScrollView.
525 * @return A handle to a newly allocated Dali resource.
527 static ScrollView New();
530 * @brief Downcast an Object handle to ScrollView.
532 * If handle points to a ScrollView the downcast produces valid
533 * handle. If not the returned handle is left uninitialized.
535 * @param[in] handle Handle to an object
536 * @return handle to a ScrollView or an uninitialized handle
538 static ScrollView DownCast( BaseHandle handle );
543 * @brief Get snap-animation's AlphaFunction.
545 * @return Current easing alpha function of the snap animation.
547 AlphaFunction GetScrollSnapAlphaFunction() const;
550 * @brief Set snap-animation's AlphaFunction.
552 * @param[in] alpha Easing alpha function of the snap animation.
554 void SetScrollSnapAlphaFunction(AlphaFunction alpha);
557 * @brief Get flick-animation's AlphaFunction.
559 * @return Current easing alpha function of the flick animation.
561 AlphaFunction GetScrollFlickAlphaFunction() const;
564 * @brief Set flick-animation's AlphaFunction.
566 * @param[in] alpha Easing alpha function of the flick animation.
568 void SetScrollFlickAlphaFunction(AlphaFunction alpha);
571 * @brief Gets the time for the scroll snap-animation.
573 * This animation occurs when the user drags, and releases.
575 * @return The time in seconds for the animation to take.
577 float GetScrollSnapDuration() const;
580 * @brief Sets the time for the scroll snap-animation.
582 * This animation occurs when the user drags, and releases.
584 * @param[in] time The time in seconds for the animation to take.
586 void SetScrollSnapDuration(float time);
589 * @brief Gets the time for the scroll flick-animation.
591 * This animation occurs when the user flicks scroll view.
593 * @return The time in seconds for the animation to take.
595 float GetScrollFlickDuration() const;
598 * @brief Sets the time for the scroll flick-animation.
600 * This animation occurs when the user flicks scroll view.
602 * @param[in] time The time in seconds for the animation to take.
604 void SetScrollFlickDuration(float time);
607 * @brief Set X axis ruler.
609 * Defines how scrolling horizontally is snapped, and
610 * the boundary (domain) in which the ScrollView can pan.
612 * @param[in] ruler The ruler to be used for the X axis
614 void SetRulerX(RulerPtr ruler);
617 * @brief Set Y axis ruler.
619 * Defines how scrolling vertically is snapped, and the boundary
620 * (domain) in which the ScrollView can pan.
622 * @param[in] ruler The ruler to be used for the Y axis
624 void SetRulerY(RulerPtr ruler);
627 * @brief Set Scroll's touch sensitivity.
629 * @note Unlike SetSensitive(), this determines whether this ScrollView
630 * should react (e.g. pan), without disrupting the sensitivity of it's children.
632 * @param[in] sensitive true to enable scroll, false to disable scrolling
634 void SetScrollSensitive(bool sensitive);
637 * @brief Set maximum overshoot amount.
639 * The final overshoot value is within 0.0f to 1.0f, but the maximum
640 * overshoot is in pixels (e.g. if you scroll 75 pixels beyond the
641 * edge of a scrollable area and the maximum overshoot is 100 then
642 * the final overshoot value will be 0.75f)
644 * @param[in] overshootX the maximum number of horizontally scrolled pixels before overshoot X reaches 1.0f
645 * @param[in] overshootY the maximum number of vertically scrolled pixels before overshoot Y reaches 1.0f
647 void SetMaxOvershoot(float overshootX, float overshootY);
650 * @brief Set Snap Overshoot animation's AlphaFunction.
652 * @param[in] alpha Easing alpha function of the overshoot snap animation.
654 void SetSnapOvershootAlphaFunction(AlphaFunction alpha);
657 * @brief Set Snap Overshoot animation's Duration.
659 * @note Set duration to 0 seconds, to disable Animation.
661 * @param[in] duration The duration of the overshoot snap animation.
663 void SetSnapOvershootDuration(float duration);
666 * @brief Enables or Disables Actor Auto-Snap mode.
668 * When Actor Auto-Snap mode has been enabled, ScrollView will automatically
669 * snap to the closest actor (The closest actor will appear in the center of
672 * @param[in] enable Enables (true), or disables (false) Actor AutoSnap
674 void SetActorAutoSnap(bool enable);
677 * @brief Enables or Disables Wrap mode for ScrollView contents.
679 * When enabled, the ScrollView contents are wrapped over the X/Y Domain.
681 * @note You must apply a position constraint that causes Wrapping
684 * @param[in] enable Enables (true), or disables (false) Wrap Mode.
686 void SetWrapMode(bool enable);
689 * @brief Gets the current distance needed to scroll for ScrollUpdatedSignal to be emitted
691 * @return Current scroll update distance
693 int GetScrollUpdateDistance() const;
696 * @brief Sets the distance needed to scroll for ScrollUpdatedSignal to be emitted
698 * The scroll update distance tells ScrollView how far to move before ScrollUpdatedSignal the informs application.
699 * Each time the ScrollView crosses this distance the signal will be emitted
701 * @param[in] distance The distance for ScrollView to move before emitting update signal
703 void SetScrollUpdateDistance(int distance);
706 * @brief Returns state of Axis Auto Lock mode.
708 * @return Whether Axis Auto Lock mode has been enabled or not.
710 bool GetAxisAutoLock() const;
713 * @brief Enables or Disables Axis Auto Lock mode for panning within the ScrollView.
715 * When enabled, any pan gesture that appears mostly horizontal or mostly
716 * vertical, will be automatically restricted to horizontal only or vertical
717 * only panning, until the pan gesture has completed.
719 * @param[in] enable Enables (true), or disables (false) AxisAutoLock mode.
721 void SetAxisAutoLock(bool enable);
724 * @brief Gets the gradient threshold at which a panning gesture
725 * should be locked to the Horizontal or Vertical axis.
727 * @return The gradient, a value between 0.0 and 1.0f.
729 float GetAxisAutoLockGradient() const;
732 * @brief Sets the gradient threshold at which a panning gesture should be locked to the
733 * Horizontal or Vertical axis.
735 * By default this is 0.36 (0.36:1) which means angles less than 20
736 * degrees to an axis will lock to that axis.
738 * @note: Specifying a value of 1.0 (the maximum value accepted) indicates that
739 * all panning gestures will auto-lock. Either to the horizontal or vertical axis.
741 * @param[in] gradient A value between 0.0 and 1.0 (auto-lock for all angles)
743 void SetAxisAutoLockGradient(float gradient);
746 * @brief Gets the friction coefficient setting for ScrollView when
747 * flicking in free panning mode.
749 * This is a value in stage-diagonals per second^2.
750 * stage-diagonal = Length( stage.width, stage.height )
751 * @return Friction coefficient is returned.
753 float GetFrictionCoefficient() const;
756 * @brief Sets the friction coefficient for ScrollView when flicking
757 * in free panning mode.
759 * This is a value in stage-diagonals per second^2.
760 * stage-diagonal = Length( stage.width, stage.height ).
762 * A stage 480x800 in size has a diagonal length of 933.
763 * Friction coefficient of 1.0 means the swipe velocity will
764 * reduce by 1.0 * 933 pixels/sec^2.
765 * @param[in] friction Friction coefficient, must be greater than 0.0 (default = 1.0)
767 void SetFrictionCoefficient(float friction);
770 * @brief Gets the flick speed coefficient for ScrollView when
771 * flicking in free panning mode.
773 * This is a constant which multiplies the input touch
774 * flick velocity to determine the actual velocity at
775 * which to move the scrolling area.
776 * @return The flick speed coefficient is returned.
778 float GetFlickSpeedCoefficient() const;
781 * @brief Sets the flick speed coefficient for ScrollView when
782 * flicking in free panning mode.
784 * This is a constant which multiplies the input touch
785 * flick velocity to determine the actual velocity at
786 * which to move the scrolling area.
787 * @param[in] speed The flick speed coefficient (default = 1.0).
789 void SetFlickSpeedCoefficient(float speed);
792 * @brief Returns the minimum pan distance required for a flick gesture in pixels
794 * @return Minimum pan distance vector with separate x and y distance
796 Vector2 GetMinimumDistanceForFlick() const;
799 * @brief Sets the minimum pan distance required for a flick in pixels
801 * 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
803 * @param[in] distance The minimum pan distance for a flick
805 void SetMinimumDistanceForFlick( const Vector2& distance );
808 * @brief Returns the minimum pan speed required for a flick gesture in pixels per second
810 * @return Minimum pan speed
812 float GetMinimumSpeedForFlick() const;
815 * @brief Sets the minimum pan speed required for a flick in pixels per second
817 * @param[in] speed The minimum pan speed for a flick
819 void SetMinimumSpeedForFlick( float speed );
822 * @brief Gets the maximum flick speed setting for ScrollView when
823 * flicking in free panning mode.
825 * This is a value in stage-diagonals per second.
826 * stage-diagonal = Length( stage.width, stage.height )
827 * @return Maximum flick speed is returned
829 float GetMaxFlickSpeed() const;
832 * @brief Sets the maximum flick speed for the ScrollView when
833 * flicking in free panning mode.
835 * This is a value in stage-diagonals per second.
836 * stage-diagonal = Length( stage.width, stage.height )
838 * A stage 480x800 in size has a diagonal length of 933.
839 * Max Flick speed of 1.0 means the maximum velocity of
840 * a swipe can be 1.0 * 933 pixels/sec.
841 * @param[in] speed Maximum flick speed (default = 3.0)
843 void SetMaxFlickSpeed(float speed);
846 * @brief Gets the step of scroll distance in actor coordinates for
847 * each wheel event received in free panning mode.
849 * @return The step of scroll distance(pixel) in X and Y axes.
851 Vector2 GetWheelScrollDistanceStep() const;
854 * @brief Sets the step of scroll distance in actor coordinates for
855 * each wheel event received in free panning mode.
857 * @param[in] step The step of scroll distance(pixel) in X and Y axes.
859 * @note: If snap points are defined in the rulers, it will always
860 * scroll to the next snap point towards the scroll direction while
861 * receiving the wheel events.
864 void SetWheelScrollDistanceStep(Vector2 step);
867 * @brief Retrieves current scroll position.
869 * @returns The current scroll position.
871 Vector2 GetCurrentScrollPosition() const;
874 * @brief Retrieves current scroll page based on ScrollView
875 * dimensions being the size of one page, and all pages laid out in
876 * a grid fashion, increasing from left to right until the end of
879 * @note: Pages start from 0 as the first page, not 1.
881 * @returns The Current page.
883 unsigned int GetCurrentPage() const;
886 * @brief Scrolls View to position specified (contents will scroll to this position).
888 * Position 0,0 is the origin. Increasing X scrolls contents left, while
889 * increasing Y scrolls contents up.
890 * - If Rulers have been applied to the axes, then the contents will scroll until
891 * reaching the domain boundary.
892 * @note Contents will not snap to ruler snap points.
894 * @param[in] position The position to scroll to.
896 void ScrollTo(const Vector2& position);
899 * @brief Scrolls View to position specified (contents will scroll to this position).
901 * Position 0,0 is the origin. Increasing X scrolls contents left, while
902 * increasing Y scrolls contents up.
903 * - If Rulers have been applied to the axes, then the contents will scroll until
904 * reaching the domain boundary.
905 * @note Contents will not snap to ruler snap points.
907 * @param[in] position The position to scroll to.
908 * @param[in] duration The duration of the animation in seconds
910 void ScrollTo(const Vector2& position, float duration);
913 * @brief Scrolls View to position specified (contents will scroll to this position)
915 * Position 0,0 is the origin. Increasing X scrolls contents left, while
916 * increasing Y scrolls contents up.
917 * - If Rulers have been applied to the axes, then the contents will scroll until
918 * reaching the domain boundary.
919 * @note Contents will not snap to ruler snap points.
921 * @param[in] position The position to scroll to.
922 * @param[in] duration The duration of the animation in seconds
923 * @param[in] alpha The alpha function to use
925 void ScrollTo(const Vector2& position, float duration, AlphaFunction alpha);
928 * @brief Scrolls View to position specified (contents will scroll to this position).
930 * Position 0,0 is the origin. Increasing X scrolls contents left, while
931 * increasing Y scrolls contents up.
932 * - If Rulers have been applied to the axes, then the contents will scroll until
933 * reaching the domain boundary.
934 * @note Contents will not snap to ruler snap points.
935 * Biasing parameters are provided such that in scenarios with 2 or 2x2 pages in
936 * wrap mode, the application developer can decide whether to scroll left or right
937 * to get to the target page
939 * @param[in] position The position to scroll to.
940 * @param[in] duration The duration of the animation in seconds
941 * @param[in] horizontalBias Whether to bias scrolling to left or right.
942 * @param[in] verticalBias Whether to bias scrolling to top or bottom.
944 void ScrollTo(const Vector2& position, float duration,
945 DirectionBias horizontalBias, DirectionBias verticalBias);
948 * @brief Scrolls View to position specified (contents will scroll to this position)
950 * Position 0,0 is the origin. Increasing X scrolls contents left, while
951 * increasing Y scrolls contents up.
952 * - If Rulers have been applied to the axes, then the contents will scroll until
953 * reaching the domain boundary.
954 * @note Contents will not snap to ruler snap points.
955 * Biasing parameters are provided such that in scenarios with 2 or 2x2 pages in
956 * wrap mode, the application developer can decide whether to scroll left or right
957 * to get to the target page
959 * @param[in] position The position to scroll to.
960 * @param[in] duration The duration of the animation in seconds
961 * @param[in] horizontalBias Whether to bias scrolling to left or right.
962 * @param[in] verticalBias Whether to bias scrolling to top or bottom.
963 * @param[in] alpha Alpha function to use
965 void ScrollTo(const Vector2& position, float duration, AlphaFunction alpha,
966 DirectionBias horizontalBias, DirectionBias verticalBias);
969 * @brief Scrolls View to page currently based on assumption that each page is
970 * "(page) * ScrollViewSize.width, 0".
972 * @note Should probably be upgraded so that page is an abstract class, that can be
973 * a function of ScrollViewSize, ruler domain, ruler snap points etc. as pages may be
974 * orchestrated in a 2D grid fashion, or variable width.
976 * @param[in] page to scroll to
978 void ScrollTo(unsigned int page);
981 * @brief Scrolls View to page currently based on assumption that each page is
982 * "(page) * ScrollViewSize.width, 0".
984 * @note Should probably be upgraded so that page is an abstract class, that can be
985 * a function of ScrollViewSize, ruler domain, ruler snap points etc. as pages may be
986 * orchestrated in a 2D grid fashion, or variable width.
988 * @param[in] page to scroll to
989 * @param[in] duration The duration of the animation in seconds
991 void ScrollTo(unsigned int page, float duration);
994 * @brief Scrolls View to page currently based on assumption that each page is
995 * "(page) * ScrollViewSize.width, 0".
997 * @note Should probably be upgraded so that page is an abstract class, that can be
998 * a function of ScrollViewSize, ruler domain, ruler snap points etc. as pages may be
999 * orchestrated in a 2D grid fashion, or variable width.
1000 * A biasing parameter is provided such that in scenarios with 2 pages in wrap mode,
1001 * the application developer can decide whether to scroll left or right to get to
1004 * @param[in] page to scroll to
1005 * @param[in] duration The duration of the animation in seconds
1006 * @param[in] bias Whether to bias scrolling to left or right.
1008 void ScrollTo(unsigned int page, float duration, DirectionBias bias);
1011 * @brief Scrolls View such that actor appears in the center of the ScrollView.
1013 * @note Actor must be a direct child of ScrollView, otherwise will
1014 * cause an assertion failure.
1015 * @param[in] actor The actor to center in on (via Scrolling).
1017 void ScrollTo(Actor& actor);
1020 * @brief Scrolls View such that actor appears in the center of the ScrollView.
1022 * @note Actor must be a direct child of ScrollView, otherwise will
1023 * cause an assertion failure.
1024 * @param[in] actor The actor to center in on (via Scrolling).
1025 * @param[in] duration The duration of the animation in seconds
1027 void ScrollTo(Actor& actor, float duration);
1030 * @brief Scrolls View to the nearest snap points as specified by the Rulers.
1032 * If already at snap points, then will return false, and not scroll.
1034 * @return True if Snapping necessary.
1036 bool ScrollToSnapPoint();
1039 * @brief Applies a constraint that will affect the children of ScrollView.
1041 * @note this affects all existing and future Actors that are added to scrollview.
1042 * @param[in] constraint The constraint to apply
1044 void ApplyConstraintToChildren(Constraint constraint);
1047 * @brief Removes all constraints that will affect the children of ScrollView.
1049 * @note this removes all constraints from actors that have been added
1052 void RemoveConstraintsFromChildren();
1055 * @brief Apply Effect to ScrollView.
1057 * @param[in] effect The effect to apply to scroll view
1059 void ApplyEffect(ScrollViewEffect effect);
1062 * @brief Remove Effect from ScrollView.
1064 * @param[in] effect The effect to remove.
1066 void RemoveEffect(ScrollViewEffect effect);
1069 * @brief Remove All Effects from ScrollView.
1071 void RemoveAllEffects();
1074 * @brief Binds actor to this ScrollView.
1076 * Once an actor is bound to a ScrollView, it will be subject to
1077 * that ScrollView's properties.
1079 * @param[in] child The actor to add to this ScrollView.
1081 void BindActor(Actor child);
1084 * @brief Unbind Actor from this ScrollView.
1086 * Once Unbound, this ScrollView will not affect the actor.
1087 * @note this does not remove the child from the ScrollView container
1089 * @param[in] child The actor to be unbound.
1091 void UnbindActor(Actor child);
1094 * @brief Allows the user to constrain the scroll view in a particular direction.
1096 * @param[in] direction The axis to constrain the scroll-view to.
1097 * Usually set to PanGestureDetector::DIRECTION_VERTICAL or PanGestureDetector::DIRECTION_HORIZONTAL (but can be any other angle if desired).
1098 * @param[in] threshold The threshold to apply around the axis.
1099 * @note If no threshold is specified, then the default threshold of PI * 0.25 radians (or 45 degrees) is used.
1101 void SetScrollingDirection( Radian direction, Radian threshold = PanGestureDetector::DEFAULT_THRESHOLD );
1104 * @brief Remove a direction constraint from the scroll view.
1106 * @param[in] direction The axis to stop constraining to.
1107 * Usually will be PanGestureDetector::DIRECTION_VERTICAL or PanGestureDetector::DIRECTION_HORIZONTAL (but can be any other angle if desired).
1109 void RemoveScrollingDirection( Radian direction );
1114 * @brief Signal emitted when the ScrollView has started to snap or flick (it tells the target
1115 * position, scale, rotation for the snap or flick)
1117 * A callback of the following type may be connected:
1119 * void YourCallbackName(const SnapEvent& event);
1121 * @pre The Object has been initialized.
1122 * @return The signal to connect to.
1124 SnapStartedSignalType& SnapStartedSignal();
1126 public: // Not intended for application developers
1129 * @brief Creates a handle using the Toolkit::Internal implementation.
1131 * @param[in] implementation The Control implementation.
1133 DALI_INTERNAL ScrollView(Internal::ScrollView& implementation);
1136 * @brief Allows the creation of this Control from an Internal::CustomActor pointer.
1138 * @param[in] internal A pointer to the internal CustomActor.
1140 explicit DALI_INTERNAL ScrollView( Dali::Internal::CustomActor* internal );
1146 } // namespace Toolkit
1150 #endif // __DALI_TOOLKIT_SCROLL_VIEW_H__