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