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