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 std::string SCROLL_TIME_PROPERTY_NAME; ///< Property, name "scroll-time", type FLOAT
415 static const std::string SCROLL_POSITION_PROPERTY_NAME; ///< Property, name "scroll-position", type VECTOR3
416 static const std::string SCROLL_PRE_POSITION_PROPERTY_NAME; ///< Property, name "scroll-pre-position", type VECTOR3
417 static const std::string SCROLL_OVERSHOOT_X_PROPERTY_NAME; ///< Property, name "scroll-overshoot-x", type float
418 static const std::string SCROLL_OVERSHOOT_Y_PROPERTY_NAME; ///< Property, name "scroll-overshoot-y", type float
419 static const std::string SCROLL_FINAL_PROPERTY_NAME; ///< Property, name "scroll-final", type VECTOR3
420 static const std::string SCROLL_WRAP_PROPERTY_NAME; ///< Property, name "scroll-wrap", type BOOLEAN
421 static const std::string SCROLL_PANNING_PROPERTY_NAME; ///< Property, name "scroll-panning", type BOOLEAN
422 static const std::string SCROLL_SCROLLING_PROPERTY_NAME; ///< Property, name "scroll-scrolling", type BOOLEAN
423 static const std::string SCROLL_POSITION_DELTA_PROPERTY_NAME; ///< Property, name "scroll-position-delta" type VECTOR3
424 static const std::string SCROLL_START_PAGE_POSITION_PROPERTY_NAME; ///< Property, name "scroll-start-page-position" type VECTOR3
428 static const float DEFAULT_SLOW_SNAP_ANIMATION_DURATION; ///< Default Drag-Release animation time.
429 static const float DEFAULT_FAST_SNAP_ANIMATION_DURATION; ///< Default Drag-Flick animation time.
430 static const float DEFAULT_SNAP_OVERSHOOT_DURATION; ///< Default Overshoot snapping animation time.
431 static const float DEFAULT_MAX_OVERSHOOT; ///< Default maximum allowed overshoot
433 static const float DEFAULT_AXIS_AUTO_LOCK_GRADIENT; ///< Default Axis-AutoLock gradient threshold. default is 0.36:1 (20 degrees)
434 static const float DEFAULT_FRICTION_COEFFICIENT; ///< Default Friction Co-efficient. (in stage diagonals per second)
435 static const float DEFAULT_FLICK_SPEED_COEFFICIENT; ///< Default Flick speed coefficient (multiples input touch velocity)
436 static const float DEFAULT_MAX_FLICK_SPEED; ///< Default Maximum flick speed. (in stage diagonals per second)
441 * @brief Clamp signal event's data
445 ClampState3D scale; ///< Clamp information for scale axes
446 ClampState3D position; ///< Clamp information for position axes
447 ClampState rotation; ///< Clamp information for rotation
451 * @brief Snap signal event's data.
455 SnapType type; ///< Current snap commencing
456 Vector3 position; ///< Target snap position
457 float duration; ///< Duration of snap animation.
460 typedef Signal< void ( const SnapEvent& ) > SnapStartedSignalType; ///< SnapStarted signal type
463 * @brief Signal emitted when the ScrollView has started to snap or flick (it tells the target
464 * position, scale, rotation for the snap or flick)
466 SnapStartedSignalType& SnapStartedSignal();
471 * @brief Creates an empty ScrollView handle.
476 * @brief Copy constructor.
478 * Creates another handle that points to the same real object
480 * @param[in] handle to copy from
482 ScrollView( const ScrollView& handle );
485 * @brief Assignment operator.
487 * Changes this handle to point to another real object
488 * @param[in] handle The handle to copy from
489 * @return A reference to this
491 ScrollView& operator=( const ScrollView& handle );
496 * This is non-virtual since derived Handle types must not contain data or virtual methods.
501 * @brief Create an initialized ScrollView.
503 * @return A handle to a newly allocated Dali resource.
505 static ScrollView New();
508 * @brief Downcast an Object handle to ScrollView.
510 * If handle points to a ScrollView the downcast produces valid
511 * handle. If not the returned handle is left uninitialized.
513 * @param[in] handle Handle to an object
514 * @return handle to a ScrollView or an uninitialized handle
516 static ScrollView DownCast( BaseHandle handle );
521 * @brief Get snap-animation's AlphaFunction.
523 * @return Current easing alpha function of the snap animation.
525 AlphaFunction GetScrollSnapAlphaFunction() const;
528 * @brief Set snap-animation's AlphaFunction.
530 * @param[in] alpha Easing alpha function of the snap animation.
532 void SetScrollSnapAlphaFunction(AlphaFunction alpha);
535 * @brief Get flick-animation's AlphaFunction.
537 * @return Current easing alpha function of the flick animation.
539 AlphaFunction GetScrollFlickAlphaFunction() const;
542 * @brief Set flick-animation's AlphaFunction.
544 * @param[in] alpha Easing alpha function of the flick animation.
546 void SetScrollFlickAlphaFunction(AlphaFunction alpha);
549 * @brief Gets the time for the scroll snap-animation.
551 * This animation occurs when the user drags, and releases.
553 * @return The time in seconds for the animation to take.
555 float GetScrollSnapDuration() const;
558 * @brief Sets the time for the scroll snap-animation.
560 * This animation occurs when the user drags, and releases.
562 * @param[in] time The time in seconds for the animation to take.
564 void SetScrollSnapDuration(float time);
567 * @brief Gets the time for the scroll flick-animation.
569 * This animation occurs when the user flicks scroll view.
571 * @return The time in seconds for the animation to take.
573 float GetScrollFlickDuration() const;
576 * @brief Sets the time for the scroll flick-animation.
578 * This animation occurs when the user flicks scroll view.
580 * @param[in] time The time in seconds for the animation to take.
582 void SetScrollFlickDuration(float time);
585 * @brief Set X axis ruler.
587 * Defines how scrolling horizontally is snapped, and
588 * the boundary (domain) in which the ScrollView can pan.
590 * @param[in] ruler The ruler to be used for the X axis
592 void SetRulerX(RulerPtr ruler);
595 * @brief Set Y axis ruler.
597 * Defines how scrolling vertically is snapped, and the boundary
598 * (domain) in which the ScrollView can pan.
600 * @param[in] ruler The ruler to be used for the Y axis
602 void SetRulerY(RulerPtr ruler);
605 * @brief Set Scroll's touch sensitivity.
607 * @note Unlike SetSensitive(), this determines whether this ScrollView
608 * should react (e.g. pan), without disrupting the sensitivity of it's children.
610 * @param[in] sensitive true to enable scroll, false to disable scrolling
612 void SetScrollSensitive(bool sensitive);
615 * @brief Set maximum overshoot amount.
617 * The final overshoot value is within 0.0f to 1.0f, but the maximum
618 * overshoot is in pixels (e.g. if you scroll 75 pixels beyond the
619 * edge of a scrollable area and the maximum overshoot is 100 then
620 * the final overshoot value will be 0.75f)
622 * @param[in] overshootX the maximum number of horizontally scrolled pixels before overshoot X reaches 1.0f
623 * @param[in] overshootY the maximum number of vertically scrolled pixels before overshoot Y reaches 1.0f
625 void SetMaxOvershoot(float overshootX, float overshootY);
628 * @brief Set Snap Overshoot animation's AlphaFunction.
630 * @param[in] alpha Easing alpha function of the overshoot snap animation.
632 void SetSnapOvershootAlphaFunction(AlphaFunction alpha);
635 * @brief Set Snap Overshoot animation's Duration.
637 * @note Set duration to 0 seconds, to disable Animation.
639 * @param[in] duration The duration of the overshoot snap animation.
641 void SetSnapOvershootDuration(float duration);
644 * @brief Enables or Disables Actor Auto-Snap mode.
646 * When Actor Auto-Snap mode has been enabled, ScrollView will automatically
647 * snap to the closest actor (The closest actor will appear in the center of
650 * @param[in] enable Enables (true), or disables (false) Actor AutoSnap
652 void SetActorAutoSnap(bool enable);
655 * @brief Enables or Disables Wrap mode for ScrollView contents.
657 * When enabled, the ScrollView contents are wrapped over the X/Y Domain.
659 * @note You must apply a position constraint that causes Wrapping
662 * @param[in] enable Enables (true), or disables (false) Wrap Mode.
664 void SetWrapMode(bool enable);
667 * @brief Gets the current distance needed to scroll for ScrollUpdatedSignal to be emitted
669 * @return Current scroll update distance
671 int GetScrollUpdateDistance() const;
674 * @brief Sets the distance needed to scroll for ScrollUpdatedSignal to be emitted
676 * The scroll update distance tells ScrollView how far to move before ScrollUpdatedSignal the informs application.
677 * Each time the ScrollView crosses this distance the signal will be emitted
679 * @param[in] distance The distance for ScrollView to move before emitting update signal
681 void SetScrollUpdateDistance(int distance);
684 * @brief Returns state of Axis Auto Lock mode.
686 * @return Whether Axis Auto Lock mode has been enabled or not.
688 bool GetAxisAutoLock() const;
691 * @brief Enables or Disables Axis Auto Lock mode for panning within the ScrollView.
693 * When enabled, any pan gesture that appears mostly horizontal or mostly
694 * vertical, will be automatically restricted to horizontal only or vertical
695 * only panning, until the pan gesture has completed.
697 * @param[in] enable Enables (true), or disables (false) AxisAutoLock mode.
699 void SetAxisAutoLock(bool enable);
702 * @brief Gets the gradient threshold at which a panning gesture
703 * should be locked to the Horizontal or Vertical axis.
705 * @return The gradient, a value between 0.0 and 1.0f.
707 float GetAxisAutoLockGradient() const;
710 * @brief Sets the gradient threshold at which a panning gesture should be locked to the
711 * Horizontal or Vertical axis.
713 * By default this is 0.36 (0.36:1) which means angles less than 20
714 * degrees to an axis will lock to that axis.
716 * @note: Specifying a value of 1.0 (the maximum value accepted) indicates that
717 * all panning gestures will auto-lock. Either to the horizontal or vertical axis.
719 * @param[in] gradient A value between 0.0 and 1.0 (auto-lock for all angles)
721 void SetAxisAutoLockGradient(float gradient);
724 * @brief Gets the friction coefficient setting for ScrollView when
725 * flicking in free panning mode.
727 * This is a value in stage-diagonals per second^2.
728 * stage-diagonal = Length( stage.width, stage.height )
729 * @return Friction coefficient is returned.
731 float GetFrictionCoefficient() const;
734 * @brief Sets the friction coefficient for ScrollView when flicking
735 * in free panning mode.
737 * This is a value in stage-diagonals per second^2.
738 * stage-diagonal = Length( stage.width, stage.height ).
740 * A stage 480x800 in size has a diagonal length of 933.
741 * Friction coefficient of 1.0 means the swipe velocity will
742 * reduce by 1.0 * 933 pixels/sec^2.
743 * @param[in] friction Friction coefficient, must be greater than 0.0 (default = 1.0)
745 void SetFrictionCoefficient(float friction);
748 * @brief Gets the flick speed coefficient for ScrollView when
749 * flicking in free panning mode.
751 * This is a constant which multiplies the input touch
752 * flick velocity to determine the actual velocity at
753 * which to move the scrolling area.
754 * @return The flick speed coefficient is returned.
756 float GetFlickSpeedCoefficient() const;
759 * @brief Sets the flick speed coefficient for ScrollView when
760 * flicking in free panning mode.
762 * This is a constant which multiplies the input touch
763 * flick velocity to determine the actual velocity at
764 * which to move the scrolling area.
765 * @param[in] speed The flick speed coefficient (default = 1.0).
767 void SetFlickSpeedCoefficient(float speed);
770 * @brief Returns the minimum pan distance required for a flick gesture in pixels
772 * @return Minimum pan distance vector with separate x and y distance
774 Vector2 GetMinimumDistanceForFlick() const;
777 * @brief Sets the minimum pan distance required for a flick in pixels
779 * 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
781 * @param[in] distance The minimum pan distance for a flick
783 void SetMinimumDistanceForFlick( const Vector2& distance );
786 * @brief Returns the minimum pan speed required for a flick gesture in pixels per second
788 * @return Minimum pan speed
790 float GetMinimumSpeedForFlick() const;
793 * @brief Sets the minimum pan speed required for a flick in pixels per second
795 * @param[in] speed The minimum pan speed for a flick
797 void SetMinimumSpeedForFlick( float speed );
800 * @brief Gets the maximum flick speed setting for ScrollView when
801 * flicking in free panning mode.
803 * This is a value in stage-diagonals per second.
804 * stage-diagonal = Length( stage.width, stage.height )
805 * @return Maximum flick speed is returned
807 float GetMaxFlickSpeed() const;
810 * @brief Sets the maximum flick speed for the ScrollView when
811 * flicking in free panning mode.
813 * This is a value in stage-diagonals per second.
814 * stage-diagonal = Length( stage.width, stage.height )
816 * A stage 480x800 in size has a diagonal length of 933.
817 * Max Flick speed of 1.0 means the maximum velocity of
818 * a swipe can be 1.0 * 933 pixels/sec.
819 * @param[in] speed Maximum flick speed (default = 3.0)
821 void SetMaxFlickSpeed(float speed);
824 * @brief Gets the step of scroll distance in actor coordinates for
825 * each mouse wheel event received in free panning mode.
827 * @return The step of scroll distance(pixel) in X and Y axes.
829 Vector2 GetMouseWheelScrollDistanceStep() const;
832 * @brief Sets the step of scroll distance in actor coordinates for
833 * each mouse wheel event received in free panning mode.
835 * @param[in] step The step of scroll distance(pixel) in X and Y axes.
837 * @note: If snap points are defined in the rulers, it will always
838 * scroll to the next snap point towards the scroll direction while
839 * receiving the mouse wheel events.
842 void SetMouseWheelScrollDistanceStep(Vector2 step);
845 * @brief Retrieves current scroll position.
847 * @returns The current scroll position.
849 Vector3 GetCurrentScrollPosition() const;
852 * @brief Sets the current scroll position, overriding current scroll animations. If panning is currently taking place
853 * SetScrollPosition will have no effect. Try to ensure panning has stopped before calling this function.
855 * @param[in] position The new scroll position to set.
857 void SetScrollPosition(const Vector3& position);
860 * @brief Retrieves current scroll page based on ScrollView
861 * dimensions being the size of one page, and all pages laid out in
862 * a grid fashion, increasing from left to right until the end of
865 * @note: Pages start from 0 as the first page, not 1.
867 * @returns The Current page.
869 unsigned int GetCurrentPage() const;
872 * @brief Scrolls View to position specified (contents will scroll to this position).
874 * Position 0,0 is the origin. Increasing X scrolls contents left, while
875 * increasing Y scrolls contents up.
876 * - If Rulers have been applied to the axes, then the contents will scroll until
877 * reaching the domain boundary.
878 * @note Contents will not snap to ruler snap points.
880 * @param[in] position The position to scroll to.
882 void ScrollTo(const Vector3 &position);
885 * @brief Scrolls View to position specified (contents will scroll to this position).
887 * Position 0,0 is the origin. Increasing X scrolls contents left, while
888 * increasing Y scrolls contents up.
889 * - If Rulers have been applied to the axes, then the contents will scroll until
890 * reaching the domain boundary.
891 * @note Contents will not snap to ruler snap points.
893 * @param[in] position The position to scroll to.
894 * @param[in] duration The duration of the animation in seconds
896 void ScrollTo(const Vector3 &position, float duration);
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
909 * @param[in] alpha The alpha function to use
911 void ScrollTo(const Vector3 &position, float duration, AlphaFunction alpha);
914 * @brief Scrolls View to position specified (contents will scroll to this position).
916 * Position 0,0 is the origin. Increasing X scrolls contents left, while
917 * increasing Y scrolls contents up.
918 * - If Rulers have been applied to the axes, then the contents will scroll until
919 * reaching the domain boundary.
920 * @note Contents will not snap to ruler snap points.
921 * Biasing parameters are provided such that in scenarios with 2 or 2x2 pages in
922 * wrap mode, the application developer can decide whether to scroll left or right
923 * to get to the target page
925 * @param[in] position The position to scroll to.
926 * @param[in] duration The duration of the animation in seconds
927 * @param[in] horizontalBias Whether to bias scrolling to left or right.
928 * @param[in] verticalBias Whether to bias scrolling to top or bottom.
930 void ScrollTo(const Vector3 &position, float duration,
931 DirectionBias horizontalBias, DirectionBias verticalBias);
934 * @brief Scrolls View to position specified (contents will scroll to this position)
936 * Position 0,0 is the origin. Increasing X scrolls contents left, while
937 * increasing Y scrolls contents up.
938 * - If Rulers have been applied to the axes, then the contents will scroll until
939 * reaching the domain boundary.
940 * @note Contents will not snap to ruler snap points.
941 * Biasing parameters are provided such that in scenarios with 2 or 2x2 pages in
942 * wrap mode, the application developer can decide whether to scroll left or right
943 * to get to the target page
945 * @param[in] position The position to scroll to.
946 * @param[in] duration The duration of the animation in seconds
947 * @param[in] horizontalBias Whether to bias scrolling to left or right.
948 * @param[in] verticalBias Whether to bias scrolling to top or bottom.
949 * @param[in] alpha Alpha function to use
951 void ScrollTo(const Vector3 &position, float duration, AlphaFunction alpha,
952 DirectionBias horizontalBias, DirectionBias verticalBias);
955 * @brief Scrolls View to page currently based on assumption that each page is
956 * "(page) * ScrollViewSize.width, 0".
958 * @note Should probably be upgraded so that page is an abstract class, that can be
959 * a function of ScrollViewSize, ruler domain, ruler snap points etc. as pages may be
960 * orchestrated in a 2D grid fashion, or variable width.
962 * @param[in] page to scroll to
964 void ScrollTo(unsigned int page);
967 * @brief Scrolls View to page currently based on assumption that each page is
968 * "(page) * ScrollViewSize.width, 0".
970 * @note Should probably be upgraded so that page is an abstract class, that can be
971 * a function of ScrollViewSize, ruler domain, ruler snap points etc. as pages may be
972 * orchestrated in a 2D grid fashion, or variable width.
974 * @param[in] page to scroll to
975 * @param[in] duration The duration of the animation in seconds
977 void ScrollTo(unsigned int page, float duration);
980 * @brief Scrolls View to page currently based on assumption that each page is
981 * "(page) * ScrollViewSize.width, 0".
983 * @note Should probably be upgraded so that page is an abstract class, that can be
984 * a function of ScrollViewSize, ruler domain, ruler snap points etc. as pages may be
985 * orchestrated in a 2D grid fashion, or variable width.
986 * A biasing parameter is provided such that in scenarios with 2 pages in wrap mode,
987 * the application developer can decide whether to scroll left or right to get to
990 * @param[in] page to scroll to
991 * @param[in] duration The duration of the animation in seconds
992 * @param[in] bias Whether to bias scrolling to left or right.
994 void ScrollTo(unsigned int page, float duration, DirectionBias bias);
997 * @brief Scrolls View such that actor appears in the center of the ScrollView.
999 * @note Actor must be a direct child of ScrollView, otherwise will
1000 * cause an assertion failure.
1001 * @param[in] actor The actor to center in on (via Scrolling).
1003 void ScrollTo(Actor& actor);
1006 * @brief Scrolls View such that actor appears in the center of the ScrollView.
1008 * @note Actor must be a direct child of ScrollView, otherwise will
1009 * cause an assertion failure.
1010 * @param[in] actor The actor to center in on (via Scrolling).
1011 * @param[in] duration The duration of the animation in seconds
1013 void ScrollTo(Actor& actor, float duration);
1016 * @brief Scrolls View to the nearest snap points as specified by the Rulers.
1018 * If already at snap points, then will return false, and not scroll.
1020 * @return True if Snapping necessary.
1022 bool ScrollToSnapPoint();
1025 * @brief Applies a constraint that will affect the children of ScrollView.
1027 * @note this affects all existing and future Actors that are added to scrollview.
1028 * @param[in] constraint The constraint to apply
1030 void ApplyConstraintToChildren(Constraint constraint);
1033 * @brief Removes all constraints that will affect the children of ScrollView.
1035 * @note this removes all constraints from actors that have been added
1038 void RemoveConstraintsFromChildren();
1041 * @brief Apply Effect to ScrollView.
1043 * @param[in] effect The effect to apply to scroll view
1045 void ApplyEffect(ScrollViewEffect effect);
1048 * @brief Remove Effect from ScrollView.
1050 * @param[in] effect The effect to remove.
1052 void RemoveEffect(ScrollViewEffect effect);
1055 * @brief Remove All Effects from ScrollView.
1057 void RemoveAllEffects();
1060 * @brief Binds actor to this ScrollView.
1062 * Once an actor is bound to a ScrollView, it will be subject to
1063 * that ScrollView's properties.
1065 * @param[in] child The actor to add to this ScrollView.
1067 void BindActor(Actor child);
1070 * @brief Unbind Actor from this ScrollView.
1072 * Once Unbound, this ScrollView will not affect the actor.
1073 * @note this does not remove the child from the ScrollView container
1075 * @param[in] child The actor to be unbound.
1077 void UnbindActor(Actor child);
1080 * @brief Allows the user to constrain the scroll view in a particular direction.
1082 * @param[in] direction The axis to constrain the scroll-view to.
1083 * Usually set to PanGestureDetector::DIRECTION_VERTICAL or PanGestureDetector::DIRECTION_HORIZONTAL (but can be any other angle if desired).
1084 * @param[in] threshold The threshold to apply around the axis.
1085 * @note If no threshold is specified, then the default threshold of PI * 0.25 radians (or 45 degrees) is used.
1087 void SetScrollingDirection( Radian direction, Radian threshold = PanGestureDetector::DEFAULT_THRESHOLD );
1090 * @brief Remove a direction constraint from the scroll view.
1092 * @param[in] direction The axis to stop constraining to.
1093 * Usually will be PanGestureDetector::DIRECTION_VERTICAL or PanGestureDetector::DIRECTION_HORIZONTAL (but can be any other angle if desired).
1095 void RemoveScrollingDirection( Radian direction );
1097 public: // Not intended for application developers
1100 * @brief Creates a handle using the Toolkit::Internal implementation.
1102 * @param[in] implementation The Control implementation.
1104 DALI_INTERNAL ScrollView(Internal::ScrollView& implementation);
1107 * @brief Allows the creation of this Control from an Internal::CustomActor pointer.
1109 * @param[in] internal A pointer to the internal CustomActor.
1111 explicit DALI_INTERNAL ScrollView( Dali::Internal::CustomActor* internal );
1114 } // namespace Toolkit
1118 #endif // __DALI_TOOLKIT_SCROLL_VIEW_H__