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 * @addtogroup CAPI_DALI_TOOLKIT_SCROLL_VIEW_MODULE
27 #include <dali-toolkit/public-api/controls/scrollable/scrollable.h>
29 namespace Dali DALI_IMPORT_API
35 namespace Internal DALI_INTERNAL
41 * @brief The snap type
50 * @brief DirectionBias types.
54 DirectionBiasLeft = -1, ///< Bias scroll snap to Left
55 DirectionBiasNone = 0, ///< Don't bias scroll snap
56 DirectionBiasRight = 1 ///< Bias scroll snap to Right
60 * @brief Used for specifying minimum/maximum extents of a ruler.
67 * @brief Creates Ruler domain allowing a point to traverse between min and max extents.
69 * @param[in] min Minimum extent (point cannot traverse less than this)
70 * @param[in] max Maximum extent (point cannot traverse greater than this)
71 * @param[in] enabled Whether domain has been enabled or not.
73 explicit RulerDomain(float min, float max, bool enabled = true);
77 float min; ///< Minimum extent (point cannot traverse less than this)
78 float max; ///< Maximum extent (point cannot traverse greater than this)
79 bool enabled; ///< Whether domain has been enabled or not.
82 * @brief Clamps value (x) from (min) to (max).
84 * An optional length parameter can be specified to suggest that the
85 * subject is not a point but a line to that should be clamped.
87 * @param[in] x X point to be clamped between (min) and (max) extents.
88 * @param[in] length (optional) The Length of the line from (x) to (x + length) to be clamped.
89 * @param[in] scale Scaling parameter which treats domain as scaled in calculations.
90 * @return The clamped value.
92 float Clamp(float x, float length = 0.0f, float scale = 1.0f) const;
95 * @brief Clamps value (x) from (min) to (max).
97 * An optional length parameter can be specified to suggest that the
98 * subject is not a point but a line to that should be clamped.
100 * @param[in] x X point to be clamped between (min) and (max) extents.
101 * @param[in] length (optional) The Length of the line from (x) to (x + length) to be clamped.
102 * @param[in] scale Scaling parameter which treats domain as scaled in calculations.
103 * @param[out] clamped Whether clamping occured and which size (None, Min or Max)
104 * @return The clamped value.
106 float Clamp(float x, float length, float scale, ClampState &clamped) const;
109 * @brief Returns (max-min) size of ruler.
111 * @return The size of the ruler from min to max.
113 float GetSize() const;
118 * @brief Abstract class to define scroll axes.
120 * It can specify whether they are traversable, where their snap
121 * points are and their domain.
123 class Ruler : public RefObject
126 /// @brief The type of the ruler
128 Fixed, ///< A fixed ruler
129 Free ///< A free ruler
135 * @brief Constructs ruler, default enabled, with limitless domain.
140 * @brief Snaps (x) in accordance to the ruler settings.
142 * @param[in] x The input value on the ruler to be snapped.
143 * @param[in] bias (optional) The biasing employed for snapping
144 * 0 floor input (floor x) "Used for Flick Left"
145 * 0.5 round input (floor x + 0.5) "Used for Release"
146 * 1 ceil input (floor x + 1.0) "Used for Flick Right"
147 * @return The position of the one dimensional point passed in once snapped.
149 virtual float Snap(float x, float bias = 0.5f) const = 0;
152 * @brief Returns position from page, based on whatever the ruler
155 * If (wrap) is true, then will set volume to the number of
156 * times page has exceeded the domain's volume (volume being the
157 * number of pages within the domain), while wrapping the position
160 * @param[in] page The page index
161 * @param[out] volume The overflow volume when the page exceeds the domain (wrap must be enabled)
162 * @param[in] wrap Enable wrap mode
163 * @return The position representing this page point.
165 virtual float GetPositionFromPage(unsigned int page, unsigned int &volume, bool wrap) const = 0;
168 * @brief Returns page from position, based on whatever the ruler
171 * If (wrap) is true, then will return a page wrapped within the domain.
173 * @param[in] position The position on the domain
174 * @param[in] wrap Enable wrap mode
175 * @return The page where this position resides.
177 virtual unsigned int GetPageFromPosition(float position, bool wrap) const = 0;
180 * @brief Returns the total number of pages within this Ruler.
182 * @return The number of pages in the Ruler.
184 virtual unsigned int GetTotalPages() const = 0;
189 * @brief Gets the ruler type.
191 * @return The ruler type.
193 Ruler::RulerType GetType() const;
196 * @brief Returns whether this axis has been enabled or not.
198 * @return true if axis is enabled
200 bool IsEnabled() const;
203 * @brief Enables ruler (ruler must be enabled in order to traverse along it).
208 * @brief Disables ruler.
213 * @brief Sets Domain.
215 * @param[in] domain Ruler domain object.
217 void SetDomain(RulerDomain domain);
220 * @brief Gets Domain.
224 const RulerDomain &GetDomain() const;
227 * @brief Disables Domain (minimum/maximum extents for this axis).
229 void DisableDomain();
232 * @brief Clamps value (x) from (min) to (max).
234 * An optional length parameter can be specified to suggest that the
235 * subject is not a point but a line that should be clamped.
237 * @param[in] x X point to be clamped between (min) and (max) extents.
238 * @param[in] length (optional) The Length of the line from (x) to (x + length) to be clamped.
239 * @param[in] scale Scaling parameter which treats domain as scaled in calculations.
240 * @return The clamped value.
242 float Clamp(float x, float length = 0.0f, float scale = 1.0f) const;
246 * @brief Clamps value (x) from (min) to (max).
248 * An optional length parameter can be specified to suggest that the
249 * subject is not a point but a line to that should be clamped.
251 * @param[in] x X point to be clamped between (min) and (max) extents.
252 * @param[in] length (optional) The Length of the line from (x) to (x + length) to be clamped.
253 * @param[in] scale Scaling parameter which treats domain as scaled in calculations.
254 * @param[out] clamped Whether clamping occured and which size (None, Min or Max)
255 * @return The clamped value.
257 float Clamp(float x, float length, float scale, ClampState &clamped) const;
260 * @brief Snaps and Clamps (x) in accordance to ruler settings.
262 * @param[in] x value to be snapped in accordance to ruler snap value,
263 * and clamped in accordance to the ruler's domain (if set).
264 * @param[in] bias (optional) The biasing employed for snapping
265 * 0 floor input (floor x) "Used for Flick Left"
266 * 0.5 round input (floor x + 0.5) "Used for Release"
267 * 1 ceil input (floor x + 1.0) "Used for Flick Right"
268 * @param[in] length (optional) The Length of the line from (x) to (x + length)
270 * @param[in] scale Scaling parameter which treats domain as scaled in calculations.
271 * @return the clamped value after snapping
273 float SnapAndClamp(float x, float bias = 0.5f, float length = 0.0f, float scale = 1.0f) const;
276 * @brief Snaps and Clamps (x) in accordance to ruler settings.
278 * @param[in] x value to be snapped in accordance to ruler snap value,
279 * and clamped in accordance to the ruler's domain (if set).
280 * @param[in] bias (optional) The biasing employed for snapping
281 * 0 floor input (floor x) "Used for Flick Left"
282 * 0.5 round input (floor x + 0.5) "Used for Release"
283 * 1 ceil input (floor x + 1.0) "Used for Flick Right"
284 * @param[in] length (optional) The Length of the line from (x) to (x + length)
286 * @param[in] scale Scaling parameter which treats domain as scaled in calculations.
287 * @param[out] clamped Whether clamping occured and which size (None, Min or Max)
288 * @return The clamped value after snapping
290 float SnapAndClamp(float x, float bias, float length, float scale, ClampState &clamped) const;
295 * @brief Destructor - A reference counted object may only be deleted by calling Unreference().
301 RulerType mType; ///< Type of Ruler (Fixed or Free).
302 bool mEnabled; ///< If the ruler is enabled.
303 RulerDomain mDomain; ///< The domain of the ruler.
307 typedef IntrusivePtr<Ruler> RulerPtr; ///< Pointer to Dali::Toolkit::Ruler object
310 * @brief Concrete implementation of Ruler that has no snapping and has one single page.
312 class DefaultRuler : public Ruler
316 * @brief DefaultRuler constructor.
321 * @copydoc Toolkit::Ruler::Snap
323 virtual float Snap(float x, float bias) const;
326 * @copydoc Toolkit::Ruler::GetPositionFromPage
328 virtual float GetPositionFromPage(unsigned int page, unsigned int &volume, bool wrap) const;
331 * @copydoc Toolkit::Ruler::GetPageFromPosition
333 virtual unsigned int GetPageFromPosition(float position, bool wrap) const;
336 * @copydoc Toolkit::Ruler::GetTotalPages
338 virtual unsigned int GetTotalPages() const;
342 * @brief Concrete implementation of Ruler that has fixed snapping.
344 class FixedRuler : public Ruler
350 * @param[in] spacing The spacing between each interval on this ruler.
352 FixedRuler(float spacing = 1.0f);
355 * @copydoc Toolkit::Ruler::Snap
357 virtual float Snap(float x, float bias) const;
360 * @copydoc Toolkit::Ruler::GetPositionFromPage
362 virtual float GetPositionFromPage(unsigned int page, unsigned int &volume, bool wrap) const;
365 * @copydoc Toolkit::Ruler::GetPageFromPosition
367 virtual unsigned int GetPageFromPosition(float position, bool wrap) const;
370 * @copydoc Toolkit::Ruler::GetTotalPages
372 virtual unsigned int GetTotalPages() const;
375 float mSpacing; ///< The spacing between each interval
378 class ScrollViewEffect;
382 * @brief ScrollView contains actors that can be scrolled manually (via touch)
385 class ScrollView : public Scrollable
388 /// Page effect types
391 PageEffectNone, ///< No Effect (Standard ScrollView)
392 PageEffectOuterCube, ///< 3D Rotating Cube Effect
393 PageEffectDepth, ///< Depth Effect
394 PageEffectInnerCube, ///< Page Cube Effect
395 PageEffectCarousel, ///< Page Carousel Effect
396 PageEffectSpiral, ///< Page Spiral Effect
398 Total ///< The total number of effect types
403 static const std::string SCROLL_PAGE_CURRENT; ///< Property, name "scroll-page-current", type INT
404 static const std::string SCROLL_TIME_PROPERTY_NAME; ///< Property, name "scroll-time", type FLOAT
405 static const std::string SCROLL_POSITION_PROPERTY_NAME; ///< Property, name "scroll-position", type VECTOR3
406 static const std::string SCROLL_PRE_POSITION_PROPERTY_NAME; ///< Property, name "scroll-pre-position", type VECTOR3
407 static const std::string SCROLL_OVERSHOOT_X_PROPERTY_NAME; ///< Property, name "scroll-overshoot-x", type float
408 static const std::string SCROLL_OVERSHOOT_Y_PROPERTY_NAME; ///< Property, name "scroll-overshoot-y", type float
409 static const std::string SCROLL_FINAL_PROPERTY_NAME; ///< Property, name "scroll-final", type VECTOR3
410 static const std::string SCROLL_X_PROPERTY_NAME; ///< Property, name "scroll-x", type FLOAT
411 static const std::string SCROLL_Y_PROPERTY_NAME; ///< Property, name "scroll-y", type FLOAT
412 static const std::string SCROLL_SCALE_PROPERTY_NAME; ///< Property, name "scroll-scale", type VECTOR3
413 static const std::string SCROLL_WRAP_PROPERTY_NAME; ///< Property, name "scroll-wrap", type BOOLEAN
414 static const std::string SCROLL_PANNING_PROPERTY_NAME; ///< Property, name "scroll-panning", type BOOLEAN
415 static const std::string SCROLL_SCROLLING_PROPERTY_NAME; ///< Property, name "scroll-scrolling", type BOOLEAN
416 static const std::string SCROLL_POSITION_DELTA_PROPERTY_NAME; ///< Property, name "scroll-position-delta" type VECTOR3
417 static const std::string SCROLL_START_PAGE_POSITION_PROPERTY_NAME; ///< Property, name "scroll-start-page-position" type VECTOR3
421 static const float DEFAULT_SLOW_SNAP_ANIMATION_DURATION; ///< Default Drag-Release animation time.
422 static const float DEFAULT_FAST_SNAP_ANIMATION_DURATION; ///< Default Drag-Flick animation time.
423 static const float DEFAULT_SNAP_OVERSHOOT_DURATION; ///< Default Overshoot snapping animation time.
424 static const float DEFAULT_MAX_OVERSHOOT; ///< Default maximum allowed overshoot
426 static const float DEFAULT_AXIS_AUTO_LOCK_GRADIENT; ///< Default Axis-AutoLock gradient threshold. default is 0.36:1 (20 degrees)
427 static const float DEFAULT_FRICTION_COEFFICIENT; ///< Default Friction Co-efficient. (in stage diagonals per second)
428 static const float DEFAULT_FLICK_SPEED_COEFFICIENT; ///< Default Flick speed coefficient (multiples input touch velocity)
429 static const float DEFAULT_MAX_FLICK_SPEED; ///< Default Maximum flick speed. (in stage diagonals per second)
432 static const char* const SIGNAL_SNAP_STARTED; ///< Name "snap-started"
434 /// Direction of transitions
437 DirectionFlagLeft = 0x01,
438 DirectionFlagRight = 0x02,
439 DirectionFlagUp = 0x04,
440 DirectionFlagDown = 0x08,
441 DirectionFlagTransitionOn = 0x10, ///< doesnt mean a page is moving towards centre, it affects whether the current page is using values for moving onto screen or off screen, if the user changes scroll direction we dont want things to flip over when in view
442 DirectionFlagTransitionOff = 0x20,
443 DirectionFlagMask_Direction = DirectionFlagLeft | DirectionFlagRight | DirectionFlagUp | DirectionFlagDown,
444 DirectionFlagMask_Transition = DirectionFlagTransitionOn | DirectionFlagTransitionOff
450 * @brief Snap signal event's data.
454 SnapType type; ///< Current snap commencing
455 Vector3 position; ///< Target snap position
456 float duration; ///< Duration of snap animation.
459 typedef SignalV2< void ( const SnapEvent& ) > SnapStartedSignalV2; ///< SnapStarted signal type
462 * @brief Signal emitted when the ScrollView has started to snap or flick (it tells the target
463 * position, scale, rotation for the snap or flick)
465 SnapStartedSignalV2& SnapStartedSignal();
470 * @brief Creates an empty ScrollView handle.
475 * @brief Copy constructor.
477 * Creates another handle that points to the same real object
479 * @param[in] handle to copy from
481 ScrollView( const ScrollView& handle );
484 * @brief Assignment operator.
486 * Changes this handle to point to another real object
487 * @param[in] handle The handle to copy from
488 * @return A reference to this
490 ScrollView& operator=( const ScrollView& handle );
495 * This is non-virtual since derived Handle types must not contain data or virtual methods.
500 * @brief Create an initialized ScrollView.
502 * @return A handle to a newly allocated Dali resource.
504 static ScrollView New();
507 * @brief Downcast an Object handle to ScrollView.
509 * If handle points to a ScrollView the downcast produces valid
510 * handle. If not the returned handle is left uninitialized.
512 * @param[in] handle Handle to an object
513 * @return handle to a ScrollView or an uninitialized handle
515 static ScrollView DownCast( BaseHandle handle );
520 * @brief Get snap-animation's AlphaFunction.
522 * @return Current easing alpha function of the snap animation.
524 AlphaFunction GetScrollSnapAlphaFunction() const;
527 * @brief Set snap-animation's AlphaFunction.
529 * @param[in] alpha Easing alpha function of the snap animation.
531 void SetScrollSnapAlphaFunction(AlphaFunction alpha);
534 * @brief Get flick-animation's AlphaFunction.
536 * @return Current easing alpha function of the flick animation.
538 AlphaFunction GetScrollFlickAlphaFunction() const;
541 * @brief Set flick-animation's AlphaFunction.
543 * @param[in] alpha Easing alpha function of the flick animation.
545 void SetScrollFlickAlphaFunction(AlphaFunction alpha);
548 * @brief Gets the time for the scroll snap-animation.
550 * This animation occurs when the user drags, and releases.
552 * @return The time in seconds for the animation to take.
554 float GetScrollSnapDuration() const;
557 * @brief Sets the time for the scroll snap-animation.
559 * This animation occurs when the user drags, and releases.
561 * @param[in] time The time in seconds for the animation to take.
563 void SetScrollSnapDuration(float time);
566 * @brief Gets the time for the scroll flick-animation.
568 * This animation occurs when the user flicks scroll view.
570 * @return The time in seconds for the animation to take.
572 float GetScrollFlickDuration() const;
575 * @brief Sets the time for the scroll flick-animation.
577 * This animation occurs when the user flicks scroll view.
579 * @param[in] time The time in seconds for the animation to take.
581 void SetScrollFlickDuration(float time);
584 * @brief Set X axis ruler.
586 * Defines how scrolling horizontally is snapped, and
587 * the boundary (domain) in which the ScrollView can pan.
589 * @param[in] ruler The ruler to be used for the X axis
591 void SetRulerX(RulerPtr ruler);
594 * @brief Set Y axis ruler.
596 * Defines how scrolling vertically is snapped, and the boundary
597 * (domain) in which the ScrollView can pan.
599 * @param[in] ruler The ruler to be used for the Y axis
601 void SetRulerY(RulerPtr ruler);
604 * @brief Set Scale-X axis ruler.
606 * Defines how scaling horizontally is snapped, and the extent
607 * (domain) to which scaling can be performed e.g. 10% to 200%
609 * @param[in] ruler The ruler to be used for the Scale-X axis
611 * @deprecated Scaling not supported
613 void SetRulerScaleX(RulerPtr ruler);
616 * @brief Set Scale-Y axis ruler.
618 * Defines how scaling vertically is snapped, and the extent
619 * (domain) to which scaling can be performed e.g. 10% to 200%
621 * @param[in] ruler The ruler to be used for the Scale-Y axis
623 * @deprecated Scaling not supported
625 void SetRulerScaleY(RulerPtr ruler);
628 * @brief Set Scroll's touch sensitivity.
630 * @note Unlike SetSensitive(), this determines whether this ScrollView
631 * should react (e.g. pan), without disrupting the sensitivity of it's children.
633 * @param[in] sensitive true to enable scroll, false to disable scrolling
635 void SetScrollSensitive(bool sensitive);
638 * @brief Set maximum overshoot amount.
640 * The final overshoot value is within 0.0f to 1.0f, but the maximum
641 * overshoot is in pixels (e.g. if you scroll 75 pixels beyond the
642 * edge of a scrollable area and the maximum overshoot is 100 then
643 * the final overshoot value will be 0.75f)
645 * @param[in] overshootX the maximum number of horizontally scrolled pixels before overshoot X reaches 1.0f
646 * @param[in] overshootY the maximum number of vertically scrolled pixels before overshoot Y reaches 1.0f
648 void SetMaxOvershoot(float overshootX, float overshootY);
651 * @brief Set Snap Overshoot animation's AlphaFunction.
653 * @param[in] alpha Easing alpha function of the overshoot snap animation.
655 void SetSnapOvershootAlphaFunction(AlphaFunction alpha);
658 * @brief Set Snap Overshoot animation's Duration.
660 * @note Set duration to 0 seconds, to disable Animation.
662 * @param[in] duration The duration of the overshoot snap animation.
664 void SetSnapOvershootDuration(float duration);
667 * @brief Sets Touches required for pan gestures.
669 * Panning requires number of touches to be within (minTouches) and
672 * If (endOutside) is true, then outside this range of touches,
673 * the pan gesture will end and thus will snap.
675 * If (endOutside) is false, then outside this range of touches,
676 * the pan gesture will pause. but will not end until touches = 0.
678 * @param[in] minTouches Minimum touches for panning to occur.
679 * @param[out] maxTouches Maxiumum touches for panning to occur.
680 * @param[in] endOutside Whether to end the panning gesture outside of touch range
682 void SetTouchesRequiredForPanning(unsigned int minTouches = 1, unsigned int maxTouches = 1, bool endOutside = true);
685 * @brief Enables or Disables Actor Auto-Snap mode.
687 * When Actor Auto-Snap mode has been enabled, ScrollView will automatically
688 * snap to the closest actor (The closest actor will appear in the center of
691 * @param[in] enable Enables (true), or disables (false) Actor AutoSnap
693 void SetActorAutoSnap(bool enable);
696 * @brief Enables or Disables Wrap mode for ScrollView contents.
698 * When enabled, the ScrollView contents are wrapped over the X/Y Domain.
700 * @note You must apply a position constraint that causes Wrapping
703 * @param[in] enable Enables (true), or disables (false) Wrap Mode.
705 void SetWrapMode(bool enable);
709 * @brief Gets the current refresh interval in milliseconds.
711 * @return Current refresh interval in milliseconds
713 int GetRefreshInterval() const;
717 * @brief Sets the refresh interval in milliseconds.
719 * The refresh interval is a notification signal
720 * (SignalScrollUpdate), that is periodically fired when scrolling
721 * animation is occuring.
723 * When set to 0. No update signals are sent.
725 * @param[in] milliseconds The frequency of the event in milliseconds
727 void SetRefreshInterval(int milliseconds);
730 * @brief Gets the current distance needed to scroll for ScrollUpdatedSignal to be emitted
732 * @return Current scroll update distance
734 int GetScrollUpdateDistance() const;
737 * @brief Sets the distance needed to scroll for ScrollUpdatedSignal to be emitted
739 * The scroll update distance tells ScrollView how far to move before ScrollUpdatedSignal the informs application.
740 * Each time the ScrollView crosses this distance the signal will be emitted
742 * @param[in] distance The distance for ScrollView to move before emitting update signal
744 void SetScrollUpdateDistance(int distance);
747 * @brief Returns state of Axis Auto Lock mode.
749 * @return Whether Axis Auto Lock mode has been enabled or not.
751 bool GetAxisAutoLock() const;
754 * @brief Enables or Disables Axis Auto Lock mode for panning within the ScrollView.
756 * When enabled, any pan gesture that appears mostly horizontal or mostly
757 * vertical, will be automatically restricted to horizontal only or vertical
758 * only panning, until the pan gesture has completed.
760 * @param[in] enable Enables (true), or disables (false) AxisAutoLock mode.
762 void SetAxisAutoLock(bool enable);
765 * @brief Gets the gradient threshold at which a panning gesture
766 * should be locked to the Horizontal or Vertical axis.
768 * @return The gradient, a value between 0.0 and 1.0f.
770 float GetAxisAutoLockGradient() const;
773 * @brief Sets the gradient threshold at which a panning gesture should be locked to the
774 * Horizontal or Vertical axis.
776 * By default this is 0.36 (0.36:1) which means angles less than 20
777 * degrees to an axis will lock to that axis.
779 * @note: Specifying a value of 1.0 (the maximum value accepted) indicates that
780 * all panning gestures will auto-lock. Either to the horizontal or vertical axis.
782 * @param[in] gradient A value between 0.0 and 1.0 (auto-lock for all angles)
784 void SetAxisAutoLockGradient(float gradient);
787 * @brief Gets the friction coefficient setting for ScrollView when
788 * flicking in free panning mode.
790 * This is a value in stage-diagonals per second^2.
791 * stage-diagonal = Length( stage.width, stage.height )
792 * @return Friction coefficient is returned.
794 float GetFrictionCoefficient() const;
797 * @brief Sets the friction coefficient for ScrollView when flicking
798 * in free panning mode.
800 * This is a value in stage-diagonals per second^2.
801 * stage-diagonal = Length( stage.width, stage.height ).
803 * A stage 480x800 in size has a diagonal length of 933.
804 * Friction coefficient of 1.0 means the swipe velocity will
805 * reduce by 1.0 * 933 pixels/sec^2.
806 * @param[in] friction Friction coefficient, must be greater than 0.0 (default = 1.0)
808 void SetFrictionCoefficient(float friction);
811 * @brief Gets the flick speed coefficient for ScrollView when
812 * flicking in free panning mode.
814 * This is a constant which multiplies the input touch
815 * flick velocity to determine the actual velocity at
816 * which to move the scrolling area.
817 * @return The flick speed coefficient is returned.
819 float GetFlickSpeedCoefficient() const;
822 * @brief Sets the flick speed coefficient for ScrollView when
823 * flicking in free panning mode.
825 * This is a constant which multiplies the input touch
826 * flick velocity to determine the actual velocity at
827 * which to move the scrolling area.
828 * @param[in] speed The flick speed coefficient (default = 1.0).
830 void SetFlickSpeedCoefficient(float speed);
833 * @brief Returns the minimum pan distance required for a flick gesture in pixels
835 * @return Minimum pan distance vector with separate x and y distance
837 Vector2 GetMinimumDistanceForFlick() const;
840 * @brief Sets the minimum pan distance required for a flick in pixels
842 * 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
844 * @param[in] distance The minimum pan distance for a flick
846 void SetMinimumDistanceForFlick( const Vector2& distance );
849 * @brief Returns the minimum pan speed required for a flick gesture in pixels per second
851 * @return Minimum pan speed
853 float GetMinimumSpeedForFlick() const;
856 * @brief Sets the minimum pan speed required for a flick in pixels per second
858 * @param[in] speed The minimum pan speed for a flick
860 void SetMinimumSpeedForFlick( float speed );
863 * @brief Gets the maximum flick speed setting for ScrollView when
864 * flicking in free panning mode.
866 * This is a value in stage-diagonals per second.
867 * stage-diagonal = Length( stage.width, stage.height )
868 * @return Maximum flick speed is returned
870 float GetMaxFlickSpeed() const;
873 * @brief Sets the maximum flick speed for the ScrollView when
874 * flicking in free panning mode.
876 * This is a value in stage-diagonals per second.
877 * stage-diagonal = Length( stage.width, stage.height )
879 * A stage 480x800 in size has a diagonal length of 933.
880 * Max Flick speed of 1.0 means the maximum velocity of
881 * a swipe can be 1.0 * 933 pixels/sec.
882 * @param[in] speed Maximum flick speed (default = 3.0)
884 void SetMaxFlickSpeed(float speed);
887 * @brief Gets the step of scroll distance in actor coordinates for
888 * each mouse wheel event received in free panning mode.
890 * @return The step of scroll distance(pixel) in X and Y axes.
892 Vector2 GetMouseWheelScrollDistanceStep() const;
895 * @brief Sets the step of scroll distance in actor coordinates for
896 * each mouse wheel event received in free panning mode.
898 * @param[in] step The step of scroll distance(pixel) in X and Y axes.
900 * @note: If snap points are defined in the rulers, it will always
901 * scroll to the next snap point towards the scroll direction while
902 * receiving the mouse wheel events.
905 void SetMouseWheelScrollDistanceStep(Vector2 step);
908 * @brief Retrieves current scroll position.
910 * @returns The current scroll position.
912 Vector3 GetCurrentScrollPosition() const;
915 * @brief Sets the current scroll position, overriding current scroll animations. If panning is currently taking place
916 * SetScrollPosition will have no effect. Try to ensure panning has stopped before calling this function.
918 * @param[in] position The new scroll position to set.
920 void SetScrollPosition(const Vector3& position);
923 * @brief Retrieves current scroll scale.
925 * @returns The current scroll scale.
927 * @deprecated Scaling not supported
929 Vector3 GetCurrentScrollScale() const;
932 * @brief Retrieves current scroll page based on ScrollView
933 * dimensions being the size of one page, and all pages laid out in
934 * a grid fashion, increasing from left to right until the end of
937 * @note: Pages start from 0 as the first page, not 1.
939 * @returns The Current page.
941 unsigned int GetCurrentPage() const;
944 * @brief Transforms View to position, scale and rotation specified.
946 * @param[in] position The position to transform to.
947 * @param[in] scale The scale to transform to.
948 * @param[in] rotation The rotation to transform to.
950 * @deprecated Scaling or rotation not supported, use ScrollTo(const Vector3&)
952 void TransformTo(const Vector3& position, const Vector3& scale, float rotation);
955 * @brief Transforms View to position, scale and rotation specified in the duration specified.
957 * @param[in] position The position to transform to.
958 * @param[in] scale The scale to transform to.
959 * @param[in] rotation The rotation to transform to.
960 * @param[in] duration The duration for this animation in seconds.
962 * @deprecated Scaling or rotation not supported, use ScrollTo(const Vector3&, float)
964 void TransformTo(const Vector3& position, const Vector3& scale, float rotation, float duration);
967 * @brief Scrolls View to position specified (contents will scroll to this position).
969 * Position 0,0 is the origin. Increasing X scrolls contents left, while
970 * increasing Y scrolls contents up.
971 * - If Rulers have been applied to the axes, then the contents will scroll until
972 * reaching the domain boundary.
973 * @note Contents will not snap to ruler snap points.
975 * @param[in] position The position to scroll to.
977 void ScrollTo(const Vector3 &position);
980 * @brief Scrolls View to position specified (contents will scroll to this position).
982 * Position 0,0 is the origin. Increasing X scrolls contents left, while
983 * increasing Y scrolls contents up.
984 * - If Rulers have been applied to the axes, then the contents will scroll until
985 * reaching the domain boundary.
986 * @note Contents will not snap to ruler snap points.
988 * @param[in] position The position to scroll to.
989 * @param[in] duration The duration of the animation in seconds
991 void ScrollTo(const Vector3 &position, float duration);
994 * @brief Scrolls View to position specified (contents will scroll to this position).
996 * Position 0,0 is the origin. Increasing X scrolls contents left, while
997 * increasing Y scrolls contents up.
998 * - If Rulers have been applied to the axes, then the contents will scroll until
999 * reaching the domain boundary.
1000 * @note Contents will not snap to ruler snap points.
1001 * Biasing parameters are provided such that in scenarios with 2 or 2x2 pages in
1002 * wrap mode, the application developer can decide whether to scroll left or right
1003 * to get to the target page
1005 * @param[in] position The position to scroll to.
1006 * @param[in] duration The duration of the animation in seconds
1007 * @param[in] horizontalBias Whether to bias scrolling to left or right.
1008 * @param[in] verticalBias Whether to bias scrolling to top or bottom.
1010 void ScrollTo(const Vector3 &position, float duration,
1011 DirectionBias horizontalBias, DirectionBias verticalBias);
1014 * @brief Scrolls View to page currently based on assumption that each page is
1015 * "(page) * ScrollViewSize.width, 0".
1017 * @note Should probably be upgraded so that page is an abstract class, that can be
1018 * a function of ScrollViewSize, ruler domain, ruler snap points etc. as pages may be
1019 * orchestrated in a 2D grid fashion, or variable width.
1021 * @param[in] page to scroll to
1023 void ScrollTo(unsigned int page);
1026 * @brief Scrolls View to page currently based on assumption that each page is
1027 * "(page) * ScrollViewSize.width, 0".
1029 * @note Should probably be upgraded so that page is an abstract class, that can be
1030 * a function of ScrollViewSize, ruler domain, ruler snap points etc. as pages may be
1031 * orchestrated in a 2D grid fashion, or variable width.
1033 * @param[in] page to scroll to
1034 * @param[in] duration The duration of the animation in seconds
1036 void ScrollTo(unsigned int page, float duration);
1039 * @brief Scrolls View to page currently based on assumption that each page is
1040 * "(page) * ScrollViewSize.width, 0".
1042 * @note Should probably be upgraded so that page is an abstract class, that can be
1043 * a function of ScrollViewSize, ruler domain, ruler snap points etc. as pages may be
1044 * orchestrated in a 2D grid fashion, or variable width.
1045 * A biasing parameter is provided such that in scenarios with 2 pages in wrap mode,
1046 * the application developer can decide whether to scroll left or right to get to
1049 * @param[in] page to scroll to
1050 * @param[in] duration The duration of the animation in seconds
1051 * @param[in] bias Whether to bias scrolling to left or right.
1053 void ScrollTo(unsigned int page, float duration, DirectionBias bias);
1056 * @brief Scrolls View such that actor appears in the center of the ScrollView.
1058 * @note Actor must be a direct child of ScrollView, otherwise will
1059 * cause an assertion failure.
1060 * @param[in] actor The actor to center in on (via Scrolling).
1062 void ScrollTo(Actor& actor);
1065 * @brief Scrolls View such that actor appears in the center of the ScrollView.
1067 * @note Actor must be a direct child of ScrollView, otherwise will
1068 * cause an assertion failure.
1069 * @param[in] actor The actor to center in on (via Scrolling).
1070 * @param[in] duration The duration of the animation in seconds
1072 void ScrollTo(Actor& actor, float duration);
1075 * @brief Scrolls View to the nearest snap points as specified by the Rulers.
1077 * If already at snap points, then will return false, and not scroll.
1079 * @return True if Snapping necessary.
1081 bool ScrollToSnapPoint();
1084 * @brief Scales View to (scale).
1086 * @param[in] scale The scale factor the animate to.
1088 * @deprecated Scaling not supported
1090 void ScaleTo(const Vector3& scale);
1093 * @brief Scales View to (scale).
1095 * @param[in] scale The scale factor the animate to.
1096 * @param[in] duration The duration of the animation in seconds.
1098 * @deprecated Scaling not supported
1100 void ScaleTo(const Vector3& scale, float duration);
1103 * @brief Applies a constraint that will affect the children of ScrollView.
1105 * @note this affects all existing and future Actors that are added to scrollview.
1106 * @param[in] constraint The constraint to apply
1108 void ApplyConstraintToChildren(Constraint constraint);
1111 * @brief Removes all constraints that will affect the children of ScrollView.
1113 * @note this removes all constraints from actors that have been added
1116 void RemoveConstraintsFromChildren();
1119 * @brief Apply Effect to ScrollView.
1121 * @param[in] effect The effect to apply to scroll view
1123 void ApplyEffect(ScrollViewEffect effect);
1126 * @brief ApplyEffect Applies a predefined effect.
1128 * @param[in] effect enum for the predefined effect
1129 * @return The scrollview effect that was applied
1131 ScrollViewEffect ApplyEffect(ScrollView::PageEffect effect);
1134 * @brief Remove Effect from ScrollView.
1136 * @param[in] effect The effect to remove.
1138 void RemoveEffect(ScrollViewEffect effect);
1141 * @brief Remove All Effects from ScrollView.
1143 void RemoveAllEffects();
1146 * @brief Binds actor to this ScrollView.
1148 * Once an actor is bound to a ScrollView, it will be subject to
1149 * that ScrollView's properties.
1151 * @param[in] child The actor to add to this ScrollView.
1153 void BindActor(Actor child);
1156 * @brief Unbind Actor from this ScrollView.
1158 * Once Unbound, this ScrollView will not affect the actor.
1159 * @note this does not remove the child from the ScrollView container
1161 * @param[in] child The actor to be unbound.
1163 void UnbindActor(Actor child);
1166 * @brief Allows the user to constrain the scroll view in a particular direction.
1168 * @param[in] direction The axis to constrain the scroll-view to.
1169 * Usually set to PanGestureDetector::DIRECTION_VERTICAL or PanGestureDetector::DIRECTION_HORIZONTAL (but can be any other angle if desired).
1170 * @param[in] threshold The threshold to apply around the axis.
1171 * @note If no threshold is specified, then the default threshold of PI * 0.25 radians (or 45 degrees) is used.
1173 void SetScrollingDirection( Radian direction, Radian threshold = PanGestureDetector::DEFAULT_THRESHOLD );
1176 * @brief Remove a direction constraint from the scroll view.
1178 * @param[in] direction The axis to stop constraining to.
1179 * Usually will be PanGestureDetector::DIRECTION_VERTICAL or PanGestureDetector::DIRECTION_HORIZONTAL (but can be any other angle if desired).
1181 void RemoveScrollingDirection( Radian direction );
1183 public: // Not intended for application developers
1186 * @brief Creates a handle using the Toolkit::Internal implementation.
1188 * @param[in] implementation The Control implementation.
1190 ScrollView(Internal::ScrollView& implementation);
1193 * @brief Allows the creation of this Control from an Internal::CustomActor pointer.
1195 * @param[in] internal A pointer to the internal CustomActor.
1197 ScrollView( Dali::Internal::CustomActor* internal );
1200 } // namespace Toolkit
1207 #endif // __DALI_TOOLKIT_SCROLL_VIEW_H__