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

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