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

java.lang.Object
  extended by 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.
RichList(Manager manager, boolean imageSpaceUsed, int numberOfLabelFields, int numberOfDescriptionFields, int focusPolicy)
          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.
 TableController getController()
          Returns a reference to the underlying TableController object of this RichList.
 int getFocusRow()
          Get the row index that has focus.
 TableModel getModel()
          Returns a reference to the underlying TableModel object of this RichList.
 TableView getView()
          Returns a reference to the underlying TableView object of this RichList.
 void insert(int rowIndex, Object[] data)
          Adds an array of data at a particular position in the RichList.
 boolean isFocusPolicy(int focusPolicy)
          Checks whether the specified focus policy is currently active.
 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.
 void setCommand(Command command)
          Set the command that will be executed when a row is clicked on.
 void setCommandContext(Object commandContext)
          Sets command context to be executed when a row is clicked on.
 void setFocusPolicy(int newFocusPolicy)
          Sets the current focus policy of this RichList.
 
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

RichList

public RichList(Manager manager,
                boolean imageSpaceUsed,
                int numberOfLabelFields,
                int numberOfDescriptionFields,
                int focusPolicy)
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".
focusPolicy - The focus policy applied to the RichList. Acceptable values are: TableController.FIELD_FOCUS, TableController.ROW_FOCUS or TableController.REGION_FOCUS
Throws:
IllegalArgumentException - if the manager provided to the constructor is null or if numberOfLabelFields or numberOfDescriptionFields are negative values.
Since:
BlackBerry API 7.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

getFocusRow

public int getFocusRow()
Get the row index that has focus.

Returns:
The row index that has focus.
Since:
BlackBerry API 7.0.0

setCommand

public void setCommand(Command command)
Set the command that will be executed when a row is clicked on. For more information, see Command Framework API.

Parameters:
command - Command to execute when a row is clicked.
Since:
BlackBerry API 7.0.0

setCommandContext

public void setCommandContext(Object commandContext)
Sets command context to be executed when a row is clicked on.

Parameters:
commandContext - Command context to use when the Command instance is executed.
Since:
BlackBerry API 7.0.0

setFocusPolicy

public void setFocusPolicy(int newFocusPolicy)
Sets the current focus policy of this RichList.

Parameters:
newFocusPolicy - Acceptable values are: TableController.FIELD_FOCUS, TableController.ROW_FOCUS or TableController.REGION_FOCUS
Since:
BlackBerry API 7.0.0

isFocusPolicy

public boolean isFocusPolicy(int focusPolicy)
Checks whether the specified focus policy is currently active.

Parameters:
focusPolicy - Acceptable values are: TableController.FIELD_FOCUS, TableController.ROW_FOCUS or TableController.REGION_FOCUS
Returns:
A boolean value indicating whether the specified focus policy is the same as the currently active one.
Since:
BlackBerry API 7.0.0

getModel

public TableModel getModel()
Returns a reference to the underlying TableModel object of this RichList.

Returns:
The TableModel object that corresponds to this RichList object.
Since:
BlackBerry API 7.0.0

getView

public TableView getView()
Returns a reference to the underlying TableView object of this RichList.

Returns:
The TableView object that corresponds to this RichList object.
Since:
BlackBerry API 7.0.0

getController

public TableController getController()
Returns a reference to the underlying TableController object of this RichList.

Returns:
The TableController object that corresponds to this RichList object.
Since:
BlackBerry API 7.0.0





Copyright 1999-2011 Research In Motion Limited. 295 Phillip Street, Waterloo, Ontario, Canada, N2L 3W8. All Rights Reserved.
Java is a trademark of Oracle America Inc. in the US and other countries.
Legal