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

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