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