X-Git-Url: http://review.tizen.org/git/?p=platform%2Fcore%2Fuifw%2Fdali-toolkit.git;a=blobdiff_plain;f=dali-toolkit%2Fpublic-api%2Fcontrols%2Fscrollable%2Fscrollable.h;h=38050ae8e09b3cfdb02705f82a1b3346a14eb217;hp=907f7a1911031a5b30ae6564e4cb6c6820fce6af;hb=b694e7e2ae624e206e1548b1a863c554eb9cd4d7;hpb=57869973578f6a0b0f836d396c7232ddb8302c6b diff --git a/dali-toolkit/public-api/controls/scrollable/scrollable.h b/dali-toolkit/public-api/controls/scrollable/scrollable.h index 907f7a1..38050ae 100644 --- a/dali-toolkit/public-api/controls/scrollable/scrollable.h +++ b/dali-toolkit/public-api/controls/scrollable/scrollable.h @@ -1,8 +1,8 @@ -#ifndef __DALI_TOOLKIT_SCROLLABLE_H__ -#define __DALI_TOOLKIT_SCROLLABLE_H__ +#ifndef DALI_TOOLKIT_SCROLLABLE_H +#define DALI_TOOLKIT_SCROLLABLE_H /* - * Copyright (c) 2014 Samsung Electronics Co., Ltd. + * Copyright (c) 2019 Samsung Electronics Co., Ltd. * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. @@ -31,129 +31,94 @@ namespace Internal DALI_INTERNAL { class Scrollable; } - -/** - * @brief How axes/rotation or scale are clamped - */ -enum ClampState -{ - NotClamped, ///< The quantity isn't clamped - ClampedToMin, ///< The quantity is clamped to the min value - ClampedToMax ///< The quantity is clamped to the max value -}; - -/** - * @brief A 2 dimensional clamp - */ -struct ClampState2 -{ - ClampState x; ///< The clamp state of the x axis - ClampState y; ///< The clamp state of the y axis -}; - /** - * @brief A 3 dimensional clamp + * @addtogroup dali_toolkit_controls_scrollable + * @{ */ -struct ClampState3 -{ - ClampState x; ///< The clamp state of the x axis - ClampState y; ///< The clamp state of the y axis - ClampState z; ///< The clamp state of the z axis -}; /** * @brief Base class for derived Scrollables that contains actors that can be scrolled manually * (via touch) or automatically. * * Scrollables such as ScrollView and ItemView can be derived from this class. + * + * Signals + * | %Signal Name | Method | + * |------------------|------------------------------| + * | scrollStarted | @ref ScrollStartedSignal() | + * | scrollCompleted | @ref ScrollCompletedSignal() | + * | scrollUpdated | @ref ScrollUpdatedSignal() | + * @SINCE_1_0.0 */ -class DALI_IMPORT_API Scrollable : public Control +class DALI_TOOLKIT_API Scrollable : public Control { public: /** - * @brief Clamp signal event's data + * @brief Enumeration for the start and end property ranges for this control. + * @SINCE_1_0.0 */ - struct ClampEvent + enum PropertyRange { - ClampState3 scale; ///< Clamp information for scale axes - ClampState3 position; ///< Clamp information for position axes - ClampState rotation; ///< Clamp information for rotation + PROPERTY_START_INDEX = Control::CONTROL_PROPERTY_END_INDEX + 1, ///< @SINCE_1_0.0 + PROPERTY_END_INDEX = PROPERTY_START_INDEX + 1000, ///< Reserve property indices @SINCE_1_0.0 + + ANIMATABLE_PROPERTY_START_INDEX = ANIMATABLE_PROPERTY_REGISTRATION_START_INDEX, + ANIMATABLE_PROPERTY_END_INDEX = ANIMATABLE_PROPERTY_REGISTRATION_START_INDEX + 1000 ///< Reserve animatable property indices @SINCE_1_0.0 }; /** - * @brief Scroll component types + * @brief Enumeration for the instance of properties belonging to the Scrollable class. + * @SINCE_1_0.0 */ - enum ScrollComponentType + struct Property { - HorizontalScrollBar, - VerticalScrollBar, - OvershootIndicator, + /** + * @brief Enumeration for the instance of properties belonging to the Scrollable class. + * @SINCE_1_0.0 + */ + enum + { + // Event side properties + OVERSHOOT_EFFECT_COLOR = PROPERTY_START_INDEX, ///< Property, name "overshootEffectColor", @see SetOvershootEffectColor(), type Vector4 @SINCE_1_0.0 + OVERSHOOT_ANIMATION_SPEED, ///< Property, name "overshootAnimationSpeed", @see SetOvershootAnimationSpeed(), type float @SINCE_1_0.0 + OVERSHOOT_ENABLED, ///< Property, name "overshootEnabled", @see SetOvershootEnabled(), type bool, @SINCE_1_1.18 + OVERSHOOT_SIZE, ///< Property, name "overshootSize", type Vector2, @SINCE_1_1.31 + SCROLL_TO_ALPHA_FUNCTION, ///< Property, name "scrollToAlphaFunction", type int, @SINCE_1_1.33 + + // Animatable properties + SCROLL_RELATIVE_POSITION = ANIMATABLE_PROPERTY_START_INDEX, ///< Property, name "scrollRelativePosition", type Vector2 @SINCE_1_0.0 + SCROLL_POSITION_MIN, ///< Property, name "scrollPositionMin", type Vector2 @SINCE_1_0.0 + SCROLL_POSITION_MIN_X, ///< Property, name "scrollPositionMinX", type float @SINCE_1_0.0 + SCROLL_POSITION_MIN_Y, ///< Property, name "scrollPositionMinY", type float @SINCE_1_0.0 + SCROLL_POSITION_MAX, ///< Property, name "scrollPositionMax", type Vector2 @SINCE_1_0.0 + SCROLL_POSITION_MAX_X, ///< Property, name "scrollPositionMaxX", type float @SINCE_1_0.0 + SCROLL_POSITION_MAX_Y, ///< Property, name "scrollPositionMaxY", type float @SINCE_1_0.0 + CAN_SCROLL_VERTICAL, ///< Property, name "canScrollVertical", type bool @SINCE_1_0.0 + CAN_SCROLL_HORIZONTAL ///< Property, name "canScrollHorizontal", type bool @SINCE_1_0.0 + }; }; - // Custom properties - - static const std::string SCROLL_RELATIVE_POSITION_PROPERTY_NAME; ///< Property, name "scroll-relative-position", type VECTOR3 - static const std::string SCROLL_POSITION_MIN_PROPERTY_NAME; ///< Property, name "scroll-position-min", type VECTOR3 - static const std::string SCROLL_POSITION_MAX_PROPERTY_NAME; ///< Property, name "scroll-position-max", type VECTOR3 - static const std::string SCROLL_DIRECTION_PROPERTY_NAME; ///< Property, name "scroll-direction", type VECTOR2 + // Typedefs - /// @name Properties - /** @{ */ - static const Property::Index PROPERTY_OVERSHOOT_EFFECT_COLOR; ///< Property, name "overshoot-effect-color", @see SetOvershootEffectColor(), type VECTOR4 - static const Property::Index PROPERTY_OVERSHOOT_ANIMATION_SPEED; ///< Property, name "overshoot-animation-speed", @see SetOvershootAnimationSpeed(), type FLOAT - /** @} */ - - /// @name Signals - /** @{ */ - static const char* const SIGNAL_SCROLL_STARTED; ///< "scroll-started"; - static const char* const SIGNAL_SCROLL_COMPLETED; ///< "scroll-completed"; - static const char* const SIGNAL_SCROLL_UPDATED; ///< "scroll-updated"; - static const char* const SIGNAL_SCROLL_CLAMPED; ///< "scroll-clamped"; - /** @} */ - -public: - - typedef Signal< void ( const Vector3& ) > ScrollStartedSignalType; ///< ScrollStarted signal type - typedef Signal< void ( const Vector3& ) > ScrollCompletedSignalType; ///< ScrollCompleted signal type - typedef Signal< void ( const Vector3& ) > ScrollUpdatedSignalType; ///< Scroll updated signal type - typedef Signal< void ( const ClampEvent& ) > ScrollClampedSignalType; ///< Scroll clamped signal type - - /** - * @brief Signal emitted when the Scrollable has moved (whether by touch or animation). - */ - ScrollStartedSignalType& ScrollStartedSignal(); - - /** - * @brief Signal emitted when the Scrollable has moved (whether by touch or animation). - */ - ScrollUpdatedSignalType& ScrollUpdatedSignal(); - - /** - * @brief Signal emitted when the Scrollable has completed movement (whether by touch or animation). - */ - ScrollCompletedSignalType& ScrollCompletedSignal(); - - /** - * @brief Signal emitted when the Scrollable is pushing against a domain boundary - * (in either position, scale, or rotation). - * - * @return The signal to connect to - */ - ScrollClampedSignalType& ScrollClampedSignal(); + typedef Signal< void ( const Vector2& ) > ScrollStartedSignalType; ///< ScrollStarted signal type @SINCE_1_0.0 + typedef Signal< void ( const Vector2& ) > ScrollCompletedSignalType; ///< ScrollCompleted signal type @SINCE_1_0.0 + typedef Signal< void ( const Vector2& ) > ScrollUpdatedSignalType; ///< Scroll updated signal type @SINCE_1_0.0 public: /** * @brief Creates an uninitialized Scrollable handle. + * @SINCE_1_0.0 */ Scrollable(); /** * @brief Copy constructor. * - * Creates another handle that points to the same real object + * Creates another handle that points to the same real object. * + * @SINCE_1_0.0 * @param handle to copy from */ Scrollable( const Scrollable& handle ); @@ -161,97 +126,147 @@ public: /** * @brief Assignment operator. * - * Changes this handle to point to another real object - * @param[in] handle to copy from + * Changes this handle to point to another real object. + * @SINCE_1_0.0 + * @param[in] handle Handle to copy from * @return A reference to this */ Scrollable& operator=( const Scrollable& handle ); /** - * @brief Destructor + * @brief Destructor. * * This is non-virtual since derived Handle types must not contain data or virtual methods. + * @SINCE_1_0.0 */ ~Scrollable(); /** - * @brief Downcast an Object handle to Scrollable. + * @brief Downcasts a handle to Scrollable handle. * - * If handle points to a Scrollable the downcast produces valid - * handle. If not the returned handle is left uninitialized. + * If handle points to a Scrollable, the downcast produces valid handle. + * If not, the returned handle is left uninitialized. * + * @SINCE_1_0.0 * @param[in] handle Handle to an object - * @return handle to a Scrollable or an uninitialized handle + * @return A handle to a Scrollable or an uninitialized handle */ static Scrollable DownCast( BaseHandle handle ); /** - * @brief Checks if a ScrollComponent has been enabled or not. - * - * @param[in] type The Scroll Component Type to check - * @return True (if Enabled) - */ - bool IsScrollComponentEnabled(Scrollable::ScrollComponentType type) const; - - /** - * @brief Enables a ScrollComponent. + * @brief Checks if scroll overshoot has been enabled or not. * - * @param[in] type The Scroll Component Type to enable + * @SINCE_1_0.0 + * @return Whether the scroll overshoot is enabled */ - void EnableScrollComponent(Scrollable::ScrollComponentType type); + bool IsOvershootEnabled() const; /** - * @brief Disables a ScrollComponent. + * @brief Sets whether to enables or disable scroll overshoot. * - * @param[in] type The Scroll Component Type to disable + * @SINCE_1_0.0 + * @param[in] enable Whether to enable the scroll overshoot or not */ - void DisableScrollComponent(Scrollable::ScrollComponentType type); + void SetOvershootEnabled(bool enable); /** - * @brief Set the color of the overshoot effect. + * @brief Sets the color of the overshoot effect. * - * @param[in] color The color of the overshoot effect. + * @SINCE_1_0.0 + * @param[in] color The color of the overshoot effect */ void SetOvershootEffectColor( const Vector4& color ); /** - * @brief Get the color of the overshoot effect. - * @return The color of the overshoot effect. + * @brief Gets the color of the overshoot effect. + * @SINCE_1_0.0 + * @return The color of the overshoot effect */ Vector4 GetOvershootEffectColor() const; /** - * @brief Set the speed of overshoot animation in pixels per second. + * @brief Sets the speed of overshoot animation in pixels per second. + * * When the speed is not greater than 0, the overshoot is set instantly with no animation. - * @param[in] pixelsPerSecond The speed of the overshoot animation. + * @SINCE_1_0.0 + * @param[in] pixelsPerSecond The speed of the overshoot animation */ void SetOvershootAnimationSpeed( float pixelsPerSecond ); /** - * @brief Get the speed of overshoot animation in pixels per second. - * @return The speed of the overshoot animation. + * @brief Gets the speed of overshoot animation in pixels per second. + * @SINCE_1_0.0 + * @return The speed of the overshoot animation */ float GetOvershootAnimationSpeed() const; +public: // Signals + + /** + * @brief Signal emitted when the Scrollable has moved (whether by touch or animation). + * + * A callback of the following type may be connected: + * @code + * void YourCallbackName(const Vector2& currentScrollPosition); + * @endcode + * @SINCE_1_0.0 + * @return The signal to connect to + * @pre The Object has been initialized. + */ + ScrollStartedSignalType& ScrollStartedSignal(); + + /** + * @brief Signal emitted when the Scrollable has moved (whether by touch or animation). + * + * A callback of the following type may be connected: + * @code + * void YourCallbackName(const Vector2& currentScrollPosition); + * @endcode + * @SINCE_1_0.0 + * @return The signal to connect to + * @pre The Object has been initialized. + */ + ScrollUpdatedSignalType& ScrollUpdatedSignal(); + + /** + * @brief Signal emitted when the Scrollable has completed movement (whether by touch or animation). + * + * A callback of the following type may be connected: + * @code + * void YourCallbackName(const Vector2& currentScrollPosition); + * @endcode + * @SINCE_1_0.0 + * @return The signal to connect to + * @pre The Object has been initialized. + */ + ScrollCompletedSignalType& ScrollCompletedSignal(); + public: // Not intended for application developers + /// @cond internal /** * @brief Creates a handle using the Toolkit::Internal implementation. * - * @param[in] implementation The Control implementation. + * @SINCE_1_0.0 + * @param[in] implementation The Control implementation */ DALI_INTERNAL Scrollable(Internal::Scrollable& implementation); /** * @brief Allows the creation of this Control from an Internal::CustomActor pointer. * - * @param[in] internal A pointer to the internal CustomActor. + * @SINCE_1_0.0 + * @param[in] internal A pointer to the internal CustomActor */ explicit DALI_INTERNAL Scrollable( Dali::Internal::CustomActor* internal ); + /// @endcond }; +/** + * @} + */ } // namespace Toolkit } // namespace Dali -#endif // __DALI_TOOLKIT_SCROLLABLE_H__ +#endif // DALI_TOOLKIT_SCROLLABLE_H