You.i Engine
CYIGridLayout Class Reference

Detailed Description

A layout that positions items in a grid.

This layout divides the available space into rows and columns, forming a set of grid cells. Each child is then positioned within one of those cells.

Container View Template Comments Specification

These values are applied to the comment field of the container composition. All properties are optional.

Label Default value Accepted values Description
spacing 10.0 floating point The amount of space left between each row and between each column.
rows 0 positive integers The number of rows that the grid should have. If 0, the rows count is determined from the number of layoutable children.
columns 0 positive integers The number of columns that the grid should have. If 0, the columns count is determined from the number of layoutable children.
uniform-rows false true, false When true, all rows will have the same height. When false, rows can be of variable height.
uniform-columns false true, false When true, all columns will have the same width. When false, columns can be of variable width.
table-cells false true, false When true, all cells within a given row have the same height, and all cells within a given column have the same height. When false, cells can have differing heights within a single row, and can have differing widths within a single column.
fill-order automatic special* The order in which cells are filled in the grid. By default, the cells are filled row-by-row, starting in the top-left corner (except when there is a fixed number of rows). See the Fill Order section for details.
pack-mode tetris wrap, tetris, first The algorithm used to try and avoid 'holes' in the grid when dealing with non-1x1 items. See the Pack Mode section for details.

The parent layout class may define more properties that can be used.

See also
CYIAnimatingLayout

Children View Template Comments Specification

These values are applied to the comment field of the to-be-laid-out children. All properties are optional.

Label Default value Accepted values Description
cell-width 1 non-0 positive integers The number of grid cells that this child takes up, horizontally, in the grid.
cell-height 1 non-0 positive integers The number of grid cells that this child takes up, vertically, in the grid.

The parent layout class may define more properties that can be used.

See also
CYIAnimatingLayout

Rows and Columns

The number of rows and columns in the grid layout can be manually specified. If the total number of layoutable children exceeds the number of grid cells, the remaining children will overflow out of the grid.

The grid layout can automatically determine the rows and columns count based on the number of layoutable children. This is done if either the configured rows or configured columns is 0 (which is the default). When only one of the rows or columns count is configured, the other value is determined by a simple division. However, when both the rows and columns counts are non-specified, the grid layout calculates rows and columns counts that approximates the aspect ratio of the incoming measure width/height. If the layout is configured to 'fit content' for either the width or height, the grid layout assumes an aspect ratio of 1:1 (e.g. same count of rows and columns).

By default, the grid layout automatically determines the rows' widths and the columns' heights based on the size of the items they contain. If this is undesirable, the uniform-rows and uniform-columns template properties can be used to force the grid layout to make all rows have the same height, or make all columns have the same width.

The 'table cells' mode can be used to change the size of the cells within a grid layout. When enabled, it causes cells within a given row to all be of the same height, and causes cells within a given column to all be of the same width. Coupled with a background node on the laid-out children, this mode results in a table-like arrangement of cells. Note that when this mode is enabled, the normal layout behaviour of the children of the grid layout is overridden, which may result in some of the layout properties set on those children not being respected.

Non-1x1 Items

By default, all children in the grid are assumed to occupy one grid cell, no matter how large the child may be. In order to increase the flexibility of the grid layout, the children can be configured with specific cell width and cell height. The total number of cells taken in the grid is expressed as (cell width * cell height). Children cannot take 0 grid cells – the cell width and cell height both cannot be smaller than 1.

Note that when using non-1x1 items, 'holes' can result in the arranged children. The use of the various Pack Modes can alleviate this by allowing reordering of children to try and fill the gaps.

Fill Order

The fill order of the grid layout determines the order in which cells are filled in the grid layout. The following table details the available fill orders for the 'fill-order' template comment (and for the FillOrder enum). The table also provides a sample fill order, given 7 layoutable children (numbered 1 to 7) and the following grid positions:

