class sap.ui.commons.layout.MatrixLayout

Visiblity: public
UX Guidelines:
Implements:
Available since: N/A
Module: sap/ui/commons/layout/MatrixLayout
Application Component: CA-UI5-CTR

A matrix layout arranges controls in a grid structure, using rows which need not have the same number of cells.

It uses predefined cell classes that guarantee appropriate distances between cells in the grid. The cell's vGutter property lets you specify additional horizontal distances easily. You can set these additional distances (known as gutters) with or without separators. The distance for each cell is specified by assigning a specific enumeration value of the class LayoutCellSeparator of the matrix data object.

You should avoid nesting matrix layouts. You should only use a matrix layout if you need to align controls horizontally across rows.


Constructor

Constructor for a new layout/MatrixLayout.

Accepts an object literal mSettings that defines initial property values, aggregated and associated objects as well as event handlers. See sap.ui.base.ManagedObject#constructor for a general description of the syntax of the settings object.

new sap.ui.commons.layout.MatrixLayout(sId?, mSettings?)
Param Type Default Value Description
sId? string

id for the new control, generated automatically if no id is given

mSettings? object

initial settings for the new control


Properties

Name Type Default Value Description
columns int

Number of columns. If not specified, the number of columns will be determined from the given cells.

Visibility: public
height sap.ui.core.CSSSize

CSS height of the matrix layout.

Visibility: public
layoutFixed boolean true

Sets the table layout. If fixed the width parameter of a column has priority, if not the width of the content of the colums has priority. The default is "fixed". If the fixed layout is used an adequate width of the MatrixLayout should be provided. Otherwise the column width displayed could be different than the given ones because of browser dependend optimazations.

Visibility: public
width sap.ui.core.CSSSize

CSS width of the matrix layout. If the LayoutFixed = true an adequate width should be provided.

Visibility: public
widths sap.ui.core.CSSSize[]

Widths of the columns. Use an array to define the widths of the columns. If a column shall have an automatical sizing enter "auto" for this column width.

Visibility: public

Aggregations

Default Aggregation: rows

Name Cardinality Type Description
rows (default) 0..n sap.ui.commons.layout.MatrixLayoutRow

The matrix layout's individual rows.


Methods Overview

Method Description
addRow

Adds some row to the aggregation rows.

createRow

Creates a new matrix layout row and appends it to this matrix layout.

Each argument must be either a matrix layout cell, which is added to the row "as is", or an arbitrary content control, which is wrapped with a new (default) matrix layout cell first and then added to the row.

destroyRows

Destroys all the rows in the aggregation rows.

sap.ui.commons.layout.MatrixLayout.extend

Creates a new subclass of class sap.ui.commons.layout.MatrixLayout with name sClassName and enriches it with the information contained in oClassInfo.

oClassInfo might contain the same kind of information as described in sap.ui.core.Control.extend.

getColumns

Gets current value of property columns.

Number of columns. If not specified, the number of columns will be determined from the given cells.

getHeight

Gets current value of property height.

CSS height of the matrix layout.

getLayoutFixed

Gets current value of property layoutFixed.

Sets the table layout. If fixed the width parameter of a column has priority, if not the width of the content of the colums has priority. The default is "fixed". If the fixed layout is used an adequate width of the MatrixLayout should be provided. Otherwise the column width displayed could be different than the given ones because of browser dependend optimazations.

Default value is true.

sap.ui.commons.layout.MatrixLayout.getMetadata

Returns a metadata object for class sap.ui.commons.layout.MatrixLayout.

getRows

Gets content of aggregation rows.

The matrix layout's individual rows.

getWidth

Gets current value of property width.

CSS width of the matrix layout. If the LayoutFixed = true an adequate width should be provided.

getWidths

Gets current value of property widths.

Widths of the columns. Use an array to define the widths of the columns. If a column shall have an automatical sizing enter "auto" for this column width.

indexOfRow

Checks for the provided sap.ui.commons.layout.MatrixLayoutRow in the aggregation rows. and returns its index if found or -1 otherwise.

insertRow

Inserts a row into the aggregation rows.

removeAllRows

Removes all the controls from the aggregation rows.

Additionally, it unregisters them from the hosting UIArea.

removeRow

Removes a row from the aggregation rows.

setColumns

Sets a new value for property columns.

Number of columns. If not specified, the number of columns will be determined from the given cells.

When called with a value of null or undefined, the default value of the property will be restored.

setHeight

Sets a new value for property height.

CSS height of the matrix layout.

When called with a value of null or undefined, the default value of the property will be restored.

setLayoutFixed

Sets a new value for property layoutFixed.

Sets the table layout. If fixed the width parameter of a column has priority, if not the width of the content of the colums has priority. The default is "fixed". If the fixed layout is used an adequate width of the MatrixLayout should be provided. Otherwise the column width displayed could be different than the given ones because of browser dependend optimazations.

When called with a value of null or undefined, the default value of the property will be restored.

