net.rim.device.api.ui.component
Class ListField

java.lang.Object
  |
  +--net.rim.device.api.ui.Field
        |
        +--net.rim.device.api.ui.component.ListField

Direct Known Subclasses:

ObjectListField

public class ListField

extends Field

Contains rows of selectable list items. List fields must register a ListFieldCallback object to handle repaint tasks. When this field must display a particular item in its list, it invokes the appropriate methods on the registered callback object.

Behaviour
Displays a vertical list of set height items.

Optionally, you can build a list field as MULTI_SELECT. Currently, this means the user is allowed to select a range of items. In the future, this might be changed to selecting arbitrary items.

Lists by default support prefix searching: pressing a character selects the next item starting with this character. A string of characters typed in quick succession forms a prefix for which to search. This prefix is discarded if either a set time ellapses or backspace is pressed. If a match cannot be found, the selected item is not changed.

Field Summary

static int	MULTI_SELECT Selection of multiple, contiguous items.
static int	NON_CONTIGUOUS_SELECT Selection of multiple, non-contiguous items (Reserved for future use).
static int	ROW_HEIGHT_FONT Used to set the row-height to the same as the font for this field.

Fields inherited from class net.rim.device.api.ui.Field

EDITABLE, EDITABLE_MASK, FIELD_BOTTOM, FIELD_HALIGN_MASK, FIELD_HCENTER, FIELD_LEFT, FIELD_RIGHT, FIELD_TOP, FIELD_VALIGN_MASK, FIELD_VCENTER, FOCUSABLE, FOCUSABLE_MASK, HIGHLIGHT_FOCUS, HIGHLIGHT_SELECT, NON_FOCUSABLE, READONLY, USE_ALL_HEIGHT, USE_ALL_WIDTH

Constructor Summary

ListField()
Constructs an empty ListField.

ListField(int numRows)
Constructs a ListField of provided size.

ListField(int numRows, long style)
Constructs a ListField of provided size and style.

Method Summary

void	delete(int index) Deletes row at specified index.
protected void	drawFocus(Graphics graphics, boolean on) Draws the focus indicator for this field.
ListFieldCallback	getCallback() Retrieves registered drawing callback object.
String	getEmptyString() Retrieves empty-marking string.
int	getEmptyStringStyle() Retrieves style of the empty-marking string.
void	getFocusRect(XYRect rect) Retrieves current focus region.
int	getPreferredWidth() Retrieves this field's preferred width.
int	getRowHeight() Retrieves the current row height.
int	getSelectedIndex() Retrieves index of currently selected row.
int[]	getSelection() Retrieves currently selected item(s).
int	getSize() Retrieves the number of items in this field's list.
int	indexOfList(String prefix, int start) Retrieves first occurence of prefix in this list.
void	insert(int index) Inserts empty row at specified index.
void	invalidate() Invalidates the entire field.
void	invalidate(int index) Invalidates the specified row.
boolean	isEmpty() Determines if this list is empty.
protected boolean	keyChar(char key, int status, int time) Traps key events when modifying this field.
protected boolean	keyControl(char key, int status, int time) Like keyChar, but for control characters.
protected void	layout(int width, int height) Lays out this field's contents.
protected int	moveFocus(int amount, int status, int time) Handles moving the focus within this field.
protected void	onFocus(int direction) Invoked when this field receives the focus.
protected void	paint(Graphics graphics) Redraws this field.
void	setCallback(ListFieldCallback callback) Registers the drawing callback object for this field.
void	setEmptyString(ResourceBundleFamily family, int id, int style) Sets the displayed string when there are no choices.
void	setEmptyString(String emptyString, int style) Sets the empty-marker string for this field.
void	setRowHeight(int rowHeight) Sets the height of each row in the list field.
void	setSearchable(boolean searchable) Toggles prefix searching for this field.
void	setSelectedIndex(int index) Selects row by index.
void	setSize(int size) Sets number of items in this field.
void	setSize(int size, int focusRow) Sets number of items in this field, selecting provided row.

Methods inherited from class net.rim.device.api.ui.Field

drawHighlightRegion, fieldChangeNotify, focusAdd, focusRemove, getChangeListener, getContextMenu, getCookie, getExtent, getFieldStyle, getFocusListener, getFont, getHeight, getIndex, getLeafFieldWithFocus, getLeft, getManager, getOriginal, getPreferredHeight, getScreen, getStyle, getTop, getWidth, invalidate, isDirty, isEditable, isFocusable, isMuddy, isPasteable, isSelectable, isSelecting, isSelectionCopyable, isSelectionCutable, isSelectionDeleteable, isVisible, keyDown, keyRepeat, keyStatus, keyUp, makeContextMenu, moveFocus, onUnfocus, onVisibilityChange, paste, select, selectionCopy, selectionCut, selectionDelete, setChangeListener, setCookie, setDirty, setEditable, setExtent, setFocus, setFocusListener, setFont, setMuddy, setPosition, trackwheelClick, trackwheelUnclick, updateLayout

Methods inherited from class java.lang.Object

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

Field Detail

MULTI_SELECT

