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