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