dali-toolkit/public-api/controls/scrollable/scrollable.h

   1 #ifndef DALI_TOOLKIT_SCROLLABLE_H
   2 #define DALI_TOOLKIT_SCROLLABLE_H
   3
   4 /*
   5  * Copyright (c) 2020 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 namespace Toolkit
  27 {
  28 namespace Internal DALI_INTERNAL
  29 {
  30 class Scrollable;
  31 }
  32 /**
  33  * @addtogroup dali_toolkit_controls_scrollable
  34  * @{
  35  */
  36
  37 /**
  38  * @brief Base class for derived Scrollables that contains actors that can be scrolled manually
  39  * (via touch) or automatically.
  40  *
  41  * Scrollables such as ScrollView and ItemView can be derived from this class.
  42  *
  43  * Signals
  44  * | %Signal Name     | Method                       |
  45  * |------------------|------------------------------|
  46  * | scrollStarted    | @ref ScrollStartedSignal()   |
  47  * | scrollCompleted  | @ref ScrollCompletedSignal() |
  48  * | scrollUpdated    | @ref ScrollUpdatedSignal()   |
  49  * @SINCE_1_0.0
  50  */
  51 class DALI_TOOLKIT_API Scrollable : public Control
  52 {
  53 public:
  54   /**
  55    * @brief Enumeration for the start and end property ranges for this control.
  56    * @SINCE_1_0.0
  57    */
  58   enum PropertyRange
  59   {
  60     PROPERTY_START_INDEX = Control::CONTROL_PROPERTY_END_INDEX + 1, ///< @SINCE_1_0.0
  61     PROPERTY_END_INDEX   = PROPERTY_START_INDEX + 1000,             ///< Reserve property indices @SINCE_1_0.0
  62
  63     ANIMATABLE_PROPERTY_START_INDEX = ANIMATABLE_PROPERTY_REGISTRATION_START_INDEX,
  64     ANIMATABLE_PROPERTY_END_INDEX   = ANIMATABLE_PROPERTY_REGISTRATION_START_INDEX + 1000 ///< Reserve animatable property indices @SINCE_1_0.0
  65   };
  66
  67   /**
  68    * @brief Enumeration for the instance of properties belonging to the Scrollable class.
  69    * @SINCE_1_0.0
  70    */
  71   struct Property
  72   {
  73     /**
  74      * @brief Enumeration for the instance of properties belonging to the Scrollable class.
  75      * @SINCE_1_0.0
  76      */
  77     enum
  78     {
  79       // Event side properties
  80       OVERSHOOT_EFFECT_COLOR = PROPERTY_START_INDEX, ///< Property, name "overshootEffectColor",      @see SetOvershootEffectColor(),    type Vector4 @SINCE_1_0.0
  81       OVERSHOOT_ANIMATION_SPEED,                     ///< Property, name "overshootAnimationSpeed",   @see SetOvershootAnimationSpeed(), type float @SINCE_1_0.0
  82       OVERSHOOT_ENABLED,                             ///< Property, name "overshootEnabled",          @see SetOvershootEnabled(),        type bool,    @SINCE_1_1.18
  83       OVERSHOOT_SIZE,                                ///< Property, name "overshootSize",                                                type Vector2, @SINCE_1_1.31
  84       SCROLL_TO_ALPHA_FUNCTION,                      ///< Property, name "scrollToAlphaFunction",                                        type int,     @SINCE_1_1.33
  85
  86       // Animatable properties
  87       SCROLL_RELATIVE_POSITION = ANIMATABLE_PROPERTY_START_INDEX, ///< Property, name "scrollRelativePosition",   type Vector2 @SINCE_1_0.0
  88       SCROLL_POSITION_MIN,                                        ///< Property, name "scrollPositionMin",        type Vector2 @SINCE_1_0.0
  89       SCROLL_POSITION_MIN_X,                                      ///< Property, name "scrollPositionMinX",       type float @SINCE_1_0.0
  90       SCROLL_POSITION_MIN_Y,                                      ///< Property, name "scrollPositionMinY",       type float @SINCE_1_0.0
  91       SCROLL_POSITION_MAX,                                        ///< Property, name "scrollPositionMax",        type Vector2 @SINCE_1_0.0
  92       SCROLL_POSITION_MAX_X,                                      ///< Property, name "scrollPositionMaxX",       type float @SINCE_1_0.0
  93       SCROLL_POSITION_MAX_Y,                                      ///< Property, name "scrollPositionMaxY",       type float @SINCE_1_0.0
  94       CAN_SCROLL_VERTICAL,                                        ///< Property, name "canScrollVertical",        type bool @SINCE_1_0.0
  95       CAN_SCROLL_HORIZONTAL                                       ///< Property, name "canScrollHorizontal",      type bool @SINCE_1_0.0
  96     };
  97   };
  98
  99   // Typedefs
 100
 101   typedef Signal<void(const Vector2&)> ScrollStartedSignalType;   ///< ScrollStarted signal type @SINCE_1_0.0
 102   typedef Signal<void(const Vector2&)> ScrollCompletedSignalType; ///< ScrollCompleted signal type @SINCE_1_0.0
 103   typedef Signal<void(const Vector2&)> ScrollUpdatedSignalType;   ///< Scroll updated signal type @SINCE_1_0.0
 104
 105 public:
 106   /**
 107    * @brief Creates an uninitialized Scrollable handle.
 108    * @SINCE_1_0.0
 109    */
 110   Scrollable();
 111
 112   /**
 113    * @brief Copy constructor.
 114    *
 115    * Creates another handle that points to the same real object.
 116    *
 117    * @SINCE_1_0.0
 118    * @param handle to copy from
 119    */
 120   Scrollable(const Scrollable& handle);
 121
 122   /**
 123    * @brief Move constructor
 124    * @SINCE_1_9.23
 125    *
 126    * @param[in] rhs A reference to the moved handle
 127    */
 128   Scrollable(Scrollable&& rhs);
 129
 130   /**
 131    * @brief Assignment operator.
 132    *
 133    * Changes this handle to point to another real object.
 134    * @SINCE_1_0.0
 135    * @param[in] handle Handle to copy from
 136    * @return A reference to this
 137    */
 138   Scrollable& operator=(const Scrollable& handle);
 139
 140   /**
 141    * @brief Move assignment
 142    * @SINCE_1_9.23
 143    *
 144    * @param[in] rhs A reference to the moved handle
 145    * @return A reference to this
 146    */
 147   Scrollable& operator=(Scrollable&& rhs);
 148
 149   /**
 150    * @brief Destructor.
 151    *
 152    * This is non-virtual since derived Handle types must not contain data or virtual methods.
 153    * @SINCE_1_0.0
 154    */
 155   ~Scrollable();
 156
 157   /**
 158    * @brief Downcasts a handle to Scrollable handle.
 159    *
 160    * If handle points to a Scrollable, the downcast produces valid handle.
 161    * If not, the returned handle is left uninitialized.
 162    *
 163    * @SINCE_1_0.0
 164    * @param[in] handle Handle to an object
 165    * @return A handle to a Scrollable or an uninitialized handle
 166    */
 167   static Scrollable DownCast(BaseHandle handle);
 168
 169   /**
 170    * @brief Checks if scroll overshoot has been enabled or not.
 171    *
 172    * @SINCE_1_0.0
 173    * @return Whether the scroll overshoot is enabled
 174    */
 175   bool IsOvershootEnabled() const;
 176
 177   /**
 178    * @brief Sets whether to enables or disable scroll overshoot.
 179    *
 180    * @SINCE_1_0.0
 181    * @param[in] enable Whether to enable the scroll overshoot or not
 182    */
 183   void SetOvershootEnabled(bool enable);
 184
 185   /**
 186    * @brief Sets the color of the overshoot effect.
 187    *
 188    * @SINCE_1_0.0
 189    * @param[in] color The color of the overshoot effect
 190    */
 191   void SetOvershootEffectColor(const Vector4& color);
 192
 193   /**
 194    * @brief Gets the color of the overshoot effect.
 195    * @SINCE_1_0.0
 196    * @return The color of the overshoot effect
 197    */
 198   Vector4 GetOvershootEffectColor() const;
 199
 200   /**
 201    * @brief Sets the speed of overshoot animation in pixels per second.
 202    *
 203    * When the speed is not greater than 0, the overshoot is set instantly with no animation.
 204    * @SINCE_1_0.0
 205    * @param[in] pixelsPerSecond The speed of the overshoot animation
 206    */
 207   void SetOvershootAnimationSpeed(float pixelsPerSecond);
 208
 209   /**
 210    * @brief Gets the speed of overshoot animation in pixels per second.
 211    * @SINCE_1_0.0
 212    * @return The speed of the overshoot animation
 213    */
 214   float GetOvershootAnimationSpeed() const;
 215
 216 public: // Signals
 217   /**
 218    * @brief Signal emitted when the Scrollable has moved (whether by touch or animation).
 219    *
 220    * A callback of the following type may be connected:
 221    * @code
 222    *   void YourCallbackName(const Vector2& currentScrollPosition);
 223    * @endcode
 224    * @SINCE_1_0.0
 225    * @return The signal to connect to
 226    * @pre The Object has been initialized.
 227    */
 228   ScrollStartedSignalType& ScrollStartedSignal();
 229
 230   /**
 231    * @brief Signal emitted when the Scrollable has moved (whether by touch or animation).
 232    *
 233    * A callback of the following type may be connected:
 234    * @code
 235    *   void YourCallbackName(const Vector2& currentScrollPosition);
 236    * @endcode
 237    * @SINCE_1_0.0
 238    * @return The signal to connect to
 239    * @pre The Object has been initialized.
 240    */
 241   ScrollUpdatedSignalType& ScrollUpdatedSignal();
 242
 243   /**
 244    * @brief Signal emitted when the Scrollable has completed movement (whether by touch or animation).
 245    *
 246    * A callback of the following type may be connected:
 247    * @code
 248    *   void YourCallbackName(const Vector2& currentScrollPosition);
 249    * @endcode
 250    * @SINCE_1_0.0
 251    * @return The signal to connect to
 252    * @pre The Object has been initialized.
 253    */
 254   ScrollCompletedSignalType& ScrollCompletedSignal();
 255
 256 public: // Not intended for application developers
 257   /// @cond internal
 258   /**
 259    * @brief Creates a handle using the Toolkit::Internal implementation.
 260    *
 261    * @SINCE_1_0.0
 262    * @param[in] implementation The Control implementation
 263    */
 264   DALI_INTERNAL Scrollable(Internal::Scrollable& implementation);
 265
 266   /**
 267    * @brief Allows the creation of this Control from an Internal::CustomActor pointer.
 268    *
 269    * @SINCE_1_0.0
 270    * @param[in] internal A pointer to the internal CustomActor
 271    */
 272   explicit DALI_INTERNAL Scrollable(Dali::Internal::CustomActor* internal);
 273   /// @endcond
 274 };
 275
 276 /**
 277  * @}
 278  */
 279 } // namespace Toolkit
 280
 281 } // namespace Dali
 282
 283 #endif // DALI_TOOLKIT_SCROLLABLE_H