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