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