table.h File Reference

#include <LayOutAPI/common.h>
#include <LayOutAPI/geometry/geometry.h>
#include <LayOutAPI/model/defs.h>

Go to the source code of this file.

Enumerations
enum	LOTableCellRotation { LOTableCellRotation_0 = 0, LOTableCellRotation_90, LOTableCellRotation_180, LOTableCellRotation_270 }
	Defines the rotation angle for table cells. More...

Functions
LO_RESULT	LOTableCreate (LOTableRef *table, const LOAxisAlignedRect2D *bounds, size_t rows, size_t columns)
	Creates a table with a specified size, and a specified number of rows and columns. More...
LO_EXPORT LOTableRef	LOTableFromEntity (LOEntityRef entity)
	Gets a table from a given entity. More...
LO_EXPORT LOEntityRef	LOTableToEntity (LOTableRef table)
	Converts from a LOTableRef to a LOEntityRef. This is essentially an upcast operation. More...
LO_RESULT	LOTableGetExplodedEntities (LOTableRef table, LOEntityListRef entity_list)
	Creates the entities that represent the tabel in its exploded form and adds them to a LOEntityListRef. It is NOT necessary to explicitly release these entities, since LOEntityListRef itself adds a reference to the entities and will release them when they are removed from the list or when the list is released. More...
LO_RESULT	LOTableRelease (LOTableRef *table)
	Releases a table object. The object will be invalidated if releasing the last reference. More...
LO_RESULT	LOTableAddReference (LOTableRef table)
	Adds a reference to a table object. More...
LO_RESULT	LOTableGetDimensions (LOTableRef table, size_t *rows, size_t *columns)
	Gets the number of rows and columns in a table. More...
LO_RESULT	LOTableGetRowHeight (LOTableRef table, size_t index, double *height)
	Gets the height of a row, specified by index, in a table. More...
LO_RESULT	LOTableSetRowHeight (LOTableRef table, size_t index, double height)
	Sets the height of a row, specified by index, in a table. There is a minimum allowable row height specified by kMinimumRowHeight. More...
LO_RESULT	LOTableGetColumnWidth (LOTableRef table, size_t index, double *width)
	Gets the width of a column, specified by index, in a table. More...
LO_RESULT	LOTableSetColumnWidth (LOTableRef table, size_t index, double width)
	Sets the width of a column, specified by index, in a table. There is a minimum allowable column width specified by kMinimumColumnWidth. More...
LO_RESULT	LOTableInsertRow (LOTableRef table, size_t index)
	Inserts a row at the specified index. More...
LO_RESULT	LOTableRemoveRow (LOTableRef table, size_t index)
	Removes a row at the specified index. More...
LO_RESULT	LOTableInsertColumn (LOTableRef table, size_t index)
	Inserts a column at the specified index. More...
LO_RESULT	LOTableRemoveColumn (LOTableRef table, size_t index)
	Removes a column at the specified index. More...
LO_RESULT	LOTableCreateCellTextCopy (LOTableRef table, size_t row, size_t column, LOFormattedTextRef *text)
	Creates a copy of the formatted text entity for a table cell at the specified row and column. Currently, this will always succeed. However, future versions of LayOut may support other types of entities for table cells, so you should not assume that this will succeed. If the specified row and column is within a merged cell, then a copy of the merged cell's text entity will be created. More...
LO_RESULT	LOTableSetCellText (LOTableRef table, size_t row, size_t column, LOFormattedTextRef text)
	Sets the text entity of a table cell from a LOFormattedTextRef object. Only the text content and fill style settings will be kept. The bounds and other style settings are controlled by the table. If the specified row and column is within a merged cell, then the merged cell itself will be affected. More...
LO_RESULT	LOTableGetBorderStyle (LOTableRef table, LOStyleRef style)
	Gets the style of a table's border. More...
LO_RESULT	LOTableSetBorderStyle (LOTableRef table, LOStyleRef style)
	Sets the style of a table's border. Only the stroke style setting can be set via this method. Other style settings are controlled by the table. More...
LO_RESULT	LOTableGetRowEdgeStyle (LOTableRef table, size_t row, LOStyleRef style)
	Gets the style of a table's inner row edge. The specified row must be in the range of 0 to the number of rows minus two. More...
