Named Table Cells in Rows, Columns and the Table Cursor

From Apache OpenOffice Wiki
Jump to: navigation, search



The interface XTextTable introduces the following methods to initialize a table, work with table cells, rows and columns, and create a table cursor:

 void initialize( [in] long nRows, [in] long nColumns) 
 
 sequence< string > getCellNames() 
 com::sun::star::table::XCell getCellByName( [in] string aCellName) 
 
 com::sun::star::table::XTableRows getRows() 
 com::sun::star::table::XTableColumns getColumns() 
 
 com::sun::star::text::XTextTableCursor createCursorByCellName( [in] string aCellName) 

The method initialize() sets the number of rows and columns prior to inserting the table into the text. Non-initialized tables default to two rows and two columns.

The method getCellNames() returns a sequence of strings containing the names of all cells in the table in A1[.1.1] notation.

The method getCellByName() expects a cell name in A1[.1.1] notation, and returns a cell object that is a com.sun.star.table.XCell and a com.sun.star.text.XText. The advantage of getCellByName() is its ability to retrieve cells even in tables with split or merged cells.

The method getRows() returns a table row container supporting com.sun.star.table.XTableRows that is a com.sun.star.container.XIndexAccess, and introduces the following methods to insert an arbitrary number of table rows below a given row index position and remove rows from a certain position:

 void insertByIndex ( [in] long nIndex, [in] long nCount)
 void removeByIndex ( [in] long nIndex, [in] long nCount)

The following table shows which XTableRows methods work under which circumstances.

Method in com.sun.star.table.XTableRows In Simple table In Complex Table
getElementType() X X
hasElements() X X
getByIndex() X X
getCount() X X
insertByIndex() X -
removeByIndex() X -


Every row returned by getRows() supports the service com.sun.star.text.TextTableRow, that is, it is a com.sun.star.beans.XPropertySet which features these properties:

Properties of com.sun.star.text.TextTableRow
BackColor long - Specifies the color of the background in 0xAARRGGBB notation.
BackTransparent boolean - If true, the background color value in "BackColor" is not visible.
BackGraphicURLBackGraphicURL string - Contains the URL of a background graphic.
BackGraphicFilter string - Contains the name of the file filter of a background graphic.
BackGraphicLocation com.sun.star.style.GraphicLocation. Determines the position of the background graphic.
TableColumnSeparators Defines the column width and its merging behavior. It contains a sequence of com.sun.star.text.TableColumnSeparator structs with the fields Position and IsVisible. The value of Position is relative to the table property com.sun.star.text.TextTable:TableColumnRelativeSum. IsVisible refers to merged cells where the separator becomes invisible.
Height long - Contains the height of the table row.
IsAutoHeight boolean - If the value of this property is true, the height of the table row depends on the content of the table cells.

The method getColumns() is similar to getRows(), but restrictions apply. It returns a table column container supporting com.sun.star.table.XTableColumns that is a com.sun.star.container.XIndexAccess and introduces the following methods to insert an arbitrary number of table columns behind a given column index position and remove columns from a certain position:

 void insertByIndex( [in] long nIndex, [in] long nCount)
 void removeByIndex( [in] long nIndex, [in] long nCount)

The following table shows which XTableColumns methods work in which situation.

Methods in com.sun.star.table.XTableColumns In Simple Table In Complex Table
getElementType() X X
hasElements() X X
getByIndex() X (but returned object supports XInterface only) -
getCount() X -
insertByIndex() X -
removeByIndex() X -

The method createCursorByCellName() creates a text table cursor that can select a cell range in the table, merge or split cells, and read and write cell properties of the selected cell range. It is a com.sun.star.text.TextTableCursor service with the interfaces com.sun.star.text.XTextTableCursor and com.sun.star.beans.XPropertySet.

com.sun.star.text.TextTableCursor

These are the methods contained in XTextTableCursor:

 string getRangeName() 
 
 boolean goLeft( [in] short nCount, [in] boolean bExpand)
 boolean goRight( [in] short nCount, [in] boolean bExpand)
 boolean goUp( [in] short nCount, [in] boolean bExpand)
 boolean goDown( [in] short nCount, [in] boolean bExpand)
 
 void gotoStart( [in] boolean bExpand)
 void gotoEnd( [in] boolean bExpand)
 boolean gotoCellByName( [in] string aCellName, [in] boolean bExpand)
 
 boolean mergeRange()
 boolean splitRange( [in] short Count, [in] boolean Horizontal)

Traveling through the table calls the cursor's goLeft(), goRight(), goUp(), goDown(), gotoStart(), gotoEnd(), and gotoCellByName() methods, passing true to select cells on the way.

Once a cell range is selected, apply character and paragraph properties to the cells in the range as defined in the services com.sun.star.style.CharacterProperties, com.sun.star.style.CharacterPropertiesAsian, com.sun.star.style.CharacterPropertiesComplex and com.sun.star.style.ParagraphProperties. Moreover, split and merge cells using the text table cursor. An example is provided below.

Content on this page is licensed under the Public Documentation License (PDL).
Personal tools
In other languages