+-----+-----+-----+
|  A  |  B  |  C  |
+-----+-----+-----+
|  D  |  E  |  F  |
+-----+-----+-----+
|  G  |  H  |  I  |
+-----+-----+-----+
Enum Value Template Comment Values Description Sample Fill Order
CYIGridLayout::FillOrder::TopLeftToRight top-left-to-right Fills the grid row-by-row, starting in the top-left corner. ABCDEFG
CYIGridLayout::FillOrder::LeftTopToBottom left-top-to-bottom Fills the grid column-by-column, starting in the top-left corner. ADGBEHC
CYIGridLayout::FillOrder::TopRightToLeft top-right-to-left Fills the grid row-by-row, starting in the top-right corner. CBAFEDI
CYIGridLayout::FillOrder::RightTopToBottom right-top-to-bottom Fills the grid column-by-column, starting in the top-right corner. CFIBEHA
CYIGridLayout::FillOrder::BottomLeftToRight bottom-left-to-right Fills the grid row-by-row, starting in the bottom-left corner. GHIDEFA
CYIGridLayout::FillOrder::LeftBottomToTop left-bottom-to-top Fills the grid column-by-column, starting in the bottom-left corner. GDAHEBI
CYIGridLayout::FillOrder::BottomRightToLeft bottom-right-to-left Fills the grid row-by-row, starting in the bottom-right corner. IHGFEDC
CYIGridLayout::FillOrder::RightBottomToTop right-bottom-to-top Fills the grid column-by-column, starting in bottom-right corner. IFCHEBG
CYIGridLayout::FillOrder::Automatic auto, automatic Automatically picks between CYIGridLayout::FillOrder::TopLeftToRight and CYIGridLayout::FillOrder::LeftTopToBottom. If the rows count is configured and the columns count is not, CYIGridLayout::FillOrder::LeftTopToBottom is used. Otherwise, CYIGridLayout::FillOrder::TopLeftToRight is used. N/A

Pack Mode

The pack mode of the grid determines how non-1x1 grid items are arranged in the grid. The following table lists the available pack modes, along with a short description of each.

Enum Value Template Comment Values Description
CYIGridLayout::FillOrder::Wrap wrap Fills the grid row-by-row (or column-by-column, depending on the fill order), wrapping to the next line when a line is full.
CYIGridLayout::FillOrder::Tetris tetris, masonry Places each child in the first column (counting from the left) that can fit the child while minimizing the y position.
CYIGridLayout::FillOrder::First first, packery Places each child in the first position (counting from the top-left) which can fit the child.
Note
The selected pack mode has no effect when all children have cell dimensions of 1x1.

For the following detailed descriptions of pack modes, consider the following layoutable children:

       +---+             +---+
+---+  |   |  +-------+  |   |  +---+ +---+
| 1 |  | 2 |  |   3   |  | 4 |  | 5 | | 6 |
+---+  |   |  +-------+  |   |  +---+ +---+
 1x1   +---+     2x1     +---+   1x1   1x1
        1x2               1x2

As an example, these layoutable children will be laid-out in a 3-column grid with each pack mode. In the diagrams, X represents an empty cell in the grid.

'Wrap' Pack Mode

+---+---+---+
| 1 |   |XXX|
+---+ 2 |XXX|
|XXX|   |XXX|
+---+---+---+
|   3   |   |
+-------+ 4 |
|XXXXXXX|   |
+---+---+---+
| 5 | 6 |XXX|
+---+-------+

In this pack mode, rows are filled one by one, with the x position in each row being strictly incremented. Holes/gaps are common when using this packing mode. Despite this, this packing mode guarantees that the ordering of children is respected.

'Tetris' Pack Mode

+---+---+---+
| 1 |   |   |
+---+ 2 | 4 |
|XXX|   |   |
+---+---+---+
|   3   | 5 |
+---+---+---+
| 6 |XXXXXXX|
+---+-------+

In this pack mode, children are placed in the 'first' column that can fit them, while minimizing the y position of those children. Holes are still possible, but are more rare. The ordering of children is roughly respected, but out-of-order children can occur. For example, look at the children #2 and #4 in the previous diagram.

This pack mode is similar to the 'masonry' packing algorithm used by some web frameworks.

'First' Pack Method

+---+---+---+
| 1 |   |   |
+---+ 2 | 4 |
| 5 |   |   |
+---+---+---+
|   3   | 6 |
+---+---+---+

In this pack mode, children are placed at the first cell that can fit them. This mode attempts to backfill gaps with layoutable children. This comes at a cost: the children can be greatly out-of-order.

This pack mode is similar to the 'packery' packing algorithm used by some web frameworks.

Warning
This pack mode can be computationally intensive, with a worst-case complexity of O(n^2).

#include <layout/YiGridLayout.h>

Inheritance diagram for CYIGridLayout:

Public Types

enum  FillOrder {
  FillOrder::Automatic = 0,
  FillOrder::TopLeftToRight,
  FillOrder::LeftTopToBottom,
  FillOrder::TopRightToLeft,
  FillOrder::RightTopToBottom,
  FillOrder::BottomLeftToRight,
  FillOrder::LeftBottomToTop,
  FillOrder::BottomRightToLeft,
  FillOrder::RightBottomToTop
}
 
enum  PackMode {
  PackMode::Wrap,
  PackMode::Tetris,
  PackMode::First
}
 
- Public Types inherited from CYILayout
enum  PositioningMode {
  PositioningMode::SetPositionDirectly,
  PositioningMode::DoNotSetPositionDirectly
}
 
typedef CYILayoutConfig::CubeOffset Padding
 

Public Member Functions

 CYIGridLayout ()
 
virtual ~CYIGridLayout ()
 
void SetSpacing (float spacing)
 
float GetSpacing () const
 
void SetRowsCount (size_t rows)
 
size_t GetRowsCount () const
 
void SetColumnsCount (size_t columns)
 
size_t GetColumnsCount () const
 
void SetUseUniformRows (bool useUniformRows)
 
bool IsUsingUniformRows () const
 
void SetUseUniformColumns (bool useUniformColumns)
 
bool IsUsingUniformColumns () const
 
void SetUseTableCells (bool useTableCells)
 
bool IsUsingTableCells () const
 
void SetFillOrder (FillOrder order)
 
FillOrder GetFillOrder () const
 
void SetPackMode (PackMode mode)
 
PackMode GetPackMode () const
 
- Public Member Functions inherited from CYIAnimatingLayout
 CYIAnimatingLayout ()
 
virtual ~CYIAnimatingLayout ()
 
void DisableAnimationsOnNextLayout (bool disable=true)
 
void DisableAnimationsOnNextLayoutFor (CYISceneNode *pChild, bool disable=true)
 
virtual void ChildAdded (CYISceneNode *pChild) override
 
virtual void ChildRemoved (CYISceneNode *pChild) override
 
virtual void ChildVisibilityChanged (CYISceneNode *pChild) override
 
void SetMovingTime (uint32_t movingTimeMs)
 
uint32_t GetMovingTimeMs () const
 
void SetSizingTime (uint32_t sizingTimeMs)
 
uint32_t GetSizingTimeMs () const
 
void SetTimeInterpolator (std::unique_ptr< CYITimeInterpolator > pInterpolator)
 
CYITimeInterpolatorGetTimeInterpolator ()
 
const CYITimeInterpolatorGetTimeInterpolator () const
 
- Public Member Functions inherited from CYILayout
 CYILayout ()
 
virtual ~CYILayout ()
 
void AttachTo (CYISceneView *pView)
 
void ConfigureFromAttachedNode ()
 
void DetachFromNode ()
 
CYISceneNodeGetAssociatedSceneNode () const
 
void Measure (const CYISceneNode::MeasureSpec &widthSpec, const CYISceneNode::MeasureSpec &heightSpec, const CYISceneNode::MeasureSpec &depthSpec)
 
void ApplyMeasurements ()
 
void SetPositioningMode (PositioningMode positioningMode)
 
PositioningMode GetPositioningMode () const
 
void SetPadding (const Padding &padding)
 
const PaddingGetPadding () const
 
void SetUseReverseChildrenOrder (bool useReverseChildrenOrder)
 
bool IsUsingReverseChildrenOrder () const
 
void SetGravity (const glm::vec3 &layoutGravity)
 
void SetGravity (CYILayoutConfig::Gravity gravity)
 
const glm::vec3 & GetGravity () const
 

Protected Member Functions

virtual void Configure () override
 
virtual void OnMeasure (const CYISceneNode::MeasureSpec &widthSpec, const CYISceneNode::MeasureSpec &heightSpec, const CYISceneNode::MeasureSpec &depthSpec) override
 
virtual void OnApplyMeasurements () override
 
virtual const CYIRuntimeTypeInfoGetLayoutConfigType () const override
 
- Protected Member Functions inherited from CYIAnimatingLayout
virtual void OnMeasurementsApplied () override
 
virtual void ApplyPosition (CYISceneNode *pChild, const glm::vec3 &position) override
 
virtual void ApplySize (CYISceneNode *pChild, const glm::vec3 &size) override
 
- Protected Member Functions inherited from CYILayout
virtual void OnSceneViewAttached ()
 
virtual void OnMeasurementsCalculated (const CYISceneNode::MeasureSpec &widthSpec, const CYISceneNode::MeasureSpec &heightSpec, const CYISceneNode::MeasureSpec &depthSpec)
 
virtual std::unique_ptr< CYILayoutStateCreateLayoutStateInstance () const
 
void CreateLayoutObjectsFor (CYISceneNode *pNode) const
 
CYISceneNodeGetChild (size_t index) const
 
void ApplyMeasurementsToBackgroundChildren ()
 
const PaddingGetPaddingForChild (const CYISceneNode *pChild) const
 

Protected Attributes

float m_spacing
 
size_t m_rows
 
size_t m_columns
 
bool m_uniformRows
 
bool m_uniformColumns
 
bool m_tableCells
 
FillOrder m_fillOrder
 
PackMode m_packMode
 
- Protected Attributes inherited from CYILayout
CYISceneViewm_pNode
 In most cases, this variable is used as a node (thus the name m_pNode ) More...
 
Padding m_padding
 
bool m_reverseChildrenOrder
 
glm::vec3 m_gravity
 
PositioningMode m_positioningMode
 

Additional Inherited Members

- Static Public Member Functions inherited from CYILayout
static void RegisterAllLayouts ()
 
static bool IsLayoutable (const CYISceneNode *pNode)
 
static glm::vec3 GetDefaultSize (const CYISceneNode *pNode, const CYISceneNode::MeasureSpec &widthSpec, const CYISceneNode::MeasureSpec &heightSpec, const CYISceneNode::MeasureSpec &depthSpec)
 
static void UpdateMeasuredSizeForFitContent (const CYISceneNode *pNode, glm::vec3 *pMeasuredSize, const glm::vec3 &contentSize, const Padding &padding, const CYISceneNode::MeasureSpec &widthSpec, const CYISceneNode::MeasureSpec &heightSpec, const CYISceneNode::MeasureSpec &depthSpec)
 
static void UnscaleMeasureSpecs (const glm::vec3 &scale, CYISceneNode::MeasureSpec *pWidthSpec, CYISceneNode::MeasureSpec *pHeightSpec, CYISceneNode::MeasureSpec *pDepthSpec)
 
static float CalculateDimension (const CYISceneNode::MeasureSpec &spec, const CYILayoutConfig::SizeConstraint &constraint, float currentValue)
 
- Protected Types inherited from CYILayout
enum  Dimensions {
  Dimensions::None = 0x0,
  Dimensions::X = 0x1,
  Dimensions::Y = 0x2,
  Dimensions::Z = 0x4,
  Dimensions::AllButX = Y | Z,
  Dimensions::AllButY = X | Z,
  Dimensions::AllButZ = X | Y,
  Dimensions::All = X | Y | Z
}
 
- Static Protected Member Functions inherited from CYILayout
static void MeasureChildWithMargins (CYISceneNode *pChild, const CYISceneNode::MeasureSpec &parentWidthSpec, const CYISceneNode::MeasureSpec &parentHeightSpec, const CYISceneNode::MeasureSpec &parentDepthSpec, const Padding &padding)
 
static void MeasureChildWithMargins (CYISceneNode *pChild, const CYISceneNode::MeasureSpec &parentWidthSpec, const CYISceneNode::MeasureSpec &parentHeightSpec, const CYISceneNode::MeasureSpec &parentDepthSpec, const Padding &padding, const glm::vec3 &childScale)
 
static CYISceneNode::MeasureSpec CalculateChildMeasureSpec (const CYISceneNode::MeasureSpec &parentMeasureSpec, float padding, const CYILayoutConfig::SizeConstraint &childConstraint, float childScale)
 
static bool UpdateMeasureSpecsForFitContent (const CYISceneNode *pNode, CYISceneNode::MeasureSpec *widthSpec, CYISceneNode::MeasureSpec *heightSpec, CYISceneNode::MeasureSpec *depthSpec)
 
static void RemeasureChildrenForFillParent (const CYISceneNode *pNode, const glm::vec3 &parentMeasuredSize, const Padding &padding, Dimensions dimensionsToRemeasure)
 
static glm::vec3 GetAdjustedPosition (const glm::vec3 &desiredTopLeftPosition, const CYISceneNode *pChild)
 
static glm::vec3 GetUnadjustedPosition (const glm::vec3 &currentTopLeftPosition, const CYISceneNode *pChild)
 
static glm::vec3 GetAdjustedMeasuredSize (const CYISceneNode *pChild)
 
static glm::vec3 GetTopLeftPositionWithGravity (const glm::vec3 &layoutGravity, const glm::vec3 &childGravity, const glm::vec3 &containerTopLeft, const glm::vec3 &containerSize, const CYILayout::Padding &padding, const glm::vec3 &childSize, const CYILayoutConfig::Margin &margin, const glm::vec3 &currentChildPosition)
 
static void MeasureBackgroundChildren (CYISceneNode *pNode, const glm::vec3 &size)
 

Member Enumeration Documentation

◆ FillOrder

The fill order to use when placing layoutable items in the grid.

See also
CYIGridLayout
Enumerator
Automatic 

Use CYIGridLayout::FillOrder::LeftTopToBottom when the number of rows is fixed, use CYIGridLayout::FillOrder::TopLeftToRight otherwise.

TopLeftToRight 

Start in top-left corner and fill row-by-row.

LeftTopToBottom 

Start in top-left corner and fill column-by-column.

TopRightToLeft 

Start in top-right corner and fill row-by-row.

RightTopToBottom 

Start in top-right corner and fill column-by-column.

BottomLeftToRight 

Start in bottom-left corner and fill row-by-row.

LeftBottomToTop 

Start in bottom-left corner and fill column-by-column.

BottomRightToLeft 

Start in bottom-right corner and fill row-by-row.

RightBottomToTop 

Start in bottom-right corner and fill column-by-column.

◆ PackMode

The pack mode used when placing layoutable items in the grid. The pack mode is determines how non-1x1 items are laid out in the grid. Choosing the right pack mode can reduce gaps in the laid-out items.

Note
While the individual enum descriptions don't mention it, columns and rows are swapped when the fill order is to fill items column-by-column.
See also
CYIGridLayout
Enumerator
Wrap 

Places items row-by-row, wrapping to another row when the row is full. Leaves gaps when non-1x1 items are encountered.

Tetris 

Places items in the next position which minimizes its y position. Reduces gaps when non-1x1 items are encountered, at the cost of reordering some items.

First 

Places items in the first position that can fit them. Significantly reduces gaps when non-1x1 items are encountered, at the cost of reordering some items.

Constructor & Destructor Documentation

◆ CYIGridLayout()

CYIGridLayout::CYIGridLayout ( )

◆ ~CYIGridLayout()

virtual CYIGridLayout::~CYIGridLayout ( )
virtual

Member Function Documentation

◆ Configure()

virtual void CYIGridLayout::Configure ( )
overrideprotectedvirtual

Extracts relevant properties the associated scene node and configures this layout with said properties.

Note
Subclasses should override this method if they have custom configuration values. Remember to call the parent Configure function.

Reimplemented from CYIAnimatingLayout.

◆ GetColumnsCount()

size_t CYIGridLayout::GetColumnsCount ( ) const
See also
SetColumnsCount

◆ GetFillOrder()

FillOrder CYIGridLayout::GetFillOrder ( ) const
See also
SetFillOrder

◆ GetLayoutConfigType()

virtual const CYIRuntimeTypeInfo& CYIGridLayout::GetLayoutConfigType ( ) const
overrideprotectedvirtual

Returns the type of layout config objects used by this layout.

Note
Subclasses should override this method if the laid-out objects can have custom configuration values. Remember to base the new class on the parent class's CYILayoutConfig class.

Reimplemented from CYIAnimatingLayout.

◆ GetPackMode()

PackMode CYIGridLayout::GetPackMode ( ) const
See also
SetPackMode

◆ GetRowsCount()

size_t CYIGridLayout::GetRowsCount ( ) const
See also
SetRowsCount

◆ GetSpacing()

float CYIGridLayout::GetSpacing ( ) const
See also
SetSpacing

◆ IsUsingTableCells()

bool CYIGridLayout::IsUsingTableCells ( ) const

◆ IsUsingUniformColumns()

bool CYIGridLayout::IsUsingUniformColumns ( ) const

◆ IsUsingUniformRows()

bool CYIGridLayout::IsUsingUniformRows ( ) const

◆ OnApplyMeasurements()

virtual void CYIGridLayout::OnApplyMeasurements ( )
overrideprotectedvirtual

Applies the measured sizes of the associate scene node's children.

Warning
Implementations of this function are required to ensure that the ApplyMeasurements function of each child node is called at least once, even if those children are hidden or are non-laid-out.
Note
Typically, if OnApplyMeasurements is overridden then OnMeasure must also be overridden.
See also
CYILayout::ApplyMeasurements

Implements CYILayout.

◆ OnMeasure()

virtual void CYIGridLayout::OnMeasure ( const CYISceneNode::MeasureSpec widthSpec,
const CYISceneNode::MeasureSpec heightSpec,
const CYISceneNode::MeasureSpec depthSpec 
)
overrideprotectedvirtual

Measures the associated scene node, considering its layout configuration constraints (if available) and the provided measure specifications.

Warning
Implementations of this function are required to ensure that the Measure function of each child scene node is called at least once, even if those children are hidden or are non-laid-out.
Note
Typically, if OnMeasure is overridden then OnApplyMeasurements must also be overridden.
See also
CYILayout::Measure

Implements CYILayout.

◆ SetColumnsCount()

void CYIGridLayout::SetColumnsCount ( size_t  columns)

Sets the number of columns that the grid has to columns. If 0, the number of columns is automatically determined from the number of layoutable items and the configured number of rows. By default, the columns count is determined automatically.

◆ SetFillOrder()

void CYIGridLayout::SetFillOrder ( FillOrder  order)

Sets the fill order to order. The fill order determines the order in which cells in the grid are filled. By default, the fill order is CYIGridLayout::FillOrder::Automatic.

See also
CYIGridLayout

◆ SetPackMode()

void CYIGridLayout::SetPackMode ( PackMode  mode)

Sets the pack mode to mode. The pack mode determines how non-1x1 items are arranged in the grid. By default, the pack mode is CYIGridLayout::FillOrder::Tetris.

◆ SetRowsCount()

void CYIGridLayout::SetRowsCount ( size_t  rows)

Sets the number of rows that the grid has to rows. If 0, the number of rows is automatically determined from the number of layoutable items and the configured number of columns. By default, the rows count is determined automatically.

◆ SetSpacing()

void CYIGridLayout::SetSpacing ( float  spacing)

Sets the spacing value to spacing. By default, the spacing is 10.0.

The spacing is extra 'space' that will be added between rows and between columns.

Note
Negative values are supported, and will result in the children overlapping each other.

◆ SetUseTableCells()

void CYIGridLayout::SetUseTableCells ( bool  useTableCells)

When useTableCells is true, indicates that all cells within a given row should have the same height, and that all cells within a given column should have the same width. This setting can be used to create a grid of minimal size (using 'fit-content' on each cell), but with their background expanding to fill the whole rows/columns. By default, cells can have non-table cell sizes.

◆ SetUseUniformColumns()

void CYIGridLayout::SetUseUniformColumns ( bool  useUniformColumns)

When useUniformColumns is true, indicates that all columns in the grid should be of the same width. By default, columns can have variable widths.

◆ SetUseUniformRows()

void CYIGridLayout::SetUseUniformRows ( bool  useUniformRows)

When useUniformRows is true, indicates that all rows in the grid should be of the same height. By default, rows can have variable heights.

Member Data Documentation

◆ m_columns

size_t CYIGridLayout::m_columns
protected

◆ m_fillOrder

FillOrder CYIGridLayout::m_fillOrder
protected

◆ m_packMode

PackMode CYIGridLayout::m_packMode
protected

◆ m_rows

size_t CYIGridLayout::m_rows
protected

◆ m_spacing

float CYIGridLayout::m_spacing
protected

◆ m_tableCells

bool CYIGridLayout::m_tableCells
protected

◆ m_uniformColumns

bool CYIGridLayout::m_uniformColumns
protected

◆ m_uniformRows

bool CYIGridLayout::m_uniformRows
protected

The documentation for this class was generated from the following file: