org.odftoolkit.simple.table
Class Table

java.lang.Object
  extended by org.odftoolkit.simple.Component
      extended by org.odftoolkit.simple.table.Table

public class Table
extends Component

Table represents the table feature in ODF spreadsheet and text documents.

Table provides methods to get/add/delete/modify table column/row/cell.


Nested Class Summary
static class Table.TableBuilder
          This is a tool class which supplies all of the table creation detail.
 
Field Summary
protected  Document mDocument
           
protected  boolean mIsCellStyleInheritance
           
protected  boolean mIsDescribedBySingleElement
           
protected  boolean mIsSpreadsheet
           
 
Method Summary
 Column appendColumn()
          Append a column at the end of the table.
 List<Column> appendColumns(int columnCount)
          Append a specific number of columns to the right of the table.
 Row appendRow()
          Append a row to the end of the table.
 List<Row> appendRows(int rowCount)
          Append a specific number of rows to the end of the table.
 void applyStyle(TableTemplate template)
          Apply the formatting specified in the template to corresponding table cells.
 Cell getCellByPosition(int colIndex, int rowIndex)
          Return a single cell that is positioned at the specified column and row.
 Cell getCellByPosition(String address)
          Return a single cell that is positioned at the specified cell address.
 CellRange getCellRangeByName(String name)
          Return a range of cells by a specified name.
 CellRange getCellRangeByPosition(int startCol, int startRow, int endCol, int endRow)
          Return a range of cells within the specified range.
 CellRange getCellRangeByPosition(String startAddress, String endAddress)
          Return a range of cells within the specified range.
 Column getColumnByIndex(int index)
          Get the column at the specified index.
 int getColumnCount()
          Get the column count of this table.
 Iterator<Column> getColumnIterator()
          Return an Iterator of the column in this table.
 List<Column> getColumnList()
          Return a list of columns in the current table.
 int getHeaderColumnCount()
          Return the number of header columns in the table.
 int getHeaderRowCount()
          Return the number of header rows in this table.
static Table getInstance(TableTableElement element)
          Get a table feature instance by an instance of TableTableElement.
 TableTableElement getOdfElement()
          Return an instance of TableTableElement which represents this feature.
 Row getRowByIndex(int index)
          Get the row at the specified index.
 int getRowCount()
          Get the row count of this table.
 Iterator<Row> getRowIterator()
          Return an Iterator of the row in this table.
 List<Row> getRowList()
          Return a list of table rows in the current table.
 DefaultStyleHandler getStyleHandler()
           
 String getTableName()
          Return the table name.
 double getWidth()
          Get the width of the table (in Millimeter).
 List<Column> insertColumnsBefore(int index, int columnCount)
          Insert a specific number of columns before the column whose index is index.
 List<Row> insertRowsBefore(int index, int rowCount)
          Insert a specific number of rows before the row at index.
 boolean isCellStyleInheritance()
          Return true if cell style is inherited when a new cell is added to the table.
 boolean isProtected()
          Return true if the table is protected.
 boolean isUseRepeat()
          Return true if the new created multiple columns/rows/cells are described by a single element when it's possible.
static Table newTable(TableContainer tableContainer)
          Construct the Table feature.
static Table newTable(TableContainer tableContainer, int numRows, int numCols)
          Construct the Table feature with a specified row number and column number.
static Table newTable(TableContainer tableContainer, int numRows, int numCols, double marginLeft, double marginRight)
          Construct the Table feature with a specified row number and column number.
static Table newTable(TableContainer tableContainer, int numRows, int numCols, int headerRowNumber, int headerColumnNumber)
          Construct the Table feature with a specified row number, column number, header row number, header column number.
static Table newTable(TableContainer tableContainer, String[] rowLabel, String[] columnLabel, double[][] data)
          Construct the Table feature with a specified 2 dimension array as the data of this table.
static Table newTable(TableContainer tableContainer, String[] rowLabel, String[] columnLabel, String[][] data)
          Construct the Table feature with a specified 2 dimension array as the data of this table.
 void remove()
          Remove this table from the document
 void removeColumnsByIndex(int startIndex, int deleteColCount)
          Remove a specific number of columns, starting from the column at index.
 void removeRowsByIndex(int startIndex, int deleteRowCount)
          Remove the specific number of rows, starting from the row at index.
 void setCellStyleInheritance(boolean isEnabled)
          This method allows users to set whether cell style is inherited or not when a new cell is added to the table.
 void setProtected(boolean isProtected)
          Set if the table is protected.
 void setTableName(String tableName)
          Set the table name.
 void setUseRepeat(boolean isSingle)
          When two or more columns/rows/cells are added to a table, if they are adjoining, and have the same content and style, and do not contain horizontally/vertically merged cells, they may be described by a single element.
 void setVerticalMargin(double spaceTop, double spaceBottom)
          Modifies the margin above and below the table.
 void setWidth(double width)
          Set the width of the table (in Millimeter).
 
