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