Tizen Native API
Dali::Toolkit::ItemLayout Class Reference

An ItemLayout describes the constraints which are imposed on items in the layout. More...

Inheritance diagram for Dali::Toolkit::ItemLayout:
Dali::RefObject

Public Member Functions

virtual ~ItemLayout ()
 Forward declare future extension interface.
void SetOrientation (ControlOrientation::Type orientation)
 Set the orientation of the layout.
ControlOrientation::Type GetOrientation () const
 Query the orientation of the layout.
void GetItemSize (unsigned int itemId, const Vector3 &layoutSize, Vector3 &itemSize) const
 Retrieve the target size of an item in the layout.
void SetItemSize (const Vector3 &itemSize)
 Overrides the default size for the layout.
virtual float GetMinimumLayoutPosition (unsigned int numberOfItems, Vector3 layoutSize) const =0
 Query the minimum valid layout position; this is a negative value.
virtual float GetClosestAnchorPosition (float layoutPosition) const =0
 Query the closest anchor position for the given layout position.
virtual float GetItemScrollToPosition (unsigned int itemId) const =0
 Query the layout position for the first item in the layout to move to when the layout needs to scroll to a particular item.
virtual ItemRange GetItemsWithinArea (float firstItemPosition, Vector3 layoutSize) const =0
 Query the items within a given layout-area.
virtual float GetClosestOnScreenLayoutPosition (int itemID, float currentLayoutPosition, const Vector3 &layoutSize)
 Get the closest layout position to bring an item onto the screen.
virtual unsigned int GetReserveItemCount (Vector3 layoutSize) const =0
 Query the number of items that should be reserved, for scrolling purposes.
virtual void GetDefaultItemSize (unsigned int itemId, const Vector3 &layoutSize, Vector3 &itemSize) const =0
 Retrieve the default size of an item in the layout.
virtual Degree GetScrollDirection () const =0
 Query the scroll direction of the layout.
virtual float GetScrollSpeedFactor () const =0
 Query the scroll speed factor of the layout while dragging.
virtual float GetMaximumSwipeSpeed () const =0
 Query the maximum swipe speed in pixels per second.
virtual float GetItemFlickAnimationDuration () const =0
 Get the duration of the flick animation in second.
virtual int GetNextFocusItemID (int itemID, int maxItems, Dali::Toolkit::Control::KeyboardFocus::Direction direction, bool loopEnabled)
 Gets the id of the next item for KeyboardFocusManager to focus on depending on the inputted item ID.
virtual float GetFlickSpeedFactor () const
 Query the flick speed factor of the layout while swipping.
virtual Vector3 GetItemPosition (int itemID, float currentLayoutPosition, const Vector3 &layoutSize) const =0
 Gets the position of a given item.
virtual Extension * GetExtension ()
 Retrieve the extension for this layout.

Protected Member Functions

 ItemLayout ()
 Create a new ItemLayout; Only derived versions are instantiatable.

Detailed Description

An ItemLayout describes the constraints which are imposed on items in the layout.

  • Potentially visible items are represented by Actors, created for ItemView by the ItemFactory.
  • Constraints are applied after ItemView activates a layout.

An ItemLayout also describes the direction of input gestures, used to scroll through the layout. Whilst scrolling, the layout provides a range of items that are within a layout-area (3D bounding volume).

Since :
2.4

Constructor & Destructor Documentation

Forward declare future extension interface.

Virtual destructor

Since :
2.4

Create a new ItemLayout; Only derived versions are instantiatable.

Since :
2.4

Member Function Documentation

virtual float Dali::Toolkit::ItemLayout::GetClosestAnchorPosition ( float  layoutPosition) const [pure virtual]

Query the closest anchor position for the given layout position.

This anchor position is the position where all the items in the layout are aligned to their rounded layout positions in integer.

Since :
2.4
Parameters:
[in]layoutPositionThe layout position
Returns:
The closest anchor position for the given layout position
virtual float Dali::Toolkit::ItemLayout::GetClosestOnScreenLayoutPosition ( int  itemID,
float  currentLayoutPosition,
const Vector3 layoutSize 
) [virtual]

Get the closest layout position to bring an item onto the screen.

If the item is already fully on the screen this function will return the current layout position.

This function is used by systems such as KeyboardFocusManager to bring the next focusable item into view and all layout implementations should provide their own version of this function to ensure proper functionality of internal toolkit systems.

Since :
2.4
Parameters:
[in]itemIDid of the item to bring within the viewable screen area
[in]currentLayoutPositionthe current layout position of the item view instance
[in]layoutSizethe current size of the item view instance
Returns:
The layout position
virtual void Dali::Toolkit::ItemLayout::GetDefaultItemSize ( unsigned int  itemId,
const Vector3 layoutSize,
Vector3 itemSize 
) const [pure virtual]

Retrieve the default size of an item in the layout.

Since :
2.4
Parameters:
[in]itemIdThe ID of an item in the layout
[in]layoutSizeThe layout size
[out]itemSizeThe target size of an item
Note:
layout-position is not provided as a parameter, since applying size constraints is not recommended. Animating to target-sizes is preferable, since this allows controls to perform layouting without constraints.
virtual Extension* Dali::Toolkit::ItemLayout::GetExtension ( ) [virtual]

Retrieve the extension for this layout.

Since :
2.4
Returns:
The extension if available, NULL otherwise.
virtual float Dali::Toolkit::ItemLayout::GetFlickSpeedFactor ( ) const [virtual]

Query the flick speed factor of the layout while swipping.

