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