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