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