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

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

public class RichList
extends Object

The RichList class provides an API that makes it more convenient to access the Table API Model-View-Controller structure to make a patterned list of Bitmaps and Strings. Consider the RichList as a structure containing data formatted in a certain way. The RichList can have add, delete, insert and set operations on its data.

Since:

BlackBerry API 6.0.0

Constructor Summary

RichList(Manager manager, boolean imageSpaceUsed, int numberOfLabelFields, int numberOfDescriptionFields)
Creates a RichList instance and adds the relevant material to a provided manager.

Method Summary
void	add(Object[] data) Adds an array of data to the bottom of the RichList.
Object[]	get(int rowIndex) Retrieves the contents of a specific row in the RichList.
void	insert(int rowIndex, Object[] data) Adds an array of data at a particular position in the RichList.
void	remove(int rowIndex) Removes the contents of a specific row in the RichList and removes them from the screen as well.
void	set(int rowIndex, int objectIndex, Object data) Overwrites an object stored at a specified row index and column index in the RichList with a new object and updates the screen with this information as well.

Methods inherited from class java.lang.Object

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

Constructor Detail

RichList

public RichList(Manager manager,
                boolean imageSpaceUsed,
                int numberOfLabelFields,
                int numberOfDescriptionFields)

Creates a RichList instance and adds the relevant material to a provided manager. The shape of the DataTemplate is divided into three logical spaces. The first space is the "Image Space" which is on the top left corner. It is assigned a square of 50 pixels by 50 pixels. The second space is the "Labels Space" which are strings that will appear to the right of the "Image Space". Consider the "Labels Space" as a single column with several rows. The "Labels Space" assigns one row of space to each string. Consider the "Image Space" as a single column that spans a number of rows equal to the number of rows in the "Labels Space" The third space is the "Descriptions Space" which are strings that will appear below both the "Image Space" and the "Labels Space". The "Descriptions Space" assigns one row of space to each string. Consider the "Descriptions Space" as a series of rows that span the width of the "Image Space" column and the "Label Space" column. Please see the API documentation (these aren't ready yet) for a diagrammtic representation of this concept. The only data types that can be stored in a RichList are Strings, Bitmaps and Fields.

Parameters:

manager - The Manager object that will hold the contents of a RichList

imageSpaceUsed - If set to true, there will be an "Image Space" in the top left corner of every row of data reserved for an image with a size of 50 pixels by 50 pixels.

numberOfLabelFields - The number of text objects that should be put on the right side of the image, as part of the "Labels Space". If an image is not used, the "Label Space" is aligned to the left side of the allowed space.

numberOfDescriptionFields - the number of text objects that should be put below the image and the labels, as part of the "Descriptions Space". If an image is not used, these will be below the "Label Space".

Throws:

IllegalArgumentException - if the manager provided to the constructor is null or if numberOfLabelFields or numberOfDescriptionFields are negative values.

Since:

BlackBerry API 6.0.0

Method Detail

add

public void add(Object[] data)

Adds an array of data to the bottom of the RichList. If the "Image Space" is being used, the first item in the array must be a Bitmap object. If the "Labels Space" is being used, the Strings that represent the labels should be placed in top-first order after the Bitmap object (or at the beginning of the array if there is no image being used) If the "Descriptions Space" is being used, the Strings that represent the descriptions should be placed in the array after the Bitmap (if any) and the label Strings (if any).

Parameters:

data - An array of objects that will be added to the RichList and subsequently displayed on the screen.

Throws:

IllegalArgumentException - if the array provided is logically inconsistent with the rest of the data stored or contains something other than Strings, Bitmaps or Fields.

Since:

BlackBerry API 6.0.0

remove

public void remove(int rowIndex)

Removes the contents of a specific row in the RichList and removes them from the screen as well.

Parameters:

rowIndex - The row index of the RichList row whose contents must be removed.

Throws:

IndexOutOfBoundsException - if the index is below 0 or above the number of rows stored.

Since:

BlackBerry API 6.0.0

get

public Object[] get(int rowIndex)

Retrieves the contents of a specific row in the RichList.

Parameters:

rowIndex - The row index of the RichList row whose contents must be retrieved.

Returns:

An object array containing the contents of the retrieved row

Throws:

IndexOutOfBoundsException - if the index is below 0 or above the number of rows stored.

Since:

BlackBerry API 6.0.0

set

public void set(int rowIndex,
                int objectIndex,
                Object data)

Overwrites an object stored at a specified row index and column index in the RichList with a new object and updates the screen with this information as well.

Parameters:

rowIndex - The index of the RichList row that contains the data to be overridden.

objectIndex - The logical index of the object to be overridden within a RichList row. This follows the ordering of the objects in the array that was passed earlier via the @see RichList#add call

data - Either a String, a Bitmap or a Field object that will take the place of the old object that is being overridden.

Throws:

IllegalArgumentException - if the data provided is not a String, a Bitmap or a Field

Since:

BlackBerry API 6.0.0

insert

public void insert(int rowIndex,
                   Object[] data)

Adds an array of data at a particular position in the RichList. If the "Image Space" is being used, the first item in the array must be a Bitmap object. If the "Labels Space" is being used, the Strings that represent the labels should be placed in top-first order after the Bitmap object (or at the beginning of the array if there is no image being used) If the "Descriptions Space" is being used, the Strings that represent the descriptions should be placed in the array after the Bitmap (if any) and the label Strings (if any).

Parameters:

rowIndex - The index of the RichList row where the new information will be inserted.

data - An array of objects that will be added to the RichList and subsequently displayed on the screen.

Throws:

IllegalArgumentException - if the array provided is logically inconsistent with the rest of the data stored or contains something other than Strings, Bitmaps or Fields.

Since:

BlackBerry API 6.0.0