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