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