LO_RESULT	LOTableSetRowEdgeStyle (LOTableRef table, size_t row, LOStyleRef style)
	Sets the style of a table's inner row edge. The specified row must be in the range of 0 to the number of rows minus two. Only the stroke style setting can be set via this method. Other style settings are controlled by the table. More...
LO_RESULT	LOTableGetColumnEdgeStyle (LOTableRef table, size_t column, LOStyleRef style)
	Gets the style of a table's inner column edge. The specified column must be in the range of 0 to the number of columns minus two. More...
LO_RESULT	LOTableSetColumnEdgeStyle (LOTableRef table, size_t column, LOStyleRef style)
	Sets the style of a table's inner column edge. The specified column must be in the range of 0 to the number of rows minus two. Only the stroke style setting can be set via this method. Other style settings are controlled by the table. More...
LO_RESULT	LOTableGetCellSpan (LOTableRef table, size_t row, size_t column, size_t *row_span, size_t *column_span)
	Gets the row and column span of a table cell. If the values returned by both row_span and column_span are equal to 1, then it is a normal, non-merged cell. If either of these values are greater than 1, then it is a merged cell. If these values are both 0, then it is an unused cell that resides within the inner portion of another merged cell. More...
LO_RESULT	LOTableMergeCells (LOTableRef table, size_t start_row, size_t start_column, size_t end_row, size_t end_column)
	Merge a range of cells within a table. Only cells which are not already merged can be merged. More...
LO_RESULT	LOTableGetCellRotation (LOTableRef table, size_t row, size_t column, LOTableCellRotation *rotation)
	Gets the rotation of a table cell. More...
LO_RESULT	LOTableSetCellRotation (LOTableRef table, size_t row, size_t column, LOTableCellRotation rotation)
	Sets the rotation of a table cell. More...

Enumeration Type Documentation

enum LOTableCellRotation

Defines the rotation angle for table cells.

Enumerator
LOTableCellRotation_0	No rotation.
LOTableCellRotation_90	Rotated 90 degrees counter-clockwise.
LOTableCellRotation_180	Rotated 180 degrees (upside-down).
LOTableCellRotation_270	Rotated 270 degrees counter-clockwise.

Function Documentation

LO_RESULT LOTableAddReference

(

LOTableRef

table

)

Adds a reference to a table object.

Since

LayOut 2017, API 2.0

Parameters

[in]

table

The table object.

Returns

• SU_ERROR_NONE on success
• SU_ERROR_INVALID_INPUT if table does not refer to a valid object

LO_RESULT LOTableCreate	(	LOTableRef *	table,
		const LOAxisAlignedRect2D *	bounds,
		size_t	rows,
		size_t	columns
	)

Creates a table with a specified size, and a specified number of rows and columns.

Parameters

[out]	table	The table object.
[in]	bounds	The starting dimensions of the table.
[in]	rows	The number of rows.
[in]	columns	The number of columns.

Returns

• SU_ERROR_NONE on success
• SU_ERROR_NULL_POINTER_OUTPUT if table is NULL
• SU_ERROR_OVERWRITE_VALID if *table already refers to a valid object
• SU_ERROR_NULL_POINTER_INPUT if bounds is NULL
• SU_ERROR_OUT_OF_RANGE if bounds has a width or height of zero
• SU_ERROR_OUT_OF_RANGE if rows is less than 1
• SU_ERROR_OUT_OF_RANGE if columns is less than 1

LO_RESULT LOTableCreateCellTextCopy	(	LOTableRef	table,
		size_t	row,
		size_t	column,
		LOFormattedTextRef *	text
	)

Creates a copy of the formatted text entity for a table cell at the specified row and column. Currently, this will always succeed. However, future versions of LayOut may support other types of entities for table cells, so you should not assume that this will succeed. If the specified row and column is within a merged cell, then a copy of the merged cell's text entity will be created.

Since

LayOut 2017, API 2.0

Parameters

[in]	table	The table object.
[in]	row	The cell's row.
[in]	column	The cell's column.
[out]	text	A copy of the cell's text entity.

Returns

