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