X-Git-Url: http://review.tizen.org/git/?p=platform%2Fcore%2Fuifw%2Fdali-toolkit.git;a=blobdiff_plain;f=dali-toolkit%2Fpublic-api%2Fcontrols%2Fscrollable%2Fscroll-view%2Fscroll-view.h;h=cdc19372b3099cb06f8930cc4ead23ef97cc79c3;hp=cf579ac6024865af8415bf7c40f15aed56d9e601;hb=502a6996c58f8b8de2dd530235852d53d01d2ac0;hpb=b3aff14cae6b3af637e75171422c16661878ba8e diff --git a/dali-toolkit/public-api/controls/scrollable/scroll-view/scroll-view.h b/dali-toolkit/public-api/controls/scrollable/scroll-view/scroll-view.h index cf579ac..cdc1937 100644 --- a/dali-toolkit/public-api/controls/scrollable/scroll-view/scroll-view.h +++ b/dali-toolkit/public-api/controls/scrollable/scroll-view/scroll-view.h @@ -19,7 +19,7 @@ */ // EXTERNAL INCLUDES -#include +#include // INTERNAL INCLUDES #include @@ -34,48 +34,56 @@ namespace Internal DALI_INTERNAL { class ScrollView; } +/** + * @addtogroup dali_toolkit_controls_scroll_view + * @{ + */ /** * @brief How axes/rotation or scale are clamped + * @SINCE_1_0.0 */ enum ClampState { - NotClamped, ///< The quantity isn't clamped - ClampedToMin, ///< The quantity is clamped to the min value - ClampedToMax ///< The quantity is clamped to the max value + NotClamped, ///< The quantity isn't clamped @SINCE_1_0.0 + ClampedToMin, ///< The quantity is clamped to the min value @SINCE_1_0.0 + ClampedToMax ///< The quantity is clamped to the max value @SINCE_1_0.0 }; /** - * @brief A 3 dimensional clamp + * @brief A 2 dimensional clamp + * @SINCE_1_0.0 */ -struct ClampState3D +struct ClampState2D { ClampState x; ///< The clamp state of the x axis ClampState y; ///< The clamp state of the y axis - ClampState z; ///< The clamp state of the z axis }; /** * @brief The snap type + * @SINCE_1_0.0 */ enum SnapType { - Snap, ///< Snap - Flick ///< Flick + Snap, ///< Snap @SINCE_1_0.0 + Flick ///< Flick @SINCE_1_0.0 }; /** * @brief DirectionBias types. + * @SINCE_1_0.0 */ enum DirectionBias { - DirectionBiasLeft = -1, ///< Bias scroll snap to Left - DirectionBiasNone = 0, ///< Don't bias scroll snap - DirectionBiasRight = 1 ///< Bias scroll snap to Right + DirectionBiasLeft = -1, ///< Bias scroll snap to Left @SINCE_1_0.0 + DirectionBiasNone = 0, ///< Don't bias scroll snap @SINCE_1_0.0 + DirectionBiasRight = 1 ///< Bias scroll snap to Right @SINCE_1_0.0 }; /** * @brief Used for specifying minimum/maximum extents of a ruler. + * @SINCE_1_0.0 */ class DALI_IMPORT_API RulerDomain { @@ -84,6 +92,7 @@ public: /** * @brief Creates Ruler domain allowing a point to traverse between min and max extents. * + * @SINCE_1_0.0 * @param[in] min Minimum extent (point cannot traverse less than this) * @param[in] max Maximum extent (point cannot traverse greater than this) * @param[in] enabled Whether domain has been enabled or not. @@ -102,6 +111,7 @@ public: * An optional length parameter can be specified to suggest that the * subject is not a point but a line to that should be clamped. * + * @SINCE_1_0.0 * @param[in] x X point to be clamped between (min) and (max) extents. * @param[in] length (optional) The Length of the line from (x) to (x + length) to be clamped. * @param[in] scale Scaling parameter which treats domain as scaled in calculations. @@ -115,6 +125,7 @@ public: * An optional length parameter can be specified to suggest that the * subject is not a point but a line to that should be clamped. * + * @SINCE_1_0.0 * @param[in] x X point to be clamped between (min) and (max) extents. * @param[in] length (optional) The Length of the line from (x) to (x + length) to be clamped. * @param[in] scale Scaling parameter which treats domain as scaled in calculations. @@ -126,37 +137,44 @@ public: /** * @brief Returns (max-min) size of ruler. * + * @SINCE_1_0.0 * @return The size of the ruler from min to max. */ float GetSize() const; }; +// Forward declare future extension interface +class RulerExtension; + /** * @brief Abstract class to define scroll axes. * * It can specify whether they are traversable, where their snap * points are and their domain. + * @SINCE_1_0.0 */ class DALI_IMPORT_API Ruler : public RefObject { public: /// @brief The type of the ruler enum RulerType { - Fixed, ///< A fixed ruler - Free ///< A free ruler + Fixed, ///< A fixed ruler @SINCE_1_0.0 + Free ///< A free ruler @SINCE_1_0.0 }; public: /** * @brief Constructs ruler, default enabled, with limitless domain. + * @SINCE_1_0.0 */ Ruler(); /** * @brief Snaps (x) in accordance to the ruler settings. * + * @SINCE_1_0.0 * @param[in] x The input value on the ruler to be snapped. * @param[in] bias (optional) The biasing employed for snapping * 0 floor input (floor x) "Used for Flick Left" @@ -175,6 +193,7 @@ public: * number of pages within the domain), while wrapping the position * within the domain. * + * @SINCE_1_0.0 * @param[in] page The page index * @param[out] volume The overflow volume when the page exceeds the domain (wrap must be enabled) * @param[in] wrap Enable wrap mode @@ -188,6 +207,7 @@ public: * * If (wrap) is true, then will return a page wrapped within the domain. * + * @SINCE_1_0.0 * @param[in] position The position on the domain * @param[in] wrap Enable wrap mode * @return The page where this position resides. @@ -197,15 +217,25 @@ public: /** * @brief Returns the total number of pages within this Ruler. * + * @SINCE_1_0.0 * @return The number of pages in the Ruler. */ virtual unsigned int GetTotalPages() const = 0; + /** + * @brief Gets the extension interface of the Ruler. + * + * @SINCE_1_0.0 + * @return The extension interface of the Ruler + */ + virtual RulerExtension* GetExtension() { return NULL; } + public: /** * @brief Gets the ruler type. * + * @SINCE_1_0.0 * @return The ruler type. */ Ruler::RulerType GetType() const; @@ -213,23 +243,27 @@ public: /** * @brief Returns whether this axis has been enabled or not. * + * @SINCE_1_0.0 * @return true if axis is enabled */ bool IsEnabled() const; /** * @brief Enables ruler (ruler must be enabled in order to traverse along it). + * @SINCE_1_0.0 */ void Enable(); /** * @brief Disables ruler. + * @SINCE_1_0.0 */ void Disable(); /** * @brief Sets Domain. * + * @SINCE_1_0.0 * @param[in] domain Ruler domain object. */ void SetDomain(RulerDomain domain); @@ -237,12 +271,14 @@ public: /** * @brief Gets Domain. * + * @SINCE_1_0.0 * @return The domain */ const RulerDomain &GetDomain() const; /** * @brief Disables Domain (minimum/maximum extents for this axis). + * @SINCE_1_0.0 */ void DisableDomain(); @@ -252,6 +288,7 @@ public: * An optional length parameter can be specified to suggest that the * subject is not a point but a line that should be clamped. * + * @SINCE_1_0.0 * @param[in] x X point to be clamped between (min) and (max) extents. * @param[in] length (optional) The Length of the line from (x) to (x + length) to be clamped. * @param[in] scale Scaling parameter which treats domain as scaled in calculations. @@ -266,6 +303,7 @@ public: * An optional length parameter can be specified to suggest that the * subject is not a point but a line to that should be clamped. * + * @SINCE_1_0.0 * @param[in] x X point to be clamped between (min) and (max) extents. * @param[in] length (optional) The Length of the line from (x) to (x + length) to be clamped. * @param[in] scale Scaling parameter which treats domain as scaled in calculations. @@ -277,6 +315,7 @@ public: /** * @brief Snaps and Clamps (x) in accordance to ruler settings. * + * @SINCE_1_0.0 * @param[in] x value to be snapped in accordance to ruler snap value, * and clamped in accordance to the ruler's domain (if set). * @param[in] bias (optional) The biasing employed for snapping @@ -293,6 +332,7 @@ public: /** * @brief Snaps and Clamps (x) in accordance to ruler settings. * + * @SINCE_1_0.0 * @param[in] x value to be snapped in accordance to ruler snap value, * and clamped in accordance to the ruler's domain (if set). * @param[in] bias (optional) The biasing employed for snapping @@ -311,6 +351,7 @@ protected: /** * @brief Destructor - A reference counted object may only be deleted by calling Unreference(). + * @SINCE_1_0.0 */ virtual ~Ruler(); @@ -322,16 +363,18 @@ protected: }; -typedef IntrusivePtr RulerPtr; ///< Pointer to Dali::Toolkit::Ruler object +typedef IntrusivePtr RulerPtr; ///< Pointer to Dali::Toolkit::Ruler object @SINCE_1_0.0 /** * @brief Concrete implementation of Ruler that has no snapping and has one single page. + * @SINCE_1_0.0 */ class DALI_IMPORT_API DefaultRuler : public Ruler { public: /** * @brief DefaultRuler constructor. + * @SINCE_1_0.0 */ DefaultRuler(); @@ -358,6 +401,7 @@ public: /** * @brief Concrete implementation of Ruler that has fixed snapping. + * @SINCE_1_0.0 */ class DALI_IMPORT_API FixedRuler : public Ruler { @@ -365,6 +409,7 @@ public: /** * @brief Constructor * + * @SINCE_1_0.0 * @param[in] spacing The spacing between each interval on this ruler. */ FixedRuler(float spacing = 1.0f); @@ -404,87 +449,95 @@ class ScrollView; * | %Signal Name | Method | * |-------------------|----------------------------| * | snap-started | @ref SnapStartedSignal() | + * @SINCE_1_0.0 */ class DALI_IMPORT_API ScrollView : public Scrollable { -public: - - // Default settings - - static const float DEFAULT_SLOW_SNAP_ANIMATION_DURATION; ///< Default Drag-Release animation time. - static const float DEFAULT_FAST_SNAP_ANIMATION_DURATION; ///< Default Drag-Flick animation time. - static const float DEFAULT_SNAP_OVERSHOOT_DURATION; ///< Default Overshoot snapping animation time. - static const float DEFAULT_MAX_OVERSHOOT; ///< Default maximum allowed overshoot - - static const float DEFAULT_AXIS_AUTO_LOCK_GRADIENT; ///< Default Axis-AutoLock gradient threshold. default is 0.36:1 (20 degrees) - static const float DEFAULT_FRICTION_COEFFICIENT; ///< Default Friction Co-efficient. (in stage diagonals per second) - static const float DEFAULT_FLICK_SPEED_COEFFICIENT; ///< Default Flick speed coefficient (multiples input touch velocity) - static const float DEFAULT_MAX_FLICK_SPEED; ///< Default Maximum flick speed. (in stage diagonals per second) public: /** * @brief Clamp signal event's data + * @SINCE_1_0.0 */ struct ClampEvent { - ClampState3D scale; ///< Clamp information for scale axes - ClampState3D position; ///< Clamp information for position axes + ClampState2D scale; ///< Clamp information for scale axes + ClampState2D position; ///< Clamp information for position axes ClampState rotation; ///< Clamp information for rotation }; /** * @brief Snap signal event's data. + * @SINCE_1_0.0 */ struct SnapEvent { SnapType type; ///< Current snap commencing - Vector3 position; ///< Target snap position + Vector2 position; ///< Target snap position float duration; ///< Duration of snap animation. }; /** * @brief The start and end property ranges for this control. + * @SINCE_1_0.0 */ enum PropertyRange { + PROPERTY_START_INDEX = Toolkit::Scrollable::PROPERTY_END_INDEX + 1, ///< @SINCE_1_1.18 + PROPERTY_END_INDEX = PROPERTY_START_INDEX + 1000, ///< Reserve property indices, @SINCE_1_1.18 + ANIMATABLE_PROPERTY_START_INDEX = Toolkit::Scrollable::ANIMATABLE_PROPERTY_END_INDEX + 1, - ANIMATABLE_PROPERTY_END_INDEX = ANIMATABLE_PROPERTY_START_INDEX + 1000 ///< Reserve animatable property indices + ANIMATABLE_PROPERTY_END_INDEX = ANIMATABLE_PROPERTY_START_INDEX + 1000 ///< Reserve animatable property indices @SINCE_1_0.0 }; /** * @brief An enumeration of properties belonging to the ScrollView class. + * @SINCE_1_0.0 */ struct Property { enum { - SCROLL_POSITION = ANIMATABLE_PROPERTY_START_INDEX, ///< Property, name "scroll-position", type Vector3 - SCROLL_PRE_POSITION, ///< Property, name "scroll-pre-position", type Vector3 - OVERSHOOT_X, ///< Property, name "overshoot-x", type float - OVERSHOOT_Y, ///< Property, name "overshoot-y", type float - SCROLL_FINAL, ///< Property, name "scroll-final", type Vector3 - WRAP, ///< Property, name "wrap", type bool - PANNING, ///< Property, name "panning", type bool - SCROLLING, ///< Property, name "scrolling", type bool - SCROLL_DOMAIN_OFFSET, ///< Property, name "scroll-domain-offset" type Vector3 - SCROLL_POSITION_DELTA, ///< Property, name "scroll-position-delta" type Vector3 - START_PAGE_POSITION ///< Property, name "start-page-position" type Vector3 + // Event side properties + WRAP_ENABLED = PROPERTY_START_INDEX, ///< Property, name "wrapEnabled", @see SetWrapMode(), type bool, @SINCE_1_1.18 + PANNING_ENABLED, ///< Property, name "panningEnabled", @see SetScrollSensitive(), type bool, @SINCE_1_1.18 + AXIS_AUTO_LOCK_ENABLED, ///< Property, name "axisAutoLockEnabled", @see SetAxisAutoLock(), type bool, @SINCE_1_1.18 + WHEEL_SCROLL_DISTANCE_STEP, ///< Property, name "wheelScrollDistanceStep", @see SetWheelScrollDistanceStep(), type Vector2, @SINCE_1_1.18 + + SCROLL_POSITION = ANIMATABLE_PROPERTY_START_INDEX, ///< Property, name "scrollPosition", type Vector2 @SINCE_1_0.0 + SCROLL_PRE_POSITION, ///< Property, name "scrollPrePosition", type Vector2 @SINCE_1_0.0 + SCROLL_PRE_POSITION_X, ///< Property, name "scrollPrePositionX", type float @SINCE_1_0.0 + SCROLL_PRE_POSITION_Y, ///< Property, name "scrollPrePositionY", type float @SINCE_1_0.0 + SCROLL_PRE_POSITION_MAX, ///< Property, name "scrollPrePositionMax", type Vector2 @SINCE_1_0.0 + SCROLL_PRE_POSITION_MAX_X, ///< Property, name "scrollPrePositionMaxX", type float @SINCE_1_0.0 + SCROLL_PRE_POSITION_MAX_Y, ///< Property, name "scrollPrePositionMaxY", type float @SINCE_1_0.0 + OVERSHOOT_X, ///< Property, name "overshootX", type float @SINCE_1_0.0 + OVERSHOOT_Y, ///< Property, name "overshootY", type float @SINCE_1_0.0 + SCROLL_FINAL, ///< Property, name "scrollFinal", type Vector2 @SINCE_1_0.0 + SCROLL_FINAL_X, ///< Property, name "scrollFinalX", type float @SINCE_1_0.0 + SCROLL_FINAL_Y, ///< Property, name "scrollFinalY", type float @SINCE_1_0.0 + WRAP, ///< Property, name "wrap", type bool @SINCE_1_0.0 + PANNING, ///< Property, name "panning", type bool @SINCE_1_0.0 + SCROLLING, ///< Property, name "scrolling", type bool @SINCE_1_0.0 + SCROLL_DOMAIN_SIZE, ///< Property, name "scrollDomainSize", type Vector2 @SINCE_1_0.0 + SCROLL_DOMAIN_SIZE_X, ///< Property, name "scrollDomainSizeX", type float @SINCE_1_0.0 + SCROLL_DOMAIN_SIZE_Y, ///< Property, name "scrollDomainSizeY", type float @SINCE_1_0.0 + SCROLL_DOMAIN_OFFSET, ///< Property, name "scrollDomainOffset", type Vector2 @SINCE_1_0.0 + SCROLL_POSITION_DELTA, ///< Property, name "scrollPositionDelta", type Vector2 @SINCE_1_0.0 + START_PAGE_POSITION ///< Property, name "startPagePosition", type Vector3 @SINCE_1_0.0 }; }; - typedef Signal< void ( const SnapEvent& ) > SnapStartedSignalType; ///< SnapStarted signal type + // Typedefs - /** - * @brief Signal emitted when the ScrollView has started to snap or flick (it tells the target - * position, scale, rotation for the snap or flick) - */ - SnapStartedSignalType& SnapStartedSignal(); + typedef Signal< void ( const SnapEvent& ) > SnapStartedSignalType; ///< SnapStarted signal type @SINCE_1_0.0 public: /** * @brief Creates an empty ScrollView handle. + * @SINCE_1_0.0 */ ScrollView(); @@ -493,6 +546,7 @@ public: * * Creates another handle that points to the same real object * + * @SINCE_1_0.0 * @param[in] handle to copy from */ ScrollView( const ScrollView& handle ); @@ -501,6 +555,7 @@ public: * @brief Assignment operator. * * Changes this handle to point to another real object + * @SINCE_1_0.0 * @param[in] handle The handle to copy from * @return A reference to this */ @@ -510,12 +565,14 @@ public: * @brief Destructor * * This is non-virtual since derived Handle types must not contain data or virtual methods. + * @SINCE_1_0.0 */ ~ScrollView(); /** * @brief Create an initialized ScrollView. * + * @SINCE_1_0.0 * @return A handle to a newly allocated Dali resource. */ static ScrollView New(); @@ -526,6 +583,7 @@ public: * If handle points to a ScrollView the downcast produces valid * handle. If not the returned handle is left uninitialized. * + * @SINCE_1_0.0 * @param[in] handle Handle to an object * @return handle to a ScrollView or an uninitialized handle */ @@ -536,6 +594,7 @@ public: /** * @brief Get snap-animation's AlphaFunction. * + * @SINCE_1_0.0 * @return Current easing alpha function of the snap animation. */ AlphaFunction GetScrollSnapAlphaFunction() const; @@ -543,6 +602,7 @@ public: /** * @brief Set snap-animation's AlphaFunction. * + * @SINCE_1_0.0 * @param[in] alpha Easing alpha function of the snap animation. */ void SetScrollSnapAlphaFunction(AlphaFunction alpha); @@ -550,6 +610,7 @@ public: /** * @brief Get flick-animation's AlphaFunction. * + * @SINCE_1_0.0 * @return Current easing alpha function of the flick animation. */ AlphaFunction GetScrollFlickAlphaFunction() const; @@ -557,6 +618,7 @@ public: /** * @brief Set flick-animation's AlphaFunction. * + * @SINCE_1_0.0 * @param[in] alpha Easing alpha function of the flick animation. */ void SetScrollFlickAlphaFunction(AlphaFunction alpha); @@ -566,6 +628,7 @@ public: * * This animation occurs when the user drags, and releases. * + * @SINCE_1_0.0 * @return The time in seconds for the animation to take. */ float GetScrollSnapDuration() const; @@ -575,6 +638,7 @@ public: * * This animation occurs when the user drags, and releases. * + * @SINCE_1_0.0 * @param[in] time The time in seconds for the animation to take. */ void SetScrollSnapDuration(float time); @@ -584,6 +648,7 @@ public: * * This animation occurs when the user flicks scroll view. * + * @SINCE_1_0.0 * @return The time in seconds for the animation to take. */ float GetScrollFlickDuration() const; @@ -593,6 +658,7 @@ public: * * This animation occurs when the user flicks scroll view. * + * @SINCE_1_0.0 * @param[in] time The time in seconds for the animation to take. */ void SetScrollFlickDuration(float time); @@ -603,6 +669,7 @@ public: * Defines how scrolling horizontally is snapped, and * the boundary (domain) in which the ScrollView can pan. * + * @SINCE_1_0.0 * @param[in] ruler The ruler to be used for the X axis */ void SetRulerX(RulerPtr ruler); @@ -613,6 +680,7 @@ public: * Defines how scrolling vertically is snapped, and the boundary * (domain) in which the ScrollView can pan. * + * @SINCE_1_0.0 * @param[in] ruler The ruler to be used for the Y axis */ void SetRulerY(RulerPtr ruler); @@ -620,10 +688,11 @@ public: /** * @brief Set Scroll's touch sensitivity. * + * @SINCE_1_0.0 + * @param[in] sensitive true to enable scroll, false to disable scrolling * @note Unlike SetSensitive(), this determines whether this ScrollView * should react (e.g. pan), without disrupting the sensitivity of it's children. * - * @param[in] sensitive true to enable scroll, false to disable scrolling */ void SetScrollSensitive(bool sensitive); @@ -635,6 +704,7 @@ public: * edge of a scrollable area and the maximum overshoot is 100 then * the final overshoot value will be 0.75f) * + * @SINCE_1_0.0 * @param[in] overshootX the maximum number of horizontally scrolled pixels before overshoot X reaches 1.0f * @param[in] overshootY the maximum number of vertically scrolled pixels before overshoot Y reaches 1.0f */ @@ -643,6 +713,7 @@ public: /** * @brief Set Snap Overshoot animation's AlphaFunction. * + * @SINCE_1_0.0 * @param[in] alpha Easing alpha function of the overshoot snap animation. */ void SetSnapOvershootAlphaFunction(AlphaFunction alpha); @@ -650,9 +721,10 @@ public: /** * @brief Set Snap Overshoot animation's Duration. * + * @SINCE_1_0.0 + * @param[in] duration The duration of the overshoot snap animation. * @note Set duration to 0 seconds, to disable Animation. * - * @param[in] duration The duration of the overshoot snap animation. */ void SetSnapOvershootDuration(float duration); @@ -663,6 +735,7 @@ public: * snap to the closest actor (The closest actor will appear in the center of * the ScrollView). * + * @SINCE_1_0.0 * @param[in] enable Enables (true), or disables (false) Actor AutoSnap */ void SetActorAutoSnap(bool enable); @@ -672,16 +745,18 @@ public: * * When enabled, the ScrollView contents are wrapped over the X/Y Domain. * + * @SINCE_1_0.0 + * @param[in] enable Enables (true), or disables (false) Wrap Mode. * @note You must apply a position constraint that causes Wrapping * to all children. * - * @param[in] enable Enables (true), or disables (false) Wrap Mode. */ void SetWrapMode(bool enable); /** * @brief Gets the current distance needed to scroll for ScrollUpdatedSignal to be emitted * + * @SINCE_1_0.0 * @return Current scroll update distance */ int GetScrollUpdateDistance() const; @@ -692,6 +767,7 @@ public: * The scroll update distance tells ScrollView how far to move before ScrollUpdatedSignal the informs application. * Each time the ScrollView crosses this distance the signal will be emitted * + * @SINCE_1_0.0 * @param[in] distance The distance for ScrollView to move before emitting update signal */ void SetScrollUpdateDistance(int distance); @@ -699,6 +775,7 @@ public: /** * @brief Returns state of Axis Auto Lock mode. * + * @SINCE_1_0.0 * @return Whether Axis Auto Lock mode has been enabled or not. */ bool GetAxisAutoLock() const; @@ -710,6 +787,7 @@ public: * vertical, will be automatically restricted to horizontal only or vertical * only panning, until the pan gesture has completed. * + * @SINCE_1_0.0 * @param[in] enable Enables (true), or disables (false) AxisAutoLock mode. */ void SetAxisAutoLock(bool enable); @@ -718,6 +796,7 @@ public: * @brief Gets the gradient threshold at which a panning gesture * should be locked to the Horizontal or Vertical axis. * + * @SINCE_1_0.0 * @return The gradient, a value between 0.0 and 1.0f. */ float GetAxisAutoLockGradient() const; @@ -732,6 +811,7 @@ public: * @note: Specifying a value of 1.0 (the maximum value accepted) indicates that * all panning gestures will auto-lock. Either to the horizontal or vertical axis. * + * @SINCE_1_0.0 * @param[in] gradient A value between 0.0 and 1.0 (auto-lock for all angles) */ void SetAxisAutoLockGradient(float gradient); @@ -742,6 +822,7 @@ public: * * This is a value in stage-diagonals per second^2. * stage-diagonal = Length( stage.width, stage.height ) + * @SINCE_1_0.0 * @return Friction coefficient is returned. */ float GetFrictionCoefficient() const; @@ -756,6 +837,7 @@ public: * A stage 480x800 in size has a diagonal length of 933. * Friction coefficient of 1.0 means the swipe velocity will * reduce by 1.0 * 933 pixels/sec^2. + * @SINCE_1_0.0 * @param[in] friction Friction coefficient, must be greater than 0.0 (default = 1.0) */ void SetFrictionCoefficient(float friction); @@ -767,6 +849,7 @@ public: * This is a constant which multiplies the input touch * flick velocity to determine the actual velocity at * which to move the scrolling area. + * @SINCE_1_0.0 * @return The flick speed coefficient is returned. */ float GetFlickSpeedCoefficient() const; @@ -778,6 +861,7 @@ public: * This is a constant which multiplies the input touch * flick velocity to determine the actual velocity at * which to move the scrolling area. + * @SINCE_1_0.0 * @param[in] speed The flick speed coefficient (default = 1.0). */ void SetFlickSpeedCoefficient(float speed); @@ -785,6 +869,7 @@ public: /** * @brief Returns the minimum pan distance required for a flick gesture in pixels * + * @SINCE_1_0.0 * @return Minimum pan distance vector with separate x and y distance */ Vector2 GetMinimumDistanceForFlick() const; @@ -794,6 +879,7 @@ public: * * 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 * + * @SINCE_1_0.0 * @param[in] distance The minimum pan distance for a flick */ void SetMinimumDistanceForFlick( const Vector2& distance ); @@ -801,6 +887,7 @@ public: /** * @brief Returns the minimum pan speed required for a flick gesture in pixels per second * + * @SINCE_1_0.0 * @return Minimum pan speed */ float GetMinimumSpeedForFlick() const; @@ -808,6 +895,7 @@ public: /** * @brief Sets the minimum pan speed required for a flick in pixels per second * + * @SINCE_1_0.0 * @param[in] speed The minimum pan speed for a flick */ void SetMinimumSpeedForFlick( float speed ); @@ -818,6 +906,7 @@ public: * * This is a value in stage-diagonals per second. * stage-diagonal = Length( stage.width, stage.height ) + * @SINCE_1_0.0 * @return Maximum flick speed is returned */ float GetMaxFlickSpeed() const; @@ -832,45 +921,41 @@ public: * A stage 480x800 in size has a diagonal length of 933. * Max Flick speed of 1.0 means the maximum velocity of * a swipe can be 1.0 * 933 pixels/sec. + * @SINCE_1_0.0 * @param[in] speed Maximum flick speed (default = 3.0) */ void SetMaxFlickSpeed(float speed); /** * @brief Gets the step of scroll distance in actor coordinates for - * each mouse wheel event received in free panning mode. + * each wheel event received in free panning mode. * + * @SINCE_1_0.0 * @return The step of scroll distance(pixel) in X and Y axes. */ - Vector2 GetMouseWheelScrollDistanceStep() const; + Vector2 GetWheelScrollDistanceStep() const; /** * @brief Sets the step of scroll distance in actor coordinates for - * each mouse wheel event received in free panning mode. + * each wheel event received in free panning mode. * + * @SINCE_1_0.0 * @param[in] step The step of scroll distance(pixel) in X and Y axes. * * @note: If snap points are defined in the rulers, it will always * scroll to the next snap point towards the scroll direction while - * receiving the mouse wheel events. + * receiving the wheel events. * */ - void SetMouseWheelScrollDistanceStep(Vector2 step); + void SetWheelScrollDistanceStep(Vector2 step); /** * @brief Retrieves current scroll position. * * @returns The current scroll position. + * @SINCE_1_0.0 */ - Vector3 GetCurrentScrollPosition() const; - - /** - * @brief Sets the current scroll position, overriding current scroll animations. If panning is currently taking place - * SetScrollPosition will have no effect. Try to ensure panning has stopped before calling this function. - * - * @param[in] position The new scroll position to set. - */ - void SetScrollPosition(const Vector3& position); + Vector2 GetCurrentScrollPosition() const; /** * @brief Retrieves current scroll page based on ScrollView @@ -881,6 +966,7 @@ public: * @note: Pages start from 0 as the first page, not 1. * * @returns The Current page. + * @SINCE_1_0.0 */ unsigned int GetCurrentPage() const; @@ -891,11 +977,12 @@ public: * increasing Y scrolls contents up. * - If Rulers have been applied to the axes, then the contents will scroll until * reaching the domain boundary. + * @SINCE_1_0.0 + * @param[in] position The position to scroll to. * @note Contents will not snap to ruler snap points. * - * @param[in] position The position to scroll to. */ - void ScrollTo(const Vector3 &position); + void ScrollTo(const Vector2& position); /** * @brief Scrolls View to position specified (contents will scroll to this position). @@ -904,12 +991,13 @@ public: * increasing Y scrolls contents up. * - If Rulers have been applied to the axes, then the contents will scroll until * reaching the domain boundary. - * @note Contents will not snap to ruler snap points. - * + * @SINCE_1_0.0 * @param[in] position The position to scroll to. * @param[in] duration The duration of the animation in seconds + * @note Contents will not snap to ruler snap points. + * */ - void ScrollTo(const Vector3 &position, float duration); + void ScrollTo(const Vector2& position, float duration); /** * @brief Scrolls View to position specified (contents will scroll to this position) @@ -918,13 +1006,14 @@ public: * increasing Y scrolls contents up. * - If Rulers have been applied to the axes, then the contents will scroll until * reaching the domain boundary. - * @note Contents will not snap to ruler snap points. - * + * @SINCE_1_0.0 * @param[in] position The position to scroll to. * @param[in] duration The duration of the animation in seconds * @param[in] alpha The alpha function to use + * @note Contents will not snap to ruler snap points. + * */ - void ScrollTo(const Vector3 &position, float duration, AlphaFunction alpha); + void ScrollTo(const Vector2& position, float duration, AlphaFunction alpha); /** * @brief Scrolls View to position specified (contents will scroll to this position). @@ -933,17 +1022,18 @@ public: * increasing Y scrolls contents up. * - If Rulers have been applied to the axes, then the contents will scroll until * reaching the domain boundary. + * @SINCE_1_0.0 + * @param[in] position The position to scroll to. + * @param[in] duration The duration of the animation in seconds + * @param[in] horizontalBias Whether to bias scrolling to left or right. + * @param[in] verticalBias Whether to bias scrolling to top or bottom. * @note Contents will not snap to ruler snap points. * Biasing parameters are provided such that in scenarios with 2 or 2x2 pages in * wrap mode, the application developer can decide whether to scroll left or right * to get to the target page * - * @param[in] position The position to scroll to. - * @param[in] duration The duration of the animation in seconds - * @param[in] horizontalBias Whether to bias scrolling to left or right. - * @param[in] verticalBias Whether to bias scrolling to top or bottom. */ - void ScrollTo(const Vector3 &position, float duration, + void ScrollTo(const Vector2& position, float duration, DirectionBias horizontalBias, DirectionBias verticalBias); /** @@ -953,29 +1043,31 @@ public: * increasing Y scrolls contents up. * - If Rulers have been applied to the axes, then the contents will scroll until * reaching the domain boundary. - * @note Contents will not snap to ruler snap points. - * Biasing parameters are provided such that in scenarios with 2 or 2x2 pages in - * wrap mode, the application developer can decide whether to scroll left or right - * to get to the target page - * + * @SINCE_1_0.0 * @param[in] position The position to scroll to. * @param[in] duration The duration of the animation in seconds * @param[in] horizontalBias Whether to bias scrolling to left or right. * @param[in] verticalBias Whether to bias scrolling to top or bottom. * @param[in] alpha Alpha function to use + * @note Contents will not snap to ruler snap points. + * Biasing parameters are provided such that in scenarios with 2 or 2x2 pages in + * wrap mode, the application developer can decide whether to scroll left or right + * to get to the target page + * */ - void ScrollTo(const Vector3 &position, float duration, AlphaFunction alpha, + void ScrollTo(const Vector2& position, float duration, AlphaFunction alpha, DirectionBias horizontalBias, DirectionBias verticalBias); /** * @brief Scrolls View to page currently based on assumption that each page is * "(page) * ScrollViewSize.width, 0". * + * @SINCE_1_0.0 + * @param[in] page to scroll to * @note Should probably be upgraded so that page is an abstract class, that can be * a function of ScrollViewSize, ruler domain, ruler snap points etc. as pages may be * orchestrated in a 2D grid fashion, or variable width. * - * @param[in] page to scroll to */ void ScrollTo(unsigned int page); @@ -983,12 +1075,13 @@ public: * @brief Scrolls View to page currently based on assumption that each page is * "(page) * ScrollViewSize.width, 0". * + * @SINCE_1_0.0 + * @param[in] page to scroll to + * @param[in] duration The duration of the animation in seconds * @note Should probably be upgraded so that page is an abstract class, that can be * a function of ScrollViewSize, ruler domain, ruler snap points etc. as pages may be * orchestrated in a 2D grid fashion, or variable width. * - * @param[in] page to scroll to - * @param[in] duration The duration of the animation in seconds */ void ScrollTo(unsigned int page, float duration); @@ -996,6 +1089,10 @@ public: * @brief Scrolls View to page currently based on assumption that each page is * "(page) * ScrollViewSize.width, 0". * + * @SINCE_1_0.0 + * @param[in] page to scroll to + * @param[in] duration The duration of the animation in seconds + * @param[in] bias Whether to bias scrolling to left or right. * @note Should probably be upgraded so that page is an abstract class, that can be * a function of ScrollViewSize, ruler domain, ruler snap points etc. as pages may be * orchestrated in a 2D grid fashion, or variable width. @@ -1003,28 +1100,27 @@ public: * the application developer can decide whether to scroll left or right to get to * the target page. * - * @param[in] page to scroll to - * @param[in] duration The duration of the animation in seconds - * @param[in] bias Whether to bias scrolling to left or right. */ void ScrollTo(unsigned int page, float duration, DirectionBias bias); /** * @brief Scrolls View such that actor appears in the center of the ScrollView. * + * @SINCE_1_0.0 + * @param[in] actor The actor to center in on (via Scrolling). * @note Actor must be a direct child of ScrollView, otherwise will * cause an assertion failure. - * @param[in] actor The actor to center in on (via Scrolling). */ void ScrollTo(Actor& actor); /** * @brief Scrolls View such that actor appears in the center of the ScrollView. * - * @note Actor must be a direct child of ScrollView, otherwise will - * cause an assertion failure. + * @SINCE_1_0.0 * @param[in] actor The actor to center in on (via Scrolling). * @param[in] duration The duration of the animation in seconds + * @note Actor must be a direct child of ScrollView, otherwise will + * cause an assertion failure. */ void ScrollTo(Actor& actor, float duration); @@ -1033,6 +1129,7 @@ public: * * If already at snap points, then will return false, and not scroll. * + * @SINCE_1_0.0 * @return True if Snapping necessary. */ bool ScrollToSnapPoint(); @@ -1040,14 +1137,16 @@ public: /** * @brief Applies a constraint that will affect the children of ScrollView. * - * @note this affects all existing and future Actors that are added to scrollview. + * @SINCE_1_0.0 * @param[in] constraint The constraint to apply + * @note this affects all existing and future Actors that are added to scrollview. */ void ApplyConstraintToChildren(Constraint constraint); /** * @brief Removes all constraints that will affect the children of ScrollView. * + * @SINCE_1_0.0 * @note this removes all constraints from actors that have been added * to scrollview. */ @@ -1056,6 +1155,7 @@ public: /** * @brief Apply Effect to ScrollView. * + * @SINCE_1_0.0 * @param[in] effect The effect to apply to scroll view */ void ApplyEffect(ScrollViewEffect effect); @@ -1063,12 +1163,14 @@ public: /** * @brief Remove Effect from ScrollView. * + * @SINCE_1_0.0 * @param[in] effect The effect to remove. */ void RemoveEffect(ScrollViewEffect effect); /** * @brief Remove All Effects from ScrollView. + * @SINCE_1_0.0 */ void RemoveAllEffects(); @@ -1078,6 +1180,7 @@ public: * Once an actor is bound to a ScrollView, it will be subject to * that ScrollView's properties. * + * @SINCE_1_0.0 * @param[in] child The actor to add to this ScrollView. */ void BindActor(Actor child); @@ -1086,15 +1189,17 @@ public: * @brief Unbind Actor from this ScrollView. * * Once Unbound, this ScrollView will not affect the actor. + * @SINCE_1_0.0 + * @param[in] child The actor to be unbound. * @note this does not remove the child from the ScrollView container * - * @param[in] child The actor to be unbound. */ void UnbindActor(Actor child); /** * @brief Allows the user to constrain the scroll view in a particular direction. * + * @SINCE_1_0.0 * @param[in] direction The axis to constrain the scroll-view to. * Usually set to PanGestureDetector::DIRECTION_VERTICAL or PanGestureDetector::DIRECTION_HORIZONTAL (but can be any other angle if desired). * @param[in] threshold The threshold to apply around the axis. @@ -1105,16 +1210,34 @@ public: /** * @brief Remove a direction constraint from the scroll view. * + * @SINCE_1_0.0 * @param[in] direction The axis to stop constraining to. * Usually will be PanGestureDetector::DIRECTION_VERTICAL or PanGestureDetector::DIRECTION_HORIZONTAL (but can be any other angle if desired). */ void RemoveScrollingDirection( Radian direction ); +public: // Signals + + /** + * @brief Signal emitted when the ScrollView has started to snap or flick (it tells the target + * position, scale, rotation for the snap or flick) + * + * A callback of the following type may be connected: + * @code + * void YourCallbackName(const SnapEvent& event); + * @endcode + * @SINCE_1_0.0 + * @return The signal to connect to. + * @pre The Object has been initialized. + */ + SnapStartedSignalType& SnapStartedSignal(); + public: // Not intended for application developers /** * @brief Creates a handle using the Toolkit::Internal implementation. * + * @SINCE_1_0.0 * @param[in] implementation The Control implementation. */ DALI_INTERNAL ScrollView(Internal::ScrollView& implementation); @@ -1122,11 +1245,15 @@ public: // Not intended for application developers /** * @brief Allows the creation of this Control from an Internal::CustomActor pointer. * + * @SINCE_1_0.0 * @param[in] internal A pointer to the internal CustomActor. */ explicit DALI_INTERNAL ScrollView( Dali::Internal::CustomActor* internal ); }; +/** + * @} + */ } // namespace Toolkit } // namespace Dali