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