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