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