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