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