Default value is true.

setWidth

Sets a new value for property width.

CSS width of the matrix layout. If the LayoutFixed = true an adequate width should be provided.

When called with a value of null or undefined, the default value of the property will be restored.

setWidths

Sets a new value for property widths.

Widths of the columns. Use an array to define the widths of the columns. If a column shall have an automatical sizing enter "auto" for this column width.

When called with a value of null or undefined, the default value of the property will be restored.

addRow

Adds some row to the aggregation rows.

Param Type DefaultValue Description
oRow sap.ui.commons.layout.MatrixLayoutRow

The row to add; if empty, nothing is inserted

createRow

Creates a new matrix layout row and appends it to this matrix layout.

Each argument must be either a matrix layout cell, which is added to the row "as is", or an arbitrary content control, which is wrapped with a new (default) matrix layout cell first and then added to the row.

destroyRows

Destroys all the rows in the aggregation rows.

sap.ui.commons.layout.MatrixLayout.extend

Creates a new subclass of class sap.ui.commons.layout.MatrixLayout with name sClassName and enriches it with the information contained in oClassInfo.

oClassInfo might contain the same kind of information as described in sap.ui.core.Control.extend.

Param Type DefaultValue Description
sClassName string

Name of the class being created

oClassInfo object

Object literal with information about the class

FNMetaImpl function

Constructor function for the metadata object; if not given, it defaults to the metadata implementation used by this class

getColumns

Gets current value of property columns.

Number of columns. If not specified, the number of columns will be determined from the given cells.

getHeight

Gets current value of property height.

CSS height of the matrix layout.

getLayoutFixed

Gets current value of property layoutFixed.

Sets the table layout. If fixed the width parameter of a column has priority, if not the width of the content of the colums has priority. The default is "fixed". If the fixed layout is used an adequate width of the MatrixLayout should be provided. Otherwise the column width displayed could be different than the given ones because of browser dependend optimazations.

Default value is true.

sap.ui.commons.layout.MatrixLayout.getMetadata

Returns a metadata object for class sap.ui.commons.layout.MatrixLayout.

getRows

Gets content of aggregation rows.

The matrix layout's individual rows.

getWidth

Gets current value of property width.

CSS width of the matrix layout. If the LayoutFixed = true an adequate width should be provided.

getWidths

Gets current value of property widths.

Widths of the columns. Use an array to define the widths of the columns. If a column shall have an automatical sizing enter "auto" for this column width.

indexOfRow

Checks for the provided sap.ui.commons.layout.MatrixLayoutRow in the aggregation rows. and returns its index if found or -1 otherwise.

Param Type DefaultValue Description
oRow sap.ui.commons.layout.MatrixLayoutRow

The row whose index is looked for

insertRow

Inserts a row into the aggregation rows.

Param Type DefaultValue Description
oRow sap.ui.commons.layout.MatrixLayoutRow

The row to insert; if empty, nothing is inserted

iIndex int

The 0-based index the row should be inserted at; for a negative value of iIndex, the row is inserted at position 0; for a value greater than the current size of the aggregation, the row is inserted at the last position

removeAllRows

Removes all the controls from the aggregation rows.

Additionally, it unregisters them from the hosting UIArea.

removeRow

Removes a row from the aggregation rows.

Param Type DefaultValue Description
vRow int string sap.ui.commons.layout.MatrixLayoutRow

The row to remove or its index or id

setColumns

Sets a new value for property columns.

Number of columns. If not specified, the number of columns will be determined from the given cells.

When called with a value of null or undefined, the default value of the property will be restored.

Param Type DefaultValue Description
iColumns int

New value for property columns

setHeight

Sets a new value for property height.

CSS height of the matrix layout.

When called with a value of null or undefined, the default value of the property will be restored.

Param Type DefaultValue Description
sHeight sap.ui.core.CSSSize

New value for property height

setLayoutFixed

Sets a new value for property layoutFixed.

Sets the table layout. If fixed the width parameter of a column has priority, if not the width of the content of the colums has priority. The default is "fixed". If the fixed layout is used an adequate width of the MatrixLayout should be provided. Otherwise the column width displayed could be different than the given ones because of browser dependend optimazations.

When called with a value of null or undefined, the default value of the property will be restored.

Default value is true.

Param Type DefaultValue Description
bLayoutFixed boolean true

New value for property layoutFixed

setWidth

Sets a new value for property width.

CSS width of the matrix layout. If the LayoutFixed = true an adequate width should be provided.

When called with a value of null or undefined, the default value of the property will be restored.

Param Type DefaultValue Description
sWidth sap.ui.core.CSSSize

New value for property width

setWidths

Sets a new value for property widths.

Widths of the columns. Use an array to define the widths of the columns. If a column shall have an automatical sizing enter "auto" for this column width.

When called with a value of null or undefined, the default value of the property will be restored.

Param Type DefaultValue Description
sWidths sap.ui.core.CSSSize[]

New value for property widths