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