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