capi/dali-toolkit/public-api/controls/scrollable/scroll-view/scroll-view.h

   1 #ifndef __DALI_TOOLKIT_SCROLL_VIEW_H__
   2 #define __DALI_TOOLKIT_SCROLL_VIEW_H__
   3
   4 //
   5 // Copyright (c) 2014 Samsung Electronics Co., Ltd.
   6 //
   7 // Licensed under the Flora License, Version 1.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
  10 //
  11 //     http://floralicense.org/license/
  12 //
  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.
  18 //
  19
  20 /**
  21  * @addtogroup CAPI_DALI_TOOLKIT_SCROLL_VIEW_MODULE
  22  * @{
  23  */
  24
  25 // INTERNAL INCLUDES
  26 #include <dali-toolkit/public-api/controls/scrollable/scrollable.h>
  27
  28 namespace Dali DALI_IMPORT_API
  29 {
  30
  31 namespace Toolkit
  32 {
  33
  34 namespace Internal DALI_INTERNAL
  35 {
  36 class ScrollView;
  37 }
  38
  39 /**
  40  * @brief The snap type
  41  */
  42 enum SnapType
  43 {
  44   Snap,  ///< Snap
  45   Flick  ///< Flick
  46 };
  47
  48 /**
  49  * @brief DirectionBias types.
  50  */
  51 enum DirectionBias
  52 {
  53   DirectionBiasLeft  = -1,  ///< Bias scroll snap to Left
  54   DirectionBiasNone  =  0,  ///< Don't bias scroll snap
  55   DirectionBiasRight =  1   ///< Bias scroll snap to Right
  56 };
  57
  58 /**
  59  * @brief Used for specifying minimum/maximum extents of a ruler.
  60  */
  61 class RulerDomain
  62 {
  63 public:
  64
  65   /**
  66    * @brief Creates Ruler domain allowing a point to traverse between min and max extents.
  67    *
  68    * @param[in] min Minimum extent (point cannot traverse less than this)
  69    * @param[in] max Maximum extent (point cannot traverse greater than this)
  70    * @param[in] enabled Whether domain has been enabled or not.
  71    */
  72   explicit RulerDomain(float min, float max, bool enabled = true);
  73
  74 public:
  75
  76   float min;    ///< Minimum extent (point cannot traverse less than this)
  77   float max;    ///< Maximum extent (point cannot traverse greater than this)
  78   bool enabled; ///< Whether domain has been enabled or not.
  79
  80   /**
  81    * @brief Clamps value (x) from (min) to (max).
  82    *
  83    * An optional length parameter can be specified to suggest that the
  84    * subject is not a point but a line to that should be clamped.
  85    *
  86    * @param[in] x X point to be clamped between (min) and (max) extents.
  87    * @param[in] length (optional) The Length of the line from (x) to (x + length) to be clamped.
  88    * @param[in] scale Scaling parameter which treats domain as scaled in calculations.
  89    * @return The clamped value.
  90    */
  91   float Clamp(float x, float length = 0.0f, float scale = 1.0f) const;
  92
  93   /**
  94    * @brief Clamps value (x) from (min) to (max).
  95    *
  96    * An optional length parameter can be specified to suggest that the
  97    * subject is not a point but a line to that should be clamped.
  98    *
  99    * @param[in] x X point to be clamped between (min) and (max) extents.
 100    * @param[in] length (optional) The Length of the line from (x) to (x + length) to be clamped.
 101    * @param[in] scale Scaling parameter which treats domain as scaled in calculations.
 102    * @param[out] clamped Whether clamping occured and which size (None, Min or Max)
 103    * @return The clamped value.
 104    */
 105   float Clamp(float x, float length, float scale, ClampState &clamped) const;
 106
 107   /**
 108    * @brief Returns (max-min) size of ruler.
 109    *
 110    * @return The size of the ruler from min to max.
 111    */
 112   float GetSize() const;
 113
 114 };
 115
 116 /**
 117  * @brief Abstract class to define scroll axes.
 118  *
 119  * It can specify whether they are traversable, where their snap
 120  * points are and their domain.
 121  */
 122 class Ruler : public RefObject
 123 {
 124 public:
 125   /// @brief The type of the ruler
 126   enum RulerType {
 127     Fixed,  ///< A fixed ruler
 128     Free    ///< A free ruler
 129   };
 130
 131 public:
 132
 133   /**
 134    * @brief Constructs ruler, default enabled, with limitless domain.
 135    */
 136   Ruler();
 137
 138   /**
 139    * @brief Destructor - A reference counted object may only be deleted by calling Unreference().
 140    */
 141   virtual ~Ruler();
 142
 143   /**
 144    * @brief Snaps (x) in accordance to the ruler settings.
 145    *
 146    * @param[in] x The input value on the ruler to be snapped.
 147    * @param[in] bias (optional) The biasing employed for snapping
 148    * 0 floor input (floor x) "Used for Flick Left"
 149    * 0.5 round input (floor x + 0.5) "Used for Release"
 150    * 1 ceil input (floor x + 1.0) "Used for Flick Right"
 151    * @return The position of the one dimensional point passed in once snapped.
 152    */
 153   virtual float Snap(float x, float bias = 0.5f) const = 0;
 154
 155   /**
 156    * @brief Returns position from page, based on whatever the ruler
 157    * defines as a page.
 158    *
 159    * If (wrap) is true, then will set volume to the number of
 160    * times page has exceeded the domain's volume (volume being the
 161    * number of pages within the domain), while wrapping the position
 162    * within the domain.
 163    *
 164    * @param[in] page The page index
 165    * @param[out] volume The overflow volume when the page exceeds the domain (wrap must be enabled)
 166    * @param[in] wrap Enable wrap mode
 167    * @return The position representing this page point.
 168    */
 169   virtual float GetPositionFromPage(unsigned int page, unsigned int &volume, bool wrap) const = 0;
 170
 171   /**
 172    * @brief Returns page from position, based on whatever the ruler
 173    * defines as a page.
 174    *
 175    * If (wrap) is true, then will return a page wrapped within the domain.
 176    *
 177    * @param[in] position The position on the domain
 178    * @param[in] wrap Enable wrap mode
 179    * @return The page where this position resides.
 180    */
 181   virtual unsigned int GetPageFromPosition(float position, bool wrap) const = 0;
 182
 183   /**
 184    * @brief Returns the total number of pages within this Ruler.
 185    *
 186    * @return The number of pages in the Ruler.
 187    */
 188   virtual unsigned int GetTotalPages() const = 0;
 189
 190 public:
 191
 192   /**
 193    * @brief Gets the ruler type.
 194    *
 195    * @return The ruler type.
 196    */
 197   Ruler::RulerType GetType() const;
 198
 199   /**
 200    * @brief Returns whether this axis has been enabled or not.
 201    *
 202    * @return true if axis is enabled
 203    */
 204   bool IsEnabled() const;
 205
 206   /**
 207    * @brief Enables ruler (ruler must be enabled in order to traverse along it).
 208    */
 209   void Enable();
 210
 211   /**
 212    * @brief Disables ruler.
 213    */
 214   void Disable();
 215
 216   /**
 217    * @brief Sets Domain.
 218    *
 219    * @param[in] domain Ruler domain object.
 220    */
 221   void SetDomain(RulerDomain domain);
 222
 223   /**
 224    * @brief Gets Domain.
 225    *
 226    * @return The domain
 227    */
 228   const RulerDomain &GetDomain() const;
 229
 230   /**
 231    * @brief Disables Domain (minimum/maximum extents for this axis).
 232    */
 233   void DisableDomain();
 234
 235   /**
 236    * @brief Clamps value (x) from (min) to (max).
 237    *
 238    * An optional length parameter can be specified to suggest that the
 239    * subject is not a point but a line that should be clamped.
 240    *
 241    * @param[in] x X point to be clamped between (min) and (max) extents.
 242    * @param[in] length (optional) The Length of the line from (x) to (x + length) to be clamped.
 243    * @param[in] scale Scaling parameter which treats domain as scaled in calculations.
 244    * @return The clamped value.
 245    */
 246   float Clamp(float x, float length = 0.0f, float scale = 1.0f) const;
 247
 248
 249   /**
 250    * @brief Clamps value (x) from (min) to (max).
 251    *
 252    * An optional length parameter can be specified to suggest that the
 253    * subject is not a point but a line to that should be clamped.
 254    *
 255    * @param[in] x X point to be clamped between (min) and (max) extents.
 256    * @param[in] length (optional) The Length of the line from (x) to (x + length) to be clamped.
 257    * @param[in] scale Scaling parameter which treats domain as scaled in calculations.
 258    * @param[out] clamped Whether clamping occured and which size (None, Min or Max)
 259    * @return The clamped value.
 260    */
 261   float Clamp(float x, float length, float scale, ClampState &clamped) const;
 262
 263   /**
 264    * @brief Snaps and Clamps (x) in accordance to ruler settings.
 265    *
 266    * @param[in] x value to be snapped in accordance to ruler snap value,
 267    *            and clamped in accordance to the ruler's domain (if set).
 268    * @param[in] bias (optional) The biasing employed for snapping
 269    *            0 floor input (floor x) "Used for Flick Left"
 270    *            0.5 round input (floor x + 0.5) "Used for Release"
 271    *            1 ceil input (floor x + 1.0) "Used for Flick Right"
 272    * @param[in] length (optional) The Length of the line from (x) to (x + length)
 273    *            to be clamped.
 274    * @param[in] scale Scaling parameter which treats domain as scaled in calculations.
 275    * @return the clamped value after snapping
 276    */
 277   float SnapAndClamp(float x, float bias = 0.5f, float length = 0.0f, float scale = 1.0f) const;
 278
 279   /**
 280    * @brief Snaps and Clamps (x) in accordance to ruler settings.
 281    *
 282    * @param[in] x value to be snapped in accordance to ruler snap value,
 283    *            and clamped in accordance to the ruler's domain (if set).
 284    * @param[in] bias (optional) The biasing employed for snapping
 285    * 0 floor input (floor x) "Used for Flick Left"
 286    * 0.5 round input (floor x + 0.5) "Used for Release"
 287    * 1 ceil input (floor x + 1.0) "Used for Flick Right"
 288    * @param[in] length (optional) The Length of the line from (x) to (x + length)
 289    * to be clamped.
 290    * @param[in] scale Scaling parameter which treats domain as scaled in calculations.
 291    * @param[out] clamped Whether clamping occured and which size (None, Min or Max)
 292    * @return The clamped value after snapping
 293    */
 294   float SnapAndClamp(float x, float bias, float length, float scale, ClampState &clamped) const;
 295
 296 protected:
 297
 298   RulerType mType;               ///< Type of Ruler (Fixed or Free).
 299   bool mEnabled;                 ///< If the ruler is enabled.
 300   RulerDomain mDomain;           ///< The domain of the ruler.
 301
 302 };
 303
 304 typedef IntrusivePtr<Ruler> RulerPtr; ///< Pointer to Dali::Toolkit::Ruler object
 305
 306 /**
 307  * @brief Concrete implementation of Ruler that has no snapping and has one single page.
 308  */
 309 class DefaultRuler : public Ruler
 310 {
 311 public:
 312   /**
 313    * @brief DefaultRuler constructor.
 314    */
 315   DefaultRuler();
 316
 317   /**
 318    * @copydoc Toolkit::Ruler::Snap
 319    */
 320   virtual float Snap(float x, float bias) const;
 321
 322   /**
 323    * @copydoc Toolkit::Ruler::GetPositionFromPage
 324    */
 325   virtual float GetPositionFromPage(unsigned int page, unsigned int &volume, bool wrap) const;
 326
 327   /**
 328    * @copydoc Toolkit::Ruler::GetPageFromPosition
 329    */
 330   virtual unsigned int GetPageFromPosition(float position, bool wrap) const;
 331
 332   /**
 333    * @copydoc Toolkit::Ruler::GetTotalPages
 334    */
 335   virtual unsigned int GetTotalPages() const;
 336 };
 337
 338 /**
 339  * @brief Concrete implementation of Ruler that has fixed snapping.
 340  */
 341 class FixedRuler : public Ruler
 342 {
 343 public:
 344   /**
 345    * @brief Constructor
 346    *
 347    * @param[in] spacing The spacing between each interval on this ruler.
 348    */
 349   FixedRuler(float spacing = 1.0f);
 350
 351   /**
 352    * @copydoc Toolkit::Ruler::Snap
 353    */
 354   virtual float Snap(float x, float bias) const;
 355
 356   /**
 357    * @copydoc Toolkit::Ruler::GetPositionFromPage
 358    */
 359   virtual float GetPositionFromPage(unsigned int page, unsigned int &volume, bool wrap) const;
 360
 361   /**
 362    * @copydoc Toolkit::Ruler::GetPageFromPosition
 363    */
 364   virtual unsigned int GetPageFromPosition(float position, bool wrap) const;
 365
 366   /**
 367    * @copydoc Toolkit::Ruler::GetTotalPages
 368    */
 369   virtual unsigned int GetTotalPages() const;
 370
 371 private:
 372   float mSpacing; ///< The spacing between each interval
 373 };
 374
 375 class ScrollViewEffect;
 376 class ScrollView;
 377
 378 /**
 379  * @brief ScrollView contains actors that can be scrolled manually (via touch)
 380  * or automatically.
 381  */
 382 class ScrollView : public Scrollable
 383 {
 384 public:
 385   /// Page effect types
 386   enum PageEffect
 387   {
 388     PageEffectNone,      ///< No Effect (Standard ScrollView)
 389     PageEffectOuterCube, ///< 3D Rotating Cube Effect
 390     PageEffectDepth,     ///< Depth Effect
 391     PageEffectInnerCube, ///< Page Cube Effect
 392     PageEffectCarousel,  ///< Page Carousel Effect
 393     PageEffectSpiral,    ///< Page Spiral Effect
 394
 395     Total                ///< The total number of effect types
 396   };
 397
 398   // Custom properties
 399
 400   static const std::string SCROLL_PAGE_CURRENT;                         ///< Property, name "scroll-page-current",       type INT
 401   static const std::string SCROLL_TIME_PROPERTY_NAME;                   ///< Property, name "scroll-time",               type FLOAT
 402   static const std::string SCROLL_POSITION_PROPERTY_NAME;               ///< Property, name "scroll-position",           type VECTOR3
 403   static const std::string SCROLL_PRE_POSITION_PROPERTY_NAME;           ///< Property, name "scroll-pre-position",       type VECTOR3
 404   static const std::string SCROLL_OVERSHOOT_X_PROPERTY_NAME;            ///< Property, name "scroll-overshoot-x",         type float
 405   static const std::string SCROLL_OVERSHOOT_Y_PROPERTY_NAME;            ///< Property, name "scroll-overshoot-y",         type float
 406   static const std::string SCROLL_FINAL_PROPERTY_NAME;                  ///< Property, name "scroll-final",              type VECTOR3
 407   static const std::string SCROLL_X_PROPERTY_NAME;                      ///< Property, name "scroll-x",                  type FLOAT
 408   static const std::string SCROLL_Y_PROPERTY_NAME;                      ///< Property, name "scroll-y",                  type FLOAT
 409   static const std::string SCROLL_SCALE_PROPERTY_NAME;                  ///< Property, name "scroll-scale",              type VECTOR3
 410   static const std::string SCROLL_WRAP_PROPERTY_NAME;                   ///< Property, name "scroll-wrap",               type BOOLEAN
 411   static const std::string SCROLL_PANNING_PROPERTY_NAME;                ///< Property, name "scroll-panning",            type BOOLEAN
 412   static const std::string SCROLL_SCROLLING_PROPERTY_NAME;              ///< Property, name "scroll-scrolling",          type BOOLEAN
 413   static const std::string SCROLL_POSITION_DELTA_PROPERTY_NAME;         ///< Property, name "scroll-position-delta"      type VECTOR3
 414   static const std::string SCROLL_START_PAGE_POSITION_PROPERTY_NAME;    ///< Property, name "scroll-start-page-position" type VECTOR3
 415
 416   // Default settings
 417
 418   static const float DEFAULT_SLOW_SNAP_ANIMATION_DURATION;              ///< Default Drag-Release animation time.
 419   static const float DEFAULT_FAST_SNAP_ANIMATION_DURATION;              ///< Default Drag-Flick animation time.
 420   static const float DEFAULT_SNAP_OVERSHOOT_DURATION;                   ///< Default Overshoot snapping animation time.
 421   static const float DEFAULT_MAX_OVERSHOOT;                             ///< Default maximum allowed overshoot
 422
 423   static const float DEFAULT_AXIS_AUTO_LOCK_GRADIENT;                   ///< Default Axis-AutoLock gradient threshold. default is 0.36:1 (20 degrees)
 424   static const float DEFAULT_FRICTION_COEFFICIENT;                      ///< Default Friction Co-efficient. (in stage diagonals per second)
 425   static const float DEFAULT_FLICK_SPEED_COEFFICIENT;                   ///< Default Flick speed coefficient (multiples input touch velocity)
 426   static const float DEFAULT_MAX_FLICK_SPEED;                           ///< Default Maximum flick speed. (in stage diagonals per second)
 427
 428   //Signal Names
 429   static const char* const SIGNAL_SNAP_STARTED; ///< Name "snap-started"
 430
 431   /// Direction of transitions
 432   enum EDirectionFlag
 433   {
 434     DirectionFlagLeft               = 0x01,
 435     DirectionFlagRight              = 0x02,
 436     DirectionFlagUp                 = 0x04,
 437     DirectionFlagDown               = 0x08,
 438     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
 439     DirectionFlagTransitionOff      = 0x20,
 440     DirectionFlagMask_Direction     = DirectionFlagLeft | DirectionFlagRight | DirectionFlagUp | DirectionFlagDown,
 441     DirectionFlagMask_Transition    = DirectionFlagTransitionOn | DirectionFlagTransitionOff
 442   };
 443
 444 public:
 445
 446   /**
 447    * @brief Snap signal event's data.
 448    */
 449   struct SnapEvent
 450   {
 451     SnapType type;    ///< Current snap commencing
 452     Vector3 position; ///< Target snap position
 453     Vector3 scale;    ///< Target snap scale
 454     float rotation;   ///< Target snap rotation
 455     float duration;   ///< Duration of snap animation.
 456   };
 457
 458   typedef SignalV2< void ( const SnapEvent& ) > SnapStartedSignalV2; ///< SnapStarted signal type
 459
 460   /**
 461    * @brief Signal emitted when the ScrollView has started to snap or flick (it tells the target
 462    * position, scale, rotation for the snap or flick)
 463    */
 464   SnapStartedSignalV2& SnapStartedSignal();
 465
 466 public:
 467
 468   /**
 469    * @brief Creates an empty ScrollView handle.
 470    */
 471   ScrollView();
 472
 473   /**
 474    * @brief Copy constructor.
 475    *
 476    * Creates another handle that points to the same real object
 477    *
 478    * @param[in] handle to copy from
 479    */
 480   ScrollView( const ScrollView& handle );
 481
 482   /**
 483    * @brief Assignment operator.
 484    *
 485    * Changes this handle to point to another real object
 486    * @param[in] handle The handle to copy from
 487    * @return A reference to this
 488    */
 489   ScrollView& operator=( const ScrollView& handle );
 490
 491   /**
 492    * @brief Virtual destructor.
 493    *
 494    * Dali::Object derived classes typically do not contain member data.
 495    */
 496   virtual ~ScrollView();
 497
 498   /**
 499    * @brief Create an initialized ScrollView.
 500    *
 501    * @return A handle to a newly allocated Dali resource.
 502    */
 503   static ScrollView New();
 504
 505   /**
 506    * @brief Downcast an Object handle to ScrollView.
 507    *
 508    * If handle points to a ScrollView the downcast produces valid
 509    * handle. If not the returned handle is left uninitialized.
 510    *
 511    * @param[in] handle Handle to an object
 512    * @return handle to a ScrollView or an uninitialized handle
 513    */
 514   static ScrollView DownCast( BaseHandle handle );
 515
 516 public:
 517
 518   /**
 519    * @brief Get snap-animation's AlphaFunction.
 520    *
 521    * @return Current easing alpha function of the snap animation.
 522    */
 523   AlphaFunction GetScrollSnapAlphaFunction() const;
 524
 525   /**
 526    * @brief Set snap-animation's AlphaFunction.
 527    *
 528    * @param[in] alpha Easing alpha function of the snap animation.
 529    */
 530   void SetScrollSnapAlphaFunction(AlphaFunction alpha);
 531
 532   /**
 533    * @brief Get flick-animation's AlphaFunction.
 534    *
 535    * @return Current easing alpha function of the flick animation.
 536    */
 537   AlphaFunction GetScrollFlickAlphaFunction() const;
 538
 539   /**
 540    * @brief Set flick-animation's AlphaFunction.
 541    *
 542    * @param[in] alpha Easing alpha function of the flick animation.
 543    */
 544   void SetScrollFlickAlphaFunction(AlphaFunction alpha);
 545
 546   /**
 547    * @brief Gets the time for the scroll snap-animation.
 548    *
 549    * This animation occurs when the user drags, and releases.
 550    *
 551    * @return The time in seconds for the animation to take.
 552    */
 553   float GetScrollSnapDuration() const;
 554
 555   /**
 556    * @brief Sets the time for the scroll snap-animation.
 557    *
 558    * This animation occurs when the user drags, and releases.
 559    *
 560    * @param[in] time The time in seconds for the animation to take.
 561    */
 562   void SetScrollSnapDuration(float time);
 563
 564   /**
 565    * @brief Gets the time for the scroll flick-animation.
 566    *
 567    * This animation occurs when the user flicks scroll view.
 568    *
 569    * @return The time in seconds for the animation to take.
 570    */
 571   float GetScrollFlickDuration() const;
 572
 573   /**
 574    * @brief Sets the time for the scroll flick-animation.
 575    *
 576    * This animation occurs when the user flicks scroll view.
 577    *
 578    * @param[in] time The time in seconds for the animation to take.
 579    */
 580   void SetScrollFlickDuration(float time);
 581
 582   /**
 583    * @brief Set X axis ruler.
 584    *
 585    * Defines how scrolling horizontally is snapped, and
 586    * the boundary (domain) in which the ScrollView can pan.
 587    *
 588    * @param[in] ruler The ruler to be used for the X axis
 589    */
 590   void SetRulerX(RulerPtr ruler);
 591
 592   /**
 593    * @brief Set Y axis ruler.
 594    *
 595    * Defines how scrolling vertically is snapped, and the boundary
 596    * (domain) in which the ScrollView can pan.
 597    *
 598    * @param[in] ruler The ruler to be used for the Y axis
 599    */
 600   void SetRulerY(RulerPtr ruler);
 601
 602   /**
 603    * @brief Set Scale-X axis ruler.
 604    *
 605    * Defines how scaling horizontally is snapped, and the extent
 606    * (domain) to which scaling can be performed e.g. 10% to 200%
 607    *
 608    * @param[in] ruler The ruler to be used for the Scale-X axis
 609    */
 610   void SetRulerScaleX(RulerPtr ruler);
 611
 612   /**
 613    * @brief Set Scale-Y axis ruler.
 614    *
 615    * Defines how scaling vertically is snapped, and the extent
 616    * (domain) to which scaling can be performed e.g. 10% to 200%
 617    *
 618    * @param[in] ruler The ruler to be used for the Scale-Y axis
 619    */
 620   void SetRulerScaleY(RulerPtr ruler);
 621
 622   /**
 623    * @brief Set Scroll's touch sensitivity.
 624    *
 625    * @note Unlike SetSensitive(), this determines whether this ScrollView
 626    * should react (e.g. pan), without disrupting the sensitivity of it's children.
 627    *
 628    * @param[in] sensitive true to enable scroll, false to disable scrolling
 629    */
 630   void SetScrollSensitive(bool sensitive);
 631
 632   /**
 633    * @brief Set maximum overshoot amount.
 634    *
 635    * The final overshoot value is within 0.0f to 1.0f, but the maximum
 636    * overshoot is in pixels (e.g. if you scroll 75 pixels beyond the
 637    * edge of a scrollable area and the maximum overshoot is 100 then
 638    * the final overshoot value will be 0.75f)
 639    *
 640    * @param[in] overshootX the maximum number of horizontally scrolled pixels before overshoot X reaches 1.0f
 641    * @param[in] overshootY the maximum number of vertically scrolled pixels before overshoot Y reaches 1.0f
 642    */
 643   void SetMaxOvershoot(float overshootX, float overshootY);
 644
 645   /**
 646    * @brief Set Snap Overshoot animation's AlphaFunction.
 647    *
 648    * @param[in] alpha Easing alpha function of the overshoot snap animation.
 649    */
 650   void SetSnapOvershootAlphaFunction(AlphaFunction alpha);
 651
 652   /**
 653    * @brief Set Snap Overshoot animation's Duration.
 654    *
 655    * @note Set duration to 0 seconds, to disable Animation.
 656    *
 657    * @param[in] duration The duration of the overshoot snap animation.
 658    */
 659   void SetSnapOvershootDuration(float duration);
 660
 661   /**
 662    * @brief Sets Touches required for pan gestures.
 663    *
 664    * Panning requires number of touches to be within (minTouches) and
 665    * (maxTouches).
 666    *
 667    * If (endOutside) is true, then outside this range of touches,
 668    * the pan gesture will end and thus will snap.
 669    *
 670    * If (endOutside) is false, then outside this range of touches,
 671    * the pan gesture will pause. but will not end until touches = 0.
 672    *
 673    * @param[in] minTouches Minimum touches for panning to occur.
 674    * @param[out] maxTouches Maxiumum touches for panning to occur.
 675    * @param[in] endOutside Whether to end the panning gesture outside of touch range
 676    */
 677   void SetTouchesRequiredForPanning(unsigned int minTouches = 1, unsigned int maxTouches = 1, bool endOutside = true);
 678
 679   /**
 680    * @brief Enables or Disables Actor Auto-Snap mode.
 681    *
 682    * When Actor Auto-Snap mode has been enabled, ScrollView will automatically
 683    * snap to the closest actor (The closest actor will appear in the center of
 684    * the ScrollView).
 685    *
 686    * @param[in] enable Enables (true), or disables (false) Actor AutoSnap
 687    */
 688   void SetActorAutoSnap(bool enable);
 689
 690   /**
 691    * @brief Enables or Disables Wrap mode for ScrollView contents.
 692    *
 693    * When enabled, the ScrollView contents are wrapped over the X/Y Domain.
 694    *
 695    * @note You must apply a position constraint that causes Wrapping
 696    * to all children.
 697    *
 698    * @param[in] enable Enables (true), or disables (false) Wrap Mode.
 699    */
 700   void SetWrapMode(bool enable);
 701
 702   /**
 703    * @brief Gets the current refresh interval in milliseconds.
 704    *
 705    * @return Current refresh interval in milliseconds
 706    */
 707   int GetRefreshInterval() const;
 708
 709   /**
 710    * @brief Sets the refresh interval in milliseconds.
 711    *
 712    * The refresh interval is a notification signal
 713    * (SignalScrollUpdate), that is periodically fired when scrolling
 714    * animation is occuring.
 715    *
 716    * When set to 0. No update signals are sent.
 717    *
 718    * @param[in] milliseconds The frequency of the event in milliseconds
 719    */
 720   void SetRefreshInterval(int milliseconds);
 721
 722   /**
 723    * @brief Returns state of Axis Auto Lock mode.
 724    *
 725    * @return Whether Axis Auto Lock mode has been enabled or not.
 726    */
 727   bool GetAxisAutoLock() const;
 728
 729   /**
 730    * @brief Enables or Disables Axis Auto Lock mode for panning within the ScrollView.
 731    *
 732    * When enabled, any pan gesture that appears mostly horizontal or mostly
 733    * vertical, will be automatically restricted to horizontal only or vertical
 734    * only panning, until the pan gesture has completed.
 735    *
 736    * @param[in] enable Enables (true), or disables (false) AxisAutoLock mode.
 737    */
 738   void SetAxisAutoLock(bool enable);
 739
 740   /**
 741    * @brief Gets the gradient threshold at which a panning gesture
 742    * should be locked to the Horizontal or Vertical axis.
 743    *
 744    * @return The gradient, a value between 0.0 and 1.0f.
 745    */
 746   float GetAxisAutoLockGradient() const;
 747
 748   /**
 749    * @brief Sets the gradient threshold at which a panning gesture should be locked to the
 750    * Horizontal or Vertical axis.
 751    *
 752    * By default this is 0.36 (0.36:1) which means angles less than 20
 753    * degrees to an axis will lock to that axis.
 754    *
 755    * @note: Specifying a value of 1.0 (the maximum value accepted) indicates that
 756    * all panning gestures will auto-lock. Either to the horizontal or vertical axis.
 757    *
 758    * @param[in] gradient A value between 0.0 and 1.0 (auto-lock for all angles)
 759    */
 760   void SetAxisAutoLockGradient(float gradient);
 761
 762   /**
 763    * @brief Gets the friction coefficient setting for ScrollView when
 764    * flicking in free panning mode.
 765    *
 766    * This is a value in stage-diagonals per second^2.
 767    * stage-diagonal = Length( stage.width, stage.height )
 768    * @return Friction coefficient is returned.
 769    */
 770   float GetFrictionCoefficient() const;
 771
 772   /**
 773    * @brief Sets the friction coefficient for ScrollView when flicking
 774    * in free panning mode.
 775    *
 776    * This is a value in stage-diagonals per second^2.
 777    * stage-diagonal = Length( stage.width, stage.height ).
 778    * example:
 779    * A stage 480x800 in size has a diagonal length of 933.
 780    * Friction coefficient of 1.0 means the swipe velocity will
 781    * reduce by 1.0 * 933 pixels/sec^2.
 782    * @param[in] friction Friction coefficient, must be greater than 0.0 (default = 1.0)
 783    */
 784   void SetFrictionCoefficient(float friction);
 785
 786   /**
 787    * @brief Gets the flick speed coefficient for ScrollView when
 788    * flicking in free panning mode.
 789    *
 790    * This is a constant which multiplies the input touch
 791    * flick velocity to determine the actual velocity at
 792    * which to move the scrolling area.
 793    * @return The flick speed coefficient is returned.
 794    */
 795   float GetFlickSpeedCoefficient() const;
 796
 797   /**
 798    * @brief Sets the flick speed coefficient for ScrollView when
 799    * flicking in free panning mode.
 800    *
 801    * This is a constant which multiplies the input touch
 802    * flick velocity to determine the actual velocity at
 803    * which to move the scrolling area.
 804    * @param[in] speed The flick speed coefficient (default = 1.0).
 805    */
 806   void SetFlickSpeedCoefficient(float speed);
 807
 808   /**
 809    * @brief Gets the maximum flick speed setting for ScrollView when
 810    * flicking in free panning mode.
 811    *
 812    * This is a value in stage-diagonals per second.
 813    * stage-diagonal = Length( stage.width, stage.height )
 814    * @return Maximum flick speed is returned
 815    */
 816   float GetMaxFlickSpeed() const;
 817
 818   /**
 819    * @brief Sets the maximum flick speed for the ScrollView when
 820    * flicking in free panning mode.
 821    *
 822    * This is a value in stage-diagonals per second.
 823    * stage-diagonal = Length( stage.width, stage.height )
 824    * example:
 825    * A stage 480x800 in size has a diagonal length of 933.
 826    * Max Flick speed of 1.0 means the maximum velocity of
 827    * a swipe can be 1.0 * 933 pixels/sec.
 828    * @param[in] speed Maximum flick speed (default = 3.0)
 829    */
 830   void SetMaxFlickSpeed(float speed);
 831
 832   /**
 833    * @brief Gets the step of scroll distance in actor coordinates for
 834    * each mouse wheel event received in free panning mode.
 835    *
 836    * @return The step of scroll distance(pixel) in X and Y axes.
 837    */
 838   Vector2 GetMouseWheelScrollDistanceStep() const;
 839
 840   /**
 841    * @brief Sets the step of scroll distance in actor coordinates for
 842    * each mouse wheel event received in free panning mode.
 843    *
 844    * @param[in] step The step of scroll distance(pixel) in X and Y axes.
 845    *
 846    * @note: If snap points are defined in the rulers, it will always
 847    * scroll to the next snap point towards the scroll direction while
 848    * receiving the mouse wheel events.
 849    *
 850    */
 851   void SetMouseWheelScrollDistanceStep(Vector2 step);
 852
 853   /**
 854    * @brief Retrieves current scroll position.
 855    *
 856    * @returns The current scroll position.
 857    */
 858   Vector3 GetCurrentScrollPosition() const;
 859
 860   /**
 861    * @brief Retrieves current scroll scale.
 862    *
 863    * @returns The current scroll scale.
 864    */
 865   Vector3 GetCurrentScrollScale() const;
 866
 867   /**
 868    * @brief Retrieves current scroll page based on ScrollView
 869    * dimensions being the size of one page, and all pages laid out in
 870    * a grid fashion, increasing from left to right until the end of
 871    * the X-domain.
 872    *
 873    * @note: Pages start from 0 as the first page, not 1.
 874    *
 875    * @returns The Current page.
 876    */
 877   unsigned int GetCurrentPage() const;
 878
 879   /**
 880    * @brief Transforms View to position, scale and rotation specified.
 881    *
 882    * @param[in] position The position to transform to.
 883    * @param[in] scale The scale to transform to.
 884    * @param[in] rotation The rotation to transform to.
 885    */
 886   void TransformTo(const Vector3& position, const Vector3& scale, float rotation);
 887
 888   /**
 889    * @brief Transforms View to position, scale and rotation specified.
 890    *
 891    * @param[in] position The position to transform to.
 892    * @param[in] scale The scale to transform to.
 893    * @param[in] rotation The rotation to transform to.
 894    * @param[in] duration The duration for this animation in seconds.
 895    */
 896   void TransformTo(const Vector3& position, const Vector3& scale, float rotation, float duration);
 897
 898   /**
 899    * @brief Scrolls View to position specified (contents will scroll to this position).
 900    *
 901    * Position 0,0 is the origin. Increasing X scrolls contents left, while
 902    * increasing Y scrolls contents up.
 903    * - If Rulers have been applied to the axes, then the contents will scroll until
 904    * reaching the domain boundary.
 905    * @note Contents will not snap to ruler snap points.
 906    *
 907    * @param[in] position The position to scroll to.
 908    */
 909   void ScrollTo(const Vector3 &position);
 910
 911   /**
 912    * @brief Scrolls View to position specified (contents will scroll to this position).
 913    *
 914    * Position 0,0 is the origin. Increasing X scrolls contents left, while
 915    * increasing Y scrolls contents up.
 916    * - If Rulers have been applied to the axes, then the contents will scroll until
 917    * reaching the domain boundary.
 918    * @note Contents will not snap to ruler snap points.
 919    *
 920    * @param[in] position The position to scroll to.
 921    * @param[in] duration The duration of the animation in seconds
 922    */
 923   void ScrollTo(const Vector3 &position, float duration);
 924
 925   /**
 926    * @brief Scrolls View to position specified (contents will scroll to this position).
 927    *
 928    * Position 0,0 is the origin. Increasing X scrolls contents left, while
 929    * increasing Y scrolls contents up.
 930    * - If Rulers have been applied to the axes, then the contents will scroll until
 931    * reaching the domain boundary.
 932    * @note Contents will not snap to ruler snap points.
 933    * Biasing parameters are provided such that in scenarios with 2 or 2x2 pages in
 934    * wrap mode, the application developer can decide whether to scroll left or right
 935    * to get to the target page
 936    *
 937    * @param[in] position The position to scroll to.
 938    * @param[in] duration The duration of the animation in seconds
 939    * @param[in] horizontalBias Whether to bias scrolling to left or right.
 940    * @param[in] verticalBias Whether to bias scrolling to top or bottom.
 941    */
 942   void ScrollTo(const Vector3 &position, float duration,
 943                 DirectionBias horizontalBias, DirectionBias verticalBias);
 944
 945   /**
 946    * @brief Scrolls View to page currently based on assumption that each page is
 947    * "(page) * ScrollViewSize.width, 0".
 948    *
 949    * @note Should probably be upgraded so that page is an abstract class, that can be
 950    * a function of ScrollViewSize, ruler domain, ruler snap points etc. as pages may be
 951    * orchestrated in a 2D grid fashion, or variable width.
 952    *
 953    * @param[in] page to scroll to
 954    */
 955   void ScrollTo(unsigned int page);
 956
 957   /**
 958    * @brief Scrolls View to page currently based on assumption that each page is
 959    * "(page) * ScrollViewSize.width, 0".
 960    *
 961    * @note Should probably be upgraded so that page is an abstract class, that can be
 962    * a function of ScrollViewSize, ruler domain, ruler snap points etc. as pages may be
 963    * orchestrated in a 2D grid fashion, or variable width.
 964    *
 965    * @param[in] page to scroll to
 966    * @param[in] duration The duration of the animation in seconds
 967    */
 968   void ScrollTo(unsigned int page, float duration);
 969
 970   /**
 971    * @brief Scrolls View to page currently based on assumption that each page is
 972    * "(page) * ScrollViewSize.width, 0".
 973    *
 974    * @note Should probably be upgraded so that page is an abstract class, that can be
 975    * a function of ScrollViewSize, ruler domain, ruler snap points etc. as pages may be
 976    * orchestrated in a 2D grid fashion, or variable width.
 977    * A biasing parameter is provided such that in scenarios with 2 pages in wrap mode,
 978    * the application developer can decide whether to scroll left or right to get to
 979    * the target page.
 980    *
 981    * @param[in] page to scroll to
 982    * @param[in] duration The duration of the animation in seconds
 983    * @param[in] bias Whether to bias scrolling to left or right.
 984    */
 985   void ScrollTo(unsigned int page, float duration, DirectionBias bias);
 986
 987   /**
 988    * @brief Scrolls View such that actor appears in the center of the ScrollView.
 989    *
 990    * @note Actor must be a direct child of ScrollView, otherwise will
 991    * cause an assertion failure.
 992    * @param[in] actor The actor to center in on (via Scrolling).
 993    */
 994   void ScrollTo(Actor& actor);
 995
 996   /**
 997    * @brief Scrolls View such that actor appears in the center of the ScrollView.
 998    *
 999    * @note Actor must be a direct child of ScrollView, otherwise will
1000    * cause an assertion failure.
1001    * @param[in] actor The actor to center in on (via Scrolling).
1002    * @param[in] duration The duration of the animation in seconds
1003    */
1004   void ScrollTo(Actor& actor, float duration);
1005
1006   /**
1007    * @brief Scrolls View to the nearest snap points as specified by the Rulers.
1008    *
1009    * If already at snap points, then will return false, and not scroll.
1010    *
1011    * @return True if Snapping necessary.
1012    */
1013   bool ScrollToSnapPoint();
1014
1015   /**
1016    * @brief Scales View to (scale).
1017    *
1018    * @param[in] scale The scale factor the animate to.
1019    */
1020   void ScaleTo(const Vector3& scale);
1021
1022   /**
1023    * @brief Scales View to (scale).
1024    *
1025    * @param[in] scale The scale factor the animate to.
1026    * @param[in] duration The duration of the animation in seconds.
1027    */
1028   void ScaleTo(const Vector3& scale, float duration);
1029
1030   /**
1031    * @brief Applies a constraint that will affect the children of ScrollView.
1032    *
1033    * @note this affects all existing and future Actors that are added to scrollview.
1034    * @param[in] constraint The constraint to apply
1035    */
1036   void ApplyConstraintToChildren(Constraint constraint);
1037
1038   /**
1039    * @brief Removes all constraints that will affect the children of ScrollView.
1040    *
1041    * @note this removes all constraints from actors that have been added
1042    * to scrollview.
1043    */
1044   void RemoveConstraintsFromChildren();
1045
1046   /**
1047    * @brief Apply Effect to ScrollView.
1048    *
1049    * @param[in] effect The effect to apply to scroll view
1050    */
1051   void ApplyEffect(ScrollViewEffect effect);
1052
1053   /**
1054    * @brief ApplyEffect Applies a predefined effect.
1055    *
1056    * @param[in] effect enum for the predefined effect
1057    * @return The scrollview effect that was applied
1058    */
1059   ScrollViewEffect ApplyEffect(ScrollView::PageEffect effect);
1060
1061   /**
1062    * @brief Remove Effect from ScrollView.
1063    *
1064    * @param[in] effect The effect to remove.
1065    */
1066   void RemoveEffect(ScrollViewEffect effect);
1067
1068   /**
1069    * @brief Remove All Effects from ScrollView.
1070    */
1071   void RemoveAllEffects();
1072
1073   /**
1074    * @brief Binds actor to this ScrollView.
1075    *
1076    * Once an actor is bound to a ScrollView, it will be subject to
1077    * that ScrollView's properties.
1078    *
1079    * @param[in] child The actor to add to this ScrollView.
1080    */
1081   void BindActor(Actor child);
1082
1083   /**
1084    * @brief Unbind Actor from this ScrollView.
1085    *
1086    * Once Unbound, this ScrollView will not affect the actor.
1087    * @note this does not remove the child from the ScrollView container
1088    *
1089    * @param[in] child The actor to be unbound.
1090    */
1091   void UnbindActor(Actor child);
1092
1093   /**
1094    * @brief Allows the user to constrain the scroll view in a particular direction.
1095    *
1096    * @param[in] direction The axis to constrain the scroll-view to.
1097    *                      Usually set to PanGestureDetector::DIRECTION_VERTICAL or PanGestureDetector::DIRECTION_HORIZONTAL (but can be any other angle if desired).
1098    * @param[in] threshold The threshold to apply around the axis.
1099    * @note If no threshold is specified, then the default threshold of PI * 0.25 radians (or 45 degrees) is used.
1100    */
1101   void SetScrollingDirection( Radian direction, Radian threshold = PanGestureDetector::DEFAULT_THRESHOLD );
1102
1103   /**
1104    * @brief Remove a direction constraint from the scroll view.
1105    *
1106    * @param[in] direction The axis to stop constraining to.
1107    *                      Usually will be PanGestureDetector::DIRECTION_VERTICAL or PanGestureDetector::DIRECTION_HORIZONTAL (but can be any other angle if desired).
1108    */
1109   void RemoveScrollingDirection( Radian direction );
1110
1111 public: // Not intended for application developers
1112
1113   /**
1114    * @brief Creates a handle using the Toolkit::Internal implementation.
1115    *
1116    * @param[in]  implementation  The Control implementation.
1117    */
1118   ScrollView(Internal::ScrollView& implementation);
1119
1120   /**
1121    * @brief Allows the creation of this Control from an Internal::CustomActor pointer.
1122    *
1123    * @param[in]  internal  A pointer to the internal CustomActor.
1124    */
1125   ScrollView( Dali::Internal::CustomActor* internal );
1126 };
1127
1128 } // namespace Toolkit
1129
1130 } // namespace Dali
1131
1132 /**
1133  * @}
1134  */
1135 #endif // __DALI_TOOLKIT_SCROLL_VIEW_H__