dali-toolkit/public-api/controls/scrollable/item-view/item-layout.h

   1 #ifndef __DALI_TOOLKIT_ITEM_LAYOUT_H__
   2 #define __DALI_TOOLKIT_ITEM_LAYOUT_H__
   3
   4 /*
   5  * Copyright (c) 2015 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 // EXTERNAL INCLUDES
  22 #include <dali/public-api/animation/alpha-function.h>
  23
  24 // INTERNAL INCLUDES
  25 #include <dali-toolkit/public-api/enums.h>
  26 #include <dali-toolkit/public-api/controls/control.h>
  27
  28 namespace Dali
  29 {
  30
  31 namespace Toolkit
  32 {
  33 /**
  34  * @addtogroup dali-toolkit-controls-item-view
  35  * @{
  36  */
  37
  38 class ItemLayout;
  39
  40 typedef IntrusivePtr<ItemLayout> ItemLayoutPtr; ///< Pointer to a Dali::Toolkit::ItemLayout object
  41
  42 /**
  43  * @brief A support class for managing ranges of items.
  44  */
  45 struct ItemRange
  46 {
  47   /**
  48    * @brief Create a range of item identifiers.
  49    *
  50    * @param[in] beginItem The first item within the range.
  51    * @param[in] endItem The past-the-end item.
  52    */
  53   ItemRange(unsigned int beginItem, unsigned int endItem)
  54   : begin(beginItem),
  55     end(endItem)
  56   {
  57   }
  58
  59   /**
  60    * @brief Copy Constructor.
  61    *
  62    * @param[in] copy ItemRange we should copy from.
  63    */
  64   ItemRange(const ItemRange& copy)
  65   : begin(copy.begin),
  66     end(copy.end)
  67   {
  68   }
  69
  70   /**
  71    * @brief Assignment operator.
  72    *
  73    * @param[in] range The Range to assign from.
  74    * @return The updated range.
  75    */
  76   ItemRange& operator=(const ItemRange& range)
  77   {
  78     begin = range.begin;
  79     end = range.end;
  80     return *this;
  81   }
  82
  83   /**
  84    * @brief Test whether an item is within the range.
  85    *
  86    * @param[in] itemId The item identifier.
  87    * @return True if the item is within the range.
  88    */
  89   bool Within(unsigned int itemId)
  90   {
  91     return itemId >= begin &&
  92            itemId < end;
  93   }
  94
  95   /**
  96    * @brief Create the intersection of two ranges.
  97    *
  98    * @param[in] second The second range.
  99    * @return The intersection.
 100    */
 101   ItemRange Intersection(const ItemRange& second)
 102   {
 103     ItemRange intersection(0u, 0u);
 104
 105     // If the ranges intersect
 106     if ( (begin < second.end && end > second.begin) ||
 107          (second.begin < end && second.end > begin) )
 108     {
 109       intersection.begin = std::max(begin, second.begin);
 110       intersection.end   = std::min(end, second.end);
 111     }
 112
 113     return intersection;
 114   }
 115
 116   unsigned int begin; ///< The start of the range
 117   unsigned int end;   ///< The end of the range
 118 };
 119
 120 /**
 121  * @brief An ItemLayout describes the constraints which are imposed on items in the layout.
 122  *
 123  *   - Potentially visible items are represented by Actors, created for ItemView by the ItemFactory.
 124  *   - Constraints are applied after ItemView activates a layout.
 125  *
 126  * An ItemLayout also describes the direction of input gestures, used to scroll through the layout.
 127  * Whilst scrolling, the layout provides a range of items that are within a layout-area (3D bounding volume).
 128  */
 129 class DALI_IMPORT_API ItemLayout : public RefObject
 130 {
 131 public:
 132
 133   class Extension; ///< Forward declare future extension interface
 134
 135   /**
 136    * @brief Virtual destructor.
 137    */
 138   DALI_IMPORT_API virtual ~ItemLayout();
 139
 140   /**
 141    * @brief Set the orientation of the layout.
 142    *
 143    * @param[in] orientation The orientation of the layout.
 144    */
 145   DALI_IMPORT_API void SetOrientation(ControlOrientation::Type orientation);
 146
 147   /**
 148    * @brief Query the orientation of the layout.
 149    *
 150    * @return the orientation of the layout.
 151    */
 152   DALI_IMPORT_API ControlOrientation::Type GetOrientation() const;
 153
 154   /**
 155    * @brief Retrieve the target size of an item in the layout.
 156    *
 157    * This will return the default size for the layout unless overridden by calling SetItemSize().
 158    *
 159    * @note layout-position is not provided as a parameter, since applying size constraints is not recommended.
 160    * Animating to target-sizes is preferable, since this allows controls to perform layouting without constraints.
 161    * @param[in] itemId The ID of an item in the layout.
 162    * @param[in] layoutSize The layout size
 163    * @param[out] itemSize The target size of an item.
 164    */
 165   DALI_IMPORT_API void GetItemSize( unsigned int itemId, const Vector3& layoutSize, Vector3& itemSize ) const;
 166
 167   /**
 168    * @brief Overrides the default size for the layout.
 169    *
 170    * @param[in] itemSize The size of each item.
 171    */
 172   DALI_IMPORT_API void SetItemSize( const Vector3& itemSize );
 173
 174   /**
 175    * @brief Query the minimum valid layout position; this is a negative value.
 176    *
 177    * When scrolling, the first item will move within the range 0 to GetMinimumLayoutPosition().
 178    * @param[in] numberOfItems The current number of items in the layout.
 179    * @param[in] layoutSize The size of the layout area.
 180    * @return The minimum layout position.
 181    */
 182   virtual float GetMinimumLayoutPosition(unsigned int numberOfItems, Vector3 layoutSize) const = 0;
 183
 184   /**
 185    * @brief Query the closest anchor position for the given layout position.
 186    *
 187    * This anchor position is the position where all the items in the layout are aligned to
 188    * their rounded layout positions in integer.
 189    * @param[in] layoutPosition The layout position.
 190    * @return The closest anchor position for the given layout position.
 191    */
 192   virtual float GetClosestAnchorPosition(float layoutPosition) const = 0;
 193
 194   /**
 195    * @brief Query the layout position for the first item in the layout to move to when the layout
 196    * needs to scroll to a particular item.
 197    *
 198    * @param[in] itemId The ID of an item in the layout.
 199    * @return The layout position for the first item in the layout to move to.
 200    */
 201   virtual float GetItemScrollToPosition(unsigned int itemId) const = 0;
 202
 203   /**
 204    * @brief Query the items within a given layout-area.
 205    *
 206    * @param[in] firstItemPosition The layout-position of the first item in the layout.
 207    * @param[in] layoutSize The size of the layout area.
 208    * @return The ID of the first & last visible item.
 209    */
 210   virtual ItemRange GetItemsWithinArea(float firstItemPosition, Vector3 layoutSize) const = 0;
 211
 212   /**
 213    * @brief Get the closest layout position to bring an item onto the screen.
 214    *
 215    * If the item is already fully on the screen this function will
 216    * return the current layout position.
 217    *
 218    * This function is used by systems such as KeyboardFocusManager to
 219    * bring the next focusable item into view and all layout
 220    * implementations should provide their own version of this function
 221    * to ensure proper functionality of internal toolkit systems.
 222    *
 223    * @param[in] itemID id of the item to bring within the viewable screen area
 224    * @param[in] currentLayoutPosition the current layout position of the item view instance
 225    * @param[in] layoutSize the current size of the item view instance
 226    * @return The layout position
 227    */
 228   DALI_IMPORT_API virtual float GetClosestOnScreenLayoutPosition(int itemID, float currentLayoutPosition, const Vector3& layoutSize);
 229
 230   /**
 231    * @brief Query the number of items that should be reserved, for scrolling purposes.
 232    *
 233    * @param[in] layoutSize The size of the layout area.
 234    * @return The number of extra items. ItemView will populate itself with actors within the layout-area
 235    * (see GetItemsWithinArea), plus this number of additional items on either-side.
 236    */
 237   virtual unsigned int GetReserveItemCount(Vector3 layoutSize) const = 0;
 238
 239   /**
 240    * @brief Retrieve the default size of an item in the layout.
 241    *
 242    * @note layout-position is not provided as a parameter, since applying size constraints is not recommended.
 243    * Animating to target-sizes is preferable, since this allows controls to perform layouting without constraints.
 244    * @param[in] itemId The ID of an item in the layout.
 245    * @param[in] layoutSize The layout size
 246    * @param[out] itemSize The target size of an item.
 247    */
 248   virtual void GetDefaultItemSize( unsigned int itemId, const Vector3& layoutSize, Vector3& itemSize ) const = 0;
 249
 250   /**
 251    * @brief Query the scroll direction of the layout.
 252    *
 253    * When an input gesture follows this direction, the layout-position of items will be increased.
 254    * If the input gesture points in the opposite direction, then the layout-positions will decrease.
 255    * @return The scroll direction in degrees.
 256    */
 257   virtual Degree GetScrollDirection() const = 0;
 258
 259   /**
 260    * @brief Query the scroll speed factor of the layout while dragging.
 261    *
 262    * This factor is used by the layout to customise its scroll speed while dragging.
 263    * The factor will be multiplied with the scroll distance of how many pixels in actor coordinate,
 264    * and the layout position of the actors in ItemView will be moved by this result.
 265    * For example, when the speed factor is 0.01, if the scroll distance is 100 pixels, the layout
 266    * position of actors will be moved by 1.
 267    * Therefore, the bigger the factor is, the faster the scroll speed will be.
 268    *
 269    * @return The scroll speed factor of the layout.
 270    */
 271   virtual float GetScrollSpeedFactor() const = 0;
 272
 273   /**
 274    * @brief Query the maximum swipe speed in pixels per second.
 275    *
 276    * Swipe gestures will be clamped when exceeding this speed limit.
 277    * @return speed The maximum swipe speed.
 278    */
 279   virtual float GetMaximumSwipeSpeed() const = 0;
 280
 281   /**
 282    * @brief Get the duration of the flick animation in second.
 283    *
 284    * This is the time taken to animate each
 285    * item to its next layout position (e.g. from 1.0 to 2.0) when a flick animation is triggered
 286    * by a swipe gesture.
 287    * @return The duration of the flick animation.
 288    */
 289   virtual float GetItemFlickAnimationDuration() const = 0;
 290
 291   /**
 292    * @brief Gets the id of the next item for KeyboardFocusManager to focus on depending on the inputted item ID.
 293    *
 294    * @param[in] itemID The current focused item
 295    * @param[in] maxItems The maximum number of items in the list
 296    * @param[in] direction The directional key pressed on the keyboard
 297    * @param[in] loopEnabled Whether the KeyboardFocusManager is set to wrap around between first and last item
 298    * @return The next item ID.
 299    */
 300   DALI_IMPORT_API virtual int GetNextFocusItemID(int itemID, int maxItems, Dali::Toolkit::Control::KeyboardFocus::Direction direction, bool loopEnabled);
 301
 302   /**
 303    * @brief Query the flick speed factor of the layout while swipping.
 304    *
 305    * This factor is used by the layout to customise its scroll speed while swiping.
 306    * The factor will be multiplied with the scroll distance of how many pixels in actor coordinate,
 307    * and the layout position of the actors in ItemView will be moved by this result.
 308    * For example, when the speed factor is 0.01, if the scroll distance is 100 pixels, the layout
 309    * position of actors will be moved by 1.
 310    * Therefore, the bigger the factor is, the faster the flick speed will be.
 311    *
 312    * @return The scroll speed factor of the layout.
 313    */
 314   DALI_IMPORT_API virtual float GetFlickSpeedFactor() const;
 315
 316   /*
 317    * @brief Applies constraints defined by the layout to an actor.
 318    *
 319    * @param[in] actor The actor to constrain.
 320    * @param[in] itemId The ID of the item represented by the actor.
 321    * @param[in] layoutSize the current size of the item view instance.
 322    * @param[in] itemViewActor The item view instance which requests the application of constraints.
 323    */
 324   DALI_IMPORT_API virtual void ApplyConstraints( Actor& actor, const int itemId, const Vector3& layoutSize, const Actor& itemViewActor ) = 0;
 325
 326   /**
 327    * @brief Gets the position of a given item
 328    *
 329    * @param[in] itemID id of the item we want to get its position
 330    * @param[in] currentLayoutPosition the current layout position of the item view instance
 331    * @param[in] layoutSize the current size of the item view instance
 332    * @return The item position (x,y,z)
 333    */
 334   DALI_IMPORT_API virtual Vector3 GetItemPosition(int itemID, float currentLayoutPosition, const Vector3& layoutSize) const = 0;
 335
 336   /**
 337    * Retrieve the extension for this layout.
 338    *
 339    * @return The extension if available, NULL otherwise
 340    */
 341   virtual Extension* GetExtension()
 342   {
 343     return NULL;
 344   }
 345
 346 protected:
 347
 348   /**
 349    * @brief Create a new ItemLayout; Only derived versions are instantiatable.
 350    */
 351   DALI_IMPORT_API ItemLayout();
 352
 353 private:
 354
 355   /**
 356    * Don't allow copy constructor
 357    */
 358   ItemLayout( const ItemLayout& handle );
 359
 360   /**
 361    * Don't allow copy operator
 362    */
 363   ItemLayout& operator=( const ItemLayout& handle );
 364
 365 protected:
 366
 367   struct Impl;
 368   Impl* mImpl;
 369 };
 370
 371 /**
 372  * @}
 373  */
 374 } // namespace Toolkit
 375
 376 } // namespace Dali
 377
 378 #endif // __DALI_TOOLKIT_ITEM_LAYOUT_H__