base/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) 2014 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 class Scrollable;
  33 }
  34
  35 /**
  36  * @brief How axes/rotation or scale are clamped
  37  */
  38 enum ClampState
  39 {
  40   NotClamped,   ///< The quantity isn't clamped
  41   ClampedToMin, ///< The quantity is clamped to the min value
  42   ClampedToMax  ///< The quantity is clamped to the max value
  43 };
  44
  45 /**
  46  * @brief A 2 dimensional clamp
  47  */
  48 struct ClampState2
  49 {
  50   ClampState x; ///< The clamp state of the x axis
  51   ClampState y; ///< The clamp state of the y axis
  52 };
  53
  54 /**
  55  * @brief A 3 dimensional clamp
  56  */
  57 struct ClampState3
  58 {
  59   ClampState x; ///< The clamp state of the x axis
  60   ClampState y; ///< The clamp state of the y axis
  61   ClampState z; ///< The clamp state of the z axis
  62 };
  63
  64 /**
  65  * @brief Base class for derived Scrollables that contains actors that can be scrolled manually
  66  * (via touch) or automatically.
  67  *
  68  * Scrollables such as ScrollView and ItemView can be derived from this class.
  69  */
  70 class DALI_IMPORT_API Scrollable : public Control
  71 {
  72 public:
  73
  74   /**
  75    * @brief Clamp signal event's data
  76    */
  77   struct ClampEvent
  78   {
  79     ClampState3 scale;       ///< Clamp information for scale axes
  80     ClampState3 position;    ///< Clamp information for position axes
  81     ClampState rotation;     ///< Clamp information for rotation
  82   };
  83
  84   /**
  85    * @brief Scroll component types
  86    */
  87   enum ScrollComponentType
  88   {
  89     HorizontalScrollBar,
  90     VerticalScrollBar,
  91     OvershootIndicator,
  92   };
  93
  94   // Custom properties
  95
  96   static const std::string SCROLL_RELATIVE_POSITION_PROPERTY_NAME;      ///< Property, name "scroll-relative-position", type VECTOR3
  97   static const std::string SCROLL_POSITION_MIN_PROPERTY_NAME;           ///< Property, name "scroll-position-min",      type VECTOR3
  98   static const std::string SCROLL_POSITION_MAX_PROPERTY_NAME;           ///< Property, name "scroll-position-max",      type VECTOR3
  99   static const std::string SCROLL_DIRECTION_PROPERTY_NAME;              ///< Property, name "scroll-direction",         type VECTOR2
 100
 101   /// @name Properties
 102   /** @{ */
 103   static const Property::Index PROPERTY_OVERSHOOT_EFFECT_COLOR;         ///< Property, name "overshoot-effect-color",  @see SetOvershootEffectColor(),  type VECTOR4
 104   static const Property::Index PROPERTY_OVERSHOOT_ANIMATION_SPEED;      ///< Property, name "overshoot-animation-speed",  @see SetOvershootAnimationSpeed(),  type FLOAT
 105   /** @} */
 106
 107   /// @name Signals
 108   /** @{ */
 109   static const char* const SIGNAL_SCROLL_STARTED;   ///< "scroll-started";
 110   static const char* const SIGNAL_SCROLL_COMPLETED; ///< "scroll-completed";
 111   static const char* const SIGNAL_SCROLL_UPDATED;   ///< "scroll-updated";
 112   static const char* const SIGNAL_SCROLL_CLAMPED;   ///< "scroll-clamped";
 113   /** @} */
 114
 115 public:
 116
 117   typedef SignalV2< void ( const Vector3& ) > ScrollStartedSignalV2;   ///< ScrollStarted signal type
 118   typedef SignalV2< void ( const Vector3& ) > ScrollCompletedSignalV2; ///< ScrollCompleted signal type
 119   typedef SignalV2< void ( const Vector3& ) > ScrollUpdatedSignalV2;   ///< Scroll updated signal type
 120   typedef SignalV2< void ( const ClampEvent& ) > ScrollClampedSignalV2; ///< Scroll clamped signal type
 121
 122   /**
 123    * @brief Signal emitted when the Scrollable has moved (whether by touch or animation).
 124    */
 125   ScrollStartedSignalV2& ScrollStartedSignal();
 126
 127   /**
 128    * @brief Signal emitted when the Scrollable has moved (whether by touch or animation).
 129    */
 130   ScrollUpdatedSignalV2& ScrollUpdatedSignal();
 131
 132   /**
 133    * @brief Signal emitted when the Scrollable has completed movement (whether by touch or animation).
 134    */
 135   ScrollCompletedSignalV2& ScrollCompletedSignal();
 136
 137   /**
 138    * @brief Signal emitted when the Scrollable is pushing against a domain boundary
 139    * (in either position, scale, or rotation).
 140    *
 141    * @return The signal to connect to
 142    */
 143   ScrollClampedSignalV2& ScrollClampedSignal();
 144
 145 public:
 146
 147   /**
 148    * @brief Creates an uninitialized Scrollable handle.
 149    */
 150   Scrollable();
 151
 152   /**
 153    * @brief Copy constructor.
 154    *
 155    * Creates another handle that points to the same real object
 156    *
 157    * @param handle to copy from
 158    */
 159   Scrollable( const Scrollable& handle );
 160
 161   /**
 162    * @brief Assignment operator.
 163    *
 164    * Changes this handle to point to another real object
 165    * @param[in] handle to copy from
 166    * @return A reference to this
 167    */
 168   Scrollable& operator=( const Scrollable& handle );
 169
 170   /**
 171    * @brief Destructor
 172    *
 173    * This is non-virtual since derived Handle types must not contain data or virtual methods.
 174    */
 175   ~Scrollable();
 176
 177   /**
 178    * @brief Downcast an Object handle to Scrollable.
 179    *
 180    * If handle points to a Scrollable the downcast produces valid
 181    * handle. If not the returned handle is left uninitialized.
 182    *
 183    * @param[in] handle Handle to an object
 184    * @return handle to a Scrollable or an uninitialized handle
 185    */
 186   static Scrollable DownCast( BaseHandle handle );
 187
 188   /**
 189    * @brief Checks if a ScrollComponent has been enabled or not.
 190    *
 191    * @param[in] type The Scroll Component Type to check
 192    * @return True (if Enabled)
 193    */
 194   bool IsScrollComponentEnabled(Scrollable::ScrollComponentType type) const;
 195
 196   /**
 197    * @brief Enables a ScrollComponent.
 198    *
 199    * @param[in] type The Scroll Component Type to enable
 200    */
 201   void EnableScrollComponent(Scrollable::ScrollComponentType type);
 202
 203   /**
 204    * @brief Disables a ScrollComponent.
 205    *
 206    * @param[in] type The Scroll Component Type to disable
 207    */
 208   void DisableScrollComponent(Scrollable::ScrollComponentType type);
 209
 210   /**
 211    * @brief Set the color of the overshoot effect.
 212    *
 213    * @param[in] color The color of the overshoot effect.
 214    */
 215   void SetOvershootEffectColor( const Vector4& color );
 216
 217   /**
 218    * @brief Get the color of the overshoot effect.
 219    * @return The color of the overshoot effect.
 220    */
 221   Vector4 GetOvershootEffectColor() const;
 222
 223   /**
 224    * @brief Set the speed of overshoot animation in pixels per second.
 225    * When the speed is not greater than 0, the overshoot is set instantly with no animation.
 226    * @param[in] pixelsPerSecond The speed of the overshoot animation.
 227    */
 228   void SetOvershootAnimationSpeed( float pixelsPerSecond );
 229
 230   /**
 231    * @brief Get the speed of overshoot animation in pixels per second.
 232    * @return The speed of the overshoot animation.
 233    */
 234   float GetOvershootAnimationSpeed() const;
 235
 236 public: // Not intended for application developers
 237
 238   /**
 239    * @brief Creates a handle using the Toolkit::Internal implementation.
 240    *
 241    * @param[in]  implementation  The Control implementation.
 242    */
 243   DALI_INTERNAL Scrollable(Internal::Scrollable& implementation);
 244
 245   /**
 246    * @brief Allows the creation of this Control from an Internal::CustomActor pointer.
 247    *
 248    * @param[in]  internal  A pointer to the internal CustomActor.
 249    */
 250   explicit DALI_INTERNAL Scrollable( Dali::Internal::CustomActor* internal );
 251 };
 252
 253 } // namespace Toolkit
 254
 255 } // namespace Dali
 256
 257 #endif // __DALI_TOOLKIT_SCROLLABLE_H__