Methods inherited from class org.odftoolkit.simple.Component
getComponentByElement, getOwnerDocument, registerComponent, unregisterComponent
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

mDocument

protected Document mDocument

mIsSpreadsheet

protected boolean mIsSpreadsheet

mIsCellStyleInheritance

protected boolean mIsCellStyleInheritance

mIsDescribedBySingleElement

protected boolean mIsDescribedBySingleElement
Method Detail

getInstance

public static Table getInstance(TableTableElement element)
Get a table feature instance by an instance of TableTableElement.

Parameters:
element - an instance of TableTableElement
Returns:
an instance of Table that can represent element

newTable

public static Table newTable(TableContainer tableContainer)
Construct the Table feature. The default column count is 5. The default row count is 2.

The table will be inserted at the end of the container. An unique table name will be given, you may set a custom table name using the setTableName method.

If the tableContainer is a text document, cell borders will be created by default.

Parameters:
tableContainer - the table container that contains this table
Returns:
the created Table feature instance

newTable

public static Table newTable(TableContainer tableContainer,
                             int numRows,
                             int numCols)
Construct the Table feature with a specified row number and column number.

The table will be inserted at the end of the tableContainer. An unique table name will be given, you may set a custom table name using the setTableName method.

If the tableContainer is a text document, cell borders will be created by default.

Parameters:
tableContainer - the table container that contains this table
numRows - the row number
numCols - the column number
Returns:
a new instance of Table

newTable

public static Table newTable(TableContainer tableContainer,
                             int numRows,
                             int numCols,
                             double marginLeft,
                             double marginRight)
Construct the Table feature with a specified row number and column number.

The table will be inserted at the end of the tableContainer. An unique table name will be given, you may set a custom table name using the setTableName method.

If the tableContainer is a text document, cell borders will be created by default.

Parameters:
tableContainer - the table container that contains this table
numRows - the row number
numCols - the column number
marginLeft - double the left table margin in cm (between the left margin of document and the table)
marginRight - double the right table margin in cm (between the right margin of document and the table)
Returns:
a new instance of Table

newTable

public static Table newTable(TableContainer tableContainer,
                             int numRows,
                             int numCols,
                             int headerRowNumber,
                             int headerColumnNumber)
Construct the Table feature with a specified row number, column number, header row number, header column number.

The table will be inserted at the end of the tableContainer. An unique table name will be given, you may set a custom table name using the setTableName method.

If the tableContainer is a text document, cell borders will be created by default.

Parameters:
tableContainer - the ODF document that contains this feature
numRows - the row number
numCols - the column number
headerRowNumber - the header row number
headerColumnNumber - the header column number
Returns:
a new instance of Table

newTable

public static Table newTable(TableContainer tableContainer,
                             String[] rowLabel,
                             String[] columnLabel,
                             double[][] data)
Construct the Table feature with a specified 2 dimension array as the data of this table. The value type of each cell is float.

The table will be inserted at the end of the tableContainer. An unique table name will be given, you may set a custom table name using the setTableName method.

If the tableContainer is a text document, cell borders will be created by default.

Parameters:
tableContainer - the table container that contains this table
rowLabel - set as the header row, it can be null if no header row needed
columnLabel - set as the header column, it can be null if no header column needed
data - the two dimension array of double as the data of this table
Returns:
a new instance of Table

newTable

public static Table newTable(TableContainer tableContainer,
                             String[] rowLabel,
                             String[] columnLabel,
                             String[][] data)
Construct the Table feature with a specified 2 dimension array as the data of this table. The value type of each cell is string.

The table will be inserted at the end of the tableContainer. An unique table name will be given, you may set a custom table name using the setTableName method.

If the tableContainer is a text document, cell borders will be created by default.

Parameters:
tableContainer - the table container that contains this table
rowLabel - set as the header row, it can be null if no header row needed
columnLabel - set as the header column, it can be null if no header column needed
data - the two dimension array of string as the data of this table
Returns:
a new instance of Table

getWidth

public double getWidth()
Get the width of the table (in Millimeter).

Throw an UnsupportedOperationException if the table is one sheet of a spreadsheet document. because the sheet doesn't have an attribute of table width.

