capi/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 Flora License, Version 1.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://floralicense.org/license/
  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  * @addtogroup CAPI_DALI_TOOLKIT_ITEM_VIEW_MODULE
  22  * @{
  23  */
  24
  25 // INTERNAL INCLUDES
  26 #include <dali/dali.h>
  27 #include <dali-toolkit/public-api/enums.h>
  28 #include <dali-toolkit/public-api/controls/control.h>
  29
  30 namespace Dali DALI_IMPORT_API
  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 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   virtual ~ItemLayout();
 152
 153   /**
 154    * @brief Set the orientation of the layout.
 155    *
 156    * @param[in] orientation The orientation of the layout.
 157    */
 158   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   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   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 Tells scroll components how to interpolate our logical scroll position as a screen x/y direction.
 316    *
 317    * Application developer wants to use -ve y, +ve x as up direction and +ve y, -ve x as down direction scroll values in a
 318    * vertical scroll type effect (SpiralLayout). This means that scroll bar/overshoot indicator should be affected by y-axis.
 319    * Returning (0.0f, 0.0f) for x and (0.0f, -1.0f) for y tells us that we need to use the y scroll value to move the scroll bar
 320    * along y axis with y scroll of 0 starting at bottom (due to -1.0f on y), a value of (0.0f, 1.0f) on x axis mask would mean using y scroll value to move scroll bar along x axis
 321    *
 322    * This function is used by numerous objects such as scroll indicators and scroll overshoot indicators and all
 323    * layout implementations should provide their own version of this function to ensure proper functionality of
 324    * internal toolkit systems.
 325    *
 326    * @param[out] scrollHint Vector2 describing how x and y scroll values should be used for x-axis scrolling
 327    */
 328   virtual void GetXAxisScrollHint(Vector2& scrollHint) const;
 329
 330   /**
 331    * @brief Tells scroll components how to interpolate our logical scroll position as a screen x/y direction.
 332    *
 333    * Application developer wants to use -ve y, +ve x as up direction and +ve y, -ve x as down direction scroll values in a
 334    * vertical scroll type effect (SpiralLayout). This means that scroll bar/overshoot indicator should be affected by y-axis.
 335    * Returning (0.0f, 0.0f) for x and (0.0f, -1.0f) for y tells us that we need to use the y scroll value to move the scroll bar
 336    * along y axis with y scroll of 0 starting at bottom (due to -1.0f on y), a value of (0.0f, 1.0f) on x axis mask would mean using y scroll value to move scroll bar along x axis
 337    *
 338    * This function is used by numerous objects such as scroll indicators and scroll overshoot indicators and all
 339    * layout implementations should provide their own version of this function to ensure proper functionality of
 340    * internal toolkit systems.
 341    *
 342    * @param[out] scrollHint Vector2 describing how x and y scroll values should be used for y-axis scrolling
 343    */
 344   virtual void GetYAxisScrollHint(Vector2& scrollHint) const;
 345
 346   /**
 347    * @brief Query the scroll speed factor of the layout.
 348    *
 349    * This factor is used by the layout to customise its scroll speed while dragging and swiping.
 350    * The factor will be multiplied with the scroll distance of how many pixels in actor coordinate,
 351    * and the layout position of the actors in ItemView will be moved by this result.
 352    * For example, when the speed factor is 0.01, if the scroll distance is 100 pixels, the layout
 353    * position of actors will be moved by 1.
 354    * Therefore, the bigger the factor is, the faster the scroll speed will be.
 355    *
 356    * @return The scroll speed factor of the layout.
 357    */
 358   virtual float GetScrollSpeedFactor() const = 0;
 359
 360   /**
 361    * @brief Query the maximum swipe speed in pixels per second.
 362    *
 363    * Swipe gestures will be clamped when exceeding this speed limit.
 364    * @return speed The maximum swipe speed.
 365    */
 366   virtual float GetMaximumSwipeSpeed() const = 0;
 367
 368   /**
 369    * @brief Get the duration of the flick animation in second.
 370    *
 371    * This is the time taken to animate each
 372    * item to its next layout position (e.g. from 1.0 to 2.0) when a flick animation is triggered
 373    * by a swipe gesture.
 374    * @return The duration of the flick animation.
 375    */
 376   virtual float GetItemFlickAnimationDuration() const = 0;
 377
 378   /**
 379    * @brief Gets the id of the next item for KeyboardFocusManager to focus on depending on the inputted item ID.
 380    *
 381    * @param[in] itemID The current focused item
 382    * @param[in] maxItems The maximum number of items in the list
 383    * @param[in] direction The directional key pressed on the keyboard
 384    * @param[in] loopEnabled Whether the KeyboardFocusManager is set to wrap around between first and last item
 385    * @return The next item ID.
 386    */
 387   virtual int GetNextFocusItemID(int itemID, int maxItems, Dali::Toolkit::Control::KeyboardFocusNavigationDirection direction, bool loopEnabled);
 388
 389 protected:
 390
 391   /**
 392    * @brief Create a new ItemLayout; Only derived versions are instantiatable.
 393    */
 394   ItemLayout();
 395
 396 protected:
 397
 398   ControlOrientation::Type mOrientation; ///< the orientation of the layout.
 399 };
 400
 401 } // namespace Toolkit
 402
 403 } // namespace Dali
 404
 405 /**
 406  * @}
 407  */
 408 #endif // __DALI_TOOLKIT_ITEM_LAYOUT_H__