Tizen Native API  4.0
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 SetLayoutProperties (const Property::Map &properties)
 Apply the layout Properties.
Property::Map GetLayoutProperties ()
 Get the layout Properties.
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 void ApplyConstraints (Actor &actor, const int itemId, const Vector3 &layoutSize, const Actor &itemViewActor)=0
 Applies constraints defined by the layout to an actor.
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:
3.0, DALi version 1.0.0

Constructor & Destructor Documentation

Forward declare future extension interface.

Virtual destructor.

Since:
3.0, DALi version 1.0.0

Create a new ItemLayout; Only derived versions are instantiatable.

Since:
3.0, DALi version 1.0.0

Member Function Documentation

virtual void Dali::Toolkit::ItemLayout::ApplyConstraints ( Actor actor,
const int  itemId,
const Vector3 layoutSize,
const Actor itemViewActor 
) [pure virtual]

Applies constraints defined by the layout to an actor.

Parameters:
[in]actorThe actor to constrain.
[in]itemIdThe ID of the item represented by the actor.
[in]layoutSizeThe current size of the item view instance.
[in]itemViewActorThe item view instance which requests the application of constraints.
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:
3.0, DALi version 1.0.0
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:
3.0, DALi version 1.0.0
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:
3.0, DALi version 1.0.0
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:
3.0, DALi version 1.0.0
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:
3.0, DALi version 1.0.0
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:
3.0, DALi version 1.0.0
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:
3.0, DALi version 1.0.0
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:
3.0, DALi version 1.0.0
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:
3.0, DALi version 1.0.0
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:
3.0, DALi version 1.0.0
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.

Get the layout Properties.

Since:
4.0, DALi version 1.2.20
Returns:
the property of the layout.
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:
3.0, DALi version 1.0.0
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:
3.0, DALi version 1.0.0
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:
3.0, DALi version 1.0.0
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:
3.0, DALi version 1.0.0
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:
3.0, DALi version 1.0.0
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:
3.0, DALi version 1.0.0
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:
3.0, DALi version 1.0.0
Returns:
The scroll speed factor of the layout.
void Dali::Toolkit::ItemLayout::SetItemSize ( const Vector3 itemSize)

Overrides the default size for the layout.

Since:
3.0, DALi version 1.0.0
Parameters:
[in]itemSizeThe size of each item.

Apply the layout Properties.

Since:
4.0, DALi version 1.2.20
Parameters:
[in]propertiesThe properties the layout.

Set the orientation of the layout.

Since:
3.0, DALi version 1.0.0
Parameters:
[in]orientationThe orientation of the layout.