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
39 * @brief How axes/rotation or scale are clamped
43 NotClamped, ///< The quantity isn't clamped
44 ClampedToMin, ///< The quantity is clamped to the min value
45 ClampedToMax ///< The quantity is clamped to the max value
49 * @brief A 2 dimensional clamp
53 ClampState x; ///< The clamp state of the x axis
54 ClampState y; ///< The clamp state of the y axis
58 * @brief The snap type
67 * @brief DirectionBias types.
71 DirectionBiasLeft = -1, ///< Bias scroll snap to Left
72 DirectionBiasNone = 0, ///< Don't bias scroll snap
73 DirectionBiasRight = 1 ///< Bias scroll snap to Right
77 * @brief Used for specifying minimum/maximum extents of a ruler.
79 class DALI_IMPORT_API RulerDomain
84 * @brief Creates Ruler domain allowing a point to traverse between min and max extents.
86 * @param[in] min Minimum extent (point cannot traverse less than this)
87 * @param[in] max Maximum extent (point cannot traverse greater than this)
88 * @param[in] enabled Whether domain has been enabled or not.
90 explicit RulerDomain(float min, float max, bool enabled = true);
94 float min; ///< Minimum extent (point cannot traverse less than this)
95 float max; ///< Maximum extent (point cannot traverse greater than this)
96 bool enabled; ///< Whether domain has been enabled or not.
99 * @brief Clamps value (x) from (min) to (max).
101 * An optional length parameter can be specified to suggest that the
102 * subject is not a point but a line to that should be clamped.
104 * @param[in] x X point to be clamped between (min) and (max) extents.
105 * @param[in] length (optional) The Length of the line from (x) to (x + length) to be clamped.
106 * @param[in] scale Scaling parameter which treats domain as scaled in calculations.
107 * @return The clamped value.
109 float Clamp(float x, float length = 0.0f, float scale = 1.0f) const;
112 * @brief Clamps value (x) from (min) to (max).
114 * An optional length parameter can be specified to suggest that the
115 * subject is not a point but a line to that should be clamped.
117 * @param[in] x X point to be clamped between (min) and (max) extents.
118 * @param[in] length (optional) The Length of the line from (x) to (x + length) to be clamped.
119 * @param[in] scale Scaling parameter which treats domain as scaled in calculations.
120 * @param[out] clamped Whether clamping occured and which size (None, Min or Max)
121 * @return The clamped value.
123 float Clamp(float x, float length, float scale, ClampState &clamped) const;
126 * @brief Returns (max-min) size of ruler.
128 * @return The size of the ruler from min to max.
130 float GetSize() const;
134 // Forward declare future extension interface
135 class RulerExtension;
138 * @brief Abstract class to define scroll axes.
140 * It can specify whether they are traversable, where their snap
141 * points are and their domain.
143 class DALI_IMPORT_API Ruler : public RefObject
146 /// @brief The type of the ruler
148 Fixed, ///< A fixed ruler
149 Free ///< A free ruler
155 * @brief Constructs ruler, default enabled, with limitless domain.
160 * @brief Snaps (x) in accordance to the ruler settings.
162 * @param[in] x The input value on the ruler to be snapped.
163 * @param[in] bias (optional) The biasing employed for snapping
164 * 0 floor input (floor x) "Used for Flick Left"
165 * 0.5 round input (floor x + 0.5) "Used for Release"
166 * 1 ceil input (floor x + 1.0) "Used for Flick Right"
167 * @return The position of the one dimensional point passed in once snapped.
169 virtual float Snap(float x, float bias = 0.5f) const = 0;
172 * @brief Returns position from page, based on whatever the ruler
175 * If (wrap) is true, then will set volume to the number of
176 * times page has exceeded the domain's volume (volume being the
177 * number of pages within the domain), while wrapping the position
180 * @param[in] page The page index
181 * @param[out] volume The overflow volume when the page exceeds the domain (wrap must be enabled)
182 * @param[in] wrap Enable wrap mode
183 * @return The position representing this page point.
185 virtual float GetPositionFromPage(unsigned int page, unsigned int &volume, bool wrap) const = 0;
188 * @brief Returns page from position, based on whatever the ruler
191 * If (wrap) is true, then will return a page wrapped within the domain.
193 * @param[in] position The position on the domain
194 * @param[in] wrap Enable wrap mode
195 * @return The page where this position resides.
197 virtual unsigned int GetPageFromPosition(float position, bool wrap) const = 0;
200 * @brief Returns the total number of pages within this Ruler.
202 * @return The number of pages in the Ruler.
204 virtual unsigned int GetTotalPages() const = 0;
207 * @brief Gets the extension interface of the Ruler.
209 * @return The extension interface of the Ruler
211 virtual RulerExtension* GetExtension() { return NULL; }
216 * @brief Gets the ruler type.
218 * @return The ruler type.
220 Ruler::RulerType GetType() const;
223 * @brief Returns whether this axis has been enabled or not.
225 * @return true if axis is enabled
227 bool IsEnabled() const;
230 * @brief Enables ruler (ruler must be enabled in order to traverse along it).
235 * @brief Disables ruler.
240 * @brief Sets Domain.
242 * @param[in] domain Ruler domain object.
244 void SetDomain(RulerDomain domain);
247 * @brief Gets Domain.
251 const RulerDomain &GetDomain() const;
254 * @brief Disables Domain (minimum/maximum extents for this axis).
256 void DisableDomain();
259 * @brief Clamps value (x) from (min) to (max).
261 * An optional length parameter can be specified to suggest that the
262 * subject is not a point but a line that should be clamped.
264 * @param[in] x X point to be clamped between (min) and (max) extents.
265 * @param[in] length (optional) The Length of the line from (x) to (x + length) to be clamped.
266 * @param[in] scale Scaling parameter which treats domain as scaled in calculations.
267 * @return The clamped value.
269 float Clamp(float x, float length = 0.0f, float scale = 1.0f) const;
273 * @brief Clamps value (x) from (min) to (max).
275 * An optional length parameter can be specified to suggest that the
276 * subject is not a point but a line to that should be clamped.
278 * @param[in] x X point to be clamped between (min) and (max) extents.
279 * @param[in] length (optional) The Length of the line from (x) to (x + length) to be clamped.
280 * @param[in] scale Scaling parameter which treats domain as scaled in calculations.
281 * @param[out] clamped Whether clamping occured and which size (None, Min or Max)
282 * @return The clamped value.
284 float Clamp(float x, float length, float scale, ClampState &clamped) const;
287 * @brief Snaps and Clamps (x) in accordance to ruler settings.
289 * @param[in] x value to be snapped in accordance to ruler snap value,
290 * and clamped in accordance to the ruler's domain (if set).
291 * @param[in] bias (optional) The biasing employed for snapping
292 * 0 floor input (floor x) "Used for Flick Left"
293 * 0.5 round input (floor x + 0.5) "Used for Release"
294 * 1 ceil input (floor x + 1.0) "Used for Flick Right"
295 * @param[in] length (optional) The Length of the line from (x) to (x + length)
297 * @param[in] scale Scaling parameter which treats domain as scaled in calculations.
298 * @return the clamped value after snapping
300 float SnapAndClamp(float x, float bias = 0.5f, float length = 0.0f, float scale = 1.0f) const;
303 * @brief Snaps and Clamps (x) in accordance to ruler settings.
305 * @param[in] x value to be snapped in accordance to ruler snap value,
306 * and clamped in accordance to the ruler's domain (if set).
307 * @param[in] bias (optional) The biasing employed for snapping
308 * 0 floor input (floor x) "Used for Flick Left"
309 * 0.5 round input (floor x + 0.5) "Used for Release"
310 * 1 ceil input (floor x + 1.0) "Used for Flick Right"
311 * @param[in] length (optional) The Length of the line from (x) to (x + length)
313 * @param[in] scale Scaling parameter which treats domain as scaled in calculations.
314 * @param[out] clamped Whether clamping occured and which size (None, Min or Max)
315 * @return The clamped value after snapping
317 float SnapAndClamp(float x, float bias, float length, float scale, ClampState &clamped) const;
322 * @brief Destructor - A reference counted object may only be deleted by calling Unreference().
328 RulerType mType; ///< Type of Ruler (Fixed or Free).
329 bool mEnabled; ///< If the ruler is enabled.
330 RulerDomain mDomain; ///< The domain of the ruler.
334 typedef IntrusivePtr<Ruler> RulerPtr; ///< Pointer to Dali::Toolkit::Ruler object
337 * @brief Concrete implementation of Ruler that has no snapping and has one single page.
339 class DALI_IMPORT_API DefaultRuler : public Ruler
343 * @brief DefaultRuler constructor.
348 * @copydoc Toolkit::Ruler::Snap
350 virtual float Snap(float x, float bias) const;
353 * @copydoc Toolkit::Ruler::GetPositionFromPage
355 virtual float GetPositionFromPage(unsigned int page, unsigned int &volume, bool wrap) const;
358 * @copydoc Toolkit::Ruler::GetPageFromPosition
360 virtual unsigned int GetPageFromPosition(float position, bool wrap) const;
363 * @copydoc Toolkit::Ruler::GetTotalPages
365 virtual unsigned int GetTotalPages() const;
369 * @brief Concrete implementation of Ruler that has fixed snapping.
371 class DALI_IMPORT_API FixedRuler : public Ruler
377 * @param[in] spacing The spacing between each interval on this ruler.
379 FixedRuler(float spacing = 1.0f);
382 * @copydoc Toolkit::Ruler::Snap
384 virtual float Snap(float x, float bias) const;
387 * @copydoc Toolkit::Ruler::GetPositionFromPage
389 virtual float GetPositionFromPage(unsigned int page, unsigned int &volume, bool wrap) const;
392 * @copydoc Toolkit::Ruler::GetPageFromPosition
394 virtual unsigned int GetPageFromPosition(float position, bool wrap) const;
397 * @copydoc Toolkit::Ruler::GetTotalPages
399 virtual unsigned int GetTotalPages() const;
402 float mSpacing; ///< The spacing between each interval
405 class ScrollViewEffect;
409 * @brief ScrollView contains actors that can be scrolled manually (via touch)
413 * | %Signal Name | Method |
414 * |-------------------|----------------------------|
415 * | snap-started | @ref SnapStartedSignal() |
417 class DALI_IMPORT_API ScrollView : public Scrollable
423 * @brief Clamp signal event's data
427 ClampState2D scale; ///< Clamp information for scale axes
428 ClampState2D position; ///< Clamp information for position axes
429 ClampState rotation; ///< Clamp information for rotation
433 * @brief Snap signal event's data.
437 SnapType type; ///< Current snap commencing
438 Vector2 position; ///< Target snap position
439 float duration; ///< Duration of snap animation.
443 * @brief The start and end property ranges for this control.
447 ANIMATABLE_PROPERTY_START_INDEX = Toolkit::Scrollable::ANIMATABLE_PROPERTY_END_INDEX + 1,
448 ANIMATABLE_PROPERTY_END_INDEX = ANIMATABLE_PROPERTY_START_INDEX + 1000 ///< Reserve animatable property indices
452 * @brief An enumeration of properties belonging to the ScrollView class.
458 SCROLL_POSITION = ANIMATABLE_PROPERTY_START_INDEX, ///< Property, name "scroll-position", type Vector2
459 SCROLL_PRE_POSITION, ///< Property, name "scroll-pre-position", type Vector2
460 SCROLL_PRE_POSITION_X, ///< Property, name "scroll-pre-position-x", type float
461 SCROLL_PRE_POSITION_Y, ///< Property, name "scroll-pre-position-y", type float
462 SCROLL_PRE_POSITION_MAX, ///< Property, name "scroll-pre-position-max", type Vector2
463 SCROLL_PRE_POSITION_MAX_X, ///< Property, name "scroll-pre-position-max-x", type float
464 SCROLL_PRE_POSITION_MAX_Y, ///< Property, name "scroll-pre-position-max-y", type float
465 OVERSHOOT_X, ///< Property, name "overshoot-x", type float
466 OVERSHOOT_Y, ///< Property, name "overshoot-y", type float
467 SCROLL_FINAL, ///< Property, name "scroll-final", type Vector2
468 SCROLL_FINAL_X, ///< Property, name "scroll-final-x", type float
469 SCROLL_FINAL_Y, ///< Property, name "scroll-final-y", type float
470 WRAP, ///< Property, name "wrap", type bool
471 PANNING, ///< Property, name "panning", type bool
472 SCROLLING, ///< Property, name "scrolling", type bool
473 SCROLL_DOMAIN_SIZE, ///< Property, name "scroll-domain-size" type Vector2
474 SCROLL_DOMAIN_SIZE_X, ///< Property, name "scroll-domain-size-x" type float
475 SCROLL_DOMAIN_SIZE_Y, ///< Property, name "scroll-domain-size-y" type float
476 SCROLL_DOMAIN_OFFSET, ///< Property, name "scroll-domain-offset" type Vector2
477 SCROLL_POSITION_DELTA, ///< Property, name "scroll-position-delta" type Vector2
478 START_PAGE_POSITION ///< Property, name "start-page-position" type Vector3
484 typedef Signal< void ( const SnapEvent& ) > SnapStartedSignalType; ///< SnapStarted signal type
489 * @brief Creates an empty ScrollView handle.
494 * @brief Copy constructor.
496 * Creates another handle that points to the same real object
498 * @param[in] handle to copy from
500 ScrollView( const ScrollView& handle );
503 * @brief Assignment operator.
505 * Changes this handle to point to another real object
506 * @param[in] handle The handle to copy from
507 * @return A reference to this
509 ScrollView& operator=( const ScrollView& handle );
514 * This is non-virtual since derived Handle types must not contain data or virtual methods.
519 * @brief Create an initialized ScrollView.
521 * @return A handle to a newly allocated Dali resource.
523 static ScrollView New();
526 * @brief Downcast an Object handle to ScrollView.
528 * If handle points to a ScrollView the downcast produces valid
529 * handle. If not the returned handle is left uninitialized.
531 * @param[in] handle Handle to an object
532 * @return handle to a ScrollView or an uninitialized handle
534 static ScrollView DownCast( BaseHandle handle );
539 * @brief Get snap-animation's AlphaFunction.
541 * @return Current easing alpha function of the snap animation.
543 AlphaFunction GetScrollSnapAlphaFunction() const;
546 * @brief Set snap-animation's AlphaFunction.
548 * @param[in] alpha Easing alpha function of the snap animation.
550 void SetScrollSnapAlphaFunction(AlphaFunction alpha);
553 * @brief Get flick-animation's AlphaFunction.
555 * @return Current easing alpha function of the flick animation.
557 AlphaFunction GetScrollFlickAlphaFunction() const;
560 * @brief Set flick-animation's AlphaFunction.
562 * @param[in] alpha Easing alpha function of the flick animation.
564 void SetScrollFlickAlphaFunction(AlphaFunction alpha);
567 * @brief Gets the time for the scroll snap-animation.
569 * This animation occurs when the user drags, and releases.
571 * @return The time in seconds for the animation to take.
573 float GetScrollSnapDuration() const;
576 * @brief Sets the time for the scroll snap-animation.
578 * This animation occurs when the user drags, and releases.
580 * @param[in] time The time in seconds for the animation to take.
582 void SetScrollSnapDuration(float time);
585 * @brief Gets the time for the scroll flick-animation.
587 * This animation occurs when the user flicks scroll view.
589 * @return The time in seconds for the animation to take.
591 float GetScrollFlickDuration() const;
594 * @brief Sets the time for the scroll flick-animation.
596 * This animation occurs when the user flicks scroll view.
598 * @param[in] time The time in seconds for the animation to take.
600 void SetScrollFlickDuration(float time);
603 * @brief Set X axis ruler.
605 * Defines how scrolling horizontally is snapped, and
606 * the boundary (domain) in which the ScrollView can pan.
608 * @param[in] ruler The ruler to be used for the X axis
610 void SetRulerX(RulerPtr ruler);
613 * @brief Set Y axis ruler.
615 * Defines how scrolling vertically is snapped, and the boundary
616 * (domain) in which the ScrollView can pan.
618 * @param[in] ruler The ruler to be used for the Y axis
620 void SetRulerY(RulerPtr ruler);
623 * @brief Set Scroll's touch sensitivity.
625 * @note Unlike SetSensitive(), this determines whether this ScrollView
626 * should react (e.g. pan), without disrupting the sensitivity of it's children.
628 * @param[in] sensitive true to enable scroll, false to disable scrolling
630 void SetScrollSensitive(bool sensitive);
633 * @brief Set maximum overshoot amount.
635 * The final overshoot value is within 0.0f to 1.0f, but the maximum
636 * overshoot is in pixels (e.g. if you scroll 75 pixels beyond the
637 * edge of a scrollable area and the maximum overshoot is 100 then
638 * the final overshoot value will be 0.75f)
640 * @param[in] overshootX the maximum number of horizontally scrolled pixels before overshoot X reaches 1.0f
641 * @param[in] overshootY the maximum number of vertically scrolled pixels before overshoot Y reaches 1.0f
643 void SetMaxOvershoot(float overshootX, float overshootY);
646 * @brief Set Snap Overshoot animation's AlphaFunction.
648 * @param[in] alpha Easing alpha function of the overshoot snap animation.
650 void SetSnapOvershootAlphaFunction(AlphaFunction alpha);
653 * @brief Set Snap Overshoot animation's Duration.
655 * @note Set duration to 0 seconds, to disable Animation.
657 * @param[in] duration The duration of the overshoot snap animation.
659 void SetSnapOvershootDuration(float duration);
662 * @brief Enables or Disables Actor Auto-Snap mode.
664 * When Actor Auto-Snap mode has been enabled, ScrollView will automatically
665 * snap to the closest actor (The closest actor will appear in the center of
668 * @param[in] enable Enables (true), or disables (false) Actor AutoSnap
670 void SetActorAutoSnap(bool enable);
673 * @brief Enables or Disables Wrap mode for ScrollView contents.
675 * When enabled, the ScrollView contents are wrapped over the X/Y Domain.
677 * @note You must apply a position constraint that causes Wrapping
680 * @param[in] enable Enables (true), or disables (false) Wrap Mode.
682 void SetWrapMode(bool enable);
685 * @brief Gets the current distance needed to scroll for ScrollUpdatedSignal to be emitted
687 * @return Current scroll update distance
689 int GetScrollUpdateDistance() const;
692 * @brief Sets the distance needed to scroll for ScrollUpdatedSignal to be emitted
694 * The scroll update distance tells ScrollView how far to move before ScrollUpdatedSignal the informs application.
695 * Each time the ScrollView crosses this distance the signal will be emitted
697 * @param[in] distance The distance for ScrollView to move before emitting update signal
699 void SetScrollUpdateDistance(int distance);
702 * @brief Returns state of Axis Auto Lock mode.
704 * @return Whether Axis Auto Lock mode has been enabled or not.
706 bool GetAxisAutoLock() const;
709 * @brief Enables or Disables Axis Auto Lock mode for panning within the ScrollView.
711 * When enabled, any pan gesture that appears mostly horizontal or mostly
712 * vertical, will be automatically restricted to horizontal only or vertical
713 * only panning, until the pan gesture has completed.
715 * @param[in] enable Enables (true), or disables (false) AxisAutoLock mode.
717 void SetAxisAutoLock(bool enable);
720 * @brief Gets the gradient threshold at which a panning gesture
721 * should be locked to the Horizontal or Vertical axis.
723 * @return The gradient, a value between 0.0 and 1.0f.
725 float GetAxisAutoLockGradient() const;
728 * @brief Sets the gradient threshold at which a panning gesture should be locked to the
729 * Horizontal or Vertical axis.
731 * By default this is 0.36 (0.36:1) which means angles less than 20
732 * degrees to an axis will lock to that axis.
734 * @note: Specifying a value of 1.0 (the maximum value accepted) indicates that
735 * all panning gestures will auto-lock. Either to the horizontal or vertical axis.
737 * @param[in] gradient A value between 0.0 and 1.0 (auto-lock for all angles)
739 void SetAxisAutoLockGradient(float gradient);
742 * @brief Gets the friction coefficient setting for ScrollView when
743 * flicking in free panning mode.
745 * This is a value in stage-diagonals per second^2.
746 * stage-diagonal = Length( stage.width, stage.height )
747 * @return Friction coefficient is returned.
749 float GetFrictionCoefficient() const;
752 * @brief Sets the friction coefficient for ScrollView when flicking
753 * in free panning mode.
755 * This is a value in stage-diagonals per second^2.
756 * stage-diagonal = Length( stage.width, stage.height ).
758 * A stage 480x800 in size has a diagonal length of 933.
759 * Friction coefficient of 1.0 means the swipe velocity will
760 * reduce by 1.0 * 933 pixels/sec^2.
761 * @param[in] friction Friction coefficient, must be greater than 0.0 (default = 1.0)
763 void SetFrictionCoefficient(float friction);
766 * @brief Gets the flick speed coefficient for ScrollView when
767 * flicking in free panning mode.
769 * This is a constant which multiplies the input touch
770 * flick velocity to determine the actual velocity at
771 * which to move the scrolling area.
772 * @return The flick speed coefficient is returned.
774 float GetFlickSpeedCoefficient() const;
777 * @brief Sets the flick speed coefficient for ScrollView when
778 * flicking in free panning mode.
780 * This is a constant which multiplies the input touch
781 * flick velocity to determine the actual velocity at
782 * which to move the scrolling area.
783 * @param[in] speed The flick speed coefficient (default = 1.0).
785 void SetFlickSpeedCoefficient(float speed);
788 * @brief Returns the minimum pan distance required for a flick gesture in pixels
790 * @return Minimum pan distance vector with separate x and y distance
792 Vector2 GetMinimumDistanceForFlick() const;
795 * @brief Sets the minimum pan distance required for a flick in pixels
797 * 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
799 * @param[in] distance The minimum pan distance for a flick
801 void SetMinimumDistanceForFlick( const Vector2& distance );
804 * @brief Returns the minimum pan speed required for a flick gesture in pixels per second
806 * @return Minimum pan speed
808 float GetMinimumSpeedForFlick() const;
811 * @brief Sets the minimum pan speed required for a flick in pixels per second
813 * @param[in] speed The minimum pan speed for a flick
815 void SetMinimumSpeedForFlick( float speed );
818 * @brief Gets the maximum flick speed setting for ScrollView when
819 * flicking in free panning mode.
821 * This is a value in stage-diagonals per second.
822 * stage-diagonal = Length( stage.width, stage.height )
823 * @return Maximum flick speed is returned
825 float GetMaxFlickSpeed() const;
828 * @brief Sets the maximum flick speed for the ScrollView when
829 * flicking in free panning mode.
831 * This is a value in stage-diagonals per second.
832 * stage-diagonal = Length( stage.width, stage.height )
834 * A stage 480x800 in size has a diagonal length of 933.
835 * Max Flick speed of 1.0 means the maximum velocity of
836 * a swipe can be 1.0 * 933 pixels/sec.
837 * @param[in] speed Maximum flick speed (default = 3.0)
839 void SetMaxFlickSpeed(float speed);
842 * @brief Gets the step of scroll distance in actor coordinates for
843 * each wheel event received in free panning mode.
845 * @return The step of scroll distance(pixel) in X and Y axes.
847 Vector2 GetWheelScrollDistanceStep() const;
850 * @brief Sets the step of scroll distance in actor coordinates for
851 * each wheel event received in free panning mode.
853 * @param[in] step The step of scroll distance(pixel) in X and Y axes.
855 * @note: If snap points are defined in the rulers, it will always
856 * scroll to the next snap point towards the scroll direction while
857 * receiving the wheel events.
860 void SetWheelScrollDistanceStep(Vector2 step);
863 * @brief Retrieves current scroll position.
865 * @returns The current scroll position.
867 Vector2 GetCurrentScrollPosition() const;
870 * @brief Retrieves current scroll page based on ScrollView
871 * dimensions being the size of one page, and all pages laid out in
872 * a grid fashion, increasing from left to right until the end of
875 * @note: Pages start from 0 as the first page, not 1.
877 * @returns The Current page.
879 unsigned int GetCurrentPage() const;
882 * @brief Scrolls View to position specified (contents will scroll to this position).
884 * Position 0,0 is the origin. Increasing X scrolls contents left, while
885 * increasing Y scrolls contents up.
886 * - If Rulers have been applied to the axes, then the contents will scroll until
887 * reaching the domain boundary.
888 * @note Contents will not snap to ruler snap points.
890 * @param[in] position The position to scroll to.
892 void ScrollTo(const Vector2& position);
895 * @brief Scrolls View to position specified (contents will scroll to this position).
897 * Position 0,0 is the origin. Increasing X scrolls contents left, while
898 * increasing Y scrolls contents up.
899 * - If Rulers have been applied to the axes, then the contents will scroll until
900 * reaching the domain boundary.
901 * @note Contents will not snap to ruler snap points.
903 * @param[in] position The position to scroll to.
904 * @param[in] duration The duration of the animation in seconds
906 void ScrollTo(const Vector2& position, float duration);
909 * @brief Scrolls View to position specified (contents will scroll to this position)
911 * Position 0,0 is the origin. Increasing X scrolls contents left, while
912 * increasing Y scrolls contents up.
913 * - If Rulers have been applied to the axes, then the contents will scroll until
914 * reaching the domain boundary.
915 * @note Contents will not snap to ruler snap points.
917 * @param[in] position The position to scroll to.
918 * @param[in] duration The duration of the animation in seconds
919 * @param[in] alpha The alpha function to use
921 void ScrollTo(const Vector2& position, float duration, AlphaFunction alpha);
924 * @brief Scrolls View to position specified (contents will scroll to this position).
926 * Position 0,0 is the origin. Increasing X scrolls contents left, while
927 * increasing Y scrolls contents up.
928 * - If Rulers have been applied to the axes, then the contents will scroll until
929 * reaching the domain boundary.
930 * @note Contents will not snap to ruler snap points.
931 * Biasing parameters are provided such that in scenarios with 2 or 2x2 pages in
932 * wrap mode, the application developer can decide whether to scroll left or right
933 * to get to the target page
935 * @param[in] position The position to scroll to.
936 * @param[in] duration The duration of the animation in seconds
937 * @param[in] horizontalBias Whether to bias scrolling to left or right.
938 * @param[in] verticalBias Whether to bias scrolling to top or bottom.
940 void ScrollTo(const Vector2& position, float duration,
941 DirectionBias horizontalBias, DirectionBias verticalBias);
944 * @brief Scrolls View to position specified (contents will scroll to this position)
946 * Position 0,0 is the origin. Increasing X scrolls contents left, while
947 * increasing Y scrolls contents up.
948 * - If Rulers have been applied to the axes, then the contents will scroll until
949 * reaching the domain boundary.
950 * @note Contents will not snap to ruler snap points.
951 * Biasing parameters are provided such that in scenarios with 2 or 2x2 pages in
952 * wrap mode, the application developer can decide whether to scroll left or right
953 * to get to the target page
955 * @param[in] position The position to scroll to.
956 * @param[in] duration The duration of the animation in seconds
957 * @param[in] horizontalBias Whether to bias scrolling to left or right.
958 * @param[in] verticalBias Whether to bias scrolling to top or bottom.
959 * @param[in] alpha Alpha function to use
961 void ScrollTo(const Vector2& position, float duration, AlphaFunction alpha,
962 DirectionBias horizontalBias, DirectionBias verticalBias);
965 * @brief Scrolls View to page currently based on assumption that each page is
966 * "(page) * ScrollViewSize.width, 0".
968 * @note Should probably be upgraded so that page is an abstract class, that can be
969 * a function of ScrollViewSize, ruler domain, ruler snap points etc. as pages may be
970 * orchestrated in a 2D grid fashion, or variable width.
972 * @param[in] page to scroll to
974 void ScrollTo(unsigned int page);
977 * @brief Scrolls View to page currently based on assumption that each page is
978 * "(page) * ScrollViewSize.width, 0".
980 * @note Should probably be upgraded so that page is an abstract class, that can be
981 * a function of ScrollViewSize, ruler domain, ruler snap points etc. as pages may be
982 * orchestrated in a 2D grid fashion, or variable width.
984 * @param[in] page to scroll to
985 * @param[in] duration The duration of the animation in seconds
987 void ScrollTo(unsigned int page, float duration);
990 * @brief Scrolls View to page currently based on assumption that each page is
991 * "(page) * ScrollViewSize.width, 0".
993 * @note Should probably be upgraded so that page is an abstract class, that can be
994 * a function of ScrollViewSize, ruler domain, ruler snap points etc. as pages may be
995 * orchestrated in a 2D grid fashion, or variable width.
996 * A biasing parameter is provided such that in scenarios with 2 pages in wrap mode,
997 * the application developer can decide whether to scroll left or right to get to
1000 * @param[in] page to scroll to
1001 * @param[in] duration The duration of the animation in seconds
1002 * @param[in] bias Whether to bias scrolling to left or right.
1004 void ScrollTo(unsigned int page, float duration, DirectionBias bias);
1007 * @brief Scrolls View such that actor appears in the center of the ScrollView.
1009 * @note Actor must be a direct child of ScrollView, otherwise will
1010 * cause an assertion failure.
1011 * @param[in] actor The actor to center in on (via Scrolling).
1013 void ScrollTo(Actor& actor);
1016 * @brief Scrolls View such that actor appears in the center of the ScrollView.
1018 * @note Actor must be a direct child of ScrollView, otherwise will
1019 * cause an assertion failure.
1020 * @param[in] actor The actor to center in on (via Scrolling).
1021 * @param[in] duration The duration of the animation in seconds
1023 void ScrollTo(Actor& actor, float duration);
1026 * @brief Scrolls View to the nearest snap points as specified by the Rulers.
1028 * If already at snap points, then will return false, and not scroll.
1030 * @return True if Snapping necessary.
1032 bool ScrollToSnapPoint();
1035 * @brief Applies a constraint that will affect the children of ScrollView.
1037 * @note this affects all existing and future Actors that are added to scrollview.
1038 * @param[in] constraint The constraint to apply
1040 void ApplyConstraintToChildren(Constraint constraint);
1043 * @brief Removes all constraints that will affect the children of ScrollView.
1045 * @note this removes all constraints from actors that have been added
1048 void RemoveConstraintsFromChildren();
1051 * @brief Apply Effect to ScrollView.
1053 * @param[in] effect The effect to apply to scroll view
1055 void ApplyEffect(ScrollViewEffect effect);
1058 * @brief Remove Effect from ScrollView.
1060 * @param[in] effect The effect to remove.
1062 void RemoveEffect(ScrollViewEffect effect);
1065 * @brief Remove All Effects from ScrollView.
1067 void RemoveAllEffects();
1070 * @brief Binds actor to this ScrollView.
1072 * Once an actor is bound to a ScrollView, it will be subject to
1073 * that ScrollView's properties.
1075 * @param[in] child The actor to add to this ScrollView.
1077 void BindActor(Actor child);
1080 * @brief Unbind Actor from this ScrollView.
1082 * Once Unbound, this ScrollView will not affect the actor.
1083 * @note this does not remove the child from the ScrollView container
1085 * @param[in] child The actor to be unbound.
1087 void UnbindActor(Actor child);
1090 * @brief Allows the user to constrain the scroll view in a particular direction.
1092 * @param[in] direction The axis to constrain the scroll-view to.
1093 * Usually set to PanGestureDetector::DIRECTION_VERTICAL or PanGestureDetector::DIRECTION_HORIZONTAL (but can be any other angle if desired).
1094 * @param[in] threshold The threshold to apply around the axis.
1095 * @note If no threshold is specified, then the default threshold of PI * 0.25 radians (or 45 degrees) is used.
1097 void SetScrollingDirection( Radian direction, Radian threshold = PanGestureDetector::DEFAULT_THRESHOLD );
1100 * @brief Remove a direction constraint from the scroll view.
1102 * @param[in] direction The axis to stop constraining to.
1103 * Usually will be PanGestureDetector::DIRECTION_VERTICAL or PanGestureDetector::DIRECTION_HORIZONTAL (but can be any other angle if desired).
1105 void RemoveScrollingDirection( Radian direction );
1110 * @brief Signal emitted when the ScrollView has started to snap or flick (it tells the target
1111 * position, scale, rotation for the snap or flick)
1113 * A callback of the following type may be connected:
1115 * void YourCallbackName(const SnapEvent& event);
1117 * @pre The Object has been initialized.
1118 * @return The signal to connect to.
1120 SnapStartedSignalType& SnapStartedSignal();
1122 public: // Not intended for application developers
1125 * @brief Creates a handle using the Toolkit::Internal implementation.
1127 * @param[in] implementation The Control implementation.
1129 DALI_INTERNAL ScrollView(Internal::ScrollView& implementation);
1132 * @brief Allows the creation of this Control from an Internal::CustomActor pointer.
1134 * @param[in] internal A pointer to the internal CustomActor.
1136 explicit DALI_INTERNAL ScrollView( Dali::Internal::CustomActor* internal );
1139 } // namespace Toolkit
1143 #endif // __DALI_TOOLKIT_SCROLL_VIEW_H__