Returns:
the width of the current table (in Millimeter).

An UnsupportedOperationException will be thrown if the table is in the spreadsheet document.


setWidth

public void setWidth(double width)
Set the width of the table (in Millimeter).

Throw an UnsupportedOperationException if the table is part of a spreadsheet document that does not allow to change the table size, because spreadsheet is not allow user to set the table size.

Parameters:
width - the width that need to set (in Millimeter).

An UnsupportedOperationException will be thrown if the table is in the spreadsheet document.


applyStyle

public void applyStyle(TableTemplate template)
                throws Exception
Apply the formatting specified in the template to corresponding table cells.

A table can only be formatted as one type of styles: even-odd-rows or even-odd-columns. The rule is to check the style of odd rows and even rows in the template, only if they have one different properties, table: style-name or table:paragraph-style-name, the table template will be treated as a even-odd-columns styled table.

If one style in the template is null, the style of corresponding cells will be removed. An empty template can be used to remove all the styles in a table.

Parameters:
template -
Throws:
IllegalArgumentException - if the given template is null
Exception - if content DOM could not be initialized

getRowCount

public int getRowCount()
Get the row count of this table.

Returns:
total count of rows

getColumnCount

public int getColumnCount()
Get the column count of this table.

Returns:
total count of columns

appendRow

public Row appendRow()
Append a row to the end of the table. The style of new row is same with the last row in the table.

Since SIMPLE supports automatic table expansion. Whenever a cell outside the current table is addressed the table is instantly expanded. Method getCellByPosition can randomly access any cell, no matter it in or out of the table original range.

Returns:
a new appended row
See Also:
appendRows(int), getRowByIndex(int), getCellByPosition(int, int), getCellByPosition(String)

appendRows

public List<Row> appendRows(int rowCount)
Append a specific number of rows to the end of the table. The style of new rows are same with the last row in the table.

Since SIMPLE supports automatic table expansion. Whenever a cell outside the current table is addressed the table is instantly expanded. Method getCellByPosition can randomly access any cell, no matter it in or out of the table original range.

Parameters:
rowCount - is the number of rows to be appended.
Returns:
a list of new appended rows
See Also:
appendRow(), getRowByIndex(int), getCellByPosition(int, int), getCellByPosition(String)

appendColumn

public Column appendColumn()
Append a column at the end of the table. The style of new column is same with the last column in the table.

Since SIMPLE supports automatic table expansion. Whenever a cell outside the current table is addressed the table is instantly expanded. Method getCellByPosition can randomly access any cell, no matter it in or out of the table original range.

Returns:
a new appended column
See Also:
appendColumns(int), getColumnByIndex(int), getCellByPosition(int, int), getCellByPosition(String)

appendColumns

public List<Column> appendColumns(int columnCount)
Append a specific number of columns to the right of the table. The style of new columns are same with the rightmost column in the table.

Since SIMPLE supports automatic table expansion. Whenever a cell outside the current table is addressed the table is instantly expanded. Method getCellByPosition can randomly access any cell, no matter it in or out of the table original range.

Parameters:
columnCount - is the number of columns to be appended.
Returns:
a list of new appended columns
See Also:
appendColumn(), getColumnByIndex(int), getCellByPosition(int, int), getCellByPosition(String)

getOdfElement

public TableTableElement getOdfElement()
Return an instance of TableTableElement which represents this feature.

Specified by:
getOdfElement in class Component
Returns:
an instance of TableTableElement

insertColumnsBefore

public List<Column> insertColumnsBefore(int index,
                                        int columnCount)
Insert a specific number of columns before the column whose index is index.

Parameters:
index - is the index of the column to insert before.
columnCount - is the number of columns to insert.
Returns:
a list of new inserted columns

removeColumnsByIndex

public void removeColumnsByIndex(int startIndex,
                                 int deleteColCount)
Remove a specific number of columns, starting from the column at index.

Parameters:
startIndex - is the index of the first column to delete.
deleteColCount - is the number of columns to delete.

insertRowsBefore

public List<Row> insertRowsBefore(int index,
                                  int rowCount)
Insert a specific number of rows before the row at index.

Parameters:
index - is the index of the row to insert before.
rowCount - is the number of rows to insert.
Returns:
a list of new inserted rows

getColumnList

public List<Column> getColumnList()
Return a list of columns in the current table.

Returns:
a list of table columns

getColumnIterator

public Iterator<Column> getColumnIterator()
Return an Iterator of the column in this table.

Returns:
an Iterator of the column in this table.
Since:
0.5.5
See Also:
Iterator

