net.rim.device.api.ui.component.table
Class DataTemplate

java.lang.Object
  net.rim.device.api.ui.component.table.DataTemplate

Direct Known Subclasses:

RichListDataTemplate, SimpleListDataTemplate

public abstract class DataTemplate
extends Object

Define a repeating layout of fields from data obtained from the model associated with the DataTemplate's view.

Since:

BlackBerry API 6.0.0

Constructor Summary

DataTemplate(DataView view, int rows, int columns)
Create a DataTemplate for the provided view that has the provided number of rows and columns.

Method Summary
int	createRegion(XYRect rect) Create a region that can span rows and or columns using the default style.
int	createRegion(XYRect rect, RegionStyles style) Create a region that can span rows and or columns using the specified style.
TemplateColumnProperties	getColumnProperties(int columnIndex) Get the column properties for the provided column.
abstract Field[]	getDataFields(int modelRowIndex) Get the required fields that contain the data in the provided model row.
int	getNumberOfColumns() Get the number of columns in the DataTemplate.
int	getNumberOfRegions() Get the number of regions in the DataTemplate.
int	getNumberOfRows() Get the number of rows in the DataTemplate.
TemplateRowProperties	getRowProperties(int rowIndex) Get the row properties for the provided row.
protected DataView	getView() Get the view for the the DataTemplate.
boolean	isFixedHeight() Check if fixed height is enabled or disabled.
void	setColumnProperties(int columnIndex, TemplateColumnProperties properties) Set the column properties for the provided column.
void	setPosition(int regionIndex, int x, int y) Set the position of the field at the provided regionIndex to x,y.
void	setRowProperties(int rowIndex, TemplateRowProperties properties) Set the row properties for the provided row.
void	useFixedHeight(boolean status) Enable and disable fixed height.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

DataTemplate

public DataTemplate(DataView view,
                    int rows,
                    int columns)

Create a DataTemplate for the provided view that has the provided number of rows and columns.

Parameters:

view - the DataView that will use this template to DataTemplate to arrange fields that contain the data in the model

rows - the number of rows in the repeating pattern

columns - the number of columns in the repeating pattern

Throws:

IllegalArgumentException - thrown if rows or columns is a number less then 0.

Since:

BlackBerry API 6.0.0

Method Detail

createRegion

public int createRegion(XYRect rect,
                        RegionStyles style)

Create a region that can span rows and or columns using the specified style.

Parameters:

rect - a container of data that describes the root of a region and the number of rows and columns that are spanned by this region, rect.x and rect.y is the upper left corner of the region in terms of rows and columns, rect.width is the number of spanned columns, and rect.height is the number of spanned rows.

style - the RegionSytle to use for this region.

Returns:

the region number

Since:

BlackBerry API 6.0.0

createRegion

public int createRegion(XYRect rect)

Create a region that can span rows and or columns using the default style.

Parameters:

rect - a container of data that describes the root of a region and the number of rows and columns that are spanned by this region, rect.x and rect.y is the upper left corner of the region in terms of rows and columns, rect.width is the number of spanned columns, and rect.height is the number of spanned rows.

Returns:

the region number

Since:

BlackBerry API 6.0.0

getDataFields

public abstract Field[] getDataFields(int modelRowIndex)

Get the required fields that contain the data in the provided model row. When defining this method use the modelRowIndex to query the TableModel for the Java Object stored at that row index. Please note that it is permissible for null objects to exist as individual table model cells. There is no need to deal with the case of an entire model row being null because it is not permissible in the TableModel to specify an entire model row as null. Please note that the Field[] that is returned by this call must not have any null entries, consider the use of a { @link NullField } object in such situations.

Parameters:

modelRowIndex - the model row number that the returned fields contain

Returns:

the fields containing the data from the provided row in the model.

Since:

BlackBerry API 6.0.0

getColumnProperties

public TemplateColumnProperties getColumnProperties(int columnIndex)

Get the column properties for the provided column.

Parameters:

columnIndex - the column number to get the column properties for

Returns:

the column properties for the provided column

Throws:

IllegalArgumentException - If columnIndex is less than 0 or greater than or equal to the number of columns.

IllegalStateException - If TemplateRowProperties is set to null for rowIndex

Since:

BlackBerry API 6.0.0

setColumnProperties

public void setColumnProperties(int columnIndex,
                                TemplateColumnProperties properties)

Set the column properties for the provided column.

Parameters:

columnIndex - the column number to set the column properties for

properties - the properties to be set for the provided column number

Throws:

IllegalArgumentException - If columnIndex is less than 0 or greater than or equal to the number of columns.

Since:

BlackBerry API 6.0.0

getRowProperties

public TemplateRowProperties getRowProperties(int rowIndex)

Get the row properties for the provided row.

Parameters:

rowIndex - the row number to get the row properties for

Returns:

the row properties for the provided row

Throws:

IllegalArgumentException - If rowIndex is less than 0 or greater than or equal to the number of rows.

IllegalStateException - If TemplateRowProperties is set to null for rowIndex

Since:

BlackBerry API 6.0.0

setRowProperties

public void setRowProperties(int rowIndex,
                             TemplateRowProperties properties)

Set the row properties for the provided row.

Parameters:

rowIndex - the column number to set the row properties for

properties - the properties to be set for the provided row number

Throws:

IllegalArgumentException - If rowIndex is less than 0 or greater than or equal to the number of rows.

Since:

BlackBerry API 6.0.0

setPosition

public void setPosition(int regionIndex,
                        int x,
                        int y)

Set the position of the field at the provided regionIndex to x,y.

Parameters:

regionIndex - the region number that contains the field to be positioned

x - the x position

y - the y position

Throws:

IllegalArgumentException - if the regionIndex provided is not a valid region index value (either negative or too large)

Since:

BlackBerry API 6.0.0

getNumberOfRows

public int getNumberOfRows()

Get the number of rows in the DataTemplate.

Returns:

the number of rows in the DataTemplate

Since:

BlackBerry API 6.0.0

getNumberOfColumns

public int getNumberOfColumns()

Get the number of columns in the DataTemplate.

Returns:

the number of columns in the DataTemplate

Since:

BlackBerry API 6.0.0

getNumberOfRegions

public int getNumberOfRegions()

Get the number of regions in the DataTemplate.

Returns:

the number of regions in the DataTemplate

Since:

BlackBerry API 6.0.0

getView

protected DataView getView()

Get the view for the the DataTemplate.

Returns:

the view for the DataTemplate

Since:

BlackBerry API 6.0.0

isFixedHeight

public boolean isFixedHeight()

Check if fixed height is enabled or disabled.

Returns:

true if fixed height is enabled, otherwise false

Since:

BlackBerry API 6.0.0

useFixedHeight

public void useFixedHeight(boolean status)

Enable and disable fixed height.

Parameters:

status - if true then the height of a field is limited to the height set in the row properties, otherwise the field can grow or shrink

Since:

BlackBerry API 6.0.0