public static final int MULTI_SELECT

Selection of multiple, contiguous items.

NON_CONTIGUOUS_SELECT

public static final int NON_CONTIGUOUS_SELECT

Selection of multiple, non-contiguous items (Reserved for future use).

ROW_HEIGHT_FONT

public static final int ROW_HEIGHT_FONT

Used to set the row-height to the same as the font for this field.

Constructor Detail

ListField

public ListField()

Constructs an empty ListField.

ListField

public ListField(int numRows)

Constructs a ListField of provided size.

Parameters:

numRows - Number of rows in the list.

ListField

public ListField(int numRows,
                 long style)

Constructs a ListField of provided size and style.

Parameters:

numRows - Number of rows in the list.

style - Style for this field.

Method Detail

delete

public void delete(int index)

Deletes row at specified index.

Parameters:

index - Index of row to delete (each existing element in the list after this index is pulled back one slot).

Throws:

ArrayIndexOutOfBoundsException - If index parameter is less than zero, or larger than the size of the list.

Since:

JDE 3.6

drawFocus

protected void drawFocus(Graphics graphics,
                         boolean on)

Description copied from class: Field

Draws the focus indicator for this field.

A field's manager invokes this method after painting the field. The manager initializes the graphics object passed in for drawing with field-local coordinates. It is also assumed that the region is already drawn correctly with the oposing state for the on parameter.

When overriding this methods fields should use drawHighlightRegion to render focus and select regions instead of hardcoding the logic.

By default this method invokes drawHighlightRegion to render the focus indicator using the rect obtained from getFocusRect.

Overrides:

drawFocus in class Field

Since:

JDE 3.6

getCallback

public ListFieldCallback getCallback()

Retrieves registered drawing callback object.

