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) 2017 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/public-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 = DirectionBiasNone, DirectionBias verticalBias = DirectionBiasNone);
 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 = DirectionBiasNone, DirectionBias verticalBias = DirectionBiasNone);
 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 = DirectionBiasNone);
 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 = DirectionBiasNone, DirectionBias verticalBias = DirectionBiasNone,
 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   virtual void OnSizeAnimation(Animation& animation, const Vector3& targetSize);
 550
 551   /**
 552    * @copydoc CustomActorImpl::OnSizeSet(const Vector3&)
 553    */
 554   virtual void OnSizeSet( const Vector3& size );
 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   virtual void OnChildAdd(Actor& child);
 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   virtual void OnChildRemove(Actor& child);
 567
 568   /**
 569    * From CustomActorImpl; called after a wheelEvent is received by the owning actor.
 570    * @param[in] event The wheel event.
 571    * @return True if the event should be consumed.
 572    */
 573   virtual bool OnWheelEvent(const WheelEvent& event);
 574
 575   /**
 576    * @copydoc Toolkit::Control::OnInitialize()
 577    */
 578   virtual void OnInitialize();
 579
 580   /**
 581    * @copydoc CustomActorImpl::OnStageConnection()
 582    */
 583   virtual void OnStageConnection( int depth );
 584
 585   /**
 586    * @copydoc CustomActorImpl::OnStageDisconnection()
 587    */
 588   virtual void OnStageDisconnection();
 589
 590   /**
 591    * @copydoc Toolkit::Control::OnAccessibilityPan()
 592    */
 593   virtual bool OnAccessibilityPan(PanGesture gesture);
 594
 595   /**
 596    * @copydoc Toolkit::Scrollable::EnableScrollOvershoot()
 597    */
 598   virtual void EnableScrollOvershoot(bool enable);
 599
 600 private:
 601
 602   /**
 603    * Called after a touchSignal is received by the owning actor.
 604    *
 605    * We don't consume these events as content within the container may consume events.
 606    *
 607    * @param[in] actor The touched actor.
 608    * @param[in] touch The touch information.
 609    * @return True if the event should be consumed.
 610    */
 611   bool OnTouch( Actor actor, const TouchData& touch );
 612
 613   /**
 614    * Start a timer which calls OnTouchDownTimeout()
 615    */
 616   void StartTouchDownTimer();
 617
 618   /**
 619    * Stop a timer which calls OnTouchDownTimeout()
 620    */
 621   void StopTouchDownTimer();
 622
 623   /**
 624    * Helper to detect when touch-point has been down (outside of pan gesture)
 625    */
 626   bool OnTouchDownTimeout();
 627
 628   /**
 629    * Called whenever a snap animation has completed
 630    * @param[in] source the Animation instance that has completed.
 631    * Resets all scrolling animations and states, leaving current scroll position at SCROLL_POSITION
 632    */
 633   void ResetScrolling();
 634
 635   /**
 636    * Updates mScrollInternalPosition, mScrollPrePosition and mScrollPostPosition from their property counterparts
 637    */
 638   void UpdateLocalScrollProperties();
 639
 640   /**
 641    * Makes sure scroll values are ready for animated scrolling
 642    */
 643   void PreAnimatedScrollSetup();
 644
 645   /**
 646    * Finish an animated scroll, ensuring all scroll properties are updated
 647    * and synchronised
 648    */
 649   void FinaliseAnimatedScroll();
 650
 651   /**
 652    * Animates the internal x property to the given value
 653    *
 654    * @param[in] position The X position to animate to
 655    * @param[in] duration The time in seconds for animation
 656    * @param[in] alpha The alpha function to use for animating
 657    */
 658   void AnimateInternalXTo( float position, float duration, AlphaFunction alpha );
 659
 660   /**
 661    * Animates the internal y property to the given value
 662    *
 663    * @param[in] position The Y position to animate to
 664    * @param[in] duration The time in seconds for animation
 665    * @param[in] alpha The alpha function to use for animating
 666    */
 667   void AnimateInternalYTo( float position, float duration, AlphaFunction alpha );
 668
 669   /**
 670    * Called whenever a snap animation on the x-axis has completed
 671    * @param[in] source the Animation instance that has completed.
 672    */
 673   void OnScrollAnimationFinished( Animation& source );
 674
 675   /**
 676    * Called when either the X or Y internal scroll positions have finished snapping back to SCROLL_PRE_POSITION
 677    *
 678    * @param[in] source the Animation instance that has completed.
 679    */
 680   void OnSnapInternalPositionFinished( Animation& source );
 681
 682   /**
 683    * Called whenever a snap animation on the x-axis has completed and we need to snap pre scroll
 684    * position to our clamped position
 685    * @param[in] position The x position to snap pre scroll property to
 686    */
 687   void SnapInternalXTo( float position );
 688
 689   /**
 690    * Called whenever a snap animation on the y-axis has completed and we need to snap pre scroll
 691    * position to our clamped position
 692    * @param[in] position The y position to snap pre scroll property to
 693    */
 694   void SnapInternalYTo( float position );
 695
 696   /**
 697    * This is called internally whenever the Scroll Rulers are
 698    * modified. This will update the properties: 'scrollPositionMin'
 699    * and 'scrollPositionMax' to reflect the changes.
 700    */
 701   void UpdatePropertyDomain();
 702
 703   /**
 704    * Called when the gesture starts.
 705    */
 706   void GestureStarted();
 707
 708   /**
 709    * Amalgamated Gesture Continuing event
 710    *
 711    * @param[in] panDelta average panning delta from base position (0)
 712    */
 713   void GestureContinuing(const Vector2& panDelta);
 714
 715   /**
 716    * Called upon pan gesture event.
 717    *
 718    * @param[in] gesture The gesture event.
 719    */
 720   void OnPan( const PanGesture& pan);
 721
 722   /**
 723    * Extension of the above gestures.
 724    *
 725    * @param[in] gesture The gesture event.
 726    */
 727   void OnGestureEx(Gesture::State state);
 728
 729   /**
 730    * Performs snapping while taking into account Velocity of gesture
 731    * (velocity in pixels/sec)
 732    *
 733    * @param[in] velocity velocity in pixels/sec
 734    */
 735   bool SnapWithVelocity(Vector2 velocity);
 736
 737   /**
 738    * Finishes Container Transform
 739    * (occurs upon finishing gesture i.e. releasing)
 740    */
 741   void FinishTransform();
 742
 743   /**
 744    * Returns overshoot vector based on current position
 745    *
 746    * Overshoot vector is defined as how far outside of bounds
 747    * the viewport is trying to view (prior to being clamped).
 748    *
 749    * an overshoot of (100,50), means user is in bottom right corner,
 750    * trying to pan +100 to the right, and +50 below. This can be used
 751    * to determine an effect, such as stretching.
 752    *
 753    * @param[in] position The position for which you wish to obtain overshoot vector
 754    */
 755   Vector2 GetOvershoot(Vector2& position) const;
 756
 757   /**
 758    * Clamps position within the domain set up by X/Y Rulers
 759    *
 760    * @param[in,out] position The position you wish to clamp
 761    */
 762   void ClampPosition(Vector2& position) const;
 763
 764   /**
 765    * Clamps position within the domain set up by X/Y Rulers
 766    *
 767    * @param[in,out] position The position you wish to clamp
 768    * @param[out] clamped The results of the clamping.
 769    */
 770   void ClampPosition(Vector2& position, ClampState2D &clamped) const;
 771
 772   /**
 773    * Wraps position within the domain set up by X/Y Rulers
 774    *
 775    * @note Only wraps if mWrapMode is enabled, and respective domains
 776    * are enabled.
 777    *
 778    * @param[in,out] position The position you wish to wrap
 779    */
 780   void WrapPosition(Vector2& position) const;
 781
 782   /**
 783    * Updates the main internal scroll constraints with new ruler and domain
 784    * values
 785    */
 786   void UpdateMainInternalConstraint();
 787
 788   /**
 789    * Enables/disables the overshoot constraints
 790    *
 791    * @param[in] enabled whether to enable or disable the overshoot constraints
 792    */
 793   void SetOvershootConstraintsEnabled(bool enabled);
 794
 795   /**
 796    * Sets internal constraints for this ScrollView.
 797    * Many of these internal constraints are based on properties within
 798    * ScrollView.
 799    */
 800   void SetInternalConstraints();
 801
 802 protected:
 803
 804   /**
 805    * Construct a new ScrollView.
 806    */
 807   ScrollView();
 808
 809   /**
 810    * A reference counted object may only be deleted by calling Unreference()
 811    */
 812   virtual ~ScrollView();
 813
 814 private:
 815
 816   /**
 817    * Searches this ScrollView, and attempts to Unbind
 818    * systematically this Actor from the ScrollView attached.
 819    *
 820    * @param[in] child The actor to be unbound.
 821    */
 822   virtual void FindAndUnbindActor(Actor child);
 823
 824   /**
 825    * Gets position property.
 826    *
 827    * @return The current position
 828    */
 829   Vector2 GetPropertyPrePosition() const;
 830
 831   /**
 832    * Gets position property.
 833    *
 834    * @return The current position
 835    */
 836   Vector2 GetPropertyPosition() const;
 837
 838   /**
 839    * Handles a Stopped animation. Its position properties need to be saved, and the animation flag
 840    * switched off.
 841    */
 842   void HandleStoppedAnimation();
 843
 844   /**
 845    * Handles a Stopped animation (whether the animation completed, or was
 846    * manually stopped). Its position properties need to be saved, and the
 847    * animation flag switched off.
 848    */
 849   void HandleSnapAnimationFinished();
 850
 851   /**
 852    * Checks if the property notifications are active and adds them if not
 853    */
 854   void SetScrollUpdateNotification( bool enabled );
 855
 856   /**
 857    * Refresh the ScrollView (used when animating to update application developer of changes)
 858    * @return True if the refresh timer should be kept running.
 859    */
 860   void OnScrollUpdateNotification(Dali::PropertyNotification& source);
 861
 862   /**
 863    * Set up default rulers using a property map
 864    * @param[in] scrollModeMap A map defining the characteristics of X and Y scrolling
 865    * using either FixedRuler or DefaultRuler.
 866    */
 867   void SetScrollMode( const Property::Map& scrollModeMap );
 868
 869 private:
 870
 871   // Undefined
 872   ScrollView(const ScrollView&);
 873
 874   // Undefined
 875   ScrollView& operator=(const ScrollView& rhs);
 876
 877 private:
 878
 879   unsigned long mTouchDownTime;         ///< The touch down time
 880
 881   int mGestureStackDepth;               ///< How many gestures are currently occuring.
 882   Vector2 mPanStartPosition;            ///< Where the pan gesture's touch down occured
 883   Vector2 mPanDelta;                    ///< Amount currently panned.
 884
 885   unsigned int mScrollStateFlags;       ///< flags indicating current state of scrolling
 886   // Scroll delegate pre and post position properties...
 887   Vector2 mScrollPrePosition;           ///< Wrapped scroll position, but not clamped
 888   Vector2 mScrollPostPosition;          ///< Wrapped and clamped, this is the final scroll position used
 889   Vector2 mScrollTargetPosition;        ///< Final target position for an animated scroll
 890   Vector2 mDomainOffset;                ///< Domain offset (this keeps track of the domain boundaries that scroll positions traverses)
 891
 892   // Rulers for each axes...
 893   RulerPtr mRulerX;
 894   RulerPtr mRulerY;
 895
 896   // Last property values set to ScrollView
 897   Vector2 mMinScroll;
 898   Vector2 mMaxScroll;
 899
 900   Animation mInternalXAnimation;        ///< Animates mPropertyX to a snap position or application requested scroll position
 901   Animation mInternalYAnimation;        ///< Animates mPropertyY to a snap position or application requested scroll position
 902
 903
 904   Vector2 mLastVelocity;                ///< Record the last velocity from PanGesture (Finish event doesn't have correct velocity)
 905   LockAxis mLockAxis;
 906
 907   Timer mTouchDownTimer;                ///< Used to interrupt snap-animation. This cannot be done in OnTouch without breaking fast flick behavior.
 908
 909   float mScrollUpdateDistance;          ///< Distance for scrolling to travel for the scroll update notifications
 910   Dali::PropertyNotification mScrollXUpdateNotification; ///< scroll x position update notification
 911   Dali::PropertyNotification mScrollYUpdateNotification; ///< scroll y position update notification
 912
 913   Actor mInternalActor;                 ///< Internal actor (we keep internal actors in here e.g. scrollbars, so we can ignore it in searches)
 914
 915   ScrollViewEffectContainer mEffects;   ///< Container keeping track of all the applied effects.
 916
 917   Vector2   mMaxOvershoot;                      ///< Number of scrollable pixels that will take overshoot from 0.0f to 1.0f
 918   Vector2   mUserMaxOvershoot;                  ///< Set by user, allows overriding of default max overshoot for the scroll indicator
 919   float     mSnapOvershootDuration;             ///< Duration for overshoot snapping back to Vector2::ZERO
 920   AlphaFunction mSnapOvershootAlphaFunction;    ///< AlphaFunction to be used for this overshoot.
 921
 922   float mSnapDuration;                          ///< Time for the snap animation to take (in seconds).
 923   AlphaFunction mSnapAlphaFunction;             ///< AlphaFunction to be used for the Snap Animation.
 924
 925   Vector2 mMinFlickDistance;                      ///< Minimum pan distance required for a flick
 926   float mFlickSpeedThreshold;                   ///< Minimum pan speed required for a flick in pixels/ms
 927   float mFlickDuration;                         ///< Time for the flick animation to take (in seconds).
 928   AlphaFunction mFlickAlphaFunction;            ///< AlphaFunction to be used for the Flick Animation.
 929
 930   float mAxisAutoLockGradient;                  ///< Axis Auto-lock gradient threshold. Above this gradient and it will lock scrolling to closest axis.
 931   float mFrictionCoefficient;                   ///< Friction coefficient. Amount of friction to apply to free panning flick animation. in stage.lengths/sec
 932   float mFlickSpeedCoefficient;                 ///< Flick velocity coefficient. Input touch velocity is multiplied by this.
 933   float mMaxFlickSpeed;                         ///< Maximum flick speed. Maximum speed of flick in stage.lengths/sec.
 934
 935   Vector2 mWheelScrollDistanceStep;        ///< The step of scroll distance in actor coordinates in X and Y axes for each wheel event received.
 936
 937   //ScrollInternalConstraintsPtr mScrollInternalConstraints;
 938   Constraint mScrollMainInternalPrePositionConstraint;
 939   Constraint mScrollMainInternalPositionConstraint;
 940   Constraint mScrollMainInternalOvershootXConstraint;
 941   Constraint mScrollMainInternalOvershootYConstraint;
 942   Constraint mScrollMainInternalDeltaConstraint;
 943   Constraint mScrollMainInternalFinalConstraint;
 944   Constraint mScrollMainInternalRelativeConstraint;
 945   Constraint mScrollMainInternalDomainConstraint;
 946   Constraint mScrollMainInternalPrePositionMaxConstraint;
 947
 948   ScrollOvershootIndicatorPtr mOvershootIndicator;
 949   WeakHandle<Toolkit::ScrollBar> mScrollBar;
 950
 951   Toolkit::ScrollView::SnapStartedSignalType mSnapStartedSignal;
 952
 953   bool mInAccessibilityPan:1;             ///< With AccessibilityPan its easier to move between snap positions
 954   bool mScrolling:1;                      ///< Flag indicating whether the scroll view is being scrolled (by user or animation)
 955   bool mScrollInterrupted:1;              ///< Flag set for when a down event interrupts a scroll
 956   bool mPanning:1;                        ///< Whether scroll view is currently panning or not
 957   bool mSensitive:1;                      ///< Scroll Sensitivity Flag.
 958   bool mTouchDownTimeoutReached:1;        ///< Indicates when down event timeout occured without corresponding up event (touch still down)
 959   bool mActorAutoSnapEnabled:1;           ///< Whether to automatically snap to closest actor.
 960   bool mAutoResizeContainerEnabled:1;     ///< Whether to automatically resize container (affects RulerDomain's on X/Y axes)
 961   bool mWrapMode:1;                       ///< Whether to wrap contents based on container size.
 962   bool mAxisAutoLock:1;                   ///< Whether to automatically lock axis when panning.
 963   bool mAlterChild:1;                     ///< Internal flag to control behavior of OnChildAdd/OnChildRemove when Adding internal Actors.
 964   bool mDefaultMaxOvershoot:1;            ///< Whether to use default max overshoot or application defined one
 965   bool mCanScrollHorizontal:1;            ///< Local value of our property to check against
 966   bool mCanScrollVertical:1;              ///< Local value of our property to check against
 967   bool mTransientScrollBar:1;             ///< True if scroll-bar should be automatically show/hidden during/after panning
 968 };
 969
 970 } // namespace Internal
 971
 972 // Helpers for public-api forwarding methods
 973
 974 inline Toolkit::Internal::ScrollView& GetImpl(Toolkit::ScrollView& scrollView)
 975 {
 976   DALI_ASSERT_ALWAYS(scrollView);
 977
 978   Dali::RefObject& handle = scrollView.GetImplementation();
 979
 980   return static_cast<Toolkit::Internal::ScrollView&>(handle);
 981 }
 982
 983 inline const Toolkit::Internal::ScrollView& GetImpl(const Toolkit::ScrollView& scrollView)
 984 {
 985   DALI_ASSERT_ALWAYS(scrollView);
 986
 987   const Dali::RefObject& handle = scrollView.GetImplementation();
 988
 989   return static_cast<const Toolkit::Internal::ScrollView&>(handle);
 990 }
 991
 992 } // namespace Toolkit
 993
 994 } // namespace Dali
 995
 996 #endif // __DALI_TOOLKIT_INTERNAL_SCROLL_VIEW_H__