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