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