Use this method to retrieve the registered drawing callback object for this field (the object must previously have been registered with setCallback.

Returns:

Drawing callback object for this field; if no callback has yet been registered, returns null.

getFocusRect

public void getFocusRect(XYRect rect)

Retrieves current focus region.

Overrides:

getFocusRect in class Field

Parameters:

rect - To contain the focus rect for this field in local coordinates.

Since:

JDE 3.6

getRowHeight

public int getRowHeight()

Retrieves the current row height.

Returns:

Row height for this field.

getSize

public int getSize()

Retrieves the number of items in this field's list.

Returns:

Number of items in this field's list.

getPreferredWidth

public int getPreferredWidth()

Retrieves this field's preferred width.

This field's manager invokes this method to assist in its layout.

Overrides:

getPreferredWidth in class Field

Returns:

Preferred width (in pixels) of this field.

getSelectedIndex

public int getSelectedIndex()

Retrieves index of currently selected row.

Returns:

Index of currently selected item; if no row is selected, this method returns -1.

getSelection

public int[] getSelection()

Retrieves currently selected item(s).

Invoke this method to retrieve an array of the currently selected item(s).

Returns:

Currently selected item(s).

insert

public void insert(int index)

Inserts empty row at specified index.

Parameters:

index - Index before which to insert (each existing element in the list after this index is pushed down one slot).

Throws:

ArrayIndexOutOfBoundsException - If index parameter is less than zero, or larger than the size of the list.

Since:

JDE 3.6

invalidate

public void invalidate()

Invalidates the entire field.

Use this method to mark the field's entire contents as invalid, and requiring a repaint.

Overrides:

invalidate in class Field

invalidate

public void invalidate(int index)

Invalidates the specified row.

Invoked to mark a particular row as invalid, and requiring a repaint.

Parameters:

index - Index of row to repaint.

Since:

JDE 3.6

isEmpty

public boolean isEmpty()

Determines if this list is empty.

Returns:

True if this list has no items; otherwise, false.

keyChar

protected boolean keyChar(char key,
                          int status,
                          int time)

Traps key events when modifying this field.

This key generation handler method provides support for prefix searching (see the class description).

If the character generated is a BACKSPACE, this method clears out the search prefix. If character generated is printable, it's added to the prefix string for searching. Any other character gets passed upwards to the parent's keyChar method for handling.

Overrides:

keyChar in class Field

Parameters:

key - Character generated by the event.

status - State of the modifier keys.

time - Ticks since device reset. This parameter is used to judge whether a sufficient time has elapsed to reset the prefix search, or whether the new character should be appended to the prefix search string.

Returns:

True if event was consumed; otherwise, false.

Since:

JDE 3.6

keyControl

protected boolean keyControl(char key,
                             int status,
                             int time)

Like keyChar, but for control characters.

Overrides:

keyControl in class Field

Since:

JDE 3.6

getEmptyString

public String getEmptyString()

Retrieves empty-marking string.

This method retrieves the string this field uses to show that its list is empty.

Returns:

Empty-marking string.

getEmptyStringStyle

public int getEmptyStringStyle()

Retrieves style of the empty-marking string.

This method retrieves the style attributes of the string used to mark the list as empty.

Returns:

Style of the empty-marking string.

indexOfList

public int indexOfList(String prefix,
                       int start)

Retrieves first occurence of prefix in this list.

Provided a string prefix, and a start index, this method returns the index of the first item that matches against the string prefix (that is, a string prefix of foo matches a list item of foobar).

If a match can be found between the start index and the end of the list, this method returns the index of that matching item.

If a match can not be found between the start index and the end of the list, this method should return the result of getSelectedIndex().

Parameters:

prefix - Prefix to search for.

start - List item at which to commence the search.

Returns:

Results of the search (see description); if the start parameter is larger than the number of items in this list, this method returns -1.

Since:

JDE 3.6

moveFocus

protected int moveFocus(int amount,
                        int status,
                        int time)

Handles moving the focus within this field.

This method is invoked by the framework to move the focus within this field. The precise behaviour depends on the state of the modifier key in conjunction with the trackwheel roll. The direction of the roll is determined by the value of the amount parameter: a negative amount value indicates a backwards direction, whereas a positive amount indicates a forwards direction.

simple roll

Moves a number of items in the specified direction equal to the amount parameter. Any unused scroll amount is returned by this method.

ALT + roll

Jumps to the top or bottom (depending on direction) of the visible region, if not already there; otherwise, moves the focus up or down an entire visible screen. No remaining scroll amount is ever returned from an ALT roll.

SHIFT + roll

First sets the selection anchor, then extends the selection forward or backward (depending on direction) a number of items equal to the amount. This happens only if this field has the MULTI_SELECT style; otherwise, this is treated just like a simple roll (except that no remaining scroll amount is ever returned from a SHIFT roll).

Overrides:

moveFocus in class Field

Parameters:

amount - Number of positions to move, positive means forwards in this field's list, negative means backwards in this field's list.

status - Modifier key state.

time - Ticks since decice reset.

Returns:

Remaining scroll amount not used up. This may happen when plain rolling if the start or end of this field's list is reached; when ALT or SHIFT rolling no scroll amount is returned by this method.

Since:

JDE 3.6

onFocus

protected void onFocus(int direction)

Invoked when this field receives the focus.

This field's manager invokes this method when this field newly receives the focus.

Overrides:

onFocus in class Field

Parameters:

direction - If 1, the focus came from the previous field; if -1, the focus came from the subsequent field; if 0, the focus was set directly (not as a result of trackwheel movement).

Since:

JDE 3.6

paint

protected void paint(Graphics graphics)

Redraws this field.

This field's manager invokes this method during the repainting process to instruct this field to repaint itself.

This method determines what list elements require repainting, and then makes calls to the registered drawing callback to do the actual painting.

Overrides:

paint in class Field

Parameters:

graphics - Graphics context for repainting this field.

Since:

JDE 3.6

layout

protected void layout(int width,
                      int height)

Lays out this field's contents.

This field's manager invokes this method during the layout process to instruct this field to arrange its contents, given an amount of available space.

Overrides:

layout in class Field

Parameters:

width - Amount of available horizontal space.

height - Amount of available vertical space.

Since:

JDE 3.6

setCallback

public void setCallback(ListFieldCallback callback)

Registers the drawing callback object for this field.

Use this method to assign the callback object used to handle drawing updates for this field.

Parameters:

callback - Drawing callback object for this field.

Since:

JDE 3.6

setRowHeight

public void setRowHeight(int rowHeight)

Sets the height of each row in the list field.

If rowHeight is negative, it indicates the row height is in multiples of the height of the font for this field.

Parameters:

rowHeight - Height of each row in the list field. Specifying ROW_HEIGHT_FONT will use the height of the font for this field.

Throws:

IllegalArgumentException - If invalid row height parameter (if zero, or too small proper display of current font).

Since:

JDE 3.6

setEmptyString

public void setEmptyString(ResourceBundleFamily family,
                           int id,
                           int style)

Sets the displayed string when there are no choices.

This setting has less precedence than setEmptyString(String, int).

Since:

JDE 3.6

setEmptyString

public void setEmptyString(String emptyString,
                           int style)

Sets the empty-marker string for this field.

Provide this method with a string (and style) that this field can display to signify that this list field is empty (for example the string "[Empty]"). By default, the style for this string is DrawStyle.HCENTER (that is, horizontally centered text).

Parameters:

emptyString - Empty-marker string for this field.

style - Drawing style for the empty-marker string.

Since:

JDE 3.6

setSearchable

public void setSearchable(boolean searchable)

Toggles prefix searching for this field.

Parameters:

searchable - If true, this field will support prefix searching; if false, this field ignores key input.

Since:

JDE 3.6

setSelectedIndex

public void setSelectedIndex(int index)

Selects row by index.

Parameters:

index - Index of row to select, clamped to the size of the list.

Since:

JDE 3.6

setSize

public void setSize(int size)

Sets number of items in this field.

Invoke this method to reset the number of items in this field, and select the first item in the list.

Parameters:

size - New number of entries.

Since:

JDE 3.6

setSize

public void setSize(int size,
                    int focusRow)

Sets number of items in this field, selecting provided row.

Parameters:

size - New number of entries.

focusRow - Row to initially select (if you pass a value outside the range of this field's list size, this method adjusts the value to fit).

Since:

JDE 3.6