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