dali-toolkit/internal/controls/scrollable/scroll-view/scroll-overshoot-indicator-impl.h

   1 #ifndef __DALI_TOOLKIT_INTERNAL_SCROLL_OVERSHOOT_INDICATOR_H__
   2 #define __DALI_TOOLKIT_INTERNAL_SCROLL_OVERSHOOT_INDICATOR_H__
   3
   4 //
   5 // Copyright (c) 2014 Samsung Electronics Co., Ltd.
   6 //
   7 // Licensed under the Flora License, Version 1.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://floralicense.org/license/
  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 #include <dali/dali.h>
  21
  22 namespace Dali
  23 {
  24
  25 namespace Toolkit
  26 {
  27
  28 namespace Internal
  29 {
  30 class Scrollable;
  31 class ScrollOvershootEffect;
  32 class ScrollOvershootEffectGradient;
  33 class ScrollOvershootEffectRipple;
  34 typedef IntrusivePtr<ScrollOvershootEffect> ScrollOvershootEffectPtr;
  35 typedef IntrusivePtr<ScrollOvershootEffectGradient> ScrollOvershootEffectGradientPtr;
  36 typedef IntrusivePtr<ScrollOvershootEffectRipple> ScrollOvershootEffectRipplePtr;
  37
  38 struct ScrollOvershootIndicator : public Dali::RefObject
  39 {
  40 public:
  41
  42   /**
  43    * ScrollOvershootIndicator constructor.
  44    * @param[in] scrollView reference to ScrollView implementation
  45    * or horizontally (false)
  46    */
  47   ScrollOvershootIndicator( Scrollable& scrollable);
  48
  49   /**
  50    * Virtual destructor
  51    */
  52   virtual ~ScrollOvershootIndicator();
  53
  54   /**
  55    * Enables and disables the indicator
  56    * &param[in] enable true to enable, false to disable
  57    */
  58   void Enable(bool enable);
  59
  60   /**
  61    * Resets the indicator
  62    */
  63   void Reset();
  64
  65   /**
  66    * Create an initialized ScrollOvershootIndicator
  67    * @param[in] scrollView reference to ScrollView implementation
  68    * or horizontally (false)
  69    * @return A pointer to the created ScrollOvershootIndicator.
  70    */
  71   static ScrollOvershootIndicator* New( Scrollable& scrollable);
  72
  73 private:
  74   Scrollable& mScrollable;                                ///< Internal::Scrollable object
  75   ScrollOvershootEffectPtr mEffectX;                      ///< effect used for x-axis/horizontal display
  76   ScrollOvershootEffectPtr mEffectY;                      ///< effect used for y-axis/vertical display
  77 };
  78
  79 /**
  80  * ScrollOvershootEffect is a derivable class, designed to allow the application programmer to create their own
  81  * overshoot effect and apply it with minimal implementation required
  82  */
  83 struct ScrollOvershootEffect : public Dali::RefObject
  84 {
  85 public:
  86   /**
  87    * Create a new overshoot effect, passing in whether it is vertical or horizontal
  88    *
  89    * @param[in] vertical whether this effect is a vertical or horizontal one
  90    */
  91   ScrollOvershootEffect(bool vertical);
  92
  93   /**
  94    * Virtual destructor
  95    */
  96   virtual ~ScrollOvershootEffect() {}
  97
  98   /**
  99    * Returns if this is a vertical or horizontal overhoot effect
 100    *
 101    * @return true or false
 102    */
 103   inline bool IsVertical() { return mVertical; }
 104
 105   /**
 106    * Applies the indicator effect, all derived effects must implement this function
 107    *
 108    * @param[in] scrollable the scrollable object to apply this effect to
 109    */
 110   virtual void Apply(Scrollable& scrollable) = 0;
 111
 112   /**
 113    * Removes the indicator effect, all derived effects must implement this function
 114    *
 115    * @param[in] scrollable the scrollable object to remove this effect from
 116    */
 117   virtual void Remove(Scrollable& scrollable) = 0;
 118
 119   /**
 120    * Resets this overshoot effect
 121    */
 122   virtual void Reset() = 0;
 123
 124   /**
 125    * Updates the constraints used for the overshoot effect
 126    *
 127    * @param[in] scrollable the container for the overshoot effect
 128    */
 129   virtual void UpdateConstraints(Actor& scrollable) {}
 130
 131   /**
 132    * Sets up property notifications for overshoot values
 133    *
 134    * @param[in] scrollable the container for the overshoot effect
 135    */
 136   virtual void SetPropertyNotifications(Actor& scrollable) {}
 137
 138 private:
 139   bool mVertical;                      ///< whether this is a vertical/horizontal effect
 140 };
 141
 142 /**
 143  * OvershootRippleEffect is a custom shader effect for the overshoot indicator
 144  */
 145 class OvershootRippleEffect : public ShaderEffect
 146 {
 147 public:
 148
 149   /**
 150    * Create an uninitialized OvershootRippleEffect; this can be initialized with OvershootRippleEffect::New()
 151    * Calling member functions with an uninitialized Dali::Object is not allowed.
 152    */
 153   OvershootRippleEffect();
 154
 155   /**
 156    * Virtual destructor.
 157    */
 158   virtual ~OvershootRippleEffect();
 159
 160   /**
 161    * Create an initialized OvershootRippleEffect.
 162    *
 163    * @return A handle to a newly allocated Dali resource.
 164    */
 165   static OvershootRippleEffect New();
 166
 167   /**
 168    * Set the current overshoot value
 169    *
 170    * @param[in] overshoot current overshoot value in the range [0.0f,1.0f]
 171    */
 172   void SetOvershoot(float overshoot);
 173
 174   /**
 175    * Set the number of sub images in the overshoot bounce image
 176    *
 177    * @param[in] imageCount number of sub images in main ripple effect image
 178    */
 179   void SetOvershootImageCount(float imageCount);
 180
 181   /**
 182    * Get the name for the overshoot property
 183    * which can be used in Animation API's
 184    *
 185    * @return A std::string containing the property name
 186    */
 187   const std::string& GetOvershootPropertyName() const;
 188
 189   /**
 190    * Get the name for the sub image count property
 191    * which can be used in Animation API's
 192    *
 193    * @return A std::string containing the property name
 194    */
 195   const std::string& GetOvershootImageCountPropertyName() const;
 196
 197 private: // Not intended for application developers
 198   OvershootRippleEffect(ShaderEffect handle);
 199 };
 200
 201 /**
 202  * ScrollOvershootEffectGradient creates a gradiented effect at the end of the scrollable area if the user
 203  * attempts to scroll past it
 204  */
 205 struct ScrollOvershootEffectGradient : public ScrollOvershootEffect
 206 {
 207 public:
 208   /**
 209    * Create a new gradient overshoot effect, passing in whether it is vertical or horizontal
 210    *
 211    * @param[in] vertical whether this effect is a vertical or horizontal one
 212    */
 213   ScrollOvershootEffectGradient(bool vertical);
 214
 215   /**
 216    * @copydoc ScrollOvershootEffect::Apply
 217    */
 218   virtual void Apply(Scrollable& scrollable);
 219
 220   /**
 221    * @copydoc ScrollOvershootEffect::Remove
 222    */
 223   virtual void Remove(Scrollable& scrollable);
 224
 225   /**
 226    * @copydoc ScrollOvershootEffect::Reset
 227    */
 228   virtual void Reset() {}
 229
 230   /**
 231    * Constrains the size of the gradient image
 232    * @param[in] current current size of the image actor
 233    * @param[in] overshootPropertyX current overshoot x amount
 234    * @param[in] overshootPropertyY current overshoot y amount
 235    * @param[in] parentSizeProperty size of the scrollable area so we can make sure the image stretches across it
 236    * @return the new size of the image depending on the overshoot amount
 237    */
 238   Vector3 SizeConstraint(const Vector3& current, const PropertyInput& overshootPropertyX, const PropertyInput& overshootPropertyY, const PropertyInput& parentSizeProperty);
 239
 240   /**
 241    * Constrains the size of the gradient image
 242    * @param[in] current current rotation of the image actor
 243    * @param[in] overshootPropertyX current overshoot x amount
 244    * @param[in] overshootPropertyY current overshoot y amount
 245    * @return new rotation os the gradient image actor
 246    */
 247   Quaternion RotationConstraint(const Quaternion& current, const PropertyInput& overshootPropertyX, const PropertyInput& overshootPropertyY);
 248
 249   /**
 250    * Constrains the size of the gradient image
 251    * @param[in] current current position of the image actor
 252    * @param[in] parentSizeProperty size of the scrollable area so we can position image on the edge of it
 253    * @param[in] overshootPropertyX current overshoot x amount
 254    * @param[in] overshootPropertyY current overshoot y amount
 255    * @return new position of the gradient image actor
 256    */
 257   Vector3 PositionConstraint(const Vector3& current, const PropertyInput& parentSizeProperty, const PropertyInput& overshootPropertyX, const PropertyInput& overshootPropertyY);
 258
 259   /**
 260    * Constrains the size of the gradient image
 261    * @param[in] current current visibility of the image actor
 262    * @param[in] overshootPropertyX current overshoot x amount
 263    * @param[in] overshootPropertyY current overshoot y amount
 264    * @return new visibility property depending on overshoot values
 265    */
 266   bool VisibilityConstraint(const bool& current, const PropertyInput& canScrollProperty);
 267
 268   /**
 269    * Creates a new ScrollOvershootEffectGradient objects and returns a pointer to it
 270    * @param[in] vertical whether to create a vertical(true) or horizontal effect
 271    * @return a pointer to the new effect
 272    */
 273   static ScrollOvershootEffectGradientPtr New( bool vertical );
 274
 275 private:
 276   float mMaxOvershootImageSize;            ///< maximum size of the image when overshoot value is 1.0f
 277   ImageActor mOvershootImage;              ///< the overshoot image...
 278   ActiveConstraint    mSizeConstraint;     ///< active constraint handle used to store the image width constraint
 279   ActiveConstraint    mRotationConstraint; ///< active constraint handle used to store the image rotation constraint
 280   ActiveConstraint    mPositionConstraint; ///< active constraint handle used to store the image position constraint
 281   ActiveConstraint    mVisibilityConstraint; ///< active constraint handle used to store the image visibility constraint
 282 };
 283
 284 /**
 285  * ScrollOvershootEffectRipple creates an animated bounce effect at the end of the scrollable area if the user
 286  * attempts to scroll past it
 287  */
 288 struct ScrollOvershootEffectRipple : public ScrollOvershootEffect, public ConnectionTracker
 289 {
 290 public:
 291   /**
 292    * Create a new gradient overshoot effect, passing in whether it is vertical or horizontal
 293    */
 294   ScrollOvershootEffectRipple(bool vertical);
 295
 296   /**
 297    * @copydoc ScrollOvershootEffect::Apply
 298    */
 299   virtual void Apply(Scrollable& scrollable);
 300
 301   /**
 302    * @copydoc ScrollOvershootEffect::Remove
 303    */
 304   virtual void Remove(Scrollable& scrollable);
 305
 306   /**
 307    * @copydoc ScrollOvershootEffect::Reset
 308    */
 309   virtual void Reset();
 310
 311   /**
 312    * @copydoc ScrollOvershootEffect::UpdateConstraints(Actor& scrollable)
 313    */
 314   virtual void UpdateConstraints(Actor& scrollable);
 315
 316   /**
 317    * @copydoc ScrollOvershootEffect::SetPropertyNotification
 318    */
 319   virtual void SetPropertyNotifications(Actor& scrollable);
 320
 321   /**
 322    * Constrains the size of the gradient image
 323    * @param[in] current current position of the image actor
 324    * @param[in] parentSizeProperty size of the scrollable area so we can position image on the edge of it
 325    * @param[in] overshootProperty current overshoot amount for this indicator's axis
 326    * @return new position of the gradient image actor
 327    */
 328   Vector3 PositionConstraint(const Vector3& current, const PropertyInput& parentSizeProperty, const PropertyInput& overshootProperty);
 329
 330   /**
 331    * Informs overshoot effect to update image position and to animate effect overshoot value for a
 332    * positive overshoot value from scrollview
 333    *
 334    * @param[in] source the property notification that triggered this callback
 335    */
 336   void OnPositiveOvershootNotification(PropertyNotification& source);
 337
 338   /**
 339    * Informs overshoot effect to update image position and to animate effect overshoot value for a
 340    * negative overshoot value from scrollview
 341    *
 342    * @param[in] source the property notification that triggered this callback
 343    */
 344   void OnNegativeOvershootNotification(PropertyNotification& source);
 345
 346   /**
 347    * Function to animate effect overshoot value either to -1.0f/1.0f or 0.0f
 348    *
 349    * @param[in] overshootAmount the amount to animate overshoot to [-1.0f,0.0f,1.0f]
 350    */
 351   void AnimateScrollOvershoot(float overshootAmount);
 352
 353   /**
 354    * Connects to the animation finished signal of our overshoot animation
 355    *
 356    * @param[in] animation the animation instance that has finished
 357    */
 358   void OnOvershootAnimFinished(Animation& animation);
 359
 360   /**
 361    * Creates a new ScrollOvershootEffectGradient objects and returns a pointer to it
 362    * @param[in] vertical whether to create a vertical(true) or horizontal effect
 363    * @return a pointer to the new effect
 364    */
 365   static ScrollOvershootEffectRipplePtr New( bool vertical );
 366
 367 private:
 368
 369   float mMaxOvershootImageSize;            ///< maximum size of the image when overshoot value is 1.0f
 370   ImageActor mOvershootImage;              ///< the overshoot image...
 371   Animation mScrollOvershootAnimation;     ///< animation
 372   bool      mAnimatingOvershootOn;         ///< whether we are currently animating overshoot to 1.0f/-1.0f (on) or to 0.0f (off)
 373   bool      mAnimateOvershootOff;          ///< whether we are currently animating overshoot to 1.0f/-1.0f (on) or to 0.0f (off)
 374   int       mCanScrollPropertyIndex;       ///< property index to a property that informs indicator if it is needed
 375   OvershootRippleEffect mRippleEffect;                 // the ripple vertex/fragment shader effect
 376   PropertyNotification mOvershootPositiveNotification; // stores the property notification used for positive overshoot values
 377   PropertyNotification mOvershootNegativeNotification; // stores the property notification used for negative overshoot values
 378   ActiveConstraint    mSizeConstraint;                 // active constraint handle used to store the image width constraint
 379   ActiveConstraint    mPositionConstraint;             // active constraint handle used to store the image position constraint
 380 };
 381
 382 } // namespace Internal
 383
 384 } // namespace Toolkit
 385
 386 } // namespace Dali
 387
 388 #endif // __DALI_TOOLKIT_INTERNAL_SCROLL_OVERSHOOT_INDICATOR_H__