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:

KeywordFilterField, ObjectListField

public class ListField
extends Field

Contains rows of selectable list items. A ListField uses a class that implements the ListFieldCallback interface to perform drawing tasks. A ListField must register a class that implements the ListFieldCallback interface using the setCallback method before the class can be used. After registration, when a ListField must display an item in its list, it invokes the appropriate methods of the registered callback class.

Behaviour
Displays a vertical list of set height items.

Optionally, you can build a list field as ListField.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.

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	NO_ALTED_PAGE_UP_DOWN Prevent the ALT key from triggering page up/down scrolling.
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

ACTION_INVOKE, AXIS_HORIZONTAL, AXIS_SEQUENTIAL, AXIS_VERTICAL, EDITABLE, EDITABLE_MASK, FIELD_BOTTOM, FIELD_HALIGN_MASK, FIELD_HCENTER, FIELD_LEADING, FIELD_LEFT, FIELD_RIGHT, FIELD_TOP, FIELD_TRAILING, FIELD_VALIGN_MASK, FIELD_VCENTER, FOCUSABLE, FOCUSABLE_MASK, HIGHLIGHT_FOCUS, HIGHLIGHT_SELECT, NON_FOCUSABLE, NON_SPELLCHECKABLE, READONLY, SPELLCHECKABLE, SPELLCHECKABLE_MASK, STATUS_MOVE_FOCUS_HORIZONTALLY, STATUS_MOVE_FOCUS_VERTICALLY, USE_ALL_HEIGHT, USE_ALL_WIDTH, VISUAL_STATE_ACTIVE, VISUAL_STATE_DISABLED, VISUAL_STATE_DISABLED_FOCUS, VISUAL_STATE_FOCUS, VISUAL_STATE_NORMAL

Constructor Summary

ListField()
Constructs a new, empty, ListField instance.

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

ListField(int numRows, long style)
Constructs a new ListField instance 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.
AccessibleContext	getAccessibleContext() Returns accessible representation of the field for a screen reader
ListFieldCallback	getCallback() Retrieves registered drawing callback object.
String	getEmptyString() Retrieves a string that this field uses to show its list is empty.
int	getEmptyStringStyle() Retrieves the style attributes of the string this field uses to show its list is empty.
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.
void	invalidateRange(int start, int end) Invalidates a range of rows in this ListField.
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) Traps control key events when modifying this field.
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	moveFocus(int x, int y, 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(String emptyString, int style) Sets the empty-marker string for this field.
void	setEmptyString(ResourceBundleFamily family, int id, int style) Sets the displayed string when there are no choices.
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, getBackground, getBackground, getBorder, getBorder, getBorder, getChangeListener, getContentHeight, getContentLeft, getContentRect, getContentRect, getContentTop, getContentWidth, getContextMenu, getCookie, getExtent, getExtent, getFieldStyle, getFocusListener, getFont, getHeight, getIndex, getLeafFieldWithFocus, getLeft, getManager, getOriginal, getPreferredHeight, getScreen, getStyle, getTop, getVisualState, getWidth, invalidate, invalidateAll, invokeAction, isDataValid, isDirty, isEditable, isFocus, isFocusable, isMuddy, isPasteable, isSelectable, isSelecting, isSelectionCopyable, isSelectionCutable, isSelectionDeleteable, isSpellCheckable, isStyle, isVisible, keyDown, keyRepeat, keyStatus, keyUp, makeContextMenu, navigationClick, navigationMovement, navigationUnclick, onDisplay, onExposed, onMenuDismissed, onMenuDismissed, onObscured, onUndisplay, onUnfocus, onVisibilityChange, paste, select, selectionCopy, selectionCut, selectionDelete, setBackground, setBackground, setBorder, setBorder, setBorder, setBorder, setChangeListener, setCookie, setDirty, setEditable, setExtent, setFocus, setFocusListener, setFont, setMuddy, setNonSpellCheckable, setPosition, setVisualState, touchEvent, 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.

See Also:

Constant Field Values

NON_CONTIGUOUS_SELECT

public static final int NON_CONTIGUOUS_SELECT

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

See Also:

Constant Field Values

NO_ALTED_PAGE_UP_DOWN

public static final int NO_ALTED_PAGE_UP_DOWN

Prevent the ALT key from triggering page up/down scrolling.

See Also:

Constant Field Values

Since:

BlackBerry API 4.0.0

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.

See Also:

Constant Field Values

Constructor Detail

ListField

public ListField()

Constructs a new, empty, ListField instance.

ListField

public ListField(int numRows)

Constructs a new ListField instance of provided size.

Parameters:

numRows - Number of rows in the list.

ListField

public ListField(int numRows,
                 long style)

Constructs a new ListField instance 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.

drawFocus

protected void drawFocus(Graphics graphics,
                         boolean on)

Draws the focus indicator for this field.

This field's manager invokes this method after painting this field. The mnager initializes the graphics context pass in for drawing with field-local coordinates. It is also assumed that the region is already drawn correctly with the opposing state for the on parameter.

Overrides:

drawFocus in class Field

Parameters:

graphics - Graphics context for drawing the focus.

on - True if the focus should be set; otherwise, false.

getAccessibleContext

public AccessibleContext getAccessibleContext()

Returns accessible representation of the field for a screen reader

Overrides:

getAccessibleContext in class Field

Returns:

AccessibleContext instance

Since:

BlackBerry API 4.6.1

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.

getEmptyString

public String getEmptyString()

Retrieves a string that this field uses to show its list is empty.

Returns:

A string used to show this field's list is empty.

getEmptyStringStyle

public int getEmptyStringStyle()

Retrieves the style attributes of the string this field uses to show its list is empty.

Returns:

The style of the string used to show this field's list is empty.

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.

getPreferredWidth

public int getPreferredWidth()

Retrieves this field's preferred width. See Field.getPreferredWidth() for more information.

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.

getRowHeight

public int getRowHeight()

Retrieves the current row height. Note: The row height returned is the default row height.

Returns:

Row height for 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).

