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) 2015 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/devel-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    * @brief Enables or disables the transient scroll-bar
 360    *
 361    * @param[in] transient True if scroll-bar should be automatically show/hidden during/after panning
 362    */
 363   void SetTransientScrollBar( bool transient );
 364
 365   /**
 366    * @copydoc Toolkit::ScrollView::GetCurrentPage
 367    */
 368   unsigned int GetCurrentPage() const;
 369
 370   /**
 371    * @copydoc Toolkit::ScrollView::GetCurrentScrollPosition
 372    */
 373   Vector2 GetCurrentScrollPosition() const;
 374
 375   /**
 376    * @copydoc ScrollTo(const Vector2&)
 377    */
 378   void TransformTo(const Vector2& position,
 379                    DirectionBias horizontalBias = DirectionBiasNone, DirectionBias verticalBias = DirectionBiasNone);
 380
 381   /**
 382    * @copydoc ScrollTo(const Vector2&, float, AlhpaFunction, DirectionBias, DirectionBias)
 383    */
 384   void TransformTo(const Vector2& position, float duration, AlphaFunction alpha,
 385                    DirectionBias horizontalBias = DirectionBiasNone, DirectionBias verticalBias = DirectionBiasNone);
 386
 387   /**
 388    * @copydoc Toolkit::ScrollView::ScrollTo(const Vector2 &position)
 389    */
 390   void ScrollTo(const Vector2 &position);
 391
 392   /**
 393    * @copydoc Toolkit::Scrollable::ScrollTo(const Vector2& position, float duration)
 394    */
 395   void ScrollTo(const Vector2& position, float duration);
 396
 397   /**
 398    * @copydoc Toolkit::Scrollable::ScrollTo(const Vector2& position, float duration, AlphaFunction alpha)
 399    */
 400   void ScrollTo(const Vector2& position, float duration, AlphaFunction alpha);
 401
 402   /**
 403    * @copydoc Toolkit::ScrollView::ScrollTo(const Vector2 &position, float duration, DirectionBias horizontalBias, DirectionBias verticalBias)
 404    */
 405   void ScrollTo(const Vector2& position, float duration,
 406                 DirectionBias horizontalBias, DirectionBias verticalBias);
 407
 408   /**
 409    * @copydoc Toolkit::ScrollView::ScrollTo(const Vector2 &position, float duration, AlphaFunction alpha, DirectionBias horizontalBias, DirectionBias verticalBias)
 410    */
 411   void ScrollTo(const Vector2& position, float duration, AlphaFunction alpha,
 412                 DirectionBias horizontalBias, DirectionBias verticalBias);
 413
 414   /**
 415    * @copydoc Toolkit::ScrollView::ScrollTo(unsigned int page)
 416    */
 417   void ScrollTo(unsigned int page);
 418
 419   /**
 420    * @copydoc Toolkit::ScrollView::ScrollTo(unsigned int page, float duration, DirectionBias bias)
 421    */
 422   void ScrollTo(unsigned int page, float duration, DirectionBias bias = DirectionBiasNone);
 423
 424   /**
 425    * @copydoc Toolkit::ScrollView::ScrollTo(Actor& actor)
 426    */
 427   void ScrollTo(Actor &actor);
 428
 429   /**
 430    * @copydoc Toolkit::ScrollView::ScrollTo(Actor& actor, float duration)
 431    */
 432   void ScrollTo(Actor &actor, float duration);
 433
 434   /**
 435    * @copydoc Toolkit::ScrollView::SetScrollingDirection()
 436    */
 437   void SetScrollingDirection( Radian direction, Radian threshold );
 438
 439   /**
 440    * @copydoc Toolkit::ScrollView::RemoveScrollingDirection()
 441    */
 442   void RemoveScrollingDirection( Radian angle );
 443
 444   /**
 445     * Finds the closest Actor to the current center of the ScrollView.
 446     *
 447     * @return A handle to the actor if found, or an empty handle if not.
 448     */
 449    Actor FindClosestActor();
 450
 451   /**
 452    * Finds the closest Actor to position in ScrollView
 453    *
 454    * @param[in] position position within ScrollView.
 455    * @param[in] dirX Whether to search only those elements that are Left,Right, or All
 456    * @param[in] dirY Whether to search only those elements that are Up,Down, or All
 457    * @param[in] dirZ Whether to search only those elements that are Out,In, or All
 458    * @return A handle to the actor if found, or an empty handle if not.
 459    */
 460   Actor FindClosestActorToPosition(const Vector3& position, FindDirection dirX = All, FindDirection dirY = All, FindDirection dirZ = All);
 461
 462   /**
 463    * @copydoc Toolkit::ScrollView::ScrollToSnapPoint
 464   */
 465   bool ScrollToSnapPoint();
 466
 467   /**
 468    * Stops animation
 469    */
 470   void StopAnimation(void);
 471
 472   /**
 473    * Stops the input animation
 474    *
 475    * @param[in] the animation to stop
 476    */
 477   void StopAnimation(Animation& animation);
 478
 479   /**
 480    * Animates to position transform.
 481    *
 482    * @param[in] position The position to animate to
 483    * @param[in] positionDuration The number of seconds this animation should run for in each axis.
 484    * @param[in] alpha The easing alpha function to use.
 485    * @param[in] findShortcuts (optional) Whether to find the shortest route (in Wrap mode)
 486    * @param[in] horizontalBias (optional) Whether to bias animation to left or right (or no biasing)
 487    * @param[in] verticalBias (optional) Whether to bias animation to top or bottom (or no biasing)
 488    * @return True if animation necessary and taking place to reach desired transform.
 489    */
 490   bool AnimateTo(const Vector2& position, const Vector2& positionDuration,
 491                              AlphaFunction alpha, bool findShortcuts = true,
 492                              DirectionBias horizontalBias = DirectionBiasNone, DirectionBias verticalBias = DirectionBiasNone,
 493                              SnapType snapType = Snap);
 494
 495   /**
 496    * @copydoc Toolkit::Scrollable::AddOverlay()
 497    */
 498   void AddOverlay(Actor actor);
 499
 500   /**
 501    * @copydoc Toolkit::Scrollable::RemoveOverlay()
 502    */
 503   void RemoveOverlay(Actor actor);
 504
 505   /**
 506    * @copydoc Toolkit::Internal::Scrollable::SetOvershootSize
 507    */
 508   void SetOvershootSize( const Vector2& size );
 509
 510   /**
 511    * @copydoc Toolkit::Internal::Scrollable::SetOvershootEffectColor
 512    */
 513   void SetOvershootEffectColor( const Vector4& color );
 514
 515   //properties
 516
 517   /**
 518    * Called when a property of an object of this type is set.
 519    * @param[in] object The object whose property is set.
 520    * @param[in] index The property index.
 521    * @param[in] value The new property value.
 522    */
 523   static void SetProperty( BaseObject* object, Property::Index index, const Property::Value& value );
 524
 525   /**
 526    * Called to retrieve a property of an object of this type.
 527    * @param[in] object The object whose property is to be retrieved.
 528    * @param[in] index The property index.
 529    * @return The current value of the property.
 530    */
 531   static Property::Value GetProperty( BaseObject* object, Property::Index index );
 532
 533 public: //Signals
 534
 535   /**
 536    * @copydoc Dali::Toolkit::ScrollView::SnapStartedSignal()
 537    */
 538   Toolkit::ScrollView::SnapStartedSignalType& SnapStartedSignal();
 539
 540   /**
 541    * Connects a callback function with the object's signals.
 542    * @param[in] object The object providing the signal.
 543    * @param[in] tracker Used to disconnect the signal.
 544    * @param[in] signalName The signal to connect to.
 545    * @param[in] functor A newly allocated FunctorDelegate.
 546    * @return True if the signal was connected.
 547    * @post If a signal was connected, ownership of functor was passed to CallbackBase. Otherwise the caller is responsible for deleting the unused functor.
 548    */
 549   static bool DoConnectSignal( BaseObject* object, ConnectionTrackerInterface* tracker, const std::string& signalName, FunctorDelegate* functor );
 550
 551 private: // private overridden functions from CustomActorImpl and Controls
 552
 553   /**
 554    * @copydoc Dali::CustomActorImpl::OnSizeAnimation(Animation&, const Vector3&)
 555    */
 556   virtual void OnSizeAnimation(Animation& animation, const Vector3& targetSize);
 557
 558   /**
 559    * @copydoc CustomActorImpl::OnSizeSet(const Vector3&)
 560    */
 561   virtual void OnSizeSet( const Vector3& size );
 562
 563   /**
 564    * From CustomActorImpl; called after a child has been added to the owning actor.
 565    * @param[in] child The child which has been added.
 566    */
 567   virtual void OnChildAdd(Actor& child);
 568
 569   /**
 570    * From CustomActorImpl; called shortly before a child is removed from the owning actor.
 571    * @param[in] child The child being removed.
 572    */
 573   virtual void OnChildRemove(Actor& child);
 574
 575   /**
 576    * From CustomActorImpl; called after a wheelEvent is received by the owning actor.
 577    * @param[in] event The wheel event.
 578    * @return True if the event should be consumed.
 579    */
 580   virtual bool OnWheelEvent(const WheelEvent& event);
 581
 582   /**
 583    * @copydoc Toolkit::Control::OnInitialize()
 584    */
 585   virtual void OnInitialize();
 586
 587   /**
 588    * @copydoc CustomActorImpl::OnStageConnection()
 589    */
 590   virtual void OnStageConnection( int depth );
 591
 592   /**
 593    * @copydoc CustomActorImpl::OnStageDisconnection()
 594    */
 595   virtual void OnStageDisconnection();
 596
 597   /**
 598    * @copydoc Toolkit::Control::OnAccessibilityPan()
 599    */
 600   virtual bool OnAccessibilityPan(PanGesture gesture);
 601
 602   /**
 603    * @copydoc Toolkit::Scrollable::EnableScrollOvershoot()
 604    */
 605   virtual void EnableScrollOvershoot(bool enable);
 606
 607 private:
 608
 609   /**
 610    * Called after a touchSignal is received by the owning actor.
 611    *
 612    * We don't consume these events as content within the container may consume events.
 613    *
 614    * @param[in] actor The touched actor.
 615    * @param[in] touch The touch information.
 616    * @return True if the event should be consumed.
 617    */
 618   bool OnTouch( Actor actor, const TouchData& touch );
 619
 620   /**
 621    * Start a timer which calls OnTouchDownTimeout()
 622    */
 623   void StartTouchDownTimer();
 624
 625   /**
 626    * Stop a timer which calls OnTouchDownTimeout()
 627    */
 628   void StopTouchDownTimer();
 629
 630   /**
 631    * Helper to detect when touch-point has been down (outside of pan gesture)
 632    */
 633   bool OnTouchDownTimeout();
 634
 635   /**
 636    * Called whenever a snap animation has completed
 637    * @param[in] source the Animation instance that has completed.
 638    * Resets all scrolling animations and states, leaving current scroll position at SCROLL_POSITION
 639    */
 640   void ResetScrolling();
 641
 642   /**
 643    * Updates mScrollInternalPosition, mScrollPrePosition and mScrollPostPosition from their property counterparts
 644    */
 645   void UpdateLocalScrollProperties();
 646
 647   /**
 648    * Makes sure scroll values are ready for animated scrolling
 649    */
 650   void PreAnimatedScrollSetup();
 651
 652   /**
 653    * Finish an animated scroll, ensuring all scroll properties are updated
 654    * and synchronised
 655    */
 656   void FinaliseAnimatedScroll();
 657
 658   /**
 659    * Animates the internal x property to the given value
 660    *
 661    * @param[in] position The X position to animate to
 662    * @param[in] duration The time in seconds for animation
 663    * @param[in] alpha The alpha function to use for animating
 664    */
 665   void AnimateInternalXTo( float position, float duration, AlphaFunction alpha );
 666
 667   /**
 668    * Animates the internal y property to the given value
 669    *
 670    * @param[in] position The Y position to animate to
 671    * @param[in] duration The time in seconds for animation
 672    * @param[in] alpha The alpha function to use for animating
 673    */
 674   void AnimateInternalYTo( float position, float duration, AlphaFunction alpha );
 675
 676   /**
 677    * Called whenever a snap animation on the x-axis has completed
 678    * @param[in] source the Animation instance that has completed.
 679    */
 680   void OnScrollAnimationFinished( Animation& source );
 681
 682   /**
 683    * Called when either the X or Y internal scroll positions have finished snapping back to SCROLL_PRE_POSITION
 684    *
 685    * @param[in] source the Animation instance that has completed.
 686    */
 687   void OnSnapInternalPositionFinished( Animation& source );
 688
 689   /**
 690    * Called whenever a snap animation on the x-axis has completed and we need to snap pre scroll
 691    * position to our clamped position
 692    * @param[in] position The x position to snap pre scroll property to
 693    */
 694   void SnapInternalXTo( float position );
 695
 696   /**
 697    * Called whenever a snap animation on the y-axis has completed and we need to snap pre scroll
 698    * position to our clamped position
 699    * @param[in] position The y position to snap pre scroll property to
 700    */
 701   void SnapInternalYTo( float position );
 702
 703   /**
 704    * This is called internally whenever the Scroll Rulers are
 705    * modified. This will update the properties: 'scrollPositionMin'
 706    * and 'scrollPositionMax' to reflect the changes.
 707    */
 708   void UpdatePropertyDomain();
 709
 710   /**
 711    * Called when the gesture starts.
 712    */
 713   void GestureStarted();
 714
 715   /**
 716    * Amalgamated Gesture Continuing event
 717    *
 718    * @param[in] panDelta average panning delta from base position (0)
 719    */
 720   void GestureContinuing(const Vector2& panDelta);
 721
 722   /**
 723    * Called upon pan gesture event.
 724    *
 725    * @param[in] gesture The gesture event.
 726    */
 727   void OnPan( const PanGesture& pan);
 728
 729   /**
 730    * Extension of the above gestures.
 731    *
 732    * @param[in] gesture The gesture event.
 733    */
 734   void OnGestureEx(Gesture::State state);
 735
 736   /**
 737    * Performs snapping while taking into account Velocity of gesture
 738    * (velocity in pixels/sec)
 739    *
 740    * @param[in] velocity velocity in pixels/sec
 741    */
 742   bool SnapWithVelocity(Vector2 velocity);
 743
 744   /**
 745    * Finishes Container Transform
 746    * (occurs upon finishing gesture i.e. releasing)
 747    */
 748   void FinishTransform();
 749
 750   /**
 751    * Returns overshoot vector based on current position
 752    *
 753    * Overshoot vector is defined as how far outside of bounds
 754    * the viewport is trying to view (prior to being clamped).
 755    *
 756    * an overshoot of (100,50), means user is in bottom right corner,
 757    * trying to pan +100 to the right, and +50 below. This can be used
 758    * to determine an effect, such as stretching.
 759    *
 760    * @param[in] position The position for which you wish to obtain overshoot vector
 761    */
 762   Vector2 GetOvershoot(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    */
 769   void ClampPosition(Vector2& position) const;
 770
 771   /**
 772    * Clamps position within the domain set up by X/Y Rulers
 773    *
 774    * @param[in,out] position The position you wish to clamp
 775    * @param[out] clamped The results of the clamping.
 776    */
 777   void ClampPosition(Vector2& position, ClampState2D &clamped) const;
 778
 779   /**
 780    * Wraps position within the domain set up by X/Y Rulers
 781    *
 782    * @note Only wraps if mWrapMode is enabled, and respective domains
 783    * are enabled.
 784    *
 785    * @param[in,out] position The position you wish to wrap
 786    */
 787   void WrapPosition(Vector2& position) const;
 788
 789   /**
 790    * Updates the main internal scroll constraints with new ruler and domain
 791    * values
 792    */
 793   void UpdateMainInternalConstraint();
 794
 795   /**
 796    * Enables/disables the overshoot constraints
 797    *
 798    * @param[in] enabled whether to enable or disable the overshoot constraints
 799    */
 800   void SetOvershootConstraintsEnabled(bool enabled);
 801
 802   /**
 803    * Sets internal constraints for this ScrollView.
 804    * Many of these internal constraints are based on properties within
 805    * ScrollView.
 806    */
 807   void SetInternalConstraints();
 808
 809   /**
 810    * @brief Querying whether ScrollView is currently panning or scrolling
 811    *
 812    * return True if ScrollView is panning or scrolling
 813    */
 814   bool IsPanningOrScrolling() const;
 815
 816 protected:
 817
 818   /**
 819    * Construct a new ScrollView.
 820    */
 821   ScrollView();
 822
 823   /**
 824    * A reference counted object may only be deleted by calling Unreference()
 825    */
 826   virtual ~ScrollView();
 827
 828 private:
 829
 830   /**
 831    * Searches this ScrollView, and attempts to Unbind
 832    * systematically this Actor from the ScrollView attached.
 833    *
 834    * @param[in] child The actor to be unbound.
 835    */
 836   virtual void FindAndUnbindActor(Actor child);
 837
 838   /**
 839    * Gets position property.
 840    *
 841    * @return The current position
 842    */
 843   Vector2 GetPropertyPrePosition() const;
 844
 845   /**
 846    * Gets position property.
 847    *
 848    * @return The current position
 849    */
 850   Vector2 GetPropertyPosition() const;
 851
 852   /**
 853    * Handles a Stopped animation. Its position properties need to be saved, and the animation flag
 854    * switched off.
 855    */
 856   void HandleStoppedAnimation();
 857
 858   /**
 859    * Handles a Stopped animation (whether the animation completed, or was
 860    * manually stopped). Its position properties need to be saved, and the
 861    * animation flag switched off.
 862    */
 863   void HandleSnapAnimationFinished();
 864
 865   /**
 866    * Checks if the property notifications are active and adds them if not
 867    */
 868   void SetScrollUpdateNotification( bool enabled );
 869
 870   /**
 871    * Refresh the ScrollView (used when animating to update application developer of changes)
 872    * @return True if the refresh timer should be kept running.
 873    */
 874   void OnScrollUpdateNotification(Dali::PropertyNotification& source);
 875
 876 private:
 877
 878   // Undefined
 879   ScrollView(const ScrollView&);
 880
 881   // Undefined
 882   ScrollView& operator=(const ScrollView& rhs);
 883
 884 private:
 885
 886   unsigned long mTouchDownTime;         ///< The touch down time
 887
 888   int mGestureStackDepth;               ///< How many gestures are currently occuring.
 889   Vector2 mPanStartPosition;            ///< Where the pan gesture's touch down occured
 890   Vector2 mPanDelta;                    ///< Amount currently panned.
 891
 892   unsigned int mScrollStateFlags;       ///< flags indicating current state of scrolling
 893   // Scroll delegate pre and post position properties...
 894   Vector2 mScrollPrePosition;           ///< Wrapped scroll position, but not clamped
 895   Vector2 mScrollPostPosition;          ///< Wrapped and clamped, this is the final scroll position used
 896   Vector2 mScrollTargetPosition;        ///< Final target position for an animated scroll
 897   Vector2 mDomainOffset;                ///< Domain offset (this keeps track of the domain boundaries that scroll positions traverses)
 898
 899   // Rulers for each axes...
 900   RulerPtr mRulerX;
 901   RulerPtr mRulerY;
 902
 903   // Last property values set to ScrollView
 904   Vector2 mMinScroll;
 905   Vector2 mMaxScroll;
 906
 907   Animation mInternalXAnimation;        ///< Animates mPropertyX to a snap position or application requested scroll position
 908   Animation mInternalYAnimation;        ///< Animates mPropertyY to a snap position or application requested scroll position
 909
 910
 911   Vector2 mLastVelocity;                ///< Record the last velocity from PanGesture (Finish event doesn't have correct velocity)
 912   LockAxis mLockAxis;
 913
 914   Timer mTouchDownTimer;                ///< Used to interrupt snap-animation. This cannot be done in OnTouch without breaking fast flick behavior.
 915
 916   float mScrollUpdateDistance;          ///< Distance for scrolling to travel for the scroll update notifications
 917   Dali::PropertyNotification mScrollXUpdateNotification; ///< scroll x position update notification
 918   Dali::PropertyNotification mScrollYUpdateNotification; ///< scroll y position update notification
 919
 920   Actor mInternalActor;                 ///< Internal actor (we keep internal actors in here e.g. scrollbars, so we can ignore it in searches)
 921
 922   ScrollViewEffectContainer mEffects;   ///< Container keeping track of all the applied effects.
 923
 924   Vector2   mMaxOvershoot;                      ///< Number of scrollable pixels that will take overshoot from 0.0f to 1.0f
 925   Vector2   mUserMaxOvershoot;                  ///< Set by user, allows overriding of default max overshoot for the scroll indicator
 926   float     mSnapOvershootDuration;             ///< Duration for overshoot snapping back to Vector2::ZERO
 927   AlphaFunction mSnapOvershootAlphaFunction;    ///< AlphaFunction to be used for this overshoot.
 928
 929   float mSnapDuration;                          ///< Time for the snap animation to take (in seconds).
 930   AlphaFunction mSnapAlphaFunction;             ///< AlphaFunction to be used for the Snap Animation.
 931
 932   Vector2 mMinFlickDistance;                      ///< Minimum pan distance required for a flick
 933   float mFlickSpeedThreshold;                   ///< Minimum pan speed required for a flick in pixels/ms
 934   float mFlickDuration;                         ///< Time for the flick animation to take (in seconds).
 935   AlphaFunction mFlickAlphaFunction;            ///< AlphaFunction to be used for the Flick Animation.
 936
 937   float mAxisAutoLockGradient;                  ///< Axis Auto-lock gradient threshold. Above this gradient and it will lock scrolling to closest axis.
 938   float mFrictionCoefficient;                   ///< Friction coefficient. Amount of friction to apply to free panning flick animation. in stage.lengths/sec
 939   float mFlickSpeedCoefficient;                 ///< Flick velocity coefficient. Input touch velocity is multiplied by this.
 940   float mMaxFlickSpeed;                         ///< Maximum flick speed. Maximum speed of flick in stage.lengths/sec.
 941
 942   Vector2 mWheelScrollDistanceStep;        ///< The step of scroll distance in actor coordinates in X and Y axes for each wheel event received.
 943
 944   //ScrollInternalConstraintsPtr mScrollInternalConstraints;
 945   Constraint mScrollMainInternalPrePositionConstraint;
 946   Constraint mScrollMainInternalPositionConstraint;
 947   Constraint mScrollMainInternalOvershootXConstraint;
 948   Constraint mScrollMainInternalOvershootYConstraint;
 949   Constraint mScrollMainInternalDeltaConstraint;
 950   Constraint mScrollMainInternalFinalConstraint;
 951   Constraint mScrollMainInternalRelativeConstraint;
 952   Constraint mScrollMainInternalDomainConstraint;
 953   Constraint mScrollMainInternalPrePositionMaxConstraint;
 954
 955   ScrollOvershootIndicatorPtr mOvershootIndicator;
 956   WeakHandle<Toolkit::ScrollBar> mScrollBar;
 957
 958   Toolkit::ScrollView::SnapStartedSignalType mSnapStartedSignal;
 959
 960   bool mInAccessibilityPan:1;             ///< With AccessibilityPan its easier to move between snap positions
 961   bool mScrolling:1;                      ///< Flag indicating whether the scroll view is being scrolled (by user or animation)
 962   bool mScrollInterrupted:1;              ///< Flag set for when a down event interrupts a scroll
 963   bool mPanning:1;                        ///< Whether scroll view is currently panning or not
 964   bool mSensitive:1;                      ///< Scroll Sensitivity Flag.
 965   bool mTouchDownTimeoutReached:1;        ///< Indicates when down event timeout occured without corresponding up event (touch still down)
 966   bool mActorAutoSnapEnabled:1;           ///< Whether to automatically snap to closest actor.
 967   bool mAutoResizeContainerEnabled:1;     ///< Whether to automatically resize container (affects RulerDomain's on X/Y axes)
 968   bool mWrapMode:1;                       ///< Whether to wrap contents based on container size.
 969   bool mAxisAutoLock:1;                   ///< Whether to automatically lock axis when panning.
 970   bool mAlterChild:1;                     ///< Internal flag to control behavior of OnChildAdd/OnChildRemove when Adding internal Actors.
 971   bool mDefaultMaxOvershoot:1;            ///< Whether to use default max overshoot or application defined one
 972   bool mCanScrollHorizontal:1;            ///< Local value of our property to check against
 973   bool mCanScrollVertical:1;              ///< Local value of our property to check against
 974   bool mTransientScrollBar:1;             ///< True if scroll-bar should be automatically show/hidden during/after panning
 975 };
 976
 977 } // namespace Internal
 978
 979 // Helpers for public-api forwarding methods
 980
 981 inline Toolkit::Internal::ScrollView& GetImpl(Toolkit::ScrollView& scrollView)
 982 {
 983   DALI_ASSERT_ALWAYS(scrollView);
 984
 985   Dali::RefObject& handle = scrollView.GetImplementation();
 986
 987   return static_cast<Toolkit::Internal::ScrollView&>(handle);
 988 }
 989
 990 inline const Toolkit::Internal::ScrollView& GetImpl(const Toolkit::ScrollView& scrollView)
 991 {
 992   DALI_ASSERT_ALWAYS(scrollView);
 993
 994   const Dali::RefObject& handle = scrollView.GetImplementation();
 995
 996   return static_cast<const Toolkit::Internal::ScrollView&>(handle);
 997 }
 998
 999 } // namespace Toolkit
1000
1001 } // namespace Dali
1002
1003 #endif // __DALI_TOOLKIT_INTERNAL_SCROLL_VIEW_H__