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 Retrieve the resize animation in the layout.
 248    *
 249    * @note This allows the layout to provide its own resize animation.
 250    * @param[in] animation The resize animation, not owned by the layout
 251    * @param[in] actor The actor to animate
 252    * @param [in] size The target size.
 253    * @param [in] durationSeconds The duration of the resizing.
 254    */
 255   virtual void GetResizeAnimation(Animation& animation, Actor actor, Vector3 size, float durationSeconds) const = 0;
 256
 257   /**
 258    * @brief Query the scroll direction of the layout.
 259    *
 260    * When an input gesture follows this direction, the layout-position of items will be increased.
 261    * If the input gesture points in the opposite direction, then the layout-positions will decrease.
 262    * @return The scroll direction in degrees.
 263    */
 264   virtual Degree GetScrollDirection() const = 0;
 265
 266   /**
 267    * @brief Query the scroll speed factor of the layout while dragging.
 268    *
 269    * This factor is used by the layout to customise its scroll speed while dragging.
 270    * The factor will be multiplied with the scroll distance of how many pixels in actor coordinate,
 271    * and the layout position of the actors in ItemView will be moved by this result.
 272    * For example, when the speed factor is 0.01, if the scroll distance is 100 pixels, the layout
 273    * position of actors will be moved by 1.
 274    * Therefore, the bigger the factor is, the faster the scroll speed will be.
 275    *
 276    * @return The scroll speed factor of the layout.
 277    */
 278   virtual float GetScrollSpeedFactor() const = 0;
 279
 280   /**
 281    * @brief Query the maximum swipe speed in pixels per second.
 282    *
 283    * Swipe gestures will be clamped when exceeding this speed limit.
 284    * @return speed The maximum swipe speed.
 285    */
 286   virtual float GetMaximumSwipeSpeed() const = 0;
 287
 288   /**
 289    * @brief Get the duration of the flick animation in second.
 290    *
 291    * This is the time taken to animate each
 292    * item to its next layout position (e.g. from 1.0 to 2.0) when a flick animation is triggered
 293    * by a swipe gesture.
 294    * @return The duration of the flick animation.
 295    */
 296   virtual float GetItemFlickAnimationDuration() const = 0;
 297
 298   /**
 299    * @brief Gets the id of the next item for KeyboardFocusManager to focus on depending on the inputted item ID.
 300    *
 301    * @param[in] itemID The current focused item
 302    * @param[in] maxItems The maximum number of items in the list
 303    * @param[in] direction The directional key pressed on the keyboard
 304    * @param[in] loopEnabled Whether the KeyboardFocusManager is set to wrap around between first and last item
 305    * @return The next item ID.
 306    */
 307   DALI_IMPORT_API virtual int GetNextFocusItemID(int itemID, int maxItems, Dali::Toolkit::Control::KeyboardFocusNavigationDirection direction, bool loopEnabled);
 308
 309   /**
 310    * @brief Query the flick speed factor of the layout while swipping.
 311    *
 312    * This factor is used by the layout to customise its scroll speed while swiping.
 313    * The factor will be multiplied with the scroll distance of how many pixels in actor coordinate,
 314    * and the layout position of the actors in ItemView will be moved by this result.
 315    * For example, when the speed factor is 0.01, if the scroll distance is 100 pixels, the layout
 316    * position of actors will be moved by 1.
 317    * Therefore, the bigger the factor is, the faster the flick speed will be.
 318    *
 319    * @return The scroll speed factor of the layout.
 320    */
 321   DALI_IMPORT_API virtual float GetFlickSpeedFactor() const;
 322
 323   /*
 324    * @brief Applies constraints defined by the layout to an actor.
 325    *
 326    * @param[in] actor The actor to constrain.
 327    * @param[in] itemId The ID of the item represented by the actor.
 328    * @param[in] layoutSize the current size of the item view instance.
 329    * @param[in] itemViewActor The item view instance which requests the application of constraints.
 330    */
 331   DALI_IMPORT_API virtual void ApplyConstraints( Actor& actor, const int itemId, const Vector3& layoutSize, const Actor& itemViewActor ) = 0;
 332
 333   /**
 334    * @brief Gets the position of a given item
 335    *
 336    * @param[in] itemID id of the item we want to get its position
 337    * @param[in] currentLayoutPosition the current layout position of the item view instance
 338    * @param[in] layoutSize the current size of the item view instance
 339    * @return The item position (x,y,z)
 340    */
 341   DALI_IMPORT_API virtual Vector3 GetItemPosition(int itemID, float currentLayoutPosition, const Vector3& layoutSize) const = 0;
 342
 343   /**
 344    * Retrieve the extension for this layout.
 345    *
 346    * @return The extension if available, NULL otherwise
 347    */
 348   virtual Extension* GetExtension()
 349   {
 350     return NULL;
 351   }
 352
 353 protected:
 354
 355   /**
 356    * @brief Create a new ItemLayout; Only derived versions are instantiatable.
 357    */
 358   DALI_IMPORT_API ItemLayout();
 359
 360 protected:
 361
 362   struct Impl;
 363   Impl* mImpl;
 364 };
 365
 366 } // namespace Toolkit
 367
 368 } // namespace Dali
 369
 370 #endif // __DALI_TOOLKIT_ITEM_LAYOUT_H__