dali-toolkit/devel-api/controls/scroll-bar/scroll-bar.h

   1 #ifndef DALI_TOOLKIT_SCROLL_BAR_H
   2 #define DALI_TOOLKIT_SCROLL_BAR_H
   3
   4 /*
   5  * Copyright (c) 2020 Samsung Electronics Co., Ltd.
   6  *
   7  * Licensed under the Apache License, Version 2.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://www.apache.org/licenses/LICENSE-2.0
  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
  21 // INTERNAL INCLUDES
  22 #include <dali-toolkit/public-api/controls/control.h>
  23
  24 namespace Dali
  25 {
  26 namespace Toolkit
  27 {
  28 namespace Internal DALI_INTERNAL
  29 {
  30 // Forward declarations
  31
  32 class ScrollBar;
  33 } // namespace DALI_INTERNAL
  34 /**
  35  * @addtogroup dali_toolkit_controls_scroll_bar
  36  * @{
  37  */
  38
  39 /**
  40  * @brief ScrollBar is a UI component that can be linked to the scrollable objects
  41  * indicating the current scroll position of the scrollable object.
  42  *
  43  * Signals
  44  * | %Signal Name                  | Method                                     |
  45  * |-------------------------------|--------------------------------------------|
  46  * | panFinished                   | @ref PanFinishedSignal()                   |
  47  * | scrollPositionIntervalReached | @ref ScrollPositionIntervalReachedSignal() |
  48  * @SINCE_1_0.0
  49  */
  50 class DALI_TOOLKIT_API ScrollBar : public Control
  51 {
  52 public:
  53   // Properties
  54
  55   /**
  56    * @brief Enumeration for the start and end property ranges for this control.
  57    * @SINCE_1_0.0
  58    */
  59   enum PropertyRange
  60   {
  61     PROPERTY_START_INDEX = Control::CONTROL_PROPERTY_END_INDEX + 1, ///< @SINCE_1_0.0
  62     PROPERTY_END_INDEX   = PROPERTY_START_INDEX + 1000              ///< Reserve property indices @SINCE_1_0.0
  63   };
  64
  65   /**
  66    * @brief Enumeration for the instance of properties belonging to the ScrollBar class.
  67    * @SINCE_1_0.0
  68    */
  69   struct Property
  70   {
  71     /**
  72      * @brief Enumeration for the instance of properties belonging to the ScrollBar class.
  73      * @SINCE_1_0.0
  74      */
  75     enum
  76     {
  77       /**
  78        * @brief The scrolling direction of the indicator.
  79        * @details Name "scrollDirection", type Property::STRING.
  80        *          Possible values are "VERTICAL" and "HORIZONTAL".
  81        * @SINCE_1_0.0
  82        * @see SetScrollDirection()
  83        */
  84       SCROLL_DIRECTION = PROPERTY_START_INDEX,
  85
  86       /**
  87        * @brief The indicator height policy.
  88        * @details Name "indicatorHeightPolicy", type Property::STRING.
  89        *          Possible values are "VARIABLE" and "FIXED".
  90        * @SINCE_1_0.0
  91        * @see SetIndicatorHeightPolicy()
  92        */
  93       INDICATOR_HEIGHT_POLICY,
  94
  95       /**
  96        * @brief The fixed height of the indicator.
  97        * @details Name "indicatorFixedHeight", type Property::FLOAT.
  98        * @SINCE_1_0.0
  99        * @see SetIndicatorFixedHeight()
 100        */
 101       INDICATOR_FIXED_HEIGHT,
 102
 103       /**
 104        * @brief The duration in seconds to show the indicator.
 105        * @details Name "indicatorShowDuration", type Property::FLOAT.
 106        * @SINCE_1_0.0
 107        * @see SetIndicatorShowDuration()
 108        */
 109       INDICATOR_SHOW_DURATION,
 110
 111       /**
 112        * @brief The duration in seconds to hide the indicator.
 113        * @details Name "indicatorHideDuration", type Property::FLOAT.
 114        * @SINCE_1_0.0
 115        * @see SetIndicatorHideDuration()
 116        */
 117       INDICATOR_HIDE_DURATION,
 118
 119       /**
 120        * @brief The intervals at which point a notification is emitted.
 121        * @details Name "scrollPositionIntervals", type Property::ARRAY.
 122        * @SINCE_1_0.0
 123        * @see SetScrollPositionIntervals()
 124        */
 125       SCROLL_POSITION_INTERVALS,
 126
 127       /**
 128        * @brief The minimum height for a variable size indicator.
 129        * @details Name "indicatorMinimumHeight", type Property::FLOAT.
 130        * @SINCE_1_1.36
 131        */
 132       INDICATOR_MINIMUM_HEIGHT,
 133
 134       /**
 135        * @brief The padding at the start of the indicator.
 136        * @details Name "indicatorStartPadding", type Property::FLOAT.
 137        *          For example, the padding at the top if scrollDirection is VERTICAL.
 138        * @SINCE_1_1.36
 139        */
 140       INDICATOR_START_PADDING,
 141
 142       /**
 143        * @brief The padding at the end of the indicator.
 144        * @details Name "indicatorEndPadding", type Property::FLOAT.
 145        *          For example, the padding at the bottom if scrollDirection is VERTICAL.
 146        * @SINCE_1_1.36
 147        */
 148       INDICATOR_END_PADDING,
 149
 150       /**
 151        * @brief The duration that transient indicators will remain fully visible.
 152        * @details name "indicatorTransientDuration", type Property::FLOAT.
 153        * @SINCE_1_2.60
 154        */
 155       INDICATOR_TRANSIENT_DURATION,
 156     };
 157   };
 158
 159   // Signals
 160
 161   typedef Signal<void()>      PanFinishedSignalType;
 162   typedef Signal<void(float)> ScrollPositionIntervalReachedSignalType;
 163
 164 public:
 165   /**
 166    * @brief Direction.
 167    * @SINCE_1_0.0
 168    */
 169   enum Direction
 170   {
 171     VERTICAL = 0, ///< Scroll in the vertical direction @SINCE_1_9.28
 172     HORIZONTAL    ///< Scroll in the horizontal direction @SINCE_1_9.28
 173   };
 174
 175   /**
 176    * @brief Indicator height policy.
 177    * @SINCE_1_0.0
 178    */
 179   enum IndicatorHeightPolicy
 180   {
 181     VARIABLE = 0, ///< VARIABLE height changed dynamically according to the length of scroll content @SINCE_1_9.28
 182     FIXED         ///< FIXED height regardless of the length of scroll content @SINCE_1_9.28
 183   };
 184
 185   /**
 186    * @brief Creates an uninitialized ScrollBar; this can be initialized with ScrollBar::New()
 187    * Calling member functions with an uninitialized Dali::Object is not allowed.
 188    * @SINCE_1_0.0
 189    */
 190   ScrollBar();
 191
 192   /**
 193    * @brief Copy constructor.
 194    * @SINCE_1_0.0
 195    * @param[in] scrollBar Handle to an object
 196    */
 197   ScrollBar(const ScrollBar& scrollBar);
 198
 199   /**
 200    * @brief Assignment operator.
 201    * @SINCE_1_0.0
 202    * @param[in] scrollBar Handle to an object
 203    * @return A reference to this
 204    */
 205   ScrollBar& operator=(const ScrollBar& scrollBar);
 206
 207   /**
 208    * @brief Destructor.
 209    *
 210    * This is non-virtual since derived Handle types must not contain data or virtual methods.
 211    * @SINCE_1_0.0
 212    */
 213   ~ScrollBar();
 214
 215   /**
 216    * @brief Creates an initialized ScrollBar.
 217    * @SINCE_1_0.0
 218    * @param[in] direction The direction of scroll bar (either vertically or horizontally)
 219    * @return A pointer to the created ScrollBar
 220    */
 221   static ScrollBar New(Direction direction = VERTICAL);
 222
 223   /**
 224    * @brief Downcasts a handle to ScrollBar handle.
 225    *
 226    * If handle points to a ScrollBar, the downcast produces valid handle.
 227    * If not, the returned handle is left uninitialized.
 228    * @SINCE_1_0.0
 229    * @param[in] handle Handle to an object
 230    * @return Handle to a ScrollBar or an uninitialized handle
 231    */
 232   static ScrollBar DownCast(BaseHandle handle);
 233
 234   /**
 235    * @brief Sets the source of the scroll position properties.
 236    *
 237    * @SINCE_1_0.0
 238    * @param[in] handle The handle of the object owing the scroll properties
 239    * @param[in] propertyScrollPosition The index of the scroll position property (The scroll position, type float)
 240    * @param[in] propertyMinScrollPosition The index of the minimum scroll position property (The minimum scroll position, type float)
 241    * @param[in] propertyMaxScrollPosition The index of the maximum scroll position property (The maximum scroll position, type float)
 242    * @param[in] propertyScrollContentSize The index of the scroll content size property (The size of the scrollable content in actor coordinates, type float)
 243    * @pre The handle to the object owing the scroll properties has been initialised and the property index must be valid.
 244    */
 245   void SetScrollPropertySource(Handle handle, Dali::Property::Index propertyScrollPosition, Dali::Property::Index propertyMinScrollPosition, Dali::Property::Index propertyMaxScrollPosition, Dali::Property::Index propertyScrollContentSize);
 246
 247   /**
 248    * @brief Sets the indicator of scroll bar.
 249    *
 250    * @SINCE_1_0.0
 251    * @param[in] indicator The indicator that moves to indicate the current scroll position
 252    * @pre The scroll bar actor has been initialized.
 253    */
 254   void SetScrollIndicator(Actor indicator);
 255
 256   /**
 257    * @brief Gets the indicator of scroll bar.
 258    *
 259    * @SINCE_1_0.0
 260    * @return The indicator indicates the current scroll position of the scrollable content
 261    * @pre The scroll bar actor has been initialized.
 262    */
 263   Actor GetScrollIndicator();
 264
 265   /**
 266    * @brief Sets the list of values to get notification when the current scroll position of the scrollable
 267    * object goes above or below any of these values.
 268    *
 269    * @SINCE_1_0.0
 270    * @param[in] positions List of values to receive notifications for when the current scroll position crosses them
 271    * @pre The scroll bar actor has been initialized.
 272    */
 273   void SetScrollPositionIntervals(const Dali::Vector<float>& positions);
 274
 275   /**
 276    * @brief Gets the list of values to receive notifications when the current scroll position of the scrollable
 277    * object goes above or below any of these values.
 278    *
 279    * @SINCE_1_0.0
 280    * @return The list of values to receive notifications for when the current scroll position crosses them
 281    * @pre The scroll bar actor has been initialized.
 282    *
 283    */
 284   Dali::Vector<float> GetScrollPositionIntervals() const;
 285
 286   /**
 287    * @brief Sets the direction of scroll bar to scroll either vertically or horizontally.
 288    *
 289    * @SINCE_1_0.0
 290    * @param[in] direction The direction of scroll bar (either vertically or horizontally)
 291    * @pre The scroll bar actor has been initialized.
 292    */
 293   void SetScrollDirection(Direction direction);
 294
 295   /**
 296    * @brief Gets the direction of scroll bar.
 297    *
 298    * @SINCE_1_0.0
 299    * @return The direction of scroll bar
 300    */
 301   Direction GetScrollDirection() const;
 302
 303   /**
 304    * @brief Sets the height policy of scroll indicator to have either variable or fixed height.
 305    *
 306    * @SINCE_1_0.0
 307    * @param[in] policy The height policy of scroll indicator
 308    * @pre The scroll bar actor has been initialized.
 309    */
 310   void SetIndicatorHeightPolicy(IndicatorHeightPolicy policy);
 311
 312   /**
 313    * @brief Gets the height policy of scroll indicator.
 314    *
 315    * @SINCE_1_0.0
 316    * @return The height policy of scroll indicator
 317    */
 318   IndicatorHeightPolicy GetIndicatorHeightPolicy() const;
 319
 320   /**
 321    * @brief Sets the fixed height of scroll indicator.
 322    *
 323    * Normally the height of scroll indicator is changed dynamically according to the length of scroll content.
 324    * However, when the height policy of scroll indicator is set to be fixed, the height will be kept fixed
 325    * regardless of the length of scroll content.
 326    *
 327    * @SINCE_1_0.0
 328    * @param[in] height The fixed height of the scroll indicator
 329    * @pre The scroll bar actor has been initialized.
 330    *
 331    */
 332   void SetIndicatorFixedHeight(float height);
 333
 334   /**
 335    * @brief Gets the fix height of scroll indicator.
 336    * @SINCE_1_0.0
 337    * @return The fixed height of the scroll indicator
 338    */
 339   float GetIndicatorFixedHeight() const;
 340
 341   /**
 342    * @brief Sets the duration in seconds for the scroll indicator to become fully visible.
 343    *
 344    * @SINCE_1_0.0
 345    * @param[in] durationSeconds The duration for the scroll indicator to become fully visible
 346    * @pre The scroll bar actor has been initialised; durationSeconds must be zero or greater; zero means the indicator will be shown instantly.
 347    *
 348    */
 349   void SetIndicatorShowDuration(float durationSeconds);
 350
 351   /**
 352    * @brief Gets the duration in seconds for the scroll indicator to become fully visible.
 353    * @SINCE_1_0.0
 354    * @return The duration for the scroll indicator to become fully visible
 355    */
 356   float GetIndicatorShowDuration() const;
 357
 358   /**
 359    * @brief Sets the duration in seconds for the scroll indicator to become fully invisible.
 360    *
 361    * @SINCE_1_0.0
 362    * @param[in] durationSeconds The duration for the scroll indicator to become fully invisible
 363    * @pre The scroll bar actor has been initialised; durationSeconds must be zero or greater; zero means the indicator will be hidden instantly.
 364    *
 365    */
 366   void SetIndicatorHideDuration(float durationSeconds);
 367
 368   /**
 369    * @brief Gets the duration in seconds for the scroll indicator to become fully invisible.
 370    * @SINCE_1_0.0
 371    * @return The duration for the scroll indicator to become fully invisible
 372    */
 373   float GetIndicatorHideDuration() const;
 374
 375   /**
 376    * @brief Shows the scroll indicator.
 377    * @SINCE_1_0.0
 378    */
 379   void ShowIndicator();
 380
 381   /**
 382    * @brief Hides the scroll indicator.
 383    * @SINCE_1_0.0
 384    */
 385   void HideIndicator();
 386
 387 public: // Signals
 388   /**
 389    * @brief Signal emitted when panning is finished on the scroll indicator.
 390    *
 391    * Signal only emitted when the source of the scroll position properties are set.
 392    *
 393    * A callback of the following type may be connected:
 394    * @code
 395    *   void YourCallbackName();
 396    * @endcode
 397    * @SINCE_1_0.0
 398    * @return The signal to connect to
 399    * @pre The Object has been initialized.
 400    */
 401   ScrollBar::PanFinishedSignalType& PanFinishedSignal();
 402
 403   /**
 404    * @brief Signal emitted when the current scroll position of the scrollable content
 405    * goes above or below the values specified by SCROLL_POSITION_INTERVALS property.
 406    *
 407    * Signal only emitted when the source of the scroll position properties are set.
 408    *
 409    * A callback of the following type may be connected:
 410    * @code
 411    *   void YourCallbackName(float currentScrollPosition);
 412    * @endcode
 413    * @SINCE_1_0.0
 414    * @return The signal to connect to
 415    * @pre The Object has been initialized.
 416    */
 417   ScrollBar::ScrollPositionIntervalReachedSignalType& ScrollPositionIntervalReachedSignal();
 418
 419 public: // Not intended for application developers
 420   /// @cond internal
 421   /**
 422    * @brief Creates a handle using the Toolkit::Internal implementation.
 423    * @SINCE_1_0.0
 424    * @param[in] implementation The Control implementation
 425    */
 426   DALI_INTERNAL ScrollBar(Internal::ScrollBar& implementation);
 427
 428   /**
 429    * @brief Allows the creation of this Control from an Internal::CustomActor pointer.
 430    * @SINCE_1_0.0
 431    * @param[in] internal A pointer to the internal CustomActor
 432    */
 433   explicit DALI_INTERNAL ScrollBar(Dali::Internal::CustomActor* internal);
 434   /// @endcond
 435 };
 436
 437 /**
 438  * @}
 439  */
 440 } // namespace Toolkit
 441
 442 } // namespace Dali
 443
 444 #endif // DALI_TOOLKIT_SCROLL_BAR_H