getRowList

public List<Row> getRowList()
Return a list of table rows in the current table.

Returns:
a list of table rows

getRowIterator

public Iterator<Row> getRowIterator()
Return an Iterator of the row in this table.

Returns:
an Iterator of the row in this table.
Since:
0.5.5
See Also:
Iterator

getColumnByIndex

public Column getColumnByIndex(int index)
Get the column at the specified index. The table will be automatically expanded, when the given index is outside of the original table.

Parameters:
index - the zero-based index of the column.
Returns:
the column at the specified index

getRowByIndex

public Row getRowByIndex(int index)
Get the row at the specified index. The table will be automatically expanded, when the given index is outside of the original table.

Parameters:
index - the zero-based index of the row.
Returns:
the row at the specified index

removeRowsByIndex

public void removeRowsByIndex(int startIndex,
                              int deleteRowCount)
Remove the specific number of rows, starting from the row at index.

Parameters:
startIndex - is the zero-based index of the first row to delete.
deleteRowCount - is the number of rows to delete.

remove

public void remove()
Remove this table from the document


getHeaderRowCount

public int getHeaderRowCount()
Return the number of header rows in this table.

Returns:
the number of header rows.

getHeaderColumnCount

public int getHeaderColumnCount()
Return the number of header columns in the table.

Returns:
the number of header columns.

getTableName

public String getTableName()
Return the table name.

Returns:
the table name

setTableName

public void setTableName(String tableName)
Set the table name.

Parameters:
tableName - the table name
Throws:
IllegalArgumentException - if the tableName is duplicate with one of tables in the current document

isProtected

public boolean isProtected()
Return true if the table is protected.

Returns:
true if the table is protected

setProtected

public void setProtected(boolean isProtected)
Set if the table is protected.

Parameters:
isProtected - the protected attribute of the table to be set

isCellStyleInheritance

public boolean isCellStyleInheritance()
Return true if cell style is inherited when a new cell is added to the table.

The default setting is inherited. In this condition, the style of new column is same with the previous column before the inserted position, while the style of new row is same with the last row before the inserted position.

This feature setting will influence appendRow(), appendColumn(), appendRows(), appendColumns(), insertRowsBefore() and insertColumnsBefore().

For getCellByPosition(), getCellRangeByPosition(), getCellRangeByName(), getRowByIndex() and getColumnByIndex(), if need automatically expand cells, it will return empty cell(s) without any style settings. So inheritance setting have no effect on them.

Returns:
true if cell style is inherited when a new cell is added to the table.
Since:
0.4.5
See Also:
setCellStyleInheritance(boolean), appendColumn(), appendColumns(int), appendRow(), appendRows(int), insertColumnsBefore(int, int), insertRowsBefore(int, int), getCellByPosition(int, int), getCellByPosition(String), getCellRangeByPosition(int, int, int, int), getCellRangeByPosition(String, String), getCellRangeByName(String), getColumnByIndex(int), getRowByIndex(int)

setCellStyleInheritance

public void setCellStyleInheritance(boolean isEnabled)
This method allows users to set whether cell style is inherited or not when a new cell is added to the table. Of course, the default setting is inherited. In this condition, the style of new column is same with the previous column before the inserted position, while the style of new row is same with the last row before the inserted position.

This feature setting will influence appendRow(), appendColumn(), appendRows(), appendColumns(), insertRowsBefore() and insertColumnsBefore().

For getCellByPosition(), getCellRangeByPosition(), getCellRangeByName(), getRowByIndex() and getColumnByIndex(), if need automatically expand cells, it will return empty cell(s) without any style settings. So inheritance setting have no effect on them.

Parameters:
isEnabled - ifisEnabled is true, cell style will be inherited by new cell.
Since:
0.4.5
See Also:
isCellStyleInheritance(), appendColumn(), appendColumns(int), appendRow(), appendRows(int), insertColumnsBefore(int, int), insertRowsBefore(int, int), getCellByPosition(int, int), getCellByPosition(String), getCellRangeByPosition(int, int, int, int), getCellRangeByPosition(String, String), getCellRangeByName(String), getColumnByIndex(int), getRowByIndex(int)

isUseRepeat

public boolean isUseRepeat()
Return true if the new created multiple columns/rows/cells are described by a single element when it's possible.

The default setting is true, which helps to decrease the document size. If setting is false, each column/row/cell will be described by its owned single element.

This feature setting will influence appendRows(), appendColumns(), insertRowsBefore(), insertColumnsBefore(), getCellByPosition(), getCellRangeByPosition(), getCellRangeByName(), getRowByIndex() and getColumnByIndex().

