X-Git-Url: http://review.tizen.org/git/?p=platform%2Fcore%2Fuifw%2Fdali-toolkit.git;a=blobdiff_plain;f=dali-toolkit%2Fpublic-api%2Fcontrols%2Fscroll-bar%2Fscroll-bar.h;h=3f1ad10bee0e51fe2f0bba20e0209f54df6e23bd;hp=f246c937396075855410abf8a7aae431b052b8f5;hb=07bbc876b9b069903dd4ed86c9dd5f2f66fc3b86;hpb=ee3bdc95f623f41feb37be10f21bef1d9da1e805 diff --git a/dali-toolkit/public-api/controls/scroll-bar/scroll-bar.h b/dali-toolkit/public-api/controls/scroll-bar/scroll-bar.h index f246c93..3f1ad10 100755 --- a/dali-toolkit/public-api/controls/scroll-bar/scroll-bar.h +++ b/dali-toolkit/public-api/controls/scroll-bar/scroll-bar.h @@ -2,7 +2,7 @@ #define __DALI_TOOLKIT_SCROLL_BAR_H__ /* - * Copyright (c) 2014 Samsung Electronics Co., Ltd. + * Copyright (c) 2015 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. @@ -18,11 +18,8 @@ * */ -// EXTERNAL INCLUDES -#include - // INTERNAL INCLUDES -#include +#include namespace Dali { @@ -30,41 +27,75 @@ namespace Dali namespace Toolkit { -// Forward declarations -class ScrollConnector; - namespace Internal DALI_INTERNAL { // Forward declarations class ScrollBar; } +/** + * @addtogroup dali-toolkit-controls-scroll-bar + * @{ + */ /** - * ScrollBar is a UI component that can be added to the scrollable controls - * indicating the current scroll position of the scrollable content. + * ScrollBar is a UI component that can be linked to the scrollable objects + * indicating the current scroll position of the scrollable object. * * Signals - * | %Signal Name | Method | - * |--------------------------|-------------------------------------| - * | scroll-position-notified | @ref ScrollPositionNotifiedSignal() | + * | %Signal Name | Method | + * |----------------------------------|--------------------------------------------| + * | pan-finished | @ref PanFinishedSignal() | + * | scroll-position-interval-reached | @ref ScrollPositionIntervalReachedSignal() | */ -class DALI_IMPORT_API ScrollBar : public ScrollComponent +class DALI_IMPORT_API ScrollBar : public Control { public: + // Properties + + /** + * @brief The start and end property ranges for this control. + */ + enum PropertyRange + { + PROPERTY_START_INDEX = Control::CONTROL_PROPERTY_END_INDEX + 1, + PROPERTY_END_INDEX = PROPERTY_START_INDEX + 1000 ///< Reserve property indices + }; + + /** + * @brief An enumeration of properties belonging to the ScrollBar class. + */ + struct Property + { + enum + { + SCROLL_DIRECTION = PROPERTY_START_INDEX, ///< name "scroll-direction", @see SetScrollDirection(), type std::string + INDICATOR_HEIGHT_POLICY, ///< name "indicator-height-policy", @see SetIndicatorHeightPolicy(), type std::string + INDICATOR_FIXED_HEIGHT, ///< name "indicator-fixed-height", @see SetIndicatorFixedHeight(), type float + INDICATOR_SHOW_DURATION, ///< name "indicator-show-duration", @see SetIndicatorShowDuration(), type float + INDICATOR_HIDE_DURATION, ///< name "indicator-hide-duration", @see SetIndicatorHideDuration(), type float + SCROLL_POSITION_INTERVALS ///< name "scroll-position-intervals",@see SetScrollPositionIntervals() type Property::Array + }; + }; + // Signals - typedef Signal< void ( float ) > ScrollPositionNotifiedSignalType; - // Properties - static const Property::Index PROPERTY_INDICATOR_HEIGHT_POLICY; ///< name "indicator-height-policy", @see SetIndicatorHeightPolicy(), type STRING - static const Property::Index PROPERTY_INDICATOR_FIXED_HEIGHT; ///< name "indicator-fixed-height", @see SetIndicatorFixedHeight(), type FLOAT - static const Property::Index PROPERTY_INDICATOR_SHOW_DURATION; ///< name "indicator-show-duration", @see SetIndicatorShowDuration(), type FLOAT - static const Property::Index PROPERTY_INDICATOR_HIDE_DURATION; ///< name "indicator-hide-duration", @see SetIndicatorHideDuration(), type FLOAT + typedef Signal< void () > PanFinishedSignalType; + typedef Signal< void ( float ) > ScrollPositionIntervalReachedSignalType; public: /** + * @brief Direction. + */ + enum Direction + { + Vertical = 0, ///< Scroll in the vertical direction + Horizontal ///< Scroll in the horizontal direction + }; + + /** * @brief Indicator height policy. */ enum IndicatorHeightPolicy @@ -76,7 +107,6 @@ public: /** * @brief Create an uninitialized ScrollBar; this can be initialized with ScrollBar::New() * Calling member functions with an uninitialized Dali::Object is not allowed. - * or horizontally (false) */ ScrollBar(); @@ -99,9 +129,10 @@ public: /** * @brief Create an initialized ScrollBar + * @param[in] direction The direction of scroll bar (either vertically or horizontally). * @return A pointer to the created ScrollBar. */ - static ScrollBar New(); + static ScrollBar New(Direction direction = Vertical); /** * @brief Downcast an Object handle to ScrollBar. If handle points to a ScrollBar the @@ -112,17 +143,26 @@ public: static ScrollBar DownCast( BaseHandle handle ); /** - * @brief Sets the image for the indicator of scroll bar. + * @brief Set the source of the scroll position properties. * - * @pre The scroll bar actor has been initialised. + * * @pre The handle to the object owing the scroll properties has been initialised and the property index must be vaild. * - * The indicator image is resized (stretched according to scale settings), - * to reflect the size of the scroll indicator and minimum/maximum limits - * of the scroll position. + * @param[in] handle The handle of the object owing the scroll properties. + * @param[in] propertyScrollPosition The index of the scroll position property (The scroll position, type float). + * @param[in] propertyMinScrollPosition The index of the minimum scroll position property (The minimum scroll position, type float). + * @param[in] propertyMaxScrollPosition The index of the maximum scroll position property (The maximum scroll position, type float). + * @param[in] propertyScrollContentSize The index of the scroll content size property (The size of the scrollable content in actor coordinates, type float). + */ + void SetScrollPropertySource( Handle handle, Dali::Property::Index propertyScrollPosition, Dali::Property::Index propertyMinScrollPosition, Dali::Property::Index propertyMaxScrollPosition, Dali::Property::Index propertyScrollContentSize ); + + /** + * @brief Sets the indicator of scroll bar. + * + * @pre The scroll bar actor has been initialised. * - * @param[in] image The image of indicator that moves to indicate the current scroll position. + * @param[in] indicator The indicator that moves to indicate the current scroll position. */ - void SetIndicatorImage( Image image ); + void SetScrollIndicator( Actor indicator ); /** * @brief Gets the indicator of scroll bar. @@ -134,14 +174,40 @@ public: Actor GetScrollIndicator(); /** - * @brief Sets the values to get notification when the current scroll position of the scrollable - * content goes above or below any of these values. + * @brief Sets the list of values to get notification when the current scroll position of the scrollable + * object goes above or below any of these values. * * @pre The scroll bar actor has been initialised. * * @param[in] positions List of values to receive notifications for when the current scroll position crosses them */ - void SetPositionNotifications( const std::vector& positions ); + void SetScrollPositionIntervals( const Dali::Vector& positions ); + + /** + * @brief Gets the list of values to receive notifications when the current scroll position of the scrollable + * object goes above or below any of these values. + * + * @pre The scroll bar actor has been initialised. + * + * @return The list of values to receive notifications for when the current scroll position crosses them + */ + Dali::Vector GetScrollPositionIntervals() const; + + /** + * @brief Sets the direction of scroll bar to scroll either vertically or horizontally. + * + * @pre The scroll bar actor has been initialised. + * + * @param[in] direction The direction of scroll bar (either vertically or horizontally). + */ + void SetScrollDirection( Direction direction ); + + /** + * @brief Gets the direction of scroll bar. + * + * @return The direction of scroll bar. + */ + Direction GetScrollDirection() const; /** * @brief Sets the height policy of scroll indicator to have either variable or fixed height. @@ -157,7 +223,7 @@ public: * * @return The height policy of scroll indicator */ - IndicatorHeightPolicy GetIndicatorHeightPolicy(); + IndicatorHeightPolicy GetIndicatorHeightPolicy() const; /** * @brief Sets the fixed height of scroll indicator. @@ -175,12 +241,12 @@ public: * @brief Gets the fix height of scroll indicator. * @return The fixed height of the scroll indicator */ - float GetIndicatorFixedHeight(); + float GetIndicatorFixedHeight() const; /** * @brief Sets the duration in second for the scroll indicator to become fully visible * - * @pre The scroll bar actor has been initialised. + * @pre The scroll bar actor has been initialised; durationSeconds must be zero or greater; zero means the indicator will be shown instantly. * * @param[in] durationSeconds The duration for the scroll indicator to become fully visible */ @@ -190,12 +256,12 @@ public: * @brief Gets the duration in second for the scroll indicator to become fully visible * @return The duration for the scroll indicator to become fully visible */ - float GetIndicatorShowDuration(); + float GetIndicatorShowDuration() const; /** * @brief Sets the duration in second for the scroll indicator to become fully invisible * - * @pre The scroll bar actor has been initialised. + * @pre The scroll bar actor has been initialised; durationSeconds must be zero or greater; zero means the indicator will be hidden instantly. * * @param[in] durationSeconds The duration for the scroll indicator to become fully invisible */ @@ -205,21 +271,37 @@ public: * @brief Gets the duration in second for the scroll indicator to become fully invisible * @return The duration for the scroll indicator to become fully invisible */ - float GetIndicatorHideDuration(); + float GetIndicatorHideDuration() const; /** * @brief Shows the scroll indicator */ - void Show(); + void ShowIndicator(); /** * @brief Hides the scroll indicator */ - void Hide(); + void HideIndicator(); + +public: // Signals /** - * @brief Signal emitted when the current scroll position of the scrollable content goes above or below the values - * specified by SetPositionNotifications. + * @brief Signal emitted when panning is finished on the scroll indicator. + * Signal only emitted when the source of the scroll position properties are set. + * + * A callback of the following type may be connected: + * @code + * void YourCallbackName(); + * @endcode + * @pre The Object has been initialized. + * @return The signal to connect to. + */ + ScrollBar::PanFinishedSignalType& PanFinishedSignal(); + + /** + * @brief Signal emitted when the current scroll position of the scrollable content + * goes above or below the values specified by SCROLL_POSITION_INTERVALS property. + * Signal only emitted when the source of the scroll position properties are set. * * A callback of the following type may be connected: * @code @@ -228,7 +310,7 @@ public: * @pre The Object has been initialized. * @return The signal to connect to. */ - ScrollBar::ScrollPositionNotifiedSignalType& ScrollPositionNotifiedSignal(); + ScrollBar::ScrollPositionIntervalReachedSignalType& ScrollPositionIntervalReachedSignal(); public: // Not intended for application developers @@ -245,11 +327,11 @@ public: // Not intended for application developers explicit DALI_INTERNAL ScrollBar( Dali::Internal::CustomActor* internal ); }; +/** + * @} + */ } // namespace Toolkit } // namespace Dali -/** - * @} - */ #endif // __DALI_TOOLKIT_SCROLL_BAR_H__