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=d988212cc2be310078229a3403fbadc0c60de208;hp=5adb04c425a9a643747e7c82950c91806c697653;hb=b694e7e2ae624e206e1548b1a863c554eb9cd4d7;hpb=818994dc0acac601b0b27c0b715259b504ef4ceb 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 5adb04c..d988212 100755 --- a/dali-toolkit/public-api/controls/scroll-bar/scroll-bar.h +++ b/dali-toolkit/public-api/controls/scroll-bar/scroll-bar.h @@ -1,191 +1,450 @@ -#ifndef __DALI_TOOLKIT_SCROLL_BAR_H__ -#define __DALI_TOOLKIT_SCROLL_BAR_H__ - -// -// Copyright (c) 2014 Samsung Electronics Co., Ltd. -// -// Licensed under the Flora License, Version 1.0 (the License); -// you may not use this file except in compliance with the License. -// You may obtain a copy of the License at -// -// http://floralicense.org/license/ -// -// Unless required by applicable law or agreed to in writing, software -// distributed under the License is distributed on an AS IS BASIS, -// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -// See the License for the specific language governing permissions and -// limitations under the License. -// +#ifndef DALI_TOOLKIT_SCROLL_BAR_H +#define DALI_TOOLKIT_SCROLL_BAR_H + +/* + * 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. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + * + */ // INTERNAL INCLUDES -#include #include -namespace Dali DALI_IMPORT_API +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. + * @brief 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 | + * |-------------------------------|--------------------------------------------| + * | panFinished | @ref PanFinishedSignal() | + * | scrollPositionIntervalReached | @ref ScrollPositionIntervalReachedSignal() | + * @SINCE_1_0.0 */ -class ScrollBar : public Control +class DALI_TOOLKIT_API ScrollBar : public Control { public: + // Properties + + /** + * @brief Enumeration for the start and end property ranges for this control. + * @SINCE_1_0.0 + */ + enum PropertyRange + { + 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 + }; + + /** + * @brief Enumeration for the instance of properties belonging to the ScrollBar class. + * @SINCE_1_0.0 + */ + struct Property + { + /** + * @brief Enumeration for the instance of properties belonging to the ScrollBar class. + * @SINCE_1_0.0 + */ + enum + { + /** + * @brief The scrolling direction of the indicator. + * @details Name "scrollDirection", type Property::STRING. + * Possible values are "Vertical" and "Horizontal". + * @SINCE_1_0.0 + * @see SetScrollDirection() + */ + SCROLL_DIRECTION = PROPERTY_START_INDEX, + + /** + * @brief The indicator height policy. + * @details Name "indicatorHeightPolicy", type Property::STRING. + * Possible values are "Variable" and "Fixed". + * @SINCE_1_0.0 + * @see SetIndicatorHeightPolicy() + */ + INDICATOR_HEIGHT_POLICY, + + /** + * @brief The fixed height of the indicator. + * @details Name "indicatorFixedHeight", type Property::FLOAT. + * @SINCE_1_0.0 + * @see SetIndicatorFixedHeight() + */ + INDICATOR_FIXED_HEIGHT, + + /** + * @brief The duration in seconds to show the indicator. + * @details Name "indicatorShowDuration", type Property::FLOAT. + * @SINCE_1_0.0 + * @see SetIndicatorShowDuration() + */ + INDICATOR_SHOW_DURATION, + + /** + * @brief The duration in seconds to hide the indicator. + * @details Name "indicatorHideDuration", type Property::FLOAT. + * @SINCE_1_0.0 + * @see SetIndicatorHideDuration() + */ + INDICATOR_HIDE_DURATION, + + /** + * @brief The intervals at which point a notification is emitted. + * @details Name "scrollPositionIntervals", type Property::ARRAY. + * @SINCE_1_0.0 + * @see SetScrollPositionIntervals() + */ + SCROLL_POSITION_INTERVALS, + + /** + * @brief The minimum height for a variable size indicator. + * @details Name "indicatorMinimumHeight", type Property::FLOAT. + * @SINCE_1_1.36 + */ + INDICATOR_MINIMUM_HEIGHT, + + /** + * @brief The padding at the start of the indicator. + * @details Name "indicatorStartPadding", type Property::FLOAT. + * For example, the padding at the top if scrollDirection is Vertical. + * @SINCE_1_1.36 + */ + INDICATOR_START_PADDING, + + /** + * @brief The padding at the end of the indicator. + * @details Name "indicatorEndPadding", type Property::FLOAT. + * For example, the padding at the bottom if scrollDirection is Vertical. + * @SINCE_1_1.36 + */ + INDICATOR_END_PADDING, + + /** + * @brief The duration that transient indicators will remain fully visible. + * @details name "indicatorTransientDuration", type Property::FLOAT. + * @SINCE_1_2.60 + */ + INDICATOR_TRANSIENT_DURATION, + }; + }; + // Signals - static const char* const SCROLL_POSITION_NOTIFIED_SIGNAL_NAME; ///< "scroll-position-notified" signal name - typedef SignalV2< void ( float ) > ScrollPositionNotifiedSignalType; + + typedef Signal< void () > PanFinishedSignalType; + typedef Signal< void ( float ) > ScrollPositionIntervalReachedSignalType; public: /** - * @brief Create an uninitialized ScrollBar; this can be initialized with ScrollBar::New() + * @brief Direction. + * @SINCE_1_0.0 + */ + enum Direction + { + Vertical = 0, ///< Scroll in the vertical direction @SINCE_1_0.0 + Horizontal ///< Scroll in the horizontal direction @SINCE_1_0.0 + }; + + /** + * @brief Indicator height policy. + * @SINCE_1_0.0 + */ + enum IndicatorHeightPolicy + { + Variable = 0, ///< Variable height changed dynamically according to the length of scroll content @SINCE_1_0.0 + Fixed ///< Fixed height regardless of the length of scroll content @SINCE_1_0.0 + }; + + /** + * @brief Creates an uninitialized ScrollBar; this can be initialized with ScrollBar::New() * Calling member functions with an uninitialized Dali::Object is not allowed. - * or horizontally (false) + * @SINCE_1_0.0 */ ScrollBar(); /** * @brief Copy constructor. + * @SINCE_1_0.0 + * @param[in] scrollBar Handle to an object */ ScrollBar( const ScrollBar& scrollBar ); /** * @brief Assignment operator. + * @SINCE_1_0.0 + * @param[in] scrollBar Handle to an object + * @return A reference to this */ ScrollBar& operator=( const ScrollBar& scrollBar ); /** - * @brief Virtual destructor. - * Dali::Object derived classes typically do not contain member data. + * @brief Destructor. + * + * This is non-virtual since derived Handle types must not contain data or virtual methods. + * @SINCE_1_0.0 */ - virtual ~ScrollBar(); + ~ScrollBar(); /** - * @brief Create an initialized ScrollBar - * @return A pointer to the created ScrollBar. + * @brief Creates an initialized ScrollBar. + * @SINCE_1_0.0 + * @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 - * downcast produces valid handle. If not the returned handle is left uninitialized. + * @brief Downcasts a handle to ScrollBar handle. + * + * If handle points to a ScrollBar, 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 ScrollBar or an uninitialized handle + * @return Handle to a ScrollBar or an uninitialized handle */ static ScrollBar DownCast( BaseHandle handle ); /** - * @brief Sets the scroll connector for the scroll bar. + * @brief Sets the source of the scroll position properties. + * + * @SINCE_1_0.0 + * @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) + * @pre The handle to the object owing the scroll properties has been initialised and the property index must be valid. + */ + 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. + * @SINCE_1_0.0 + * @param[in] indicator The indicator that moves to indicate the current scroll position + * @pre The scroll bar actor has been initialized. + */ + void SetScrollIndicator( Actor indicator ); + + /** + * @brief Gets the indicator of scroll bar. * - * @param[in] connector Scroll connector used to connect scrollable container with this ScrollBar + * @SINCE_1_0.0 + * @return The indicator indicates the current scroll position of the scrollable content + * @pre The scroll bar actor has been initialized. */ - void SetScrollConnector( ScrollConnector connector ); + Actor GetScrollIndicator(); /** - * @brief Sets the image for the background of scroll indicator. + * @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. + * @SINCE_1_0.0 + * @param[in] positions List of values to receive notifications for when the current scroll position crosses them + * @pre The scroll bar actor has been initialized. + */ + 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. * - * The background image is resized (stretched according to scale settings), - * to the size of the ScrollBar. + * @SINCE_1_0.0 + * @return The list of values to receive notifications for when the current scroll position crosses them + * @pre The scroll bar actor has been initialized. * - * @param[in] image The image to cover background - * @param[in] border The nine patch border for the image. */ - void SetBackgroundImage( Image image, const Vector4& border ); + Dali::Vector GetScrollPositionIntervals() const; /** - * @brief Sets the image for the indicator of scroll bar. + * @brief Sets the direction of scroll bar to scroll either vertically or horizontally. * - * @pre The scroll bar actor has been initialised. + * @SINCE_1_0.0 + * @param[in] direction The direction of scroll bar (either vertically or horizontally) + * @pre The scroll bar actor has been initialized. + */ + void SetScrollDirection( Direction direction ); + + /** + * @brief Gets the direction of scroll bar. * - * 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. + * @SINCE_1_0.0 + * @return The direction of scroll bar + */ + Direction GetScrollDirection() const; + + /** + * @brief Sets the height policy of scroll indicator to have either variable or fixed height. * - * @param[in] image The image of indicator that moves to indicate the current scroll position. - * @param[in] border The nine patch border for the image. + * @SINCE_1_0.0 + * @param[in] policy The height policy of scroll indicator + * @pre The scroll bar actor has been initialized. */ - void SetIndicatorImage( Image image, const Vector4& border ); + void SetIndicatorHeightPolicy( IndicatorHeightPolicy policy ); /** - * @brief Gets the indicator of scroll bar. + * @brief Gets the height policy of scroll indicator. + * + * @SINCE_1_0.0 + * @return The height policy of scroll indicator + */ + IndicatorHeightPolicy GetIndicatorHeightPolicy() const; + + /** + * @brief Sets the fixed height of scroll indicator. + * + * Normally the height of scroll indicator is changed dynamically according to the length of scroll content. + * However, when the height policy of scroll indicator is set to be fixed, the height will be kept fixed + * regardless of the length of scroll content. * - * @pre The scroll bar actor has been initialised. + * @SINCE_1_0.0 + * @param[in] height The fixed height of the scroll indicator + * @pre The scroll bar actor has been initialized. * - * The indicator indicates the current scroll position of the scrollable content. */ - Actor GetScrollIndicator(); + void SetIndicatorFixedHeight( float height ); + + /** + * @brief Gets the fix height of scroll indicator. + * @SINCE_1_0.0 + * @return The fixed height of the scroll indicator + */ + float GetIndicatorFixedHeight() const; /** - * @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 duration in seconds for the scroll indicator to become fully visible. * - * @pre The scroll bar actor has been initialised. + * @SINCE_1_0.0 + * @param[in] durationSeconds The duration for the scroll indicator to become fully visible + * @pre The scroll bar actor has been initialised; durationSeconds must be zero or greater; zero means the indicator will be shown instantly. * - * @param[in] positions List of values to receive notifications for when the current scroll position crosses them */ - void SetPositionNotifications( const std::vector& positions ); + void SetIndicatorShowDuration( float durationSeconds ); + + /** + * @brief Gets the duration in seconds for the scroll indicator to become fully visible. + * @SINCE_1_0.0 + * @return The duration for the scroll indicator to become fully visible + */ + float GetIndicatorShowDuration() const; + + /** + * @brief Sets the duration in seconds for the scroll indicator to become fully invisible. + * + * @SINCE_1_0.0 + * @param[in] durationSeconds The duration for the scroll indicator to become fully invisible + * @pre The scroll bar actor has been initialised; durationSeconds must be zero or greater; zero means the indicator will be hidden instantly. + * + */ + void SetIndicatorHideDuration( float durationSeconds ); + + /** + * @brief Gets the duration in seconds for the scroll indicator to become fully invisible. + * @SINCE_1_0.0 + * @return The duration for the scroll indicator to become fully invisible + */ + float GetIndicatorHideDuration() const; /** - * @brief Shows the scroll indicator + * @brief Shows the scroll indicator. + * @SINCE_1_0.0 */ - void Show(); + void ShowIndicator(); /** - * @brief Hides the scroll indicator + * @brief Hides the scroll indicator. + * @SINCE_1_0.0 + */ + void HideIndicator(); + +public: // Signals + + /** + * @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 + * @SINCE_1_0.0 + * @return The signal to connect to + * @pre The Object has been initialized. */ - void Hide(); + ScrollBar::PanFinishedSignalType& PanFinishedSignal(); /** - * @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 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 * void YourCallbackName(float currentScrollPosition); * @endcode + * @SINCE_1_0.0 + * @return The signal to connect to * @pre The Object has been initialized. - * @return The signal to connect to. */ - ScrollBar::ScrollPositionNotifiedSignalType& ScrollPositionNotifiedSignal(); + ScrollBar::ScrollPositionIntervalReachedSignalType& ScrollPositionIntervalReachedSignal(); public: // Not intended for application developers + /// @cond internal /** - * Creates a handle using the Toolkit::Internal implementation. - * @param[in] implementation The Control implementation. + * @brief Creates a handle using the Toolkit::Internal implementation. + * @SINCE_1_0.0 + * @param[in] implementation The Control implementation */ - ScrollBar( Internal::ScrollBar& implementation ); + DALI_INTERNAL ScrollBar( Internal::ScrollBar& implementation ); /** - * Allows the creation of this Control from an Internal::CustomActor pointer. - * @param[in] internal A pointer to the internal CustomActor. + * @brief Allows the creation of this Control from an Internal::CustomActor pointer. + * @SINCE_1_0.0 + * @param[in] internal A pointer to the internal CustomActor */ - ScrollBar( Dali::Internal::CustomActor* internal ); + explicit DALI_INTERNAL ScrollBar( Dali::Internal::CustomActor* internal ); + /// @endcond }; +/** + * @} + */ } // namespace Toolkit } // namespace Dali -/** - * @} - */ -#endif // __DALI_TOOLKIT_SCROLL_BAR_H__ +#endif // DALI_TOOLKIT_SCROLL_BAR_H