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