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