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 Creates 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 Tests 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 Creates 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 Retrieve the target size of an item in the layout.
 185    *
 186    * This will return the default size for the layout unless overridden by calling SetItemSize().
 187    *
 188    * @SINCE_1_0.0
 189    * @param[in] itemId The ID of an item in the layout.
 190    * @param[in] layoutSize The layout size
 191    * @param[out] itemSize The target size of an item.
 192    * @note layout-position is not provided as a parameter, since applying size constraints is not recommended.
 193    * Animating to target-sizes is preferable, since this allows controls to perform layouting without constraints.
 194    */
 195   DALI_IMPORT_API void GetItemSize( unsigned int itemId, const Vector3& layoutSize, Vector3& itemSize ) const;
 196
 197   /**
 198    * @brief Overrides the default size for the layout.
 199    *
 200    * @SINCE_1_0.0
 201    * @param[in] itemSize The size of each item.
 202    */
 203   DALI_IMPORT_API void SetItemSize( const Vector3& itemSize );
 204
 205   /**
 206    * @brief Query the minimum valid layout position; this is a negative value.
 207    *
 208    * When scrolling, the first item will move within the range 0 to GetMinimumLayoutPosition().
 209    * @SINCE_1_0.0
 210    * @param[in] numberOfItems The current number of items in the layout.
 211    * @param[in] layoutSize The size of the layout area.
 212    * @return The minimum layout position.
 213    */
 214   virtual float GetMinimumLayoutPosition(unsigned int numberOfItems, Vector3 layoutSize) const = 0;
 215
 216   /**
 217    * @brief Query the closest anchor position for the given layout position.
 218    *
 219    * This anchor position is the position where all the items in the layout are aligned to
 220    * their rounded layout positions in integer.
 221    * @SINCE_1_0.0
 222    * @param[in] layoutPosition The layout position.
 223    * @return The closest anchor position for the given layout position.
 224    */
 225   virtual float GetClosestAnchorPosition(float layoutPosition) const = 0;
 226
 227   /**
 228    * @brief Query the layout position for the first item in the layout to move to when the layout
 229    * needs to scroll to a particular item.
 230    *
 231    * @SINCE_1_0.0
 232    * @param[in] itemId The ID of an item in the layout.
 233    * @return The layout position for the first item in the layout to move to.
 234    */
 235   virtual float GetItemScrollToPosition(unsigned int itemId) const = 0;
 236
 237   /**
 238    * @brief Query the items within a given layout-area.
 239    *
 240    * @SINCE_1_0.0
 241    * @param[in] firstItemPosition The layout-position of the first item in the layout.
 242    * @param[in] layoutSize The size of the layout area.
 243    * @return The ID of the first & last visible item.
 244    */
 245   virtual ItemRange GetItemsWithinArea(float firstItemPosition, Vector3 layoutSize) const = 0;
 246
 247   /**
 248    * @brief Get the closest layout position to bring an item onto the screen.
 249    *
 250    * If the item is already fully on the screen this function will
 251    * return the current layout position.
 252    *
 253    * This function is used by systems such as KeyboardFocusManager to
 254    * bring the next focusable item into view and all layout
 255    * implementations should provide their own version of this function
 256    * to ensure proper functionality of internal toolkit systems.
 257    *
 258    * @SINCE_1_0.0
 259    * @param[in] itemID id of the item to bring within the viewable screen area
 260    * @param[in] currentLayoutPosition the current layout position of the item view instance
 261    * @param[in] layoutSize the current size of the item view instance
 262    * @return The layout position
 263    */
 264   DALI_IMPORT_API virtual float GetClosestOnScreenLayoutPosition(int itemID, float currentLayoutPosition, const Vector3& layoutSize);
 265
 266   /**
 267    * @brief Query the number of items that should be reserved, for scrolling purposes.
 268    *
 269    * @SINCE_1_0.0
 270    * @param[in] layoutSize The size of the layout area.
 271    * @return The number of extra items. ItemView will populate itself with actors within the layout-area
 272    * (see GetItemsWithinArea), plus this number of additional items on either-side.
 273    */
 274   virtual unsigned int GetReserveItemCount(Vector3 layoutSize) const = 0;
 275
 276   /**
 277    * @brief Retrieve the default size of an item in the layout.
 278    *
 279    * @SINCE_1_0.0
 280    * @param[in] itemId The ID of an item in the layout.
 281    * @param[in] layoutSize The layout size
 282    * @param[out] itemSize The target size of an item.
 283    * @note layout-position is not provided as a parameter, since applying size constraints is not recommended.
 284    * Animating to target-sizes is preferable, since this allows controls to perform layouting without constraints.
 285    */
 286   virtual void GetDefaultItemSize( unsigned int itemId, const Vector3& layoutSize, Vector3& itemSize ) const = 0;
 287
 288   /**
 289    * @brief Query the scroll direction of the layout.
 290    *
 291    * When an input gesture follows this direction, the layout-position of items will be increased.
 292    * If the input gesture points in the opposite direction, then the layout-positions will decrease.
 293    * @SINCE_1_0.0
 294    * @return The scroll direction in degrees.
 295    */
 296   virtual Degree GetScrollDirection() const = 0;
 297
 298   /**
 299    * @brief Query the scroll speed factor of the layout while dragging.
 300    *
 301    * This factor is used by the layout to customise its scroll speed while dragging.
 302    * The factor will be multiplied with the scroll distance of how many pixels in actor coordinate,
 303    * and the layout position of the actors in ItemView will be moved by this result.
 304    * For example, when the speed factor is 0.01, if the scroll distance is 100 pixels, the layout
 305    * position of actors will be moved by 1.
 306    * Therefore, the bigger the factor is, the faster the scroll speed will be.
 307    *
 308    * @SINCE_1_0.0
 309    * @return The scroll speed factor of the layout.
 310    */
 311   virtual float GetScrollSpeedFactor() const = 0;
 312
 313   /**
 314    * @brief Query the maximum swipe speed in pixels per second.
 315    *
 316    * Swipe gestures will be clamped when exceeding this speed limit.
 317    * @SINCE_1_0.0
 318    * @return speed The maximum swipe speed.
 319    */
 320   virtual float GetMaximumSwipeSpeed() const = 0;
 321
 322   /**
 323    * @brief Get the duration of the flick animation in second.
 324    *
 325    * This is the time taken to animate each
 326    * item to its next layout position (e.g. from 1.0 to 2.0) when a flick animation is triggered
 327    * by a swipe gesture.
 328    * @SINCE_1_0.0
 329    * @return The duration of the flick animation.
 330    */
 331   virtual float GetItemFlickAnimationDuration() const = 0;
 332
 333   /**
 334    * @brief Gets the id of the next item for KeyboardFocusManager to focus on depending on the inputted item ID.
 335    *
 336    * @SINCE_1_0.0
 337    * @param[in] itemID The current focused item
 338    * @param[in] maxItems The maximum number of items in the list
 339    * @param[in] direction The directional key pressed on the keyboard
 340    * @param[in] loopEnabled Whether the KeyboardFocusManager is set to wrap around between first and last item
 341    * @return The next item ID.
 342    */
 343   DALI_IMPORT_API virtual int GetNextFocusItemID(int itemID, int maxItems, Dali::Toolkit::Control::KeyboardFocus::Direction direction, bool loopEnabled);
 344
 345   /**
 346    * @brief Query the flick speed factor of the layout while swipping.
 347    *
 348    * This factor is used by the layout to customise its scroll speed while swiping.
 349    * The factor will be multiplied with the scroll distance of how many pixels in actor coordinate,
 350    * and the layout position of the actors in ItemView will be moved by this result.
 351    * For example, when the speed factor is 0.01, if the scroll distance is 100 pixels, the layout
 352    * position of actors will be moved by 1.
 353    * Therefore, the bigger the factor is, the faster the flick speed will be.
 354    *
 355    * @SINCE_1_0.0
 356    * @return The scroll speed factor of the layout.
 357    */
 358   DALI_IMPORT_API virtual float GetFlickSpeedFactor() const;
 359
 360   /*
 361    * @brief Applies constraints defined by the layout to an actor.
 362    *
 363    * @param[in] actor The actor to constrain.
 364    * @param[in] itemId The ID of the item represented by the actor.
 365    * @param[in] layoutSize The current size of the item view instance.
 366    * @param[in] itemViewActor The item view instance which requests the application of constraints.
 367    */
 368   DALI_IMPORT_API virtual void ApplyConstraints( Actor& actor, const int itemId, const Vector3& layoutSize, const Actor& itemViewActor ) = 0;
 369
 370   /**
 371    * @brief Gets the position of a given item
 372    *
 373    * @SINCE_1_0.0
 374    * @param[in] itemID The id of the item we want to get its position
 375    * @param[in] currentLayoutPosition The current layout position of the item view instance
 376    * @param[in] layoutSize The current size of the item view instance
 377    * @return The item position (x,y,z)
 378    */
 379   DALI_IMPORT_API virtual Vector3 GetItemPosition(int itemID, float currentLayoutPosition, const Vector3& layoutSize) const = 0;
 380
 381   /**
 382    * @brief Retrieve the extension for this layout.
 383    *
 384    * @SINCE_1_0.0
 385    * @return The extension if available, NULL otherwise
 386    */
 387   virtual Extension* GetExtension()
 388   {
 389     return NULL;
 390   }
 391
 392 protected:
 393
 394   /**
 395    * @brief Create a new ItemLayout; Only derived versions are instantiatable.
 396    * @SINCE_1_0.0
 397    */
 398   DALI_IMPORT_API ItemLayout();
 399
 400 private:
 401
 402   /**
 403    * @brief Don't allow copy constructor
 404    * @SINCE_1_0.0
 405    */
 406   ItemLayout( const ItemLayout& handle );
 407
 408   /**
 409    * @brief Don't allow copy operator
 410    * @SINCE_1_0.0
 411    */
 412   ItemLayout& operator=( const ItemLayout& handle );
 413
 414 protected:
 415
 416   struct Impl;
 417   Impl* mImpl;
 418 };
 419
 420 /**
 421  * @}
 422  */
 423 } // namespace Toolkit
 424
 425 } // namespace Dali
 426
 427 #endif // __DALI_TOOLKIT_ITEM_LAYOUT_H__