1 #ifndef __DALI_TOOLKIT_SCROLL_VIEW_H__
2 #define __DALI_TOOLKIT_SCROLL_VIEW_H__
5 * Copyright (c) 2014 Samsung Electronics Co., Ltd.
7 * Licensed under the Apache License, Version 2.0 (the "License");
8 * you may not use this file except in compliance with the License.
9 * You may obtain a copy of the License at
11 * http://www.apache.org/licenses/LICENSE-2.0
13 * Unless required by applicable law or agreed to in writing, software
14 * distributed under the License is distributed on an "AS IS" BASIS,
15 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
16 * See the License for the specific language governing permissions and
17 * limitations under the License.
22 #include <dali/public-api/animation/alpha-functions.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 3 dimensional clamp
53 ClampState x; ///< The clamp state of the x axis
54 ClampState y; ///< The clamp state of the y axis
55 ClampState z; ///< The clamp state of the z axis
59 * @brief The snap type
68 * @brief DirectionBias types.
72 DirectionBiasLeft = -1, ///< Bias scroll snap to Left
73 DirectionBiasNone = 0, ///< Don't bias scroll snap
74 DirectionBiasRight = 1 ///< Bias scroll snap to Right
78 * @brief Used for specifying minimum/maximum extents of a ruler.
80 class DALI_IMPORT_API RulerDomain
85 * @brief Creates Ruler domain allowing a point to traverse between min and max extents.
87 * @param[in] min Minimum extent (point cannot traverse less than this)
88 * @param[in] max Maximum extent (point cannot traverse greater than this)
89 * @param[in] enabled Whether domain has been enabled or not.
91 explicit RulerDomain(float min, float max, bool enabled = true);
95 float min; ///< Minimum extent (point cannot traverse less than this)
96 float max; ///< Maximum extent (point cannot traverse greater than this)
97 bool enabled; ///< Whether domain has been enabled or not.
100 * @brief Clamps value (x) from (min) to (max).
102 * An optional length parameter can be specified to suggest that the
103 * subject is not a point but a line to that should be clamped.
105 * @param[in] x X point to be clamped between (min) and (max) extents.
106 * @param[in] length (optional) The Length of the line from (x) to (x + length) to be clamped.
107 * @param[in] scale Scaling parameter which treats domain as scaled in calculations.
108 * @return The clamped value.
110 float Clamp(float x, float length = 0.0f, float scale = 1.0f) const;
113 * @brief Clamps value (x) from (min) to (max).
115 * An optional length parameter can be specified to suggest that the
116 * subject is not a point but a line to that should be clamped.
118 * @param[in] x X point to be clamped between (min) and (max) extents.
119 * @param[in] length (optional) The Length of the line from (x) to (x + length) to be clamped.
120 * @param[in] scale Scaling parameter which treats domain as scaled in calculations.
121 * @param[out] clamped Whether clamping occured and which size (None, Min or Max)
122 * @return The clamped value.
124 float Clamp(float x, float length, float scale, ClampState &clamped) const;
127 * @brief Returns (max-min) size of ruler.
129 * @return The size of the ruler from min to max.
131 float GetSize() const;
136 * @brief Abstract class to define scroll axes.
138 * It can specify whether they are traversable, where their snap
139 * points are and their domain.
141 class DALI_IMPORT_API Ruler : public RefObject
144 /// @brief The type of the ruler
146 Fixed, ///< A fixed ruler
147 Free ///< A free ruler
153 * @brief Constructs ruler, default enabled, with limitless domain.
158 * @brief Snaps (x) in accordance to the ruler settings.
160 * @param[in] x The input value on the ruler to be snapped.
161 * @param[in] bias (optional) The biasing employed for snapping
162 * 0 floor input (floor x) "Used for Flick Left"
163 * 0.5 round input (floor x + 0.5) "Used for Release"
164 * 1 ceil input (floor x + 1.0) "Used for Flick Right"
165 * @return The position of the one dimensional point passed in once snapped.
167 virtual float Snap(float x, float bias = 0.5f) const = 0;
170 * @brief Returns position from page, based on whatever the ruler
173 * If (wrap) is true, then will set volume to the number of
174 * times page has exceeded the domain's volume (volume being the
175 * number of pages within the domain), while wrapping the position
178 * @param[in] page The page index
179 * @param[out] volume The overflow volume when the page exceeds the domain (wrap must be enabled)
180 * @param[in] wrap Enable wrap mode
181 * @return The position representing this page point.
183 virtual float GetPositionFromPage(unsigned int page, unsigned int &volume, bool wrap) const = 0;
186 * @brief Returns page from position, based on whatever the ruler
189 * If (wrap) is true, then will return a page wrapped within the domain.
191 * @param[in] position The position on the domain
192 * @param[in] wrap Enable wrap mode
193 * @return The page where this position resides.
195 virtual unsigned int GetPageFromPosition(float position, bool wrap) const = 0;
198 * @brief Returns the total number of pages within this Ruler.
200 * @return The number of pages in the Ruler.
202 virtual unsigned int GetTotalPages() const = 0;
207 * @brief Gets the ruler type.
209 * @return The ruler type.
211 Ruler::RulerType GetType() const;
214 * @brief Returns whether this axis has been enabled or not.
216 * @return true if axis is enabled
218 bool IsEnabled() const;
221 * @brief Enables ruler (ruler must be enabled in order to traverse along it).
226 * @brief Disables ruler.
231 * @brief Sets Domain.
233 * @param[in] domain Ruler domain object.
235 void SetDomain(RulerDomain domain);
238 * @brief Gets Domain.
242 const RulerDomain &GetDomain() const;
245 * @brief Disables Domain (minimum/maximum extents for this axis).
247 void DisableDomain();
250 * @brief Clamps value (x) from (min) to (max).
252 * An optional length parameter can be specified to suggest that the
253 * subject is not a point but a line that should be clamped.
255 * @param[in] x X point to be clamped between (min) and (max) extents.
256 * @param[in] length (optional) The Length of the line from (x) to (x + length) to be clamped.
257 * @param[in] scale Scaling parameter which treats domain as scaled in calculations.
258 * @return The clamped value.
260 float Clamp(float x, float length = 0.0f, float scale = 1.0f) const;
264 * @brief Clamps value (x) from (min) to (max).
266 * An optional length parameter can be specified to suggest that the
267 * subject is not a point but a line to that should be clamped.
269 * @param[in] x X point to be clamped between (min) and (max) extents.
270 * @param[in] length (optional) The Length of the line from (x) to (x + length) to be clamped.
271 * @param[in] scale Scaling parameter which treats domain as scaled in calculations.
272 * @param[out] clamped Whether clamping occured and which size (None, Min or Max)
273 * @return The clamped value.
275 float Clamp(float x, float length, float scale, ClampState &clamped) const;
278 * @brief Snaps and Clamps (x) in accordance to ruler settings.
280 * @param[in] x value to be snapped in accordance to ruler snap value,
281 * and clamped in accordance to the ruler's domain (if set).
282 * @param[in] bias (optional) The biasing employed for snapping
283 * 0 floor input (floor x) "Used for Flick Left"
284 * 0.5 round input (floor x + 0.5) "Used for Release"
285 * 1 ceil input (floor x + 1.0) "Used for Flick Right"
286 * @param[in] length (optional) The Length of the line from (x) to (x + length)
288 * @param[in] scale Scaling parameter which treats domain as scaled in calculations.
289 * @return the clamped value after snapping
291 float SnapAndClamp(float x, float bias = 0.5f, float length = 0.0f, float scale = 1.0f) const;
294 * @brief Snaps and Clamps (x) in accordance to ruler settings.
296 * @param[in] x value to be snapped in accordance to ruler snap value,
297 * and clamped in accordance to the ruler's domain (if set).
298 * @param[in] bias (optional) The biasing employed for snapping
299 * 0 floor input (floor x) "Used for Flick Left"
300 * 0.5 round input (floor x + 0.5) "Used for Release"
301 * 1 ceil input (floor x + 1.0) "Used for Flick Right"
302 * @param[in] length (optional) The Length of the line from (x) to (x + length)
304 * @param[in] scale Scaling parameter which treats domain as scaled in calculations.
305 * @param[out] clamped Whether clamping occured and which size (None, Min or Max)
306 * @return The clamped value after snapping
308 float SnapAndClamp(float x, float bias, float length, float scale, ClampState &clamped) const;
313 * @brief Destructor - A reference counted object may only be deleted by calling Unreference().
319 RulerType mType; ///< Type of Ruler (Fixed or Free).
320 bool mEnabled; ///< If the ruler is enabled.
321 RulerDomain mDomain; ///< The domain of the ruler.
325 typedef IntrusivePtr<Ruler> RulerPtr; ///< Pointer to Dali::Toolkit::Ruler object
328 * @brief Concrete implementation of Ruler that has no snapping and has one single page.
330 class DALI_IMPORT_API DefaultRuler : public Ruler
334 * @brief DefaultRuler constructor.
339 * @copydoc Toolkit::Ruler::Snap
341 virtual float Snap(float x, float bias) const;
344 * @copydoc Toolkit::Ruler::GetPositionFromPage
346 virtual float GetPositionFromPage(unsigned int page, unsigned int &volume, bool wrap) const;
349 * @copydoc Toolkit::Ruler::GetPageFromPosition
351 virtual unsigned int GetPageFromPosition(float position, bool wrap) const;
354 * @copydoc Toolkit::Ruler::GetTotalPages
356 virtual unsigned int GetTotalPages() const;
360 * @brief Concrete implementation of Ruler that has fixed snapping.
362 class DALI_IMPORT_API FixedRuler : public Ruler
368 * @param[in] spacing The spacing between each interval on this ruler.
370 FixedRuler(float spacing = 1.0f);
373 * @copydoc Toolkit::Ruler::Snap
375 virtual float Snap(float x, float bias) const;
378 * @copydoc Toolkit::Ruler::GetPositionFromPage
380 virtual float GetPositionFromPage(unsigned int page, unsigned int &volume, bool wrap) const;
383 * @copydoc Toolkit::Ruler::GetPageFromPosition
385 virtual unsigned int GetPageFromPosition(float position, bool wrap) const;
388 * @copydoc Toolkit::Ruler::GetTotalPages
390 virtual unsigned int GetTotalPages() const;
393 float mSpacing; ///< The spacing between each interval
396 class ScrollViewEffect;
400 * @brief ScrollView contains actors that can be scrolled manually (via touch)
404 * | %Signal Name | Method |
405 * |-------------------|----------------------------|
406 * | snap-started | @ref SnapStartedSignal() |
408 class DALI_IMPORT_API ScrollView : public Scrollable
414 static const float DEFAULT_SLOW_SNAP_ANIMATION_DURATION; ///< Default Drag-Release animation time.
415 static const float DEFAULT_FAST_SNAP_ANIMATION_DURATION; ///< Default Drag-Flick animation time.
416 static const float DEFAULT_SNAP_OVERSHOOT_DURATION; ///< Default Overshoot snapping animation time.
417 static const float DEFAULT_MAX_OVERSHOOT; ///< Default maximum allowed overshoot
419 static const float DEFAULT_AXIS_AUTO_LOCK_GRADIENT; ///< Default Axis-AutoLock gradient threshold. default is 0.36:1 (20 degrees)
420 static const float DEFAULT_FRICTION_COEFFICIENT; ///< Default Friction Co-efficient. (in stage diagonals per second)
421 static const float DEFAULT_FLICK_SPEED_COEFFICIENT; ///< Default Flick speed coefficient (multiples input touch velocity)
422 static const float DEFAULT_MAX_FLICK_SPEED; ///< Default Maximum flick speed. (in stage diagonals per second)
427 * @brief Clamp signal event's data
431 ClampState3D scale; ///< Clamp information for scale axes
432 ClampState3D 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 Vector3 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 "scroll-position", type Vector3
463 SCROLL_PRE_POSITION, ///< Property, name "scroll-pre-position", type Vector3
464 OVERSHOOT_X, ///< Property, name "overshoot-x", type float
465 OVERSHOOT_Y, ///< Property, name "overshoot-y", type float
466 SCROLL_FINAL, ///< Property, name "scroll-final", type Vector3
467 WRAP, ///< Property, name "wrap", type bool
468 PANNING, ///< Property, name "panning", type bool
469 SCROLLING, ///< Property, name "scrolling", type bool
470 SCROLL_DOMAIN_OFFSET, ///< Property, name "scroll-domain-offset" type Vector3
471 SCROLL_POSITION_DELTA, ///< Property, name "scroll-position-delta" type Vector3
472 START_PAGE_POSITION ///< Property, name "start-page-position" type Vector3
476 typedef Signal< void ( const SnapEvent& ) > SnapStartedSignalType; ///< SnapStarted signal type
479 * @brief Signal emitted when the ScrollView has started to snap or flick (it tells the target
480 * position, scale, rotation for the snap or flick)
482 SnapStartedSignalType& SnapStartedSignal();
487 * @brief Creates an empty ScrollView handle.
492 * @brief Copy constructor.
494 * Creates another handle that points to the same real object
496 * @param[in] handle to copy from
498 ScrollView( const ScrollView& handle );
501 * @brief Assignment operator.
503 * Changes this handle to point to another real object
504 * @param[in] handle The handle to copy from
505 * @return A reference to this
507 ScrollView& operator=( const ScrollView& handle );
512 * This is non-virtual since derived Handle types must not contain data or virtual methods.
517 * @brief Create an initialized ScrollView.
519 * @return A handle to a newly allocated Dali resource.
521 static ScrollView New();
524 * @brief Downcast an Object handle to ScrollView.
526 * If handle points to a ScrollView the downcast produces valid
527 * handle. If not the returned handle is left uninitialized.
529 * @param[in] handle Handle to an object
530 * @return handle to a ScrollView or an uninitialized handle
532 static ScrollView DownCast( BaseHandle handle );
537 * @brief Get snap-animation's AlphaFunction.
539 * @return Current easing alpha function of the snap animation.
541 AlphaFunction GetScrollSnapAlphaFunction() const;
544 * @brief Set snap-animation's AlphaFunction.
546 * @param[in] alpha Easing alpha function of the snap animation.
548 void SetScrollSnapAlphaFunction(AlphaFunction alpha);
551 * @brief Get flick-animation's AlphaFunction.
553 * @return Current easing alpha function of the flick animation.
555 AlphaFunction GetScrollFlickAlphaFunction() const;
558 * @brief Set flick-animation's AlphaFunction.
560 * @param[in] alpha Easing alpha function of the flick animation.
562 void SetScrollFlickAlphaFunction(AlphaFunction alpha);
565 * @brief Gets the time for the scroll snap-animation.
567 * This animation occurs when the user drags, and releases.
569 * @return The time in seconds for the animation to take.
571 float GetScrollSnapDuration() const;
574 * @brief Sets the time for the scroll snap-animation.
576 * This animation occurs when the user drags, and releases.
578 * @param[in] time The time in seconds for the animation to take.
580 void SetScrollSnapDuration(float time);
583 * @brief Gets the time for the scroll flick-animation.
585 * This animation occurs when the user flicks scroll view.
587 * @return The time in seconds for the animation to take.
589 float GetScrollFlickDuration() const;
592 * @brief Sets the time for the scroll flick-animation.
594 * This animation occurs when the user flicks scroll view.
596 * @param[in] time The time in seconds for the animation to take.
598 void SetScrollFlickDuration(float time);
601 * @brief Set X axis ruler.
603 * Defines how scrolling horizontally is snapped, and
604 * the boundary (domain) in which the ScrollView can pan.
606 * @param[in] ruler The ruler to be used for the X axis
608 void SetRulerX(RulerPtr ruler);
611 * @brief Set Y axis ruler.
613 * Defines how scrolling vertically is snapped, and the boundary
614 * (domain) in which the ScrollView can pan.
616 * @param[in] ruler The ruler to be used for the Y axis
618 void SetRulerY(RulerPtr ruler);
621 * @brief Set Scroll's touch sensitivity.
623 * @note Unlike SetSensitive(), this determines whether this ScrollView
624 * should react (e.g. pan), without disrupting the sensitivity of it's children.
626 * @param[in] sensitive true to enable scroll, false to disable scrolling
628 void SetScrollSensitive(bool sensitive);
631 * @brief Set maximum overshoot amount.
633 * The final overshoot value is within 0.0f to 1.0f, but the maximum
634 * overshoot is in pixels (e.g. if you scroll 75 pixels beyond the
635 * edge of a scrollable area and the maximum overshoot is 100 then
636 * the final overshoot value will be 0.75f)
638 * @param[in] overshootX the maximum number of horizontally scrolled pixels before overshoot X reaches 1.0f
639 * @param[in] overshootY the maximum number of vertically scrolled pixels before overshoot Y reaches 1.0f
641 void SetMaxOvershoot(float overshootX, float overshootY);
644 * @brief Set Snap Overshoot animation's AlphaFunction.
646 * @param[in] alpha Easing alpha function of the overshoot snap animation.
648 void SetSnapOvershootAlphaFunction(AlphaFunction alpha);
651 * @brief Set Snap Overshoot animation's Duration.
653 * @note Set duration to 0 seconds, to disable Animation.
655 * @param[in] duration The duration of the overshoot snap animation.
657 void SetSnapOvershootDuration(float duration);
660 * @brief Enables or Disables Actor Auto-Snap mode.
662 * When Actor Auto-Snap mode has been enabled, ScrollView will automatically
663 * snap to the closest actor (The closest actor will appear in the center of
666 * @param[in] enable Enables (true), or disables (false) Actor AutoSnap
668 void SetActorAutoSnap(bool enable);
671 * @brief Enables or Disables Wrap mode for ScrollView contents.
673 * When enabled, the ScrollView contents are wrapped over the X/Y Domain.
675 * @note You must apply a position constraint that causes Wrapping
678 * @param[in] enable Enables (true), or disables (false) Wrap Mode.
680 void SetWrapMode(bool enable);
683 * @brief Gets the current distance needed to scroll for ScrollUpdatedSignal to be emitted
685 * @return Current scroll update distance
687 int GetScrollUpdateDistance() const;
690 * @brief Sets the distance needed to scroll for ScrollUpdatedSignal to be emitted
692 * The scroll update distance tells ScrollView how far to move before ScrollUpdatedSignal the informs application.
693 * Each time the ScrollView crosses this distance the signal will be emitted
695 * @param[in] distance The distance for ScrollView to move before emitting update signal
697 void SetScrollUpdateDistance(int distance);
700 * @brief Returns state of Axis Auto Lock mode.
702 * @return Whether Axis Auto Lock mode has been enabled or not.
704 bool GetAxisAutoLock() const;
707 * @brief Enables or Disables Axis Auto Lock mode for panning within the ScrollView.
709 * When enabled, any pan gesture that appears mostly horizontal or mostly
710 * vertical, will be automatically restricted to horizontal only or vertical
711 * only panning, until the pan gesture has completed.
713 * @param[in] enable Enables (true), or disables (false) AxisAutoLock mode.
715 void SetAxisAutoLock(bool enable);
718 * @brief Gets the gradient threshold at which a panning gesture
719 * should be locked to the Horizontal or Vertical axis.
721 * @return The gradient, a value between 0.0 and 1.0f.
723 float GetAxisAutoLockGradient() const;
726 * @brief Sets the gradient threshold at which a panning gesture should be locked to the
727 * Horizontal or Vertical axis.
729 * By default this is 0.36 (0.36:1) which means angles less than 20
730 * degrees to an axis will lock to that axis.
732 * @note: Specifying a value of 1.0 (the maximum value accepted) indicates that
733 * all panning gestures will auto-lock. Either to the horizontal or vertical axis.
735 * @param[in] gradient A value between 0.0 and 1.0 (auto-lock for all angles)
737 void SetAxisAutoLockGradient(float gradient);
740 * @brief Gets the friction coefficient setting for ScrollView when
741 * flicking in free panning mode.
743 * This is a value in stage-diagonals per second^2.
744 * stage-diagonal = Length( stage.width, stage.height )
745 * @return Friction coefficient is returned.
747 float GetFrictionCoefficient() const;
750 * @brief Sets the friction coefficient for ScrollView when flicking
751 * in free panning mode.
753 * This is a value in stage-diagonals per second^2.
754 * stage-diagonal = Length( stage.width, stage.height ).
756 * A stage 480x800 in size has a diagonal length of 933.
757 * Friction coefficient of 1.0 means the swipe velocity will
758 * reduce by 1.0 * 933 pixels/sec^2.
759 * @param[in] friction Friction coefficient, must be greater than 0.0 (default = 1.0)
761 void SetFrictionCoefficient(float friction);
764 * @brief Gets the flick speed coefficient for ScrollView when
765 * flicking in free panning mode.
767 * This is a constant which multiplies the input touch
768 * flick velocity to determine the actual velocity at
769 * which to move the scrolling area.
770 * @return The flick speed coefficient is returned.
772 float GetFlickSpeedCoefficient() const;
775 * @brief Sets the flick speed coefficient for ScrollView when
776 * flicking in free panning mode.
778 * This is a constant which multiplies the input touch
779 * flick velocity to determine the actual velocity at
780 * which to move the scrolling area.
781 * @param[in] speed The flick speed coefficient (default = 1.0).
783 void SetFlickSpeedCoefficient(float speed);
786 * @brief Returns the minimum pan distance required for a flick gesture in pixels
788 * @return Minimum pan distance vector with separate x and y distance
790 Vector2 GetMinimumDistanceForFlick() const;
793 * @brief Sets the minimum pan distance required for a flick in pixels
795 * 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
797 * @param[in] distance The minimum pan distance for a flick
799 void SetMinimumDistanceForFlick( const Vector2& distance );
802 * @brief Returns the minimum pan speed required for a flick gesture in pixels per second
804 * @return Minimum pan speed
806 float GetMinimumSpeedForFlick() const;
809 * @brief Sets the minimum pan speed required for a flick in pixels per second
811 * @param[in] speed The minimum pan speed for a flick
813 void SetMinimumSpeedForFlick( float speed );
816 * @brief Gets the maximum flick speed setting for ScrollView when
817 * flicking in free panning mode.
819 * This is a value in stage-diagonals per second.
820 * stage-diagonal = Length( stage.width, stage.height )
821 * @return Maximum flick speed is returned
823 float GetMaxFlickSpeed() const;
826 * @brief Sets the maximum flick speed for the ScrollView when
827 * flicking in free panning mode.
829 * This is a value in stage-diagonals per second.
830 * stage-diagonal = Length( stage.width, stage.height )
832 * A stage 480x800 in size has a diagonal length of 933.
833 * Max Flick speed of 1.0 means the maximum velocity of
834 * a swipe can be 1.0 * 933 pixels/sec.
835 * @param[in] speed Maximum flick speed (default = 3.0)
837 void SetMaxFlickSpeed(float speed);
840 * @brief Gets the step of scroll distance in actor coordinates for
841 * each mouse wheel event received in free panning mode.
843 * @return The step of scroll distance(pixel) in X and Y axes.
845 Vector2 GetMouseWheelScrollDistanceStep() const;
848 * @brief Sets the step of scroll distance in actor coordinates for
849 * each mouse wheel event received in free panning mode.
851 * @param[in] step The step of scroll distance(pixel) in X and Y axes.
853 * @note: If snap points are defined in the rulers, it will always
854 * scroll to the next snap point towards the scroll direction while
855 * receiving the mouse wheel events.
858 void SetMouseWheelScrollDistanceStep(Vector2 step);
861 * @brief Retrieves current scroll position.
863 * @returns The current scroll position.
865 Vector3 GetCurrentScrollPosition() const;
868 * @brief Sets the current scroll position, overriding current scroll animations. If panning is currently taking place
869 * SetScrollPosition will have no effect. Try to ensure panning has stopped before calling this function.
871 * @param[in] position The new scroll position to set.
873 void SetScrollPosition(const Vector3& position);
876 * @brief Retrieves current scroll page based on ScrollView
877 * dimensions being the size of one page, and all pages laid out in
878 * a grid fashion, increasing from left to right until the end of
881 * @note: Pages start from 0 as the first page, not 1.
883 * @returns The Current page.
885 unsigned int GetCurrentPage() const;
888 * @brief Scrolls View to position specified (contents will scroll to this position).
890 * Position 0,0 is the origin. Increasing X scrolls contents left, while
891 * increasing Y scrolls contents up.
892 * - If Rulers have been applied to the axes, then the contents will scroll until
893 * reaching the domain boundary.
894 * @note Contents will not snap to ruler snap points.
896 * @param[in] position The position to scroll to.
898 void ScrollTo(const Vector3 &position);
901 * @brief Scrolls View to position specified (contents will scroll to this position).
903 * Position 0,0 is the origin. Increasing X scrolls contents left, while
904 * increasing Y scrolls contents up.
905 * - If Rulers have been applied to the axes, then the contents will scroll until
906 * reaching the domain boundary.
907 * @note Contents will not snap to ruler snap points.
909 * @param[in] position The position to scroll to.
910 * @param[in] duration The duration of the animation in seconds
912 void ScrollTo(const Vector3 &position, float duration);
915 * @brief Scrolls View to position specified (contents will scroll to this position)
917 * Position 0,0 is the origin. Increasing X scrolls contents left, while
918 * increasing Y scrolls contents up.
919 * - If Rulers have been applied to the axes, then the contents will scroll until
920 * reaching the domain boundary.
921 * @note Contents will not snap to ruler snap points.
923 * @param[in] position The position to scroll to.
924 * @param[in] duration The duration of the animation in seconds
925 * @param[in] alpha The alpha function to use
927 void ScrollTo(const Vector3 &position, float duration, AlphaFunction alpha);
930 * @brief Scrolls View to position specified (contents will scroll to this position).
932 * Position 0,0 is the origin. Increasing X scrolls contents left, while
933 * increasing Y scrolls contents up.
934 * - If Rulers have been applied to the axes, then the contents will scroll until
935 * reaching the domain boundary.
936 * @note Contents will not snap to ruler snap points.
937 * Biasing parameters are provided such that in scenarios with 2 or 2x2 pages in
938 * wrap mode, the application developer can decide whether to scroll left or right
939 * to get to the target page
941 * @param[in] position The position to scroll to.
942 * @param[in] duration The duration of the animation in seconds
943 * @param[in] horizontalBias Whether to bias scrolling to left or right.
944 * @param[in] verticalBias Whether to bias scrolling to top or bottom.
946 void ScrollTo(const Vector3 &position, float duration,
947 DirectionBias horizontalBias, DirectionBias verticalBias);
950 * @brief Scrolls View to position specified (contents will scroll to this position)
952 * Position 0,0 is the origin. Increasing X scrolls contents left, while
953 * increasing Y scrolls contents up.
954 * - If Rulers have been applied to the axes, then the contents will scroll until
955 * reaching the domain boundary.
956 * @note Contents will not snap to ruler snap points.
957 * Biasing parameters are provided such that in scenarios with 2 or 2x2 pages in
958 * wrap mode, the application developer can decide whether to scroll left or right
959 * to get to the target page
961 * @param[in] position The position to scroll to.
962 * @param[in] duration The duration of the animation in seconds
963 * @param[in] horizontalBias Whether to bias scrolling to left or right.
964 * @param[in] verticalBias Whether to bias scrolling to top or bottom.
965 * @param[in] alpha Alpha function to use
967 void ScrollTo(const Vector3 &position, float duration, AlphaFunction alpha,
968 DirectionBias horizontalBias, DirectionBias verticalBias);
971 * @brief Scrolls View to page currently based on assumption that each page is
972 * "(page) * ScrollViewSize.width, 0".
974 * @note Should probably be upgraded so that page is an abstract class, that can be
975 * a function of ScrollViewSize, ruler domain, ruler snap points etc. as pages may be
976 * orchestrated in a 2D grid fashion, or variable width.
978 * @param[in] page to scroll to
980 void ScrollTo(unsigned int page);
983 * @brief Scrolls View to page currently based on assumption that each page is
984 * "(page) * ScrollViewSize.width, 0".
986 * @note Should probably be upgraded so that page is an abstract class, that can be
987 * a function of ScrollViewSize, ruler domain, ruler snap points etc. as pages may be
988 * orchestrated in a 2D grid fashion, or variable width.
990 * @param[in] page to scroll to
991 * @param[in] duration The duration of the animation in seconds
993 void ScrollTo(unsigned int page, float duration);
996 * @brief Scrolls View to page currently based on assumption that each page is
997 * "(page) * ScrollViewSize.width, 0".
999 * @note Should probably be upgraded so that page is an abstract class, that can be
1000 * a function of ScrollViewSize, ruler domain, ruler snap points etc. as pages may be
1001 * orchestrated in a 2D grid fashion, or variable width.
1002 * A biasing parameter is provided such that in scenarios with 2 pages in wrap mode,
1003 * the application developer can decide whether to scroll left or right to get to
1006 * @param[in] page to scroll to
1007 * @param[in] duration The duration of the animation in seconds
1008 * @param[in] bias Whether to bias scrolling to left or right.
1010 void ScrollTo(unsigned int page, float duration, DirectionBias bias);
1013 * @brief Scrolls View such that actor appears in the center of the ScrollView.
1015 * @note Actor must be a direct child of ScrollView, otherwise will
1016 * cause an assertion failure.
1017 * @param[in] actor The actor to center in on (via Scrolling).
1019 void ScrollTo(Actor& actor);
1022 * @brief Scrolls View such that actor appears in the center of the ScrollView.
1024 * @note Actor must be a direct child of ScrollView, otherwise will
1025 * cause an assertion failure.
1026 * @param[in] actor The actor to center in on (via Scrolling).
1027 * @param[in] duration The duration of the animation in seconds
1029 void ScrollTo(Actor& actor, float duration);
1032 * @brief Scrolls View to the nearest snap points as specified by the Rulers.
1034 * If already at snap points, then will return false, and not scroll.
1036 * @return True if Snapping necessary.
1038 bool ScrollToSnapPoint();
1041 * @brief Applies a constraint that will affect the children of ScrollView.
1043 * @note this affects all existing and future Actors that are added to scrollview.
1044 * @param[in] constraint The constraint to apply
1046 void ApplyConstraintToChildren(Constraint constraint);
1049 * @brief Removes all constraints that will affect the children of ScrollView.
1051 * @note this removes all constraints from actors that have been added
1054 void RemoveConstraintsFromChildren();
1057 * @brief Apply Effect to ScrollView.
1059 * @param[in] effect The effect to apply to scroll view
1061 void ApplyEffect(ScrollViewEffect effect);
1064 * @brief Remove Effect from ScrollView.
1066 * @param[in] effect The effect to remove.
1068 void RemoveEffect(ScrollViewEffect effect);
1071 * @brief Remove All Effects from ScrollView.
1073 void RemoveAllEffects();
1076 * @brief Binds actor to this ScrollView.
1078 * Once an actor is bound to a ScrollView, it will be subject to
1079 * that ScrollView's properties.
1081 * @param[in] child The actor to add to this ScrollView.
1083 void BindActor(Actor child);
1086 * @brief Unbind Actor from this ScrollView.
1088 * Once Unbound, this ScrollView will not affect the actor.
1089 * @note this does not remove the child from the ScrollView container
1091 * @param[in] child The actor to be unbound.
1093 void UnbindActor(Actor child);
1096 * @brief Allows the user to constrain the scroll view in a particular direction.
1098 * @param[in] direction The axis to constrain the scroll-view to.
1099 * Usually set to PanGestureDetector::DIRECTION_VERTICAL or PanGestureDetector::DIRECTION_HORIZONTAL (but can be any other angle if desired).
1100 * @param[in] threshold The threshold to apply around the axis.
1101 * @note If no threshold is specified, then the default threshold of PI * 0.25 radians (or 45 degrees) is used.
1103 void SetScrollingDirection( Radian direction, Radian threshold = PanGestureDetector::DEFAULT_THRESHOLD );
1106 * @brief Remove a direction constraint from the scroll view.
1108 * @param[in] direction The axis to stop constraining to.
1109 * Usually will be PanGestureDetector::DIRECTION_VERTICAL or PanGestureDetector::DIRECTION_HORIZONTAL (but can be any other angle if desired).
1111 void RemoveScrollingDirection( Radian direction );
1113 public: // Not intended for application developers
1116 * @brief Creates a handle using the Toolkit::Internal implementation.
1118 * @param[in] implementation The Control implementation.
1120 DALI_INTERNAL ScrollView(Internal::ScrollView& implementation);
1123 * @brief Allows the creation of this Control from an Internal::CustomActor pointer.
1125 * @param[in] internal A pointer to the internal CustomActor.
1127 explicit DALI_INTERNAL ScrollView( Dali::Internal::CustomActor* internal );
1130 } // namespace Toolkit
1134 #endif // __DALI_TOOLKIT_SCROLL_VIEW_H__