Returns:
true if the new created columns/rows/cells are described by a single element when it's possible.
Since:
0.4.5
See Also:
setUseRepeat(boolean), appendColumns(int), appendRows(int), insertColumnsBefore(int, int), insertRowsBefore(int, int), getCellByPosition(int, int), getCellByPosition(String), getCellRangeByPosition(int, int, int, int), getCellRangeByPosition(String, String), getCellRangeByName(String), getColumnByIndex(int), getRowByIndex(int)

setUseRepeat

public void setUseRepeat(boolean isSingle)
When two or more columns/rows/cells are added to a table, if they are adjoining, and have the same content and style, and do not contain horizontally/vertically merged cells, they may be described by a single element. The repeated number attribute, for row is table:number-rows-repeated, while for column and cell are table:number-columns-repeated, specifies the number of columns/rows/cells to which a column/row/cell element applies.

This method allows users to set whether the new created columns/rows/cells are described by a single element. Of course, the default setting is true, which helps to decrease the document size. If setting is false, each column/row/cell will be described by its owned single element.

This feature setting will influence appendRows(), appendColumns(), insertRowsBefore(), insertColumnsBefore(), getCellByPosition(), getCellRangeByPosition(), getCellRangeByName(), getRowByIndex() and getColumnByIndex().

Parameters:
isSingle - ifisSingle is true, the new created columns/rows/cells are described by a single element, if possible.
Since:
0.4.5
See Also:
isUseRepeat(), appendColumns(int), appendRows(int), insertColumnsBefore(int, int), insertRowsBefore(int, int), getCellByPosition(int, int), getCellByPosition(String), getCellRangeByPosition(int, int, int, int), getCellRangeByPosition(String, String), getCellRangeByName(String), getColumnByIndex(int), getRowByIndex(int)

getCellRangeByPosition

public CellRange getCellRangeByPosition(int startCol,
                                        int startRow,
                                        int endCol,
                                        int endRow)
Return a range of cells within the specified range. The table will be automatically expanded as need.

Parameters:
startCol - the column index of the first cell inside the range.
startRow - the row index of the first cell inside the range.
endCol - the column index of the last cell inside the range.
endRow - the row index of the last cell inside the range.
Returns:
the specified cell range.

getCellRangeByPosition

public CellRange getCellRangeByPosition(String startAddress,
                                        String endAddress)
Return a range of cells within the specified range. The range is specified by the cell address of the first cell and the cell address of the last cell. The table will be automatically expanded as need.

The cell address is constructed with a table name, a dot (.), an alphabetic value representing the column, and a numeric value representing the row. The table name can be omitted. For example: "$Sheet1.A1", "Sheet1.A1" and "A1" are all valid cell address.

Parameters:
startAddress - the cell address of the first cell inside the range.
endAddress - the cell address of the last cell inside the range.
Returns:
the specified cell range.

getCellRangeByName

public CellRange getCellRangeByName(String name)
Return a range of cells by a specified name.

After you get a cell range with getCellRangeByPosition, you can assign a name to this cell range with the method setCellRangeName in class CellRange. Then you will get a named range which can be represented by name. This method can be used to get a named range.

Parameters:
name - the name of the specified named range
Returns:
the specified cell range.

getCellByPosition

public Cell getCellByPosition(int colIndex,
                              int rowIndex)
Return a single cell that is positioned at the specified column and row. The table will be automatically expanded as need.

Parameters:
colIndex - the column index of the cell.
rowIndex - the row index of the cell.
Returns:
the cell at the specified position

getCellByPosition

public Cell getCellByPosition(String address)
Return a single cell that is positioned at the specified cell address. The table can be automatically expanded as need.

The cell address is constructed with a table name, a dot (.), an alphabetic value representing the column, and a numeric value representing the row. The table name can be omitted. For example: "$Sheet1.A1", "Sheet1.A1" and "A1" are all valid cell address.

Parameters:
address - the cell address of the cell.
Returns:
the cell at the specified position.

setVerticalMargin

public void setVerticalMargin(double spaceTop,
                              double spaceBottom)
Modifies the margin above and below the table.

Parameters:
spaceTop - space above the table in centimeter(cm), ex. 1.25 cm
spaceBottom - spacing below the table in centimeter(cm), ex. 0.7 cm
Since:
0.5.5

getStyleHandler

public DefaultStyleHandler getStyleHandler()


Copyright © 2010-2017 The Apache Software Foundation. All Rights Reserved.