|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectnet.rim.device.api.ui.Field
net.rim.device.api.ui.component.ListField
public class ListField
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. |
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 java.lang.Object |
---|
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
Field Detail |
---|
public static final int MULTI_SELECT
public static final int NON_CONTIGUOUS_SELECT
public static final int NO_ALTED_PAGE_UP_DOWN
public static final int ROW_HEIGHT_FONT
Constructor Detail |
---|
public ListField()
public ListField(int numRows)
numRows
- Number of rows in the list.public ListField(int numRows, long style)
numRows
- Number of rows in the list.style
- Style for this field.Method Detail |
---|
public void delete(int index)
index
- Index of row to delete (each existing element in the list
after this index is pulled back one slot).
ArrayIndexOutOfBoundsException
- If index parameter is less than
zero, or larger than the size of the list.protected void drawFocus(Graphics graphics, boolean on)
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.
drawFocus
in class Field
graphics
- Graphics context for drawing the focus.on
- True if the focus should be set; otherwise, false.public AccessibleContext getAccessibleContext()
getAccessibleContext
in class Field
public ListFieldCallback getCallback()
Use this method to retrieve the registered drawing callback object
for this field (the object must previously have been registered with
setCallback
.
public String getEmptyString()
public int getEmptyStringStyle()
public void getFocusRect(XYRect rect)
getFocusRect
in class Field
rect
- To contain the focus rect for this field in local
coordinates.public int getPreferredWidth()
Field.getPreferredWidth()
for more information.
This field's manager invokes this method to assist in its layout.
getPreferredWidth
in class Field
public int getRowHeight()
public int getSelectedIndex()
public int[] getSelection()
Invoke this method to retrieve an array of the currently selected item(s).
public int getSize()
public int indexOfList(String prefix, int start)
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()
.
prefix
- Prefix to search for.start
- List item at which to commence the search.
public void insert(int index)
index
- Index before which to insert (each existing element in
the list after this index is pushed down one slot).
ArrayIndexOutOfBoundsException
- If index parameter is less
than zero, or larger than the size of the list.public void invalidate()
Use this method to mark the field's entire contents as invalid, and requiring a repaint.
invalidate
in class Field
public void invalidate(int index)
Invoked to mark a particular row as invalid, and requiring a repaint.
index
- Index of row to repaint.public void invalidateRange(int start, int end)
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.
IllegalArgumentException
- if: end
is less than start
,
start
is greater than the number of elements in this field's list
(as given by getSize
)public boolean isEmpty()
protected boolean keyChar(char key, int status, int time)
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.
keyChar
in class Field
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.
protected boolean keyControl(char key, int status, int time)
This method behavious like ListField.keyChar(char, int, int)
, but for control
characters.
keyControl
in class Field
key
- Character generated by the event.status
- Modifier key status.time
- Number of milliseconds since the handheld was turned on.
protected void layout(int width, int height)
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.
layout
in class Field
width
- Amount of available horizontal space.height
- Amount of available vertical space.protected int moveFocus(int amount, int status, int time)
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.
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).
moveFocus
in class Field
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.
protected void moveFocus(int x, int y, int status, int time)
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.
moveFocus
in class Field
x
- Horizontal coordinate of the new focal pointy
- Vertical coordinate of the new focal pointstatus
- Modifier key state.time
- Ticks since decice reset.protected void onFocus(int direction)
This field's manager invokes this method when this field newly receives the focus.
onFocus
in class Field
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.protected void paint(Graphics graphics)
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.
paint
in class Field
graphics
- Graphics context for repainting this field.public void setCallback(ListFieldCallback callback)
Use this method to assign the callback object used to handle drawing updates for this field.
callback
- Drawing callback object for this field.public void setEmptyString(ResourceBundleFamily family, int id, int style)
This setting has less precedence than ListField.setEmptyString(String,int)
.
family
- Resource bundle family.id
- ID of resource in bundle.style
- Style for empty string.public void setEmptyString(String emptyString, int style)
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).
emptyString
- Empty-marker string for this field.style
- Drawing style for the empty-marker string.public void setRowHeight(int rowHeight)
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.
IllegalArgumentException
- If invalid row height parameter (if
zero, or too small proper display of current font).public void setSearchable(boolean searchable)
searchable
- If true, this field will support prefix searching; if
false, this field ignores key input.public void setSelectedIndex(int index)
index
- Index of row to select, clamped to the size of the list.public void setSize(int size)
Invoke this method to reset the number of items in this field, and select the first item in the list.
size
- New number of entries.public void setSize(int size, int focusRow)
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).
|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
Copyright 1999-2010 Research In Motion Limited. 295 Phillip Street, Waterloo, Ontario, Canada, N2L 3W8. All Rights Reserved.
Copyright 1993-2003 Sun Microsystems, Inc. 901 San Antonio Road, Palo Alto, California, 94303, U.S.A. All Rights Reserved.
Copyright 2002-2003 Nokia Corporation All Rights Reserved.
Java is a trademark of Sun Microsystems, Inc.