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