1 #ifndef __DALI_TOOLKIT_INTERNAL_SCROLL_OVERSHOOT_INDICATOR_H__
2 #define __DALI_TOOLKIT_INTERNAL_SCROLL_OVERSHOOT_INDICATOR_H__
5 // Copyright (c) 2014 Samsung Electronics Co., Ltd.
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
11 // http://floralicense.org/license/
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.
20 #include <dali/dali.h>
31 class ScrollOvershootEffect;
32 class ScrollOvershootEffectGradient;
33 class ScrollOvershootEffectRipple;
34 typedef IntrusivePtr<ScrollOvershootEffect> ScrollOvershootEffectPtr;
35 typedef IntrusivePtr<ScrollOvershootEffectGradient> ScrollOvershootEffectGradientPtr;
36 typedef IntrusivePtr<ScrollOvershootEffectRipple> ScrollOvershootEffectRipplePtr;
38 struct ScrollOvershootIndicator : public Dali::RefObject
43 * ScrollOvershootIndicator constructor.
44 * @param[in] scrollView reference to ScrollView implementation
45 * or horizontally (false)
47 ScrollOvershootIndicator( Scrollable& scrollable);
52 virtual ~ScrollOvershootIndicator();
55 * Enables and disables the indicator
56 * ¶m[in] enable true to enable, false to disable
58 void Enable(bool enable);
61 * Resets the indicator
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.
71 static ScrollOvershootIndicator* New( Scrollable& scrollable);
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
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
83 struct ScrollOvershootEffect : public Dali::RefObject
87 * Create a new overshoot effect, passing in whether it is vertical or horizontal
89 * @param[in] vertical whether this effect is a vertical or horizontal one
91 ScrollOvershootEffect(bool vertical);
96 virtual ~ScrollOvershootEffect() {}
99 * Returns if this is a vertical or horizontal overhoot effect
101 * @return true or false
103 inline bool IsVertical() { return mVertical; }
106 * Applies the indicator effect, all derived effects must implement this function
108 * @param[in] scrollable the scrollable object to apply this effect to
110 virtual void Apply(Scrollable& scrollable) = 0;
113 * Removes the indicator effect, all derived effects must implement this function
115 * @param[in] scrollable the scrollable object to remove this effect from
117 virtual void Remove(Scrollable& scrollable) = 0;
120 * Resets this overshoot effect
122 virtual void Reset() = 0;
125 * Updates the constraints used for the overshoot effect
127 * @param[in] scrollable the container for the overshoot effect
129 virtual void UpdateConstraints(Actor& scrollable) {}
132 * Sets up property notifications for overshoot values
134 * @param[in] scrollable the container for the overshoot effect
136 virtual void SetPropertyNotifications(Actor& scrollable) {}
139 bool mVertical; ///< whether this is a vertical/horizontal effect
143 * OvershootRippleEffect is a custom shader effect for the overshoot indicator
145 class OvershootRippleEffect : public ShaderEffect
150 * Create an uninitialized OvershootRippleEffect; this can be initialized with OvershootRippleEffect::New()
151 * Calling member functions with an uninitialized Dali::Object is not allowed.
153 OvershootRippleEffect();
156 * Virtual destructor.
158 virtual ~OvershootRippleEffect();
161 * Create an initialized OvershootRippleEffect.
163 * @return A handle to a newly allocated Dali resource.
165 static OvershootRippleEffect New();
168 * Set the current overshoot value
170 * @param[in] overshoot current overshoot value in the range [0.0f,1.0f]
172 void SetOvershoot(float overshoot);
175 * Set the number of sub images in the overshoot bounce image
177 * @param[in] imageCount number of sub images in main ripple effect image
179 void SetOvershootImageCount(float imageCount);
182 * Get the name for the overshoot property
183 * which can be used in Animation API's
185 * @return A std::string containing the property name
187 const std::string& GetOvershootPropertyName() const;
190 * Get the name for the sub image count property
191 * which can be used in Animation API's
193 * @return A std::string containing the property name
195 const std::string& GetOvershootImageCountPropertyName() const;
197 private: // Not intended for application developers
198 OvershootRippleEffect(ShaderEffect handle);
202 * ScrollOvershootEffectGradient creates a gradiented effect at the end of the scrollable area if the user
203 * attempts to scroll past it
205 struct ScrollOvershootEffectGradient : public ScrollOvershootEffect
209 * Create a new gradient overshoot effect, passing in whether it is vertical or horizontal
211 * @param[in] vertical whether this effect is a vertical or horizontal one
213 ScrollOvershootEffectGradient(bool vertical);
216 * @copydoc ScrollOvershootEffect::Apply
218 virtual void Apply(Scrollable& scrollable);
221 * @copydoc ScrollOvershootEffect::Remove
223 virtual void Remove(Scrollable& scrollable);
226 * @copydoc ScrollOvershootEffect::Reset
228 virtual void Reset() {}
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
238 Vector3 SizeConstraint(const Vector3& current, const PropertyInput& overshootPropertyX, const PropertyInput& overshootPropertyY, const PropertyInput& parentSizeProperty);
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
247 Quaternion RotationConstraint(const Quaternion& current, const PropertyInput& overshootPropertyX, const PropertyInput& overshootPropertyY);
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
257 Vector3 PositionConstraint(const Vector3& current, const PropertyInput& parentSizeProperty, const PropertyInput& overshootPropertyX, const PropertyInput& overshootPropertyY);
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
266 bool VisibilityConstraint(const bool& current, const PropertyInput& canScrollProperty);
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
273 static ScrollOvershootEffectGradientPtr New( bool vertical );
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
285 * ScrollOvershootEffectRipple creates an animated bounce effect at the end of the scrollable area if the user
286 * attempts to scroll past it
288 struct ScrollOvershootEffectRipple : public ScrollOvershootEffect, public ConnectionTracker
292 * Create a new gradient overshoot effect, passing in whether it is vertical or horizontal
294 ScrollOvershootEffectRipple(bool vertical);
297 * @copydoc ScrollOvershootEffect::Apply
299 virtual void Apply(Scrollable& scrollable);
302 * @copydoc ScrollOvershootEffect::Remove
304 virtual void Remove(Scrollable& scrollable);
307 * @copydoc ScrollOvershootEffect::Reset
309 virtual void Reset();
312 * @copydoc ScrollOvershootEffect::UpdateConstraints(Actor& scrollable)
314 virtual void UpdateConstraints(Actor& scrollable);
317 * @copydoc ScrollOvershootEffect::SetPropertyNotification
319 virtual void SetPropertyNotifications(Actor& scrollable);
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
328 Vector3 PositionConstraint(const Vector3& current, const PropertyInput& parentSizeProperty, const PropertyInput& overshootProperty);
331 * Informs overshoot effect to update image position and to animate effect overshoot value for a
332 * positive overshoot value from scrollview
334 * @param[in] source the property notification that triggered this callback
336 void OnPositiveOvershootNotification(PropertyNotification& source);
339 * Informs overshoot effect to update image position and to animate effect overshoot value for a
340 * negative overshoot value from scrollview
342 * @param[in] source the property notification that triggered this callback
344 void OnNegativeOvershootNotification(PropertyNotification& source);
347 * Function to animate effect overshoot value either to -1.0f/1.0f or 0.0f
349 * @param[in] overshootAmount the amount to animate overshoot to [-1.0f,0.0f,1.0f]
351 void AnimateScrollOvershoot(float overshootAmount);
354 * Connects to the animation finished signal of our overshoot animation
356 * @param[in] animation the animation instance that has finished
358 void OnOvershootAnimFinished(Animation& animation);
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
365 static ScrollOvershootEffectRipplePtr New( bool vertical );
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
382 } // namespace Internal
384 } // namespace Toolkit
388 #endif // __DALI_TOOLKIT_INTERNAL_SCROLL_OVERSHOOT_INDICATOR_H__