This factor is used by the layout to customise its scroll speed while swiping. The factor will be multiplied with the scroll distance of how many pixels in actor coordinate, and the layout position of the actors in ItemView will be moved by this result. For example, when the speed factor is 0.01, if the scroll distance is 100 pixels, the layout position of actors will be moved by 1. Therefore, the bigger the factor is, the faster the flick speed will be.

Since :
2.4
Returns:
The scroll speed factor of the layout
virtual float Dali::Toolkit::ItemLayout::GetItemFlickAnimationDuration ( ) const [pure virtual]

Get the duration of the flick animation in second.

This is the time taken to animate each item to its next layout position (e.g. from 1.0 to 2.0) when a flick animation is triggered by a swipe gesture.

Since :
2.4
Returns:
The duration of the flick animation
virtual Vector3 Dali::Toolkit::ItemLayout::GetItemPosition ( int  itemID,
float  currentLayoutPosition,
const Vector3 layoutSize 
) const [pure virtual]

Gets the position of a given item.

Since :
2.4
Parameters:
[in]itemIDThe id of the item we want to get its position
[in]currentLayoutPositionThe current layout position of the item view instance
[in]layoutSizeThe current size of the item view instance
Returns:
The item position (x,y,z)
virtual float Dali::Toolkit::ItemLayout::GetItemScrollToPosition ( unsigned int  itemId) const [pure virtual]

Query the layout position for the first item in the layout to move to when the layout needs to scroll to a particular item.

Since :
2.4
Parameters:
[in]itemIdThe ID of an item in the layout
Returns:
The layout position for the first item in the layout to move to
void Dali::Toolkit::ItemLayout::GetItemSize ( unsigned int  itemId,
const Vector3 layoutSize,
Vector3 itemSize 
) const

Retrieve the target size of an item in the layout.

This will return the default size for the layout unless overridden by calling SetItemSize().

Since :
2.4
Parameters:
[in]itemIdThe ID of an item in the layout
[in]layoutSizeThe layout size
[out]itemSizeThe target size of an item
Note:
layout-position is not provided as a parameter, since applying size constraints is not recommended. Animating to target-sizes is preferable, since this allows controls to perform layouting without constraints.
virtual ItemRange Dali::Toolkit::ItemLayout::GetItemsWithinArea ( float  firstItemPosition,
Vector3  layoutSize 
) const [pure virtual]

Query the items within a given layout-area.

Since :
2.4
Parameters:
[in]firstItemPositionThe layout-position of the first item in the layout
[in]layoutSizeThe size of the layout area
Returns:
The ID of the first & last visible item
virtual float Dali::Toolkit::ItemLayout::GetMaximumSwipeSpeed ( ) const [pure virtual]

Query the maximum swipe speed in pixels per second.

Swipe gestures will be clamped when exceeding this speed limit.

Since :
2.4
Returns:
speed The maximum swipe speed
virtual float Dali::Toolkit::ItemLayout::GetMinimumLayoutPosition ( unsigned int  numberOfItems,
Vector3  layoutSize 
) const [pure virtual]

Query the minimum valid layout position; this is a negative value.

When scrolling, the first item will move within the range 0 to GetMinimumLayoutPosition().

Since :
2.4
Parameters:
[in]numberOfItemsThe current number of items in the layout
[in]layoutSizeThe size of the layout area
Returns:
The minimum layout position
virtual int Dali::Toolkit::ItemLayout::GetNextFocusItemID ( int  itemID,
int  maxItems,
Dali::Toolkit::Control::KeyboardFocus::Direction  direction,
bool  loopEnabled 
) [virtual]

Gets the id of the next item for KeyboardFocusManager to focus on depending on the inputted item ID.

Since :
2.4
Parameters:
[in]itemIDThe current focused item
[in]maxItemsThe maximum number of items in the list
[in]directionThe directional key pressed on the keyboard
[in]loopEnabledWhether the KeyboardFocusManager is set to wrap around between first and last item
Returns:
The next item ID

Query the orientation of the layout.

Since :
2.4
Returns:
The orientation of the layout
virtual unsigned int Dali::Toolkit::ItemLayout::GetReserveItemCount ( Vector3  layoutSize) const [pure virtual]

Query the number of items that should be reserved, for scrolling purposes.

Since :
2.4
Parameters:
[in]layoutSizeThe size of the layout area
Returns:
The number of extra items. ItemView will populate itself with actors within the layout-area (see GetItemsWithinArea), plus this number of additional items on either-side.
virtual Degree Dali::Toolkit::ItemLayout::GetScrollDirection ( ) const [pure virtual]

Query the scroll direction of the layout.

When an input gesture follows this direction, the layout-position of items will be increased. If the input gesture points in the opposite direction, then the layout-positions will decrease.

Since :
2.4
Returns:
The scroll direction in degrees
virtual float Dali::Toolkit::ItemLayout::GetScrollSpeedFactor ( ) const [pure virtual]

Query the scroll speed factor of the layout while dragging.

This factor is used by the layout to customise its scroll speed while dragging. The factor will be multiplied with the scroll distance of how many pixels in actor coordinate, and the layout position of the actors in ItemView will be moved by this result. For example, when the speed factor is 0.01, if the scroll distance is 100 pixels, the layout position of actors will be moved by 1. Therefore, the bigger the factor is, the faster the scroll speed will be.

Since :
2.4
Returns:
The scroll speed factor of the layout
void Dali::Toolkit::ItemLayout::SetItemSize ( const Vector3 itemSize)

Overrides the default size for the layout.

Since :
2.4
Parameters:
[in]itemSizeThe size of each item

Set the orientation of the layout.

Since :
2.4
Parameters:
[in]orientationThe orientation of the layout