getSize

public int getSize()

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

Returns:

Number of items in this field's list.

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 ListField.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.

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.

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.

invalidateRange

public void invalidateRange(int start,
                            int end)

Invalidates a range of rows in this ListField.

Parameters:

start - the index of the first row to be invalidated, the top of which is the top co-ordinate for invalidation; if less than zero, then zero will be used.

end - the index of the last row to be invalidated, the bottom of which is the bottom co-ordinate for invalidation; if greater than the index of the last row then the index of the last row will be used.

Throws:

IllegalArgumentException - if: end is less than start, start is greater than the number of elements in this field's list (as given by getSize)

Since:

BlackBerry API 4.2.0

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. ListFields 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. BlackBerry devices with SureType do not support the basic form of prefix searching.

Non-printable characters: If the character generated is a BACKSPACE, this method clears out the search prefix.

Printable characters: If the character generated is printable, this method adds the character to the search prefix string. On BlackBerry devices with SureType, this method does not append the character to the search prefix string. Instead, this method resets the prefix and adds the character to the empty prefix.

Other characters: 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 - Number of milliseconds since the handheld was turned on. 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.

keyControl

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

Traps control key events when modifying this field.

This method behavious like ListField.keyChar(char, int, int), but for control characters.

Overrides:

keyControl in class Field

Parameters:

key - Character generated by the event.

status - Modifier key status.

time - Number of milliseconds since the handheld was turned on.

Returns:

True if this method consumed the event; otherwise, false.

Since:

BlackBerry API 3.6.0

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.

Specified by:

layout in class Field

Parameters:

width - Amount of available horizontal space.

height - Amount of available vertical space.

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 ListField.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 - Number of milliseconds since the handheld was turned on.

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.

moveFocus

protected void moveFocus(int x,
                         int y,
                         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. Given an x,y position in client coordinates, update the focus to point to the new location.

Overrides:

moveFocus in class Field

Parameters:

x - Horizontal coordinate of the new focal point

y - Vertical coordinate of the new focal point

status - Modifier key state.

time - Ticks since decice reset.

Since:

BlackBerry API 4.0.0

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). The focus on a particular list item is set only if the selected index has not already been set.

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.

Specified by:

paint in class Field

Parameters:

graphics - Graphics context for repainting this field.

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.

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 ListField.setEmptyString(String,int).

Parameters:

family - Resource bundle family.

id - ID of resource in bundle.

style - Style for empty string.

Since:

BlackBerry API 3.6.0

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.

setRowHeight

public void setRowHeight(int rowHeight)

Sets the height of each row in the list field.

Parameters:

rowHeight - Height of each row in the list field. Specifying ListField.ROW_HEIGHT_FONT will use the height of the font for this field. If this parameter is negative, it indicates the row height is in multiples of 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).

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.

setSelectedIndex

public void setSelectedIndex(int index)

Selects row by index.

Parameters:

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

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.

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).