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