-#ifndef __DALI_TOOLKIT_SCROLL_VIEW_H__
-#define __DALI_TOOLKIT_SCROLL_VIEW_H__
+#ifndef DALI_TOOLKIT_SCROLL_VIEW_H
+#define DALI_TOOLKIT_SCROLL_VIEW_H
/*
- * Copyright (c) 2014 Samsung Electronics Co., Ltd.
+ * Copyright (c) 2019 Samsung Electronics Co., Ltd.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
*
*/
+// EXTERNAL INCLUDES
+#include <dali/public-api/animation/alpha-function.h>
+
// INTERNAL INCLUDES
#include <dali-toolkit/public-api/controls/scrollable/scrollable.h>
{
class ScrollView;
}
+/**
+ * @addtogroup dali_toolkit_controls_scroll_view
+ * @{
+ */
+
+/**
+ * @brief Enumeration for how axes/rotation or scale are clamped.
+ * @SINCE_1_0.0
+ */
+enum ClampState
+{
+ 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 2 dimensional clamp.
+ * @SINCE_1_0.0
+ */
+struct ClampState2D
+{
+ ClampState x; ///< The clamp state of the x axis
+ ClampState y; ///< The clamp state of the y axis
+};
/**
- * @brief The snap type
+ * @brief Enumeration for 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.
+ * @brief Enumeration for 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
+class DALI_TOOLKIT_API RulerDomain
{
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.
+ * @param[in] enabled Whether domain has been enabled or not
*/
explicit RulerDomain(float min, float max, bool enabled = true);
* An optional length parameter can be specified to suggest that the
* subject is not a point but a line to that should be clamped.
*
- * @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.
- * @return The clamped value.
+ * @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
+ * @return The clamped value
*/
float Clamp(float x, float length = 0.0f, float scale = 1.0f) const;
* An optional length parameter can be specified to suggest that the
* subject is not a point but a line to that should be clamped.
*
- * @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.
- * @param[out] clamped Whether clamping occured and which size (None, Min or Max)
- * @return The clamped value.
+ * @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
+ * @param[out] clamped Whether clamping occurred and which size (None, Min or Max)
+ * @return The clamped value
*/
float Clamp(float x, float length, float scale, ClampState &clamped) const;
/**
* @brief Returns (max-min) size of ruler.
*
- * @return The size of the ruler from min to max.
+ * @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.
+ * @brief Abstracts class to define scroll axes.
*
- * It can specify whether they are traversable, where their snap
- * points are and their domain.
+ * 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
+class DALI_TOOLKIT_API Ruler : public RefObject
{
public:
- /// @brief The type of the ruler
+ /**
+ * @brief Enumeration for the type of the ruler.
+ * @SINCE_1_0.0
+ */
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.
+ * @brief Constructs ruler, enabled by default, with limitless domain.
+ * @SINCE_1_0.0
*/
Ruler();
/**
* @brief Snaps (x) in accordance to the ruler settings.
*
- * @param[in] x The input value on the ruler to be snapped.
+ * @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"
* 0.5 round input (floor x + 0.5) "Used for Release"
* 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
- * @return The position representing this page point.
+ * @return The position representing this page point
*/
virtual float GetPositionFromPage(unsigned int page, unsigned int &volume, bool wrap) const = 0;
*
* 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.
+ * @return The page where this position resides
*/
virtual unsigned int GetPageFromPosition(float position, bool wrap) const = 0;
/**
* @brief Returns the total number of pages within this Ruler.
*
- * @return The number of pages in the 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.
*
- * @return The ruler type.
+ * @SINCE_1_0.0
+ * @return The ruler type
*/
Ruler::RulerType GetType() const;
/**
* @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.
+ * @brief Sets the Domain.
*
- * @param[in] domain Ruler domain object.
+ * @SINCE_1_0.0
+ * @param[in] domain Ruler domain object
*/
void SetDomain(RulerDomain domain);
/**
- * @brief Gets Domain.
+ * @brief Gets the 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();
* An optional length parameter can be specified to suggest that the
* subject is not a point but a line that should be clamped.
*
- * @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.
- * @return The clamped value.
+ * @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
+ * @return The clamped value
*/
float Clamp(float x, float length = 0.0f, float scale = 1.0f) const;
* An optional length parameter can be specified to suggest that the
* subject is not a point but a line to that should be clamped.
*
- * @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.
- * @param[out] clamped Whether clamping occured and which size (None, Min or Max)
- * @return The clamped value.
+ * @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
+ * @param[out] clamped Whether clamping occurred and which size (None, Min or Max)
+ * @return The clamped value
*/
float Clamp(float x, float length, float scale, ClampState &clamped) const;
/**
* @brief Snaps and Clamps (x) in accordance to ruler settings.
*
- * @param[in] x value to be snapped in accordance to ruler snap value,
- * and clamped in accordance to the ruler's domain (if set).
+ * @SINCE_1_0.0
+ * @param[in] x 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
* 0 floor input (floor x) "Used for Flick Left"
* 0.5 round input (floor x + 0.5) "Used for Release"
* 1 ceil input (floor x + 1.0) "Used for Flick Right"
* @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.
- * @return the clamped value after snapping
+ * to be clamped
+ * @param[in] scale Scaling parameter which treats domain as scaled in calculations
+ * @return The clamped value after snapping
*/
float SnapAndClamp(float x, float bias = 0.5f, float length = 0.0f, float scale = 1.0f) const;
/**
* @brief Snaps and Clamps (x) in accordance to ruler settings.
*
- * @param[in] x value to be snapped in accordance to ruler snap value,
- * and clamped in accordance to the ruler's domain (if set).
+ * @SINCE_1_0.0
+ * @param[in] x 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
* 0 floor input (floor x) "Used for Flick Left"
* 0.5 round input (floor x + 0.5) "Used for Release"
* 1 ceil input (floor x + 1.0) "Used for Flick Right"
* @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.
- * @param[out] clamped Whether clamping occured and which size (None, Min or Max)
+ * to be clamped
+ * @param[in] scale Scaling parameter which treats domain as scaled in calculations
+ * @param[out] clamped Whether clamping occurred and which size (None, Min or Max)
* @return The clamped value after snapping
*/
float SnapAndClamp(float x, float bias, float length, float scale, ClampState &clamped) const;
/**
* @brief Destructor - A reference counted object may only be deleted by calling Unreference().
+ * @SINCE_1_0.0
*/
virtual ~Ruler();
};
-typedef IntrusivePtr<Ruler> RulerPtr; ///< Pointer to Dali::Toolkit::Ruler object
+typedef IntrusivePtr<Ruler> 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
+class DALI_TOOLKIT_API DefaultRuler : public Ruler
{
public:
/**
* @brief DefaultRuler constructor.
+ * @SINCE_1_0.0
*/
DefaultRuler();
/**
* @brief Concrete implementation of Ruler that has fixed snapping.
+ * @SINCE_1_0.0
*/
-class DALI_IMPORT_API FixedRuler : public Ruler
+class DALI_TOOLKIT_API FixedRuler : public Ruler
{
public:
/**
- * @brief Constructor
+ * @brief Constructor.
*
- * @param[in] spacing The spacing between each interval on this ruler.
+ * @SINCE_1_0.0
+ * @param[in] spacing The spacing between each interval on this ruler
*/
FixedRuler(float spacing = 1.0f);
* | %Signal Name | Method |
* |-------------------|----------------------------|
* | snap-started | @ref SnapStartedSignal() |
+ * @SINCE_1_0.0
*/
-class DALI_IMPORT_API ScrollView : public Scrollable
+class DALI_TOOLKIT_API ScrollView : public Scrollable
{
+
public:
- // Custom properties
-
- static const std::string SCROLL_PAGE_CURRENT; ///< Property, name "scroll-page-current", type INT
- static const std::string SCROLL_TIME_PROPERTY_NAME; ///< Property, name "scroll-time", type FLOAT
- static const std::string SCROLL_POSITION_PROPERTY_NAME; ///< Property, name "scroll-position", type VECTOR3
- static const std::string SCROLL_PRE_POSITION_PROPERTY_NAME; ///< Property, name "scroll-pre-position", type VECTOR3
- static const std::string SCROLL_OVERSHOOT_X_PROPERTY_NAME; ///< Property, name "scroll-overshoot-x", type float
- static const std::string SCROLL_OVERSHOOT_Y_PROPERTY_NAME; ///< Property, name "scroll-overshoot-y", type float
- static const std::string SCROLL_FINAL_PROPERTY_NAME; ///< Property, name "scroll-final", type VECTOR3
- static const std::string SCROLL_SCALE_PROPERTY_NAME; ///< Property, name "scroll-scale", type VECTOR3
- static const std::string SCROLL_WRAP_PROPERTY_NAME; ///< Property, name "scroll-wrap", type BOOLEAN
- static const std::string SCROLL_PANNING_PROPERTY_NAME; ///< Property, name "scroll-panning", type BOOLEAN
- static const std::string SCROLL_SCROLLING_PROPERTY_NAME; ///< Property, name "scroll-scrolling", type BOOLEAN
- static const std::string SCROLL_POSITION_DELTA_PROPERTY_NAME; ///< Property, name "scroll-position-delta" type VECTOR3
- static const std::string SCROLL_START_PAGE_POSITION_PROPERTY_NAME; ///< Property, name "scroll-start-page-position" type VECTOR3
-
- // 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)
-
- /// Direction of transitions
- enum EDirectionFlag
+ /**
+ * @brief Clamps signal event's data.
+ * @SINCE_1_0.0
+ */
+ struct ClampEvent
{
- DirectionFlagLeft = 0x01,
- DirectionFlagRight = 0x02,
- DirectionFlagUp = 0x04,
- DirectionFlagDown = 0x08,
- 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
- DirectionFlagTransitionOff = 0x20,
- DirectionFlagMask_Direction = DirectionFlagLeft | DirectionFlagRight | DirectionFlagUp | DirectionFlagDown,
- DirectionFlagMask_Transition = DirectionFlagTransitionOn | DirectionFlagTransitionOff
+ ClampState2D scale; ///< Clamp information for scale axes
+ ClampState2D position; ///< Clamp information for position axes
+ ClampState rotation; ///< Clamp information for rotation
};
-public:
-
/**
- * @brief Snap signal event's data.
+ * @brief Snaps 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.
};
- typedef Signal< void ( const SnapEvent& ) > SnapStartedSignalType; ///< SnapStarted signal type
+ /**
+ * @brief Enumeration for 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 @SINCE_1_0.0
+ };
/**
- * @brief Signal emitted when the ScrollView has started to snap or flick (it tells the target
- * position, scale, rotation for the snap or flick)
+ * @brief Enumeration for the instance of properties belonging to the ScrollView class.
+ * @SINCE_1_0.0
*/
- SnapStartedSignalType& SnapStartedSignal();
+ struct Property
+ {
+ /**
+ * @brief Enumeration for the instance of properties belonging to the ScrollView class.
+ * @SINCE_1_0.0
+ */
+ enum
+ {
+ ///////////////////////////////////////////////////////////////////////////////
+ // Event side (non-animatable) properties
+ ///////////////////////////////////////////////////////////////////////////////
+
+ /**
+ * @brief Whether wrapping is enabled.
+ * @details Name "wrapEnabled", type Property::BOOLEAN.
+ * @SINCE_1_1.18
+ * @see SetWrapMode()
+ */
+ WRAP_ENABLED = PROPERTY_START_INDEX,
+
+ /**
+ * @brief Whether panning is enabled.
+ * @details Name "panningEnabled", type Property::BOOLEAN.
+ * @SINCE_1_1.18
+ * @see SetScrollSensitive()
+ */
+ PANNING_ENABLED,
+
+ /**
+ * @brief Whether the Axis Auto Lock mode for panning within the ScrollView is enabled.
+ * @details Name "axisAutoLockEnabled", type Property::BOOLEAN.
+ * @SINCE_1_1.18
+ * @see SetAxisAutoLock()
+ */
+ AXIS_AUTO_LOCK_ENABLED,
+
+ /**
+ * @brief The step of scroll distance in actor coordinates for each wheel event received in free panning mode.
+ * @details Name "wheelScrollDistanceStep", type Property::VECTOR2.
+ * @SINCE_1_1.18
+ * @see SetWheelScrollDistanceStep()
+ */
+ WHEEL_SCROLL_DISTANCE_STEP,
+
+ /**
+ * @brief The scroll mode.
+ * @details Name "scrollMode", type Property::MAP.
+ * The scroll mode map is a frontend for the Ruler helper class, containing the following keys:
+ *
+ * | %Property Name | Type | Required | Description |
+ * |----------------------|----------|----------|---------------------------------------------------------------------------------------------------------------------------------------|
+ * | xAxisScrollEnabled | BOOLEAN | No | True if the content can be scrolled in X axis or false if not. |
+ * | xAxisSnapToInterval | FLOAT | No | When set, causes scroll view to snap to multiples of the value of the interval in the X axis while flicking. (by default no snapping) |
+ * | xAxisScrollBoundary | FLOAT | No | When set, causes scroll view unable to scroll beyond the value of the boundary in the X axis (by default no boundary) |
+ * | yAxisScrollEnabled | BOOLEAN | No | True if the content can be scrolled in Y axis or false if not. |
+ * | yAxisSnapToInterval | FLOAT | No | When set, causes scroll view to snap to multiples of the value of the interval in the Y axis while flicking. (by default no snapping) |
+ * | yAxisScrollBoundary | FLOAT | No | When set, causes scroll view unable to scroll beyond the value of the boundary in the Y axis (by default no boundary) |
+ *
+ * Alternatively, one can use the keys defined in the Dali::Toolkit::ScrollMode::Type enumeration.
+ * @SINCE_1_2.60
+ */
+ SCROLL_MODE,
+
+ ///////////////////////////////////////////////////////////////////////////////
+ // Animatable Properties
+ ///////////////////////////////////////////////////////////////////////////////
+
+ /**
+ * @brief The current scroll position.
+ * @details Name "scrollPosition", type Property::VECTOR2.
+ * @SINCE_1_0.0
+ */
+ SCROLL_POSITION = ANIMATABLE_PROPERTY_START_INDEX,
+
+ /**
+ * @brief The position before we set the clamp at scroll boundaries.
+ * @details Name "scrollPrePosition", type Property::VECTOR2.
+ * @SINCE_1_0.0
+ */
+ SCROLL_PRE_POSITION,
+
+ /**
+ * @brief The X component of SCROLL_PRE_POSITION.
+ * @details Name "scrollPrePositionX", type Property::FLOAT.
+ * @SINCE_1_0.0
+ */
+ SCROLL_PRE_POSITION_X,
+
+ /**
+ * @brief The Y component of SCROLL_PRE_POSITION.
+ * @details Name "scrollPrePositionY", type Property::VECTOR2.
+ * @SINCE_1_0.0
+ */
+ SCROLL_PRE_POSITION_Y,
+
+ /**
+ * @brief The maximum value that SCROLL_PRE_POSITION can be.
+ * @details Name "scrollPrePositionMax", type Property::VECTOR2.
+ * @SINCE_1_0.0
+ */
+ SCROLL_PRE_POSITION_MAX,
+
+ /**
+ * @brief The X component of SCROLL_PRE_POSITION_MAX.
+ * @details Name "scrollPrePositionMaxX", type Property::FLOAT.
+ * @SINCE_1_0.0
+ */
+ SCROLL_PRE_POSITION_MAX_X,
+
+ /**
+ * @brief The Y component of SCROLL_PRE_POSITION_MAX.
+ * @details Name "scrollPrePositionMaxY", type Property::FLOAT.
+ * @SINCE_1_0.0
+ */
+ SCROLL_PRE_POSITION_MAX_Y,
+
+ /**
+ * @brief The amount that we can scroll beyond the boundary along the X axis.
+ * @details Name "overshootX", type Property::FLOAT.
+ * @SINCE_1_0.0
+ */
+ OVERSHOOT_X,
+
+ /**
+ * @brief The amount that we can scroll beyond the boundary along the Y axis.
+ * @details Name "overshootY", type Property::FLOAT.
+ * @SINCE_1_0.0
+ */
+ OVERSHOOT_Y,
+
+ /**
+ * @brief The position after the overshoot value has been considered in the calculation.
+ * @details Name "scrollFinal", type Property::VECTOR2.
+ * @SINCE_1_0.0
+ */
+ SCROLL_FINAL,
+
+ /**
+ * @brief The X component of SCROLL_FINAL.
+ * @details Name "scrollFinalX", type Property::FLOAT.
+ * @SINCE_1_0.0
+ */
+ SCROLL_FINAL_X,
+
+ /**
+ * @brief The Y component of SCROLL_FINAL.
+ * @details Name "scrollFinalY", type Property::FLOAT.
+ * @SINCE_1_0.0
+ */
+ SCROLL_FINAL_Y,
+
+ /**
+ * @brief Whether scrolling wraps.
+ * @details Name "wrap", type Property::BOOLEAN.
+ * @SINCE_1_0.0
+ */
+ WRAP,
+
+ /**
+ * @brief Whether we are currently panning.
+ * @details Name "panning", type Property::BOOLEAN.
+ * @SINCE_1_0.0
+ */
+ PANNING,
+
+ /**
+ * @brief Whether we are currently scrolling.
+ * @details Name "scrolling", type Property::BOOLEAN.
+ * @SINCE_1_0.0
+ */
+ SCROLLING,
+
+ /**
+ * @brief The size of the scrolling domain.
+ * @details Name "scrollDomainSize", type Property::VECTOR2.
+ * @SINCE_1_0.0
+ */
+ SCROLL_DOMAIN_SIZE,
+
+ /**
+ * @brief The X component of SCROLL_DOMAIN_SIZE.
+ * @details Name "scrollDomainSizeX", type Property::FLOAT.
+ * @SINCE_1_0.0
+ */
+ SCROLL_DOMAIN_SIZE_X,
+
+ /**
+ * @brief The Y component of SCROLL_DOMAIN_SIZE.
+ * @details Name "scrollDomainSizeY", type Property::FLOAT.
+ * @SINCE_1_0.0
+ */
+ SCROLL_DOMAIN_SIZE_Y,
+
+ /**
+ * @brief The offset of the scroll domain.
+ * @details Name "scrollDomainOffset", type Property::VECTOR2.
+ * @SINCE_1_0.0
+ */
+ SCROLL_DOMAIN_OFFSET,
+
+ /**
+ * @brief The delta in the position when scrolling.
+ * @details Name "scrollPositionDelta", type Property::VECTOR2.
+ * @SINCE_1_0.0
+ */
+ SCROLL_POSITION_DELTA,
+
+ /**
+ * @brief The starting page position.
+ * @details Name "startPagePosition", type Property::VECTOR3.
+ * @SINCE_1_0.0
+ */
+ START_PAGE_POSITION,
+ };
+ };
+
+ // Typedefs
+
+ 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();
/**
* @brief Copy constructor.
*
- * Creates another handle that points to the same real object
+ * Creates another handle that points to the same real object.
*
- * @param[in] handle to copy from
+ * @SINCE_1_0.0
+ * @param[in] handle Handle to copy from
*/
ScrollView( const ScrollView& handle );
/**
* @brief Assignment operator.
*
- * Changes this handle to point to another real object
+ * 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
*/
ScrollView& operator=( const ScrollView& handle );
/**
- * @brief Destructor
+ * @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.
+ * @brief Creates an initialized ScrollView.
*
- * @return A handle to a newly allocated Dali resource.
+ * @SINCE_1_0.0
+ * @return A handle to a newly allocated Dali resource
*/
static ScrollView New();
/**
- * @brief Downcast an Object handle to ScrollView.
+ * @brief Downcasts a handle to ScrollView handle.
*
- * If handle points to a ScrollView the downcast produces valid
- * handle. If not the returned handle is left uninitialized.
+ * 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
+ * @return A handle to a ScrollView or an uninitialized handle
*/
static ScrollView DownCast( BaseHandle handle );
public:
/**
- * @brief Get snap-animation's AlphaFunction.
+ * @brief Gets snap-animation's AlphaFunction.
*
- * @return Current easing alpha function of the snap animation.
+ * @SINCE_1_0.0
+ * @return Current easing alpha function of the snap animation
*/
AlphaFunction GetScrollSnapAlphaFunction() const;
/**
- * @brief Set snap-animation's AlphaFunction.
+ * @brief Sets snap-animation's AlphaFunction.
*
- * @param[in] alpha Easing alpha function of the snap animation.
+ * @SINCE_1_0.0
+ * @param[in] alpha Easing alpha function of the snap animation
*/
void SetScrollSnapAlphaFunction(AlphaFunction alpha);
/**
- * @brief Get flick-animation's AlphaFunction.
+ * @brief Gets flick-animation's AlphaFunction.
*
- * @return Current easing alpha function of the flick animation.
+ * @SINCE_1_0.0
+ * @return Current easing alpha function of the flick animation
*/
AlphaFunction GetScrollFlickAlphaFunction() const;
/**
- * @brief Set flick-animation's AlphaFunction.
+ * @brief Sets flick-animation's AlphaFunction.
*
- * @param[in] alpha Easing alpha function of the flick animation.
+ * @SINCE_1_0.0
+ * @param[in] alpha Easing alpha function of the flick animation
*/
void SetScrollFlickAlphaFunction(AlphaFunction alpha);
*
* This animation occurs when the user drags, and releases.
*
- * @return The time in seconds for the animation to take.
+ * @SINCE_1_0.0
+ * @return The time in seconds for the animation to take
*/
float GetScrollSnapDuration() const;
*
* This animation occurs when the user drags, and releases.
*
- * @param[in] time The time in seconds for the animation to take.
+ * @SINCE_1_0.0
+ * @param[in] time The time in seconds for the animation to take
*/
void SetScrollSnapDuration(float time);
*
* This animation occurs when the user flicks scroll view.
*
- * @return The time in seconds for the animation to take.
+ * @SINCE_1_0.0
+ * @return The time in seconds for the animation to take
*/
float GetScrollFlickDuration() const;
*
* This animation occurs when the user flicks scroll view.
*
- * @param[in] time The time in seconds for the animation to take.
+ * @SINCE_1_0.0
+ * @param[in] time The time in seconds for the animation to take
*/
void SetScrollFlickDuration(float time);
/**
- * @brief Set X axis ruler.
+ * @brief Sets X axis ruler.
*
* 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);
/**
- * @brief Set Y axis ruler.
+ * @brief Sets Y axis ruler.
*
* 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);
/**
- * @brief Set Scroll's touch sensitivity.
+ * @brief Sets scroll sensitivity of pan gesture.
*
- * @note Unlike SetSensitive(), this determines whether this ScrollView
- * should react (e.g. pan), without disrupting the sensitivity of it's children.
+ * @SINCE_1_0.0
+ * @param[in] sensitive @c true to enable scroll, @c false to disable scrolling
+ * @note Unlike Actor::SetSensitive(), this determines whether this ScrollView
+ * should react (e.g. pan), without disrupting the sensitivity of its children.
*
- * @param[in] sensitive true to enable scroll, false to disable scrolling
*/
void SetScrollSensitive(bool sensitive);
/**
- * @brief Set maximum overshoot amount.
+ * @brief Sets maximum overshoot amount.
*
* The final overshoot value is within 0.0f to 1.0f, but the maximum
* overshoot is in pixels (e.g. if you scroll 75 pixels beyond the
* edge of a scrollable area and the maximum overshoot is 100 then
- * the final overshoot value will be 0.75f)
+ * the final overshoot value will be 0.75f).
*
- * @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
+ * @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
*/
void SetMaxOvershoot(float overshootX, float overshootY);
/**
- * @brief Set Snap Overshoot animation's AlphaFunction.
+ * @brief Sets Snap Overshoot animation's AlphaFunction.
*
- * @param[in] alpha Easing alpha function of the overshoot snap animation.
+ * @SINCE_1_0.0
+ * @param[in] alpha Easing alpha function of the overshoot snap animation
*/
void SetSnapOvershootAlphaFunction(AlphaFunction alpha);
/**
- * @brief Set Snap Overshoot animation's Duration.
+ * @brief Sets Snap Overshoot animation's Duration.
*
- * @note Set duration to 0 seconds, to disable Animation.
+ * @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);
/**
- * @brief Sets Touches required for pan gestures.
- *
- * Panning requires number of touches to be within (minTouches) and
- * (maxTouches).
- *
- * If (endOutside) is true, then outside this range of touches,
- * the pan gesture will end and thus will snap.
- *
- * If (endOutside) is false, then outside this range of touches,
- * the pan gesture will pause. but will not end until touches = 0.
- *
- * @param[in] minTouches Minimum touches for panning to occur.
- * @param[out] maxTouches Maxiumum touches for panning to occur.
- * @param[in] endOutside Whether to end the panning gesture outside of touch range
- */
- void SetTouchesRequiredForPanning(unsigned int minTouches = 1, unsigned int maxTouches = 1, bool endOutside = true);
-
- /**
* @brief Enables or Disables Actor Auto-Snap mode.
*
* When Actor Auto-Snap mode has been enabled, ScrollView will automatically
* 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);
*
* 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
+ * @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;
/**
- * @brief Sets the distance needed to scroll for ScrollUpdatedSignal to be emitted
+ * @brief Sets the distance needed to scroll for ScrollUpdatedSignal to be emitted.
*
* 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
+ * 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);
/**
* @brief Returns state of Axis Auto Lock mode.
*
- * @return Whether Axis Auto Lock mode has been enabled or not.
+ * @SINCE_1_0.0
+ * @return Whether Axis Auto Lock mode has been enabled or not
*/
bool GetAxisAutoLock() const;
* vertical, will be automatically restricted to horizontal only or vertical
* only panning, until the pan gesture has completed.
*
- * @param[in] enable Enables (true), or disables (false) AxisAutoLock mode.
+ * @SINCE_1_0.0
+ * @param[in] enable Enables (true), or disables (false) AxisAutoLock mode
*/
void SetAxisAutoLock(bool enable);
* @brief Gets the gradient threshold at which a panning gesture
* should be locked to the Horizontal or Vertical axis.
*
- * @return The gradient, a value between 0.0 and 1.0f.
+ * @SINCE_1_0.0
+ * @return The gradient, a value between 0.0 and 1.0f
*/
float GetAxisAutoLockGradient() const;
* @brief Sets the gradient threshold at which a panning gesture should be locked to the
* Horizontal or Vertical axis.
*
- * By default this is 0.36 (0.36:1) which means angles less than 20
+ * By default, this is 0.36 (0.36:1) which means angles less than 20
* degrees to an axis will lock to that axis.
*
- * @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)
+ * @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.
+ *
*/
void SetAxisAutoLockGradient(float gradient);
*
* This is a value in stage-diagonals per second^2.
* stage-diagonal = Length( stage.width, stage.height )
- * @return Friction coefficient is returned.
+ * @SINCE_1_0.0
+ * @return Friction coefficient is returned
*/
float GetFrictionCoefficient() const;
* 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.
- * @param[in] friction Friction coefficient, must be greater than 0.0 (default = 1.0)
+ * @SINCE_1_0.0
+ * @param[in] friction Friction coefficient must be greater than 0.0 (default = 1.0)
*/
void SetFrictionCoefficient(float friction);
* This is a constant which multiplies the input touch
* flick velocity to determine the actual velocity at
* which to move the scrolling area.
- * @return The flick speed coefficient is returned.
+ * @SINCE_1_0.0
+ * @return The flick speed coefficient is returned
*/
float GetFlickSpeedCoefficient() const;
* This is a constant which multiplies the input touch
* flick velocity to determine the actual velocity at
* which to move the scrolling area.
- * @param[in] speed The flick speed coefficient (default = 1.0).
+ * @SINCE_1_0.0
+ * @param[in] speed The flick speed coefficient (default = 1.0)
*/
void SetFlickSpeedCoefficient(float speed);
/**
- * @brief Returns the minimum pan distance required for a flick gesture in pixels
+ * @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;
/**
- * @brief Sets the minimum pan distance required for a flick in pixels
+ * @brief Sets the minimum pan distance required for a flick in pixels.
*
- * 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
+ * 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 );
/**
- * @brief Returns the minimum pan speed required for a flick gesture in pixels per second
+ * @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;
/**
- * @brief Sets the minimum pan speed required for a flick in pixels per second
+ * @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 );
*
* 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;
* 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.
*
- * @return The step of scroll distance(pixel) in X and Y axes.
+ * @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.
*
- * @param[in] step The step of scroll distance(pixel) in X and Y axes.
+ * @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
+ * @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.
- */
- 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.
+ * @SINCE_1_0.0
+ * @return The current scroll position
*/
- void SetScrollPosition(const Vector3& position);
+ Vector2 GetCurrentScrollPosition() const;
/**
* @brief Retrieves current scroll page based on ScrollView
* a grid fashion, increasing from left to right until the end of
* the X-domain.
*
- * @note: Pages start from 0 as the first page, not 1.
+ * @SINCE_1_0.0
+ * @note Pages start from 0 as the first page, not 1.
*
- * @returns The Current page.
+ * @return The Current page
*/
unsigned int GetCurrentPage() const;
* 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).
* 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
* @note Contents will not snap to ruler snap points.
*
- * @param[in] position The position to scroll to.
- * @param[in] duration The duration of the animation in seconds
*/
- 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)
+ * @brief Scrolls View to position specified (contents will scroll to this position).
*
* Position 0,0 is the origin. Increasing X scrolls contents left, while
* 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.
- *
- * @param[in] position The position to scroll to.
+ * @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).
* 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
+ * 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);
/**
- * @brief Scrolls View to position specified (contents will scroll to this position)
+ * @brief Scrolls View to position specified (contents will scroll to this position).
*
* Position 0,0 is the origin. Increasing X scrolls contents left, while
* 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
+ * @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
+ * 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.
- * @param[in] alpha Alpha function to use
*/
- 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 The 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);
* @brief Scrolls View to page currently based on assumption that each page is
* "(page) * ScrollViewSize.width, 0".
*
+ * @SINCE_1_0.0
+ * @param[in] page The 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);
* @brief Scrolls View to page currently based on assumption that each page is
* "(page) * ScrollViewSize.width, 0".
*
+ * @SINCE_1_0.0
+ * @param[in] page The 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.
* 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.
*
+ * @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.
- * @param[in] actor The actor to center in on (via Scrolling).
- * @param[in] duration The duration of the animation in seconds
*/
void ScrollTo(Actor& actor, float duration);
*
* If already at snap points, then will return false, and not scroll.
*
- * @return True if Snapping necessary.
+ * @SINCE_1_0.0
+ * @return True if Snapping necessary
*/
bool ScrollToSnapPoint();
/**
* @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.
*
- * @note this removes all constraints from actors that have been added
+ * @SINCE_1_0.0
+ * @note This removes all constraints from actors that have been added
* to scrollview.
*/
void RemoveConstraintsFromChildren();
/**
- * @brief Apply Effect to ScrollView.
+ * @brief Applies Effect to ScrollView.
*
+ * @SINCE_1_0.0
* @param[in] effect The effect to apply to scroll view
*/
void ApplyEffect(ScrollViewEffect effect);
/**
- * @brief Remove Effect from ScrollView.
+ * @brief Removes Effect from ScrollView.
*
- * @param[in] effect The effect to remove.
+ * @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();
* Once an actor is bound to a ScrollView, it will be subject to
* that ScrollView's properties.
*
- * @param[in] child The actor to add to this ScrollView.
+ * @SINCE_1_0.0
+ * @param[in] child The actor to add to this ScrollView
*/
void BindActor(Actor child);
/**
- * @brief Unbind Actor from this ScrollView.
+ * @brief Unbinds Actor from this ScrollView.
*
* Once Unbound, this ScrollView will not affect the actor.
- * @note this does not remove the child from the ScrollView container
+ * @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.
+ * @param[in] threshold The threshold to apply around the axis
* @note If no threshold is specified, then the default threshold of PI * 0.25 radians (or 45 degrees) is used.
*/
void SetScrollingDirection( Radian direction, Radian threshold = PanGestureDetector::DEFAULT_THRESHOLD );
/**
- * @brief Remove a direction constraint from the scroll view.
+ * @brief Removes 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
+ /// @cond internal
/**
* @brief Creates a handle using the Toolkit::Internal implementation.
*
- * @param[in] implementation The Control implementation.
+ * @SINCE_1_0.0
+ * @param[in] implementation The Control implementation
*/
DALI_INTERNAL ScrollView(Internal::ScrollView& implementation);
/**
* @brief Allows the creation of this Control from an Internal::CustomActor pointer.
*
- * @param[in] internal A pointer to the internal CustomActor.
+ * @SINCE_1_0.0
+ * @param[in] internal A pointer to the internal CustomActor
*/
explicit DALI_INTERNAL ScrollView( Dali::Internal::CustomActor* internal );
+ /// @endcond
};
+/**
+ * @}
+ */
} // namespace Toolkit
} // namespace Dali
-#endif // __DALI_TOOLKIT_SCROLL_VIEW_H__
+#endif // DALI_TOOLKIT_SCROLL_VIEW_H
projects / platform / core / uifw / dali-toolkit.git / blobdiff