capi/dali-toolkit/public-api/controls/scrollable/scroll-connector.h

   1 #ifndef __DALI_TOOLKIT_SCROLL_CONNECTOR_H__
   2 #define __DALI_TOOLKIT_SCROLL_CONNECTOR_H__
   3
   4 //
   5 // Copyright (c) 2014 Samsung Electronics Co., Ltd.
   6 //
   7 // Licensed under the Flora License, Version 1.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://floralicense.org/license/
  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 // INTERNAL INCLUDES
  21 #include <dali/dali.h>
  22
  23 namespace Dali DALI_IMPORT_API
  24 {
  25
  26 namespace Toolkit
  27 {
  28
  29 namespace Internal DALI_INTERNAL
  30 {
  31 class ScrollConnector;
  32 }
  33
  34 /**
  35  * ScrollConnector is used to connect scrollable containers with components such as scroll bars, indicators etc.
  36  *
  37  * This basically consists of:
  38  *   - A "scroll-position" property which controls which part of the scrollable content is visible
  39  *   - The minimum/maximum limits of the scroll position, which corresponds to the start & end points of the scollable list etc.
  40  *   - An "overshoot" property which shows any attempts to exceed the start & end points.
  41  *
  42  * The provider of the scrollable content is responsible for calling SetLimits(). Scroll-bar components are then expected to
  43  * receive these values via the LIMITS_CHANGED signal.
  44  *
  45  * The scroll-position property is accessible via GetScrollPositionObject(). This is intended to be shared by multiple controls
  46  * e.g. a list control may be scrolled by panning the list content, or indirectly by dragging a connected scroll-bar control.
  47  *
  48  * The overshoot property is intended for implementing 'end of list' style indicators. This property is expected to be in the range
  49  * -1 to 1, where -1 shows an attempt the scroll beyond the minimum limit, and 1 shows an attempt the scroll beyond the maximum limit.
  50  * Zero indicates normal scrolling i.e. when overshoot indicators should be hidden.
  51  */
  52 class ScrollConnector : public BaseHandle
  53 {
  54 public:
  55
  56   static const char* const SCROLL_POSITION_PROPERTY_NAME; ///< This float "scroll-position" property is available via GetScrollPositionObject()
  57   static const char* const OVERSHOOT_PROPERTY_NAME;       ///< This float "overshoot" property is available via GetScrollPositionObject()
  58
  59   static const Property::Index SCROLL_POSITION;           ///< The index of the "scroll-position" property
  60   static const Property::Index OVERSHOOT;                 ///< The index of the "overshoot" property
  61
  62   // Signals
  63   static const char* const LIMITS_CHANGED_SIGNAL_NAME;    ///< "limits-changed" signal name
  64   typedef SignalV2< void ( float min, float max ) > LimitsChangedSignalType;
  65
  66   /**
  67    * Create a ScrollConnector.
  68    * @return A handle to a newly allocated ScrollConnector.
  69    */
  70   static ScrollConnector New();
  71
  72   /**
  73    * Create an empty handle.
  74    */
  75   ScrollConnector();
  76
  77   /**
  78    * Copy constructor.
  79    * @param handle A handle to copy.
  80    */
  81   ScrollConnector( const ScrollConnector& handle );
  82
  83   /**
  84    * @copydoc Dali::BaseHandle::operator=
  85    */
  86   using Dali::BaseHandle::operator=;
  87
  88   /**
  89    * Virtual destructor.
  90    */
  91   virtual ~ScrollConnector();
  92
  93   /**
  94    * Downcast a BaseHandle to ScrollConnector handle.
  95    * @return A handle to a ScrollConnector or an empty handle.
  96    */
  97   static ScrollConnector DownCast( BaseHandle handle );
  98
  99   /**
 100    * Set The min/max values, corresponding to the start & end position of the scrollable content.
 101    * @param[in] min The minimum value.
 102    * @param[in] max The maximum value.
 103    */
 104   void SetLimits( float min, float max );
 105
 106   /**
 107    * Retrieve the min limit.
 108    * @return The minimum value.
 109    */
 110   float GetMinLimit() const;
 111
 112   /**
 113    * Retrieve the max limit.
 114    * @return The maximum value.
 115    */
 116   float GetMaxLimit() const;
 117
 118   /**
 119    * Signal emitted after the SetLimits() method has been called.
 120    */
 121   ScrollConnector::LimitsChangedSignalType& LimitsChangedSignal();
 122
 123   /**
 124    * Retrieve the object which provides the "scroll-position" property.
 125    * @return The scroll-position object.
 126    */
 127   Constrainable GetScrollPositionObject() const;
 128
 129 public: // Not intended for application developers
 130
 131   /**
 132    * Creates a handle using the Toolkit::Internal implementation.
 133    * @param[in] impl The Control implementation.
 134    */
 135   ScrollConnector( Internal::ScrollConnector* impl );
 136 };
 137
 138 } // namespace Toolkit
 139
 140 } // namespace Dali
 141
 142 #endif // __DALI_TOOLKIT_SCROLL_CONNECTOR_H__