• SU_ERROR_NONE on success
• SU_ERROR_INVALID_INPUT if table does not refer to a valid object
• SU_ERROR_OUT_OF_RANGE if row or column are out of range for the table
• SU_ERROR_NULL_POINTER_OUTPUT if entity is NULL
• SU_ERROR_OVERWRITE_VALID if *entity already refers to a valid object
• SU_ERROR_NO_DATA if the cell entity is not a formatted text entity

LO_EXPORT LOTableRef LOTableFromEntity

(

LOEntityRef

entity

)

Gets a table from a given entity.

Since

LayOut 2017, API 2.0

Parameters

[in]

entity

The entity object.

Returns

• The converted LOTableRef if the downcast operation succeeds
• If not, the returned reference will be invalid

LO_RESULT LOTableGetBorderStyle	(	LOTableRef	table,
		LOStyleRef	style
	)

Gets the style of a table's border.

Since

LayOut 2018, API 3.0

Parameters

[in]	table	The table object.
[out]	style	The style object.

Returns

• SU_ERROR_NONE on success
• SU_ERROR_INVALID_INPUT if table does not refer to a valid object
• SU_ERROR_INVALID_OUTPUT if style does not refer to a valid object

LO_RESULT LOTableGetCellRotation	(	LOTableRef	table,
		size_t	row,
		size_t	column,
		LOTableCellRotation *	rotation
	)

Gets the rotation of a table cell.

Since

LayOut 2017, API 2.0

Parameters

[in]	table	The table object.
[in]	row	The cell's row.
[in]	column	The cell's column.
[out]	rotation	The cell's rotation.

Returns

• SU_ERROR_NONE on success
• SU_ERROR_INVALID_INPUT if table does not refer to a valid object
• SU_ERROR_OUT_OF_RANGE if row is out of range for the table
• SU_ERROR_OUT_OF_RANGE if column is out of range for the table
• SU_ERROR_NULL_POINTER_OUTPUT if rotation is NULL
• SU_ERROR_NO_DATA if the specific cell is invalid due to residing within a merged cell

LO_RESULT LOTableGetCellSpan	(	LOTableRef	table,
		size_t	row,
		size_t	column,
		size_t *	row_span,
		size_t *	column_span
	)

Gets the row and column span of a table cell. If the values returned by both row_span and column_span are equal to 1, then it is a normal, non-merged cell. If either of these values are greater than 1, then it is a merged cell. If these values are both 0, then it is an unused cell that resides within the inner portion of another merged cell.

Since

LayOut 2017, API 2.0

Parameters

[in]	table	The table object.
[in]	row	The row index.
[in]	column	The column index.
[out]	row_span	The number of rows that this cell spans.
[out]	column_span	The number of columns that this cell spans.

Returns

• SU_ERROR_NONE on success
• SU_ERROR_INVALID_INPUT if table does not refer to a valid object
• SU_ERROR_OUT_OF_RANGE if row is out of range for the table
• SU_ERROR_OUT_OF_RANGE if column is out of range for the table
• SU_ERROR_NULL_POINTER_OUTPUT if row_span is NULL
• SU_ERROR_NULL_POINTER_OUTPUT if column_span is NULL

LO_RESULT LOTableGetColumnEdgeStyle	(	LOTableRef	table,
		size_t	column,
		LOStyleRef	style
	)

Gets the style of a table's inner column edge. The specified column must be in the range of 0 to the number of columns minus two.

Since

LayOut 2017, API 2.0

Parameters

[in]	table	The table object.
[in]	column	The column whose edge style to get.
[out]	style	The style object.

Returns

• SU_ERROR_NONE on success
• SU_ERROR_INVALID_INPUT if table does not refer to a valid object
• SU_ERROR_OUT_OF_RANGE if column is out of range for the table
• SU_ERROR_INVALID_OUTPUT if style does not refer to a valid object

LO_RESULT LOTableGetColumnWidth	(	LOTableRef	table,
		size_t	index,
		double *	width
	)

Gets the width of a column, specified by index, in a table.

Since

LayOut 2017, API 2.0

Parameters

[in]	table	The table object.
[in]	index	The index of the row.
[out]	width	The height of the row.

Returns

• SU_ERROR_NONE on success
• SU_ERROR_INVALID_INPUT if table does not refer to a valid object
• SU_ERROR_NULL_POINTER_OUTPUT if width is NULL
• SU_ERROR_OUT_OF_RANGE if index is not a valid index for table

LO_RESULT LOTableGetDimensions	(	LOTableRef	table,
		size_t *	rows,
		size_t *	columns
	)

Gets the number of rows and columns in a table.

Since

LayOut 2017, API 2.0

Parameters

[in]	table	The table object.
[out]	rows	The number of rows.
[out]	columns	The number of columns.

Returns

• SU_ERROR_NONE on success
• SU_ERROR_INVALID_INPUT if table does not refer to a valid object
• SU_ERROR_NULL_POINTER_OUTPUT if rows or columns are NULL

LO_RESULT LOTableGetExplodedEntities	(	LOTableRef	table,
		LOEntityListRef	entity_list
	)

Creates the entities that represent the tabel in its exploded form and adds them to a LOEntityListRef. It is NOT necessary to explicitly release these entities, since LOEntityListRef itself adds a reference to the entities and will release them when they are removed from the list or when the list is released.

Since

LayOut 2017, API 2.0

Parameters

[in]	table	The table object.
[in]	entity_list	The entity list object to add the new entities to.

Returns

• SU_ERROR_NONE on success
• SU_ERROR_INVALID_INPUT if table does not refer to a valid object
• SU_ERROR_INVALID_INPUT if entity_list does not refer to a valid object

LO_RESULT LOTableGetRowEdgeStyle	(	LOTableRef	table,
		size_t	row,
		LOStyleRef	style
	)

Gets the style of a table's inner row edge. The specified row must be in the range of 0 to the number of rows minus two.

Since

LayOut 2017, API 2.0

Parameters

[in]	table	The table object.
[in]	row	The row whose edge style to get.
[out]	style	The style object.

Returns

• SU_ERROR_NONE on success
• SU_ERROR_INVALID_INPUT if table does not refer to a valid object
• SU_ERROR_OUT_OF_RANGE if row is out of range for the table
• SU_ERROR_INVALID_OUTPUT if style does not refer to a valid object

LO_RESULT LOTableGetRowHeight	(	LOTableRef	table,
		size_t	index,
		double *	height
	)

Gets the height of a row, specified by index, in a table.

Since

LayOut 2017, API 2.0

Parameters

[in]	table	The table object.
[in]	index	The index of the row.
[out]	height	The height of the row.

Returns

• SU_ERROR_NONE on success
• SU_ERROR_INVALID_INPUT if table does not refer to a valid object
• SU_ERROR_NULL_POINTER_OUTPUT if height is NULL
• SU_ERROR_OUT_OF_RANGE if index is not a valid index for table

LO_RESULT LOTableInsertColumn	(	LOTableRef	table,
		size_t	index
	)

Inserts a column at the specified index.

Since

LayOut 2017, API 2.0

Parameters

[in]	table	The table object.
[in]	index	The index of the column to be inserted at.

Returns

• SU_ERROR_NONE on success
• SU_ERROR_INVALID_INPUT if table does not refer to a valid object
• SU_ERROR_OUT_OF_RANGE if index is not a valid index for table
• SU_ERROR_LAYER_LOCKED if the table is on a locked layer
• SU_ERROR_ENTITY_LOCKED if table is locked

LO_RESULT LOTableInsertRow	(	LOTableRef	table,
		size_t	index
	)

Inserts a row at the specified index.

Since

LayOut 2017, API 2.0

Parameters

[in]	table	The table object.
[in]	index	The index of the row to be inserted at.

Returns

• SU_ERROR_NONE on success
• SU_ERROR_INVALID_INPUT if table does not refer to a valid object
• SU_ERROR_OUT_OF_RANGE if index is not a valid index for table
• SU_ERROR_LAYER_LOCKED if the table is on a locked layer
• SU_ERROR_ENTITY_LOCKED if table is locked

LO_RESULT LOTableMergeCells	(	LOTableRef	table,
		size_t	start_row,
		size_t	start_column,
		size_t	end_row,
		size_t	end_column
	)

Merge a range of cells within a table. Only cells which are not already merged can be merged.

Since

LayOut 2017, API 2.0

Parameters

[in]	table	The table object.
[in]	start_row	The start row index.
[in]	start_column	The start column index.
[out]	end_row	The end row index.
[out]	end_column	The end column index.

Returns

• SU_ERROR_NONE on success
• SU_ERROR_INVALID_INPUT if table does not refer to a valid object
• SU_ERROR_OUT_OF_RANGE if any of the row or column indices are out of range for the table
• SU_ERROR_LAYER_LOCKED if the table is on a locked layer
• SU_ERROR_ENTITY_LOCKED if table is locked
• SU_ERROR_UNSUPPORTED if the specified range of cells only spans a single cell
• SU_ERROR_UNSUPPORTED if the specified range of cells contains a cell that is already merged

LO_RESULT LOTableRelease

(

LOTableRef *

table

)

Releases a table object. The object will be invalidated if releasing the last reference.

Since

LayOut 2017, API 2.0

Parameters

[in]

table

The table object.

Returns

• SU_ERROR_NONE on success
• SU_ERROR_NULL_POINTER_INPUT if table is NULL
• SU_ERROR_INVALID_INPUT if *table does not refer to a valid object

LO_RESULT LOTableRemoveColumn	(	LOTableRef	table,
		size_t	index
	)

Removes a column at the specified index.

Since

LayOut 2017, API 2.0

Parameters

[in]	table	The table object.
[in]	index	The index of the column to be removed.

Returns

• SU_ERROR_NONE on success
• SU_ERROR_INVALID_INPUT if table does not refer to a valid object
• SU_ERROR_OUT_OF_RANGE if index is not a valid index for table
• SU_ERROR_LAYER_LOCKED if the table is on a locked layer
• SU_ERROR_ENTITY_LOCKED if table is locked

LO_RESULT LOTableRemoveRow	(	LOTableRef	table,
		size_t	index
	)

Removes a row at the specified index.

Since

LayOut 2017, API 2.0

Parameters

[in]	table	The table object.
[in]	index	The index of the row to be removed.

Returns

• SU_ERROR_NONE on success
• SU_ERROR_INVALID_INPUT if table does not refer to a valid object
• SU_ERROR_OUT_OF_RANGE if index is not a valid index for table
• SU_ERROR_LAYER_LOCKED if the table is on a locked layer
• SU_ERROR_ENTITY_LOCKED if table is locked

LO_RESULT LOTableSetBorderStyle	(	LOTableRef	table,
		LOStyleRef	style
	)

Sets the style of a table's border. Only the stroke style setting can be set via this method. Other style settings are controlled by the table.

Since

LayOut 2018, API 3.0

Parameters

[in]	table	The table object.
[in]	style	The style object.

Returns

• SU_ERROR_NONE on success
• SU_ERROR_INVALID_INPUT if table does not refer to a valid object
• SU_ERROR_INVALID_INPUT if style does not refer to a valid object
• SU_ERROR_LAYER_LOCKED if the table is on a locked layer
• SU_ERROR_ENTITY_LOCKED if table is locked

LO_RESULT LOTableSetCellRotation	(	LOTableRef	table,
		size_t	row,
		size_t	column,
		LOTableCellRotation	rotation
	)

Sets the rotation of a table cell.

Since

LayOut 2017, API 2.0

Parameters

[in]	table	The table object.
[in]	row	The cell's row.
[in]	column	The cell's column.
[out]	rotation	The cell's rotation.

Returns

• SU_ERROR_NONE on success
• SU_ERROR_INVALID_INPUT if table does not refer to a valid object
• SU_ERROR_OUT_OF_RANGE if row is out of range for the table
• SU_ERROR_OUT_OF_RANGE if column is out of range for the table
• SU_ERROR_OUT_OF_RANGE if rotation is invalid
• SU_ERROR_LAYER_LOCKED if the table is on a locked layer
• SU_ERROR_ENTITY_LOCKED if table is locked
• SU_ERROR_UNSUPPORTED if the specific cell is invalid due to residing within a merged cell

LO_RESULT LOTableSetCellText	(	LOTableRef	table,
		size_t	row,
		size_t	column,
		LOFormattedTextRef	text
	)

Sets the text entity of a table cell from a LOFormattedTextRef object. Only the text content and fill style settings will be kept. The bounds and other style settings are controlled by the table. If the specified row and column is within a merged cell, then the merged cell itself will be affected.

Since

LayOut 2017, API 2.0

Parameters

[in]	table	The table object.
[in]	row	The cell's row.
[in]	column	The cell's column.
[in]	text	The text object representing the table cell.

Returns

• SU_ERROR_NONE on success
• SU_ERROR_INVALID_INPUT if table does not refer to a valid object
• SU_ERROR_OUT_OF_RANGE if row or column are out of range for the table
• SU_ERROR_INVALID_INPUT if entity does not refer to a valid object
• SU_ERROR_LAYER_LOCKED if the table is on a locked layer
• SU_ERROR_ENTITY_LOCKED if table is locked

LO_RESULT LOTableSetColumnEdgeStyle	(	LOTableRef	table,
		size_t	column,
		LOStyleRef	style
	)

Sets the style of a table's inner column edge. The specified column must be in the range of 0 to the number of rows minus two. Only the stroke style setting can be set via this method. Other style settings are controlled by the table.

Since

LayOut 2017, API 2.0

Parameters

[in]	table	The table object.
[in]	column	The column whose edge style to set.
[in]	style	The style object.

Returns

• SU_ERROR_NONE on success
• SU_ERROR_INVALID_INPUT if table does not refer to a valid object
• SU_ERROR_OUT_OF_RANGE if column is out of range for the table
• SU_ERROR_INVALID_INPUT if style does not refer to a valid object
• SU_ERROR_LAYER_LOCKED if the table is on a locked layer
• SU_ERROR_ENTITY_LOCKED if table is locked

LO_RESULT LOTableSetColumnWidth	(	LOTableRef	table,
		size_t	index,
		double	width
	)

Sets the width of a column, specified by index, in a table. There is a minimum allowable column width specified by kMinimumColumnWidth.

Since

LayOut 2017, API 2.0

Parameters

[in]	table	The table object.
[in]	index	The index of the column.
[out]	width	The width of the column.

Returns

• SU_ERROR_NONE on success
• SU_ERROR_INVALID_INPUT if table does not refer to a valid object
• SU_ERROR_OUT_OF_RANGE if width is is not a valid column width
• SU_ERROR_OUT_OF_RANGE if index is not a valid index for table
• SU_ERROR_LAYER_LOCKED if the table is on a locked layer
• SU_ERROR_ENTITY_LOCKED if table is locked

LO_RESULT LOTableSetRowEdgeStyle	(	LOTableRef	table,
		size_t	row,
		LOStyleRef	style
	)

Sets the style of a table's inner row edge. The specified row must be in the range of 0 to the number of rows minus two. Only the stroke style setting can be set via this method. Other style settings are controlled by the table.

Since

LayOut 2017, API 2.0

Parameters

[in]	table	The table object.
[in]	row	The row whose edge style to set.
[in]	style	The style object.

Returns

• SU_ERROR_NONE on success
• SU_ERROR_INVALID_INPUT if table does not refer to a valid object
• SU_ERROR_OUT_OF_RANGE if row is out of range for the table
• SU_ERROR_INVALID_INPUT if style does not refer to a valid object
• SU_ERROR_LAYER_LOCKED if the table is on a locked layer
• SU_ERROR_ENTITY_LOCKED if table is locked

LO_RESULT LOTableSetRowHeight	(	LOTableRef	table,
		size_t	index,
		double	height
	)

Sets the height of a row, specified by index, in a table. There is a minimum allowable row height specified by kMinimumRowHeight.

Since

LayOut 2017, API 2.0

Parameters

[in]	table	The table object.
[in]	index	The index of the row.
[out]	height	The height of the row.

Returns

• SU_ERROR_NONE on success
• SU_ERROR_INVALID_INPUT if table does not refer to a valid object
• SU_ERROR_OUT_OF_RANGE if height is not a valid row height
• SU_ERROR_OUT_OF_RANGE if index is not a valid index for table
• SU_ERROR_LAYER_LOCKED if the table is on a locked layer
• SU_ERROR_ENTITY_LOCKED if table is locked

LO_EXPORT LOEntityRef LOTableToEntity

(

LOTableRef

table

)

Converts from a LOTableRef to a LOEntityRef. This is essentially an upcast operation.

Since

LayOut 2017, API 2.0

Parameters

[in]

table

The table object.

Returns

• The converted LOEntityRef if table is a valid object
• If not, the returned reference will be invalid