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.
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.
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. |
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.
#include <layout/YiGridLayout.h>
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 } |
![]() | |
enum | PositioningMode { PositioningMode::SetPositionDirectly, PositioningMode::DoNotSetPositionDirectly } |
typedef CYILayoutConfig::CubeOffset | Padding |
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 CYIRuntimeTypeInfo & | GetLayoutConfigType () const override |
![]() | |
virtual void | OnMeasurementsApplied () override |
virtual void | ApplyPosition (CYISceneNode *pChild, const glm::vec3 &position) override |
virtual void | ApplySize (CYISceneNode *pChild, const glm::vec3 &size) override |
![]() | |
virtual void | OnSceneViewAttached () |
virtual void | OnMeasurementsCalculated (const CYISceneNode::MeasureSpec &widthSpec, const CYISceneNode::MeasureSpec &heightSpec, const CYISceneNode::MeasureSpec &depthSpec) |
virtual std::unique_ptr< CYILayoutState > | CreateLayoutStateInstance () const |
void | CreateLayoutObjectsFor (CYISceneNode *pNode) const |
CYISceneNode * | GetChild (size_t index) const |
void | ApplyMeasurementsToBackgroundChildren () |
const Padding & | GetPaddingForChild (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 |
![]() | |
CYISceneView * | m_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 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) |
![]() | |
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 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 ¤tTopLeftPosition, 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 ¤tChildPosition) |
static void | MeasureBackgroundChildren (CYISceneNode *pNode, const glm::vec3 &size) |
|
strong |
The fill order to use when placing layoutable items in the grid.
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. |
|
strong |
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.
CYIGridLayout::CYIGridLayout | ( | ) |
|
virtual |
|
overrideprotectedvirtual |
Extracts relevant properties the associated scene node and configures this layout with said properties.
Reimplemented from CYIAnimatingLayout.
size_t CYIGridLayout::GetColumnsCount | ( | ) | const |
FillOrder CYIGridLayout::GetFillOrder | ( | ) | const |
|
overrideprotectedvirtual |
Returns the type of layout config objects used by this layout.
Reimplemented from CYIAnimatingLayout.
PackMode CYIGridLayout::GetPackMode | ( | ) | const |
size_t CYIGridLayout::GetRowsCount | ( | ) | const |
float CYIGridLayout::GetSpacing | ( | ) | const |
bool CYIGridLayout::IsUsingTableCells | ( | ) | const |
bool CYIGridLayout::IsUsingUniformColumns | ( | ) | const |
bool CYIGridLayout::IsUsingUniformRows | ( | ) | const |
|
overrideprotectedvirtual |
Applies the measured sizes of the associate scene node's children.
Implements CYILayout.
|
overrideprotectedvirtual |
Measures the associated scene node, considering its layout configuration constraints (if available) and the provided measure specifications.
Implements CYILayout.
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.
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.
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.
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.
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.
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.
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.
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.
|
protected |
|
protected |
|
protected |
|
protected |
|
protected |
|
protected |
|
protected |
|
protected |