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 DALI_IMPORT_API
  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 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   /** @} */
 105
 106   /// @name Signals
 107   /** @{ */
 108   static const char* const SIGNAL_SCROLL_STARTED;   ///< "scroll-started";
 109   static const char* const SIGNAL_SCROLL_COMPLETED; ///< "scroll-completed";
 110   static const char* const SIGNAL_SCROLL_UPDATED;   ///< "scroll-updated";
 111   static const char* const SIGNAL_SCROLL_CLAMPED;   ///< "scroll-clamped";
 112   /** @} */
 113
 114 public:
 115
 116   typedef SignalV2< void ( const Vector3& ) > ScrollStartedSignalV2;   ///< ScrollStarted signal type
 117   typedef SignalV2< void ( const Vector3& ) > ScrollCompletedSignalV2; ///< ScrollCompleted signal type
 118   typedef SignalV2< void ( const Vector3& ) > ScrollUpdatedSignalV2;   ///< Scroll updated signal type
 119   typedef SignalV2< void ( const ClampEvent& ) > ScrollClampedSignalV2; ///< Scroll clamped signal type
 120
 121   /**
 122    * @brief Signal emitted when the Scrollable has moved (whether by touch or animation).
 123    */
 124   ScrollStartedSignalV2& ScrollStartedSignal();
 125
 126   /**
 127    * @brief Signal emitted when the Scrollable has moved (whether by touch or animation).
 128    */
 129   ScrollUpdatedSignalV2& ScrollUpdatedSignal();
 130
 131   /**
 132    * @brief Signal emitted when the Scrollable has completed movement (whether by touch or animation).
 133    */
 134   ScrollCompletedSignalV2& ScrollCompletedSignal();
 135
 136   /**
 137    * @brief Signal emitted when the Scrollable is pushing against a domain boundary
 138    * (in either position, scale, or rotation).
 139    *
 140    * @return The signal to connect to
 141    */
 142   ScrollClampedSignalV2& ScrollClampedSignal();
 143
 144 public:
 145
 146   /**
 147    * @brief Creates an uninitialized Scrollable handle.
 148    */
 149   Scrollable();
 150
 151   /**
 152    * @brief Copy constructor.
 153    *
 154    * Creates another handle that points to the same real object
 155    *
 156    * @param handle to copy from
 157    */
 158   Scrollable( const Scrollable& handle );
 159
 160   /**
 161    * @brief Assignment operator.
 162    *
 163    * Changes this handle to point to another real object
 164    * @param[in] handle to copy from
 165    * @return A reference to this
 166    */
 167   Scrollable& operator=( const Scrollable& handle );
 168
 169   /**
 170    * @brief Destructor
 171    *
 172    * This is non-virtual since derived Handle types must not contain data or virtual methods.
 173    */
 174   ~Scrollable();
 175
 176   /**
 177    * @brief Downcast an Object handle to Scrollable.
 178    *
 179    * If handle points to a Scrollable the downcast produces valid
 180    * handle. If not the returned handle is left uninitialized.
 181    *
 182    * @param[in] handle Handle to an object
 183    * @return handle to a Scrollable or an uninitialized handle
 184    */
 185   static Scrollable DownCast( BaseHandle handle );
 186
 187   /**
 188    * @brief Checks if a ScrollComponent has been enabled or not.
 189    *
 190    * @param[in] type The Scroll Component Type to check
 191    * @return True (if Enabled)
 192    */
 193   bool IsScrollComponentEnabled(Scrollable::ScrollComponentType type) const;
 194
 195   /**
 196    * @brief Enables a ScrollComponent.
 197    *
 198    * @param[in] type The Scroll Component Type to enable
 199    */
 200   void EnableScrollComponent(Scrollable::ScrollComponentType type);
 201
 202   /**
 203    * @brief Disables a ScrollComponent.
 204    *
 205    * @param[in] type The Scroll Component Type to disable
 206    */
 207   void DisableScrollComponent(Scrollable::ScrollComponentType type);
 208
 209   /**
 210    * @brief Set the color of the overshoot effect.
 211    *
 212    * @param[in] color The color of the overshoot effect.
 213    */
 214   void SetOvershootEffectColor( const Vector4& color );
 215
 216   /**
 217    * @brief Get the color of the overshoot effect.
 218    * @return The color of the overshoot effect.
 219    */
 220   Vector4 GetOvershootEffectColor() const;
 221
 222 public: // Not intended for application developers
 223
 224   /**
 225    * @brief Creates a handle using the Toolkit::Internal implementation.
 226    *
 227    * @param[in]  implementation  The Control implementation.
 228    */
 229   Scrollable(Internal::Scrollable& implementation);
 230
 231   /**
 232    * @brief Allows the creation of this Control from an Internal::CustomActor pointer.
 233    *
 234    * @param[in]  internal  A pointer to the internal CustomActor.
 235    */
 236   Scrollable( Dali::Internal::CustomActor* internal );
 237 };
 238
 239 } // namespace Toolkit
 240
 241 } // namespace Dali
 242
 243 #endif // __DALI_TOOLKIT_SCROLLABLE_H__