dali-toolkit/internal/controls/scrollable/scroll-view/scroll-view-impl.h

   1 #ifndef DALI_TOOLKIT_INTERNAL_SCROLL_VIEW_H
   2 #define DALI_TOOLKIT_INTERNAL_SCROLL_VIEW_H
   3
   4 /*
   5  * Copyright (c) 2020 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/adaptor-framework/timer.h>
  23 #include <dali/public-api/animation/animation.h>
  24 #include <dali/public-api/object/property-notification.h>
  25 #include <dali/public-api/object/weak-handle.h>
  26
  27 // INTERNAL INCLUDES
  28 #include <dali-toolkit/public-api/controls/control-impl.h>
  29 #include <dali-toolkit/devel-api/controls/scroll-bar/scroll-bar.h>
  30 #include <dali-toolkit/internal/controls/scrollable/scroll-view/scroll-base-impl.h>
  31 #include <dali-toolkit/public-api/controls/scrollable/scroll-view/scroll-view.h>
  32 #include <dali-toolkit/public-api/controls/scrollable/scroll-view/scroll-view-effect.h>
  33
  34 namespace Dali
  35 {
  36
  37 namespace Toolkit
  38 {
  39
  40 namespace Internal
  41 {
  42
  43 class ScrollView;
  44 typedef IntrusivePtr<ScrollView>    ScrollViewPtr;
  45
  46 class ScrollInternalConstraints;
  47 typedef IntrusivePtr<ScrollInternalConstraints>    ScrollInternalConstraintsPtr;
  48
  49 class ScrollOvershootIndicator;
  50 typedef IntrusivePtr<ScrollOvershootIndicator> ScrollOvershootIndicatorPtr;
  51
  52 /**
  53  * @copydoc Toolkit::ScrollView
  54  */
  55 class ScrollView : public ScrollBase
  56 {
  57 public:
  58
  59   /**
  60    * FindDirection specifies how searching is conducted within the Find... routines.
  61    */
  62   enum FindDirection
  63   {
  64     None = -3,        ///< Includes none within the search query.
  65     All = -2,         ///< Includes all within the search query.
  66     Left = -1,        ///< Includes only those not right !(>)
  67     Right = 1,        ///< Includes only those right (>)
  68     Up = -1,          ///< Includes only those not below  !(>)
  69     Down = 1,         ///< Includes only those below (>)
  70     Out = -1,         ///< Includes only those not infront  !(>)
  71     In = 1            ///< Includes only those infront (>)
  72   };
  73
  74   enum LockAxis
  75   {
  76     LockPossible = 0, ///< Locking is possible, but not set in stone yet.
  77     LockHorizontal,   ///< Locking is set to horizontal. (can pan vertically)
  78     LockVertical,     ///< Locking is set to vertical. (can pan horizontally)
  79     LockNone          ///< Locking is set to none (free panning).
  80   };
  81
  82   enum ScrollStateFlag
  83   {
  84     AnimatingInternalX = 0x01, ///< animating mPropertyX due to externally requested ScrollTo or internal snapping operation
  85     AnimatingInternalY = 0x02, ///< animating mPropertyY due to externally requested ScrollTo or internal snapping operation
  86     SnappingInternalX  = 0x04, ///< snapping mPropertyX back to mPropertyPreScroll x value to remove x overshoot over time
  87     SnappingInternalY  = 0x08, ///< snapping mPropertyY back to mPropertyPreScroll y value to remove y overshoot over time
  88   };
  89
  90   static const unsigned int SCROLL_X_STATE_MASK = AnimatingInternalX | SnappingInternalX;
  91   static const unsigned int SCROLL_Y_STATE_MASK = AnimatingInternalY | SnappingInternalY;
  92   static const unsigned int SCROLL_ANIMATION_FLAGS = AnimatingInternalX | AnimatingInternalY;
  93   static const unsigned int SNAP_ANIMATION_FLAGS = SnappingInternalX | SnappingInternalY;
  94
  95 private:
  96
  97   typedef std::vector<Dali::Toolkit::ScrollViewEffect> ScrollViewEffectContainer; ///< Container of Dali::Toolkit::ScrollViewEffect
  98   typedef ScrollViewEffectContainer::iterator ScrollViewEffectIter; ///< Iterator for Dali::Toolkit::ScrollViewEffectContainer
  99
 100 public:
 101
 102   /**
 103    * Create a new ScrollView.
 104    * @return A public handle to the newly allocated ScrollView.
 105    */
 106   static Dali::Toolkit::ScrollView New();
 107
 108 public:
 109
 110   /**
 111    * @copydoc Toolkit::ScrollView::GetScrollSnapAlphaFunction
 112    */
 113   AlphaFunction GetScrollSnapAlphaFunction() const;
 114
 115   /**
 116    * @copydoc Toolkit::ScrollView::SetScrollSnapAlphaFunction
 117    */
 118   void SetScrollSnapAlphaFunction(AlphaFunction alpha);
 119
 120   /**
 121    * @copydoc Toolkit::ScrollView::GetScrollFlickAlphaFunction
 122    */
 123   AlphaFunction GetScrollFlickAlphaFunction() const;
 124
 125   /**
 126    * @copydoc Toolkit::ScrollView::SetScrollFlickAlphaFunction
 127    */
 128   void SetScrollFlickAlphaFunction(AlphaFunction alpha);
 129
 130   /**
 131    * @copydoc Toolkit::ScrollView::GetScrollSnapDuration
 132    */
 133   float GetScrollSnapDuration() const;
 134
 135   /**
 136    * @copydoc Toolkit::ScrollView::SetScrollSnapDuration
 137    */
 138   void SetScrollSnapDuration(float time);
 139
 140   /**
 141    * @copydoc Toolkit::ScrollView::GetScrollFlickDuration
 142    */
 143   float GetScrollFlickDuration() const;
 144
 145   /**
 146    * @copydoc Toolkit::ScrollView::SetScrollFlickDuration
 147    */
 148   void SetScrollFlickDuration(float time);
 149
 150   /**
 151    * @copydoc Toolkit::ScrollView::ApplyEffect
 152    */
 153   void ApplyEffect(Toolkit::ScrollViewEffect effect);
 154
 155   /**
 156    * @copydoc Toolkit::ScrollView::RemoveEffect
 157    */
 158   void RemoveEffect(Toolkit::ScrollViewEffect effect);
 159
 160   /**
 161    * @copydoc Toolkit::ScrollView::RemoveAllEffects
 162    */
 163   void RemoveAllEffects();
 164
 165   /**
 166    * @copydoc Toolkit::ScrollView::ApplyConstraintToChildren
 167    */
 168   void ApplyConstraintToChildren(Constraint constraint);
 169
 170   /**
 171    * @copydoc Toolkit::ScrollView::RemoveConstraintsFromChildren
 172    */
 173   void RemoveConstraintsFromChildren();
 174
 175   /**
 176    * @copydoc Toolkit::ScrollView::GetRulerX
 177    */
 178   const RulerPtr GetRulerX() const;
 179
 180   /**
 181    * @copydoc Toolkit::ScrollView::GetRulerY
 182    */
 183   const RulerPtr GetRulerY() const;
 184
 185   /**
 186    * @copydoc Toolkit::ScrollView::SetRulerX
 187    */
 188   void SetRulerX(RulerPtr ruler);
 189
 190   /**
 191    * @copydoc Toolkit::ScrollView::SetRulerY
 192    */
 193   void SetRulerY(RulerPtr ruler);
 194
 195   /**
 196    * Retrieve the touch sensitivity.
 197    *
 198    * @return whether the touch sensitivity is true or false.
 199    */
 200   bool GetScrollSensitive();
 201
 202   /**
 203    * @copydoc Toolkit::ScrollView::SetScrollSensitive
 204    */
 205   void SetScrollSensitive(bool sensitive);
 206
 207   /**
 208    * @copydoc Toolkit::ScrollView::SetMaxOvershoot
 209    */
 210   void SetMaxOvershoot(float overshootX, float overshootY);
 211
 212   /**
 213    * @copydoc Toolkit::ScrollView::SetSnapOvershootAlphaFunction
 214    */
 215   void SetSnapOvershootAlphaFunction(AlphaFunction alpha);
 216
 217   /**
 218    * Retrieve the duartion of Snap Overshoot animation
 219    *
 220    * @return the duration.
 221    */
 222   float GetSnapOvershootDuration();
 223
 224   /**
 225    * @copydoc Toolkit::ScrollView::SetSnapOvershootDuration
 226    */
 227   void SetSnapOvershootDuration(float duration);
 228
 229   /**
 230    * Retrieve whether Actor Auto-Snap mode is enabled or not.
 231    *
 232    * @return Actor Auto-Snap mode Enabled flag.
 233    */
 234   bool GetActorAutoSnap();
 235
 236   /**
 237    * @copydoc Toolkit::ScrollView::SetActorAutoSnap
 238    */
 239   void SetActorAutoSnap(bool enable);
 240
 241   /**
 242    * Enables or Disables Auto Resizing mode for ScrollView contents.
 243    *
 244    * When enabled, the ScrollView's X/Y Domains are restricted to the
 245    * dimensions of the content's bounds, which may change as Actors are
 246    * Added/Removed, and repositioned.
 247    *
 248    * @note This has been disabled for now, as this requires some fundamental
 249    * changes to the way Actors positions and bounds are retrieved.
 250    * (currently only constraints have these initial state knowledge)
 251    *
 252    * @param[in] enable Enables (true), or disables (false) Auto Resize.
 253    */
 254   void SetAutoResize(bool enable);
 255
 256   /**
 257    * Returns whether the wrap mode has been enabled (true) or not (false).
 258    *
 259    * @return Wrap Mode Enabled flag.
 260    */
 261   bool GetWrapMode() const;
 262
 263   /**
 264    * @copydoc Toolkit::ScrollView::SetWrapMode
 265    */
 266   void SetWrapMode(bool enable);
 267
 268   /**
 269    * @copydoc Toolkit::ScrollView::GetScrollupdateDistance
 270    */
 271   int GetScrollUpdateDistance() const;
 272
 273   /**
 274    * @copydoc Toolkit::ScrollView::SetScrollUpdateDistance
 275    */
 276   void SetScrollUpdateDistance(int distance);
 277
 278   /**
 279    * @copydoc Toolkit::ScrollView::GetAxisAutoLock
 280    */
 281   bool GetAxisAutoLock() const;
 282
 283   /**
 284    * @copydoc Toolkit::ScrollView::SetAxisAutoLock
 285    */
 286   void SetAxisAutoLock(bool enable);
 287
 288   /**
 289    * @copydoc Toolkit::ScrollView::GetAxisAutoLockGradient
 290    */
 291   float GetAxisAutoLockGradient() const;
 292
 293   /**
 294    * @copydoc Toolkit::ScrollView::SetAxisAutoLockGradient
 295    */
 296   void SetAxisAutoLockGradient(float gradient);
 297
 298   /**
 299    * @copydoc Toolkit::ScrollView::GetFrictionCoefficient
 300    */
 301   float GetFrictionCoefficient() const;
 302
 303   /**
 304    * @copydoc Toolkit::ScrollView::SetFrictionCoefficient
 305    */
 306   void SetFrictionCoefficient(float friction);
 307
 308   /**
 309    * @copydoc Toolkit::ScrollView::GetFlickSpeedCoefficient
 310    */
 311   float GetFlickSpeedCoefficient() const;
 312
 313   /**
 314    * @copydoc Toolkit::ScrollView::SetFlickSpeedCoefficient
 315    */
 316   void SetFlickSpeedCoefficient(float speed);
 317
 318   /**
 319    * @copydoc Toolkit::ScrollView::GetMinimumDistanceForFlick
 320    */
 321   Vector2 GetMinimumDistanceForFlick() const;
 322
 323   /**
 324    * @copydoc Toolkit::ScrollView::SetMinimumDistanceForFlick
 325    */
 326   void SetMinimumDistanceForFlick( const Vector2& distance );
 327
 328   /**
 329    * @copydoc Toolkit::ScrollView::GetMinimumSpeedForFlick
 330    */
 331   float GetMinimumSpeedForFlick() const;
 332
 333   /**
 334    * @copydoc Toolkit::ScrollView::SetMinimumSpeedForFlick
 335    */
 336   void SetMinimumSpeedForFlick( float speed );
 337
 338   /**
 339    * @copydoc Toolkit::ScrollView::GetMaxFlickSpeed
 340    */
 341   float GetMaxFlickSpeed() const;
 342
 343   /**
 344    * @copydoc Toolkit::ScrollView::SetMaxFlickSpeed
 345    */
 346   void SetMaxFlickSpeed(float speed);
 347
 348   /**
 349    * @copydoc Toolkit::ScrollView::GetWheelScrollDistanceStep
 350    */
 351   Vector2 GetWheelScrollDistanceStep() const;
 352
 353   /**
 354    * @copydoc Toolkit::ScrollView::SetWheelScrollDistanceStep
 355    */
 356   void SetWheelScrollDistanceStep(Vector2 step);
 357
 358   /**
 359    * @copydoc Toolkit::ScrollView::GetCurrentPage
 360    */
 361   unsigned int GetCurrentPage() const;
 362
 363   /**
 364    * @copydoc Toolkit::ScrollView::GetCurrentScrollPosition
 365    */
 366   Vector2 GetCurrentScrollPosition() const;
 367
 368   /**
 369    * @copydoc ScrollTo(const Vector2&)
 370    */
 371   void TransformTo(const Vector2& position,
 372                    DirectionBias horizontalBias = DIRECTION_BIAS_NONE, DirectionBias verticalBias = DIRECTION_BIAS_NONE);
 373
 374   /**
 375    * @copydoc ScrollTo(const Vector2&, float, AlhpaFunction, DirectionBias, DirectionBias)
 376    */
 377   void TransformTo(const Vector2& position, float duration, AlphaFunction alpha,
 378                    DirectionBias horizontalBias = DIRECTION_BIAS_NONE, DirectionBias verticalBias = DIRECTION_BIAS_NONE);
 379
 380   /**
 381    * @copydoc Toolkit::ScrollView::ScrollTo(const Vector2 &position)
 382    */
 383   void ScrollTo(const Vector2 &position);
 384
 385   /**
 386    * @copydoc Toolkit::Scrollable::ScrollTo(const Vector2& position, float duration)
 387    */
 388   void ScrollTo(const Vector2& position, float duration);
 389
 390   /**
 391    * @copydoc Toolkit::Scrollable::ScrollTo(const Vector2& position, float duration, AlphaFunction alpha)
 392    */
 393   void ScrollTo(const Vector2& position, float duration, AlphaFunction alpha);
 394
 395   /**
 396    * @copydoc Toolkit::ScrollView::ScrollTo(const Vector2 &position, float duration, DirectionBias horizontalBias, DirectionBias verticalBias)
 397    */
 398   void ScrollTo(const Vector2& position, float duration,
 399                 DirectionBias horizontalBias, DirectionBias verticalBias);
 400
 401   /**
 402    * @copydoc Toolkit::ScrollView::ScrollTo(const Vector2 &position, float duration, AlphaFunction alpha, DirectionBias horizontalBias, DirectionBias verticalBias)
 403    */
 404   void ScrollTo(const Vector2& position, float duration, AlphaFunction alpha,
 405                 DirectionBias horizontalBias, DirectionBias verticalBias);
 406
 407   /**
 408    * @copydoc Toolkit::ScrollView::ScrollTo(unsigned int page)
 409    */
 410   void ScrollTo(unsigned int page);
 411
 412   /**
 413    * @copydoc Toolkit::ScrollView::ScrollTo(unsigned int page, float duration, DirectionBias bias)
 414    */
 415   void ScrollTo(unsigned int page, float duration, DirectionBias bias = DIRECTION_BIAS_NONE);
 416
 417   /**
 418    * @copydoc Toolkit::ScrollView::ScrollTo(Actor& actor)
 419    */
 420   void ScrollTo(Actor &actor);
 421
 422   /**
 423    * @copydoc Toolkit::ScrollView::ScrollTo(Actor& actor, float duration)
 424    */
 425   void ScrollTo(Actor &actor, float duration);
 426
 427   /**
 428    * @copydoc Toolkit::ScrollView::SetScrollingDirection()
 429    */
 430   void SetScrollingDirection( Radian direction, Radian threshold );
 431
 432   /**
 433    * @copydoc Toolkit::ScrollView::RemoveScrollingDirection()
 434    */
 435   void RemoveScrollingDirection( Radian angle );
 436
 437   /**
 438     * Finds the closest Actor to the current center of the ScrollView.
 439     *
 440     * @return A handle to the actor if found, or an empty handle if not.
 441     */
 442    Actor FindClosestActor();
 443
 444   /**
 445    * Finds the closest Actor to position in ScrollView
 446    *
 447    * @param[in] position position within ScrollView.
 448    * @param[in] dirX Whether to search only those elements that are Left,Right, or All
 449    * @param[in] dirY Whether to search only those elements that are Up,Down, or All
 450    * @param[in] dirZ Whether to search only those elements that are Out,In, or All
 451    * @return A handle to the actor if found, or an empty handle if not.
 452    */
 453   Actor FindClosestActorToPosition(const Vector3& position, FindDirection dirX = All, FindDirection dirY = All, FindDirection dirZ = All);
 454
 455   /**
 456    * @copydoc Toolkit::ScrollView::ScrollToSnapPoint
 457   */
 458   bool ScrollToSnapPoint();
 459
 460   /**
 461    * Stops animation
 462    */
 463   void StopAnimation(void);
 464
 465   /**
 466    * Stops the input animation
 467    *
 468    * @param[in] the animation to stop
 469    */
 470   void StopAnimation(Animation& animation);
 471
 472   /**
 473    * Animates to position transform.
 474    *
 475    * @param[in] position The position to animate to
 476    * @param[in] positionDuration The number of seconds this animation should run for in each axis.
 477    * @param[in] alpha The easing alpha function to use.
 478    * @param[in] findShortcuts (optional) Whether to find the shortest route (in Wrap mode)
 479    * @param[in] horizontalBias (optional) Whether to bias animation to left or right (or no biasing)
 480    * @param[in] verticalBias (optional) Whether to bias animation to top or bottom (or no biasing)
 481    * @return True if animation necessary and taking place to reach desired transform.
 482    */
 483   bool AnimateTo(const Vector2& position, const Vector2& positionDuration,
 484                              AlphaFunction alpha, bool findShortcuts = true,
 485                              DirectionBias horizontalBias = DIRECTION_BIAS_NONE, DirectionBias verticalBias = DIRECTION_BIAS_NONE,
 486                              SnapType snapType = SNAP);
 487
 488   /**
 489    * @copydoc Toolkit::Scrollable::AddOverlay()
 490    */
 491   void AddOverlay(Actor actor);
 492
 493   /**
 494    * @copydoc Toolkit::Scrollable::RemoveOverlay()
 495    */
 496   void RemoveOverlay(Actor actor);
 497
 498   /**
 499    * @copydoc Toolkit::Internal::Scrollable::SetOvershootSize
 500    */
 501   void SetOvershootSize( const Vector2& size );
 502
 503   /**
 504    * @copydoc Toolkit::Internal::Scrollable::SetOvershootEffectColor
 505    */
 506   void SetOvershootEffectColor( const Vector4& color );
 507
 508   //properties
 509
 510   /**
 511    * Called when a property of an object of this type is set.
 512    * @param[in] object The object whose property is set.
 513    * @param[in] index The property index.
 514    * @param[in] value The new property value.
 515    */
 516   static void SetProperty( BaseObject* object, Property::Index index, const Property::Value& value );
 517
 518   /**
 519    * Called to retrieve a property of an object of this type.
 520    * @param[in] object The object whose property is to be retrieved.
 521    * @param[in] index The property index.
 522    * @return The current value of the property.
 523    */
 524   static Property::Value GetProperty( BaseObject* object, Property::Index index );
 525
 526 public: //Signals
 527
 528   /**
 529    * @copydoc Dali::Toolkit::ScrollView::SnapStartedSignal()
 530    */
 531   Toolkit::ScrollView::SnapStartedSignalType& SnapStartedSignal();
 532
 533   /**
 534    * Connects a callback function with the object's signals.
 535    * @param[in] object The object providing the signal.
 536    * @param[in] tracker Used to disconnect the signal.
 537    * @param[in] signalName The signal to connect to.
 538    * @param[in] functor A newly allocated FunctorDelegate.
 539    * @return True if the signal was connected.
 540    * @post If a signal was connected, ownership of functor was passed to CallbackBase. Otherwise the caller is responsible for deleting the unused functor.
 541    */
 542   static bool DoConnectSignal( BaseObject* object, ConnectionTrackerInterface* tracker, const std::string& signalName, FunctorDelegate* functor );
 543
 544 private: // private overridden functions from CustomActorImpl and Controls
 545
 546   /**
 547    * @copydoc Dali::CustomActorImpl::OnSizeAnimation(Animation&, const Vector3&)
 548    */
 549   void OnSizeAnimation(Animation& animation, const Vector3& targetSize) override;
 550
 551   /**
 552    * @copydoc CustomActorImpl::OnSizeSet(const Vector3&)
 553    */
 554   void OnSizeSet( const Vector3& size ) override;
 555
 556   /**
 557    * From CustomActorImpl; called after a child has been added to the owning actor.
 558    * @param[in] child The child which has been added.
 559    */
 560   void OnChildAdd(Actor& child) override;
 561
 562   /**
 563    * From CustomActorImpl; called shortly before a child is removed from the owning actor.
 564    * @param[in] child The child being removed.
 565    */
 566   void OnChildRemove(Actor& child) override;
 567
 568   /**
 569    * Called after a wheelEvent is received by the owning actor.
 570    * @param[in] actor Actor associated with the event.
 571    * @param[in] event The wheel event.
 572    * @return True if the event should be consumed.
 573    */
 574   bool OnWheelEvent(Actor actor, const WheelEvent& event);
 575
 576   /**
 577    * @copydoc Toolkit::Control::OnInitialize()
 578    */
 579   void OnInitialize() override;
 580
 581   /**
 582    * @copydoc CustomActorImpl::OnSceneConnection()
 583    */
 584   void OnSceneConnection( int depth ) override;
 585
 586   /**
 587    * @copydoc CustomActorImpl::OnSceneDisconnection()
 588    */
 589   void OnSceneDisconnection() override;
 590
 591   /**
 592    * @copydoc Toolkit::Control::OnAccessibilityPan()
 593    */
 594   bool OnAccessibilityPan(PanGesture gesture) override;
 595
 596   /**
 597    * @copydoc Toolkit::Scrollable::EnableScrollOvershoot()
 598    */
 599   void EnableScrollOvershoot(bool enable) override;
 600
 601 private:
 602
 603   /**
 604    * Called after a touchSignal is received by the owning actor.
 605    *
 606    * We don't consume these events as content within the container may consume events.
 607    *
 608    * @param[in] actor The touched actor.
 609    * @param[in] touch The touch information.
 610    * @return True if the event should be consumed.
 611    */
 612   bool OnTouch( Actor actor, const TouchEvent& touch );
 613
 614   /**
 615    * Start a timer which calls OnTouchDownTimeout()
 616    */
 617   void StartTouchDownTimer();
 618
 619   /**
 620    * Stop a timer which calls OnTouchDownTimeout()
 621    */
 622   void StopTouchDownTimer();
 623
 624   /**
 625    * Helper to detect when touch-point has been down (outside of pan gesture)
 626    */
 627   bool OnTouchDownTimeout();
 628
 629   /**
 630    * Called whenever a snap animation has completed
 631    * @param[in] source the Animation instance that has completed.
 632    * Resets all scrolling animations and states, leaving current scroll position at SCROLL_POSITION
 633    */
 634   void ResetScrolling();
 635
 636   /**
 637    * Updates mScrollInternalPosition, mScrollPrePosition and mScrollPostPosition from their property counterparts
 638    */
 639   void UpdateLocalScrollProperties();
 640
 641   /**
 642    * Makes sure scroll values are ready for animated scrolling
 643    */
 644   void PreAnimatedScrollSetup();
 645
 646   /**
 647    * Finish an animated scroll, ensuring all scroll properties are updated
 648    * and synchronised
 649    */
 650   void FinaliseAnimatedScroll();
 651
 652   /**
 653    * Animates the internal x property to the given value
 654    *
 655    * @param[in] position The X position to animate to
 656    * @param[in] duration The time in seconds for animation
 657    * @param[in] alpha The alpha function to use for animating
 658    */
 659   void AnimateInternalXTo( float position, float duration, AlphaFunction alpha );
 660
 661   /**
 662    * Animates the internal y property to the given value
 663    *
 664    * @param[in] position The Y position to animate to
 665    * @param[in] duration The time in seconds for animation
 666    * @param[in] alpha The alpha function to use for animating
 667    */
 668   void AnimateInternalYTo( float position, float duration, AlphaFunction alpha );
 669
 670   /**
 671    * Called whenever a snap animation on the x-axis has completed
 672    * @param[in] source the Animation instance that has completed.
 673    */
 674   void OnScrollAnimationFinished( Animation& source );
 675
 676   /**
 677    * Called when either the X or Y internal scroll positions have finished snapping back to SCROLL_PRE_POSITION
 678    *
 679    * @param[in] source the Animation instance that has completed.
 680    */
 681   void OnSnapInternalPositionFinished( Animation& source );
 682
 683   /**
 684    * Called whenever a snap animation on the x-axis has completed and we need to snap pre scroll
 685    * position to our clamped position
 686    * @param[in] position The x position to snap pre scroll property to
 687    */
 688   void SnapInternalXTo( float position );
 689
 690   /**
 691    * Called whenever a snap animation on the y-axis has completed and we need to snap pre scroll
 692    * position to our clamped position
 693    * @param[in] position The y position to snap pre scroll property to
 694    */
 695   void SnapInternalYTo( float position );
 696
 697   /**
 698    * This is called internally whenever the Scroll Rulers are
 699    * modified. This will update the properties: 'scrollPositionMin'
 700    * and 'scrollPositionMax' to reflect the changes.
 701    */
 702   void UpdatePropertyDomain();
 703
 704   /**
 705    * Called when the gesture starts.
 706    */
 707   void GestureStarted();
 708
 709   /**
 710    * Amalgamated Gesture Continuing event
 711    *
 712    * @param[in] panDelta average panning delta from base position (0)
 713    */
 714   void GestureContinuing(const Vector2& panDelta);
 715
 716   /**
 717    * Called upon pan gesture event.
 718    *
 719    * @param[in] gesture The gesture event.
 720    */
 721   void OnPan( const PanGesture& pan);
 722
 723   /**
 724    * Extension of the above gestures.
 725    *
 726    * @param[in] gesture The gesture event.
 727    */
 728   void OnGestureEx(GestureState state);
 729
 730   /**
 731    * Performs snapping while taking into account Velocity of gesture
 732    * (velocity in pixels/sec)
 733    *
 734    * @param[in] velocity velocity in pixels/sec
 735    */
 736   bool SnapWithVelocity(Vector2 velocity);
 737
 738   /**
 739    * Finishes Container Transform
 740    * (occurs upon finishing gesture i.e. releasing)
 741    */
 742   void FinishTransform();
 743
 744   /**
 745    * Returns overshoot vector based on current position
 746    *
 747    * Overshoot vector is defined as how far outside of bounds
 748    * the viewport is trying to view (prior to being clamped).
 749    *
 750    * an overshoot of (100,50), means user is in bottom right corner,
 751    * trying to pan +100 to the right, and +50 below. This can be used
 752    * to determine an effect, such as stretching.
 753    *
 754    * @param[in] position The position for which you wish to obtain overshoot vector
 755    */
 756   Vector2 GetOvershoot(Vector2& position) const;
 757
 758   /**
 759    * Clamps position within the domain set up by X/Y Rulers
 760    *
 761    * @param[in,out] position The position you wish to clamp
 762    */
 763   void ClampPosition(Vector2& position) const;
 764
 765   /**
 766    * Clamps position within the domain set up by X/Y Rulers
 767    *
 768    * @param[in,out] position The position you wish to clamp
 769    * @param[out] clamped The results of the clamping.
 770    */
 771   void ClampPosition(Vector2& position, ClampState2D &clamped) const;
 772
 773   /**
 774    * Wraps position within the domain set up by X/Y Rulers
 775    *
 776    * @note Only wraps if mWrapMode is enabled, and respective domains
 777    * are enabled.
 778    *
 779    * @param[in,out] position The position you wish to wrap
 780    */
 781   void WrapPosition(Vector2& position) const;
 782
 783   /**
 784    * Updates the main internal scroll constraints with new ruler and domain
 785    * values
 786    */
 787   void UpdateMainInternalConstraint();
 788
 789   /**
 790    * Enables/disables the overshoot constraints
 791    *
 792    * @param[in] enabled whether to enable or disable the overshoot constraints
 793    */
 794   void SetOvershootConstraintsEnabled(bool enabled);
 795
 796   /**
 797    * Sets internal constraints for this ScrollView.
 798    * Many of these internal constraints are based on properties within
 799    * ScrollView.
 800    */
 801   void SetInternalConstraints();
 802
 803 protected:
 804
 805   /**
 806    * Construct a new ScrollView.
 807    */
 808   ScrollView();
 809
 810   /**
 811    * A reference counted object may only be deleted by calling Unreference()
 812    */
 813   virtual ~ScrollView();
 814
 815 private:
 816
 817   /**
 818    * Searches this ScrollView, and attempts to Unbind
 819    * systematically this Actor from the ScrollView attached.
 820    *
 821    * @param[in] child The actor to be unbound.
 822    */
 823   void FindAndUnbindActor(Actor child) override;
 824
 825   /**
 826    * Gets position property.
 827    *
 828    * @return The current position
 829    */
 830   Vector2 GetPropertyPrePosition() const;
 831
 832   /**
 833    * Gets position property.
 834    *
 835    * @return The current position
 836    */
 837   Vector2 GetPropertyPosition() const;
 838
 839   /**
 840    * Handles a Stopped animation. Its position properties need to be saved, and the animation flag
 841    * switched off.
 842    */
 843   void HandleStoppedAnimation();
 844
 845   /**
 846    * Handles a Stopped animation (whether the animation completed, or was
 847    * manually stopped). Its position properties need to be saved, and the
 848    * animation flag switched off.
 849    */
 850   void HandleSnapAnimationFinished();
 851
 852   /**
 853    * Checks if the property notifications are active and adds them if not
 854    */
 855   void SetScrollUpdateNotification( bool enabled );
 856
 857   /**
 858    * Refresh the ScrollView (used when animating to update application developer of changes)
 859    * @return True if the refresh timer should be kept running.
 860    */
 861   void OnScrollUpdateNotification(Dali::PropertyNotification& source);
 862
 863   /**
 864    * Set up default rulers using a property map
 865    * @param[in] scrollModeMap A map defining the characteristics of X and Y scrolling
 866    * using either FixedRuler or DefaultRuler.
 867    */
 868   void SetScrollMode( const Property::Map& scrollModeMap );
 869
 870 private:
 871
 872   // Undefined
 873   ScrollView(const ScrollView&);
 874
 875   // Undefined
 876   ScrollView& operator=(const ScrollView& rhs);
 877
 878 private:
 879
 880   unsigned long mTouchDownTime;         ///< The touch down time
 881
 882   int mGestureStackDepth;               ///< How many gestures are currently occuring.
 883   Vector2 mPanStartPosition;            ///< Where the pan gesture's touch down occured
 884   Vector2 mPanDelta;                    ///< Amount currently panned.
 885
 886   unsigned int mScrollStateFlags;       ///< flags indicating current state of scrolling
 887   // Scroll delegate pre and post position properties...
 888   Vector2 mScrollPrePosition;           ///< Wrapped scroll position, but not clamped
 889   Vector2 mScrollPostPosition;          ///< Wrapped and clamped, this is the final scroll position used
 890   Vector2 mScrollTargetPosition;        ///< Final target position for an animated scroll
 891   Vector2 mDomainOffset;                ///< Domain offset (this keeps track of the domain boundaries that scroll positions traverses)
 892
 893   // Rulers for each axes...
 894   RulerPtr mRulerX;
 895   RulerPtr mRulerY;
 896
 897   // Last property values set to ScrollView
 898   Vector2 mMinScroll;
 899   Vector2 mMaxScroll;
 900
 901   Animation mInternalXAnimation;        ///< Animates mPropertyX to a snap position or application requested scroll position
 902   Animation mInternalYAnimation;        ///< Animates mPropertyY to a snap position or application requested scroll position
 903
 904
 905   Vector2 mLastVelocity;                ///< Record the last velocity from PanGesture (Finish event doesn't have correct velocity)
 906   LockAxis mLockAxis;
 907
 908   Timer mTouchDownTimer;                ///< Used to interrupt snap-animation. This cannot be done in OnTouch without breaking fast flick behavior.
 909
 910   float mScrollUpdateDistance;          ///< Distance for scrolling to travel for the scroll update notifications
 911   Dali::PropertyNotification mScrollXUpdateNotification; ///< scroll x position update notification
 912   Dali::PropertyNotification mScrollYUpdateNotification; ///< scroll y position update notification
 913
 914   Actor mInternalActor;                 ///< Internal actor (we keep internal actors in here e.g. scrollbars, so we can ignore it in searches)
 915
 916   ScrollViewEffectContainer mEffects;   ///< Container keeping track of all the applied effects.
 917
 918   Vector2   mMaxOvershoot;                      ///< Number of scrollable pixels that will take overshoot from 0.0f to 1.0f
 919   Vector2   mUserMaxOvershoot;                  ///< Set by user, allows overriding of default max overshoot for the scroll indicator
 920   float     mSnapOvershootDuration;             ///< Duration for overshoot snapping back to Vector2::ZERO
 921   AlphaFunction mSnapOvershootAlphaFunction;    ///< AlphaFunction to be used for this overshoot.
 922
 923   float mSnapDuration;                          ///< Time for the snap animation to take (in seconds).
 924   AlphaFunction mSnapAlphaFunction;             ///< AlphaFunction to be used for the Snap Animation.
 925
 926   Vector2 mMinFlickDistance;                      ///< Minimum pan distance required for a flick
 927   float mFlickSpeedThreshold;                   ///< Minimum pan speed required for a flick in pixels/ms
 928   float mFlickDuration;                         ///< Time for the flick animation to take (in seconds).
 929   AlphaFunction mFlickAlphaFunction;            ///< AlphaFunction to be used for the Flick Animation.
 930
 931   float mAxisAutoLockGradient;                  ///< Axis Auto-lock gradient threshold. Above this gradient and it will lock scrolling to closest axis.
 932   float mFrictionCoefficient;                   ///< Friction coefficient. Amount of friction to apply to free panning flick animation. in stage.lengths/sec
 933   float mFlickSpeedCoefficient;                 ///< Flick velocity coefficient. Input touch velocity is multiplied by this.
 934   float mMaxFlickSpeed;                         ///< Maximum flick speed. Maximum speed of flick in stage.lengths/sec.
 935
 936   Vector2 mWheelScrollDistanceStep;        ///< The step of scroll distance in actor coordinates in X and Y axes for each wheel event received.
 937
 938   //ScrollInternalConstraintsPtr mScrollInternalConstraints;
 939   Constraint mScrollMainInternalPrePositionConstraint;
 940   Constraint mScrollMainInternalPositionConstraint;
 941   Constraint mScrollMainInternalOvershootXConstraint;
 942   Constraint mScrollMainInternalOvershootYConstraint;
 943   Constraint mScrollMainInternalDeltaConstraint;
 944   Constraint mScrollMainInternalFinalConstraint;
 945   Constraint mScrollMainInternalRelativeConstraint;
 946   Constraint mScrollMainInternalDomainConstraint;
 947   Constraint mScrollMainInternalPrePositionMaxConstraint;
 948
 949   ScrollOvershootIndicatorPtr mOvershootIndicator;
 950   WeakHandle<Toolkit::ScrollBar> mScrollBar;
 951
 952   Toolkit::ScrollView::SnapStartedSignalType mSnapStartedSignal;
 953
 954   bool mInAccessibilityPan:1;             ///< With AccessibilityPan its easier to move between snap positions
 955   bool mScrolling:1;                      ///< Flag indicating whether the scroll view is being scrolled (by user or animation)
 956   bool mScrollInterrupted:1;              ///< Flag set for when a down event interrupts a scroll
 957   bool mPanning:1;                        ///< Whether scroll view is currently panning or not
 958   bool mSensitive:1;                      ///< Scroll Sensitivity Flag.
 959   bool mTouchDownTimeoutReached:1;        ///< Indicates when down event timeout occured without corresponding up event (touch still down)
 960   bool mActorAutoSnapEnabled:1;           ///< Whether to automatically snap to closest actor.
 961   bool mAutoResizeContainerEnabled:1;     ///< Whether to automatically resize container (affects RulerDomain's on X/Y axes)
 962   bool mWrapMode:1;                       ///< Whether to wrap contents based on container size.
 963   bool mAxisAutoLock:1;                   ///< Whether to automatically lock axis when panning.
 964   bool mAlterChild:1;                     ///< Internal flag to control behavior of OnChildAdd/OnChildRemove when Adding internal Actors.
 965   bool mDefaultMaxOvershoot:1;            ///< Whether to use default max overshoot or application defined one
 966   bool mCanScrollHorizontal:1;            ///< Local value of our property to check against
 967   bool mCanScrollVertical:1;              ///< Local value of our property to check against
 968   bool mTransientScrollBar:1;             ///< True if scroll-bar should be automatically show/hidden during/after panning
 969 };
 970
 971 } // namespace Internal
 972
 973 // Helpers for public-api forwarding methods
 974
 975 inline Toolkit::Internal::ScrollView& GetImpl(Toolkit::ScrollView& scrollView)
 976 {
 977   DALI_ASSERT_ALWAYS(scrollView);
 978
 979   Dali::RefObject& handle = scrollView.GetImplementation();
 980
 981   return static_cast<Toolkit::Internal::ScrollView&>(handle);
 982 }
 983
 984 inline const Toolkit::Internal::ScrollView& GetImpl(const Toolkit::ScrollView& scrollView)
 985 {
 986   DALI_ASSERT_ALWAYS(scrollView);
 987
 988   const Dali::RefObject& handle = scrollView.GetImplementation();
 989
 990   return static_cast<const Toolkit::Internal::ScrollView&>(handle);
 991 }
 992
 993 } // namespace Toolkit
 994
 995 } // namespace Dali
 996
 997 #endif // DALI_TOOLKIT_INTERNAL_SCROLL_VIEW_H