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