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