|
|||||||||
| 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.ScrollView
net.rim.device.api.ui.Manager
net.rim.device.api.ui.container.VerticalFieldManager
net.rim.device.api.ui.component.AutoCompleteField
public class AutoCompleteField
AutoCompleteField lets you create a text field that presents users with a changing list of words that are associated with the characters they have typed in the field. Users can select one of the presented matches or continue typing to further restrict the choices presented in the list.
When you construct an AutoCompleteField you must associate a BasicFilteredList with it.
The BasicFilteredList includes the data objects that are compared against to produce the list of matches
presented to the user. You can configure both which fields in the data objects are compared
against and which fields are displayed when a match occurs. For example, you can compare what the user types to the value
of the DATA_FIELD_CONTACTS_BIRTHDAY field in the DATA_SOURCE_CONTACTS data source,
but return the value of the corresponding DATA_FIELD_CONTACTS_NAME_FULL field.
There are four types of data that you can bind to a BasicFilteredList
to use with AutoCompleteField:
StringsObjectsStrings and a corresponding array of ObjectsBy default, the autocomplete field displays the set of strings returned by the comparison process in a drop-down list. You can configure aspects of this list by specifying style flags when you construct the field. You can change what is displayed and how the user can interact with the list.
The following code snippet demonstrates how to add an AutoCompleteField to a screen class.
The comparison data is a set of literal strings in this case.
BasicFilteredList filterList = new BasicFilteredList();
String[] days = {"Monday","Tuesday","Wednesday",
"Thursday","Friday","Saturday","Sunday"};
int uniqueID = 0;
filterList.addDataSet(uniqueID,days,"days",BasicFilteredList.COMPARISON_IGNORE_CASE);
AutoCompleteField autoCompleteField = new AutoCompleteField(filterList);
add(autoCompleteField);
The following code snippet demonstrates how to specify fields of a BlackBerry device data source to use for comparisons
and returned matches. In this case, the data source is Contacts, the field that is compared against is
DATA_FIELD_CONTACTS_NAME_FULL and name, email and phone information is displayed.
BasicFilteredList filterList = new BasicFilteredList();
int uniqueID = 0;
long srcType = BasicFilteredList.DATA_SOURCE_CONTACTS;
long searchField = BasicFilteredList.DATA_FIELD_CONTACTS_NAME_FULL;
long requestedFields = BasicFilteredList.DATA_FIELD_CONTACTS_NAME_FULL
| BasicFilteredList.DATA_FIELD_CONTACTS_EMAIL
| BasicFilteredList.DATA_FIELD_CONTACTS_PHONE_ALL;
long primaryField = BasicFilteredList.DATA_FIELD_CONTACTS_NAME_FULL;
filterList.addDataSource(uniqueID,
srcType,
searchField,
requestedFields,
primaryField,
-1, //no secondary specified
"Contact");
long style = AutoCompleteField.LIST_EXPAND_ON_HIGHLIGHT;
AutoCompleteField autoCompleteField = new AutoCompleteField(filterList, style);
add(autoCompleteField);
BasicFilteredList| Field Summary | ||
|---|---|---|
static long |
LIST_DROPDOWN
Specifies that the associated ListField be a drop-down list that displays only results returned by the comparison process. |
|
static long |
LIST_EXPANDED_ROWS_NOT_SELECTABLE
Specifies that the expanded list items not be individually selectable. |
|
static long |
LIST_EXPAND_ON_CLICK
Specifies that the list expand to show more data when the user clicks the list item. |
|
static long |
LIST_EXPAND_ON_HIGHLIGHT
Specifies that the list expand to show more data when the user highlights the list item. |
|
static long |
LIST_HIDDEN
Specifies that the search results be displayed in a list that is not visible. |
|
static long |
LIST_SHOW_DATA_SET_NAME
Specifies that list items include the name of the data set or data source as a prefix. |
|
static long |
LIST_SHOW_MATCHED_FIELD_NAME_AND_VALUE
Specifies that list items include the name and value of the matched field after the primary field (if there is no secondary field). |
|
static long |
LIST_SHOW_MATCHED_FIELD_VALUE
Specifies that list items include the value of the matched field after the primary field (if there is no secondary field). |
|
static long |
LIST_SHOW_REQUESTED_FIELD_NAME
Specifies that expanded list items include the name of the requested field as a prefix to the requested field value. |
|
static long |
LIST_STATIC
Specifies that the search results be displayed in a list that is always visible. |
|
static int |
SELECT_ENTER
Indicates that the list item was selected by pressing ENTER. |
|
static int |
SELECT_TRACKBALL_CLICK
Indicates that the list item was selected by a trackball click. |
|
static int |
SELECT_TRACKWHEEL_CLICK
Indicates that the list item was selected by a trackwheel click. |
|
| Fields inherited from class net.rim.device.api.ui.Manager |
|---|
BOTTOMMOST, DOWNWARD, HORIZONTAL_SCROLL, HORIZONTAL_SCROLLBAR, HORIZONTAL_SCROLLBAR_MASK, HORIZONTAL_SCROLL_MASK, LEAVE_BLANK_SPACE, LEFTMOST, LEFTWARD, NO_HORIZONTAL_SCROLL, NO_HORIZONTAL_SCROLLBAR, NO_SCROLL_RESET, NO_VERTICAL_SCROLL, NO_VERTICAL_SCROLLBAR, QUANTA_FONT, RIGHTMOST, RIGHTWARD, TOPMOST, UPWARD, VERTICAL_SCROLL, VERTICAL_SCROLLBAR, VERTICAL_SCROLLBAR_MASK, VERTICAL_SCROLL_MASK |
| Fields inherited from interface net.rim.device.api.ui.FieldChangeListener |
|---|
PROGRAMMATIC |
| Constructor Summary | ||
|---|---|---|
AutoCompleteField(BasicFilteredList filteredList)
Instantiate the field, passing in a filtered list. |
||
AutoCompleteField(BasicFilteredList filteredList,
long style)
Instantiate the field, passing in a filtered list and style attributes for the AutoCompleteField. |
||
AutoCompleteField(BasicFilteredList filteredList,
long styleAutoCompleteField,
long styleBasicEditField,
long styleListField)
Instantiate the field, passing in a filtered list and style attributes for the AutoCompleteField as well as its BasicEditField and ListField. |
||
| Method Summary | ||
|---|---|---|
protected void |
drawExpandedListRow(ListField listField,
Graphics graphics,
int index,
int offset,
int y,
int width)
Invoked to display subitems when an item in the results list is expanded. |
|
void |
drawListRow(ListField listField,
Graphics g,
int index,
int y,
int width)
Invoked when a particular row requires painting. |
|
void |
fieldChanged(Field field,
int context)
Executed whenever the text in the field changes. |
|
Object |
get(ListField listField,
int index)
Return the choice at a given index. |
|
AccessibleContext |
getAccessibleContext()
Returns an object that provides access to information that can be used by assistive technology. |
|
protected XYEdges |
getDropMargin()
Returns the left and right margins for the drop-down list. |
|
BasicEditField |
getEditField()
Get the edit field associated with this AutoCompleteField. |
|
protected int |
getExpandedSize(BasicFilteredListResult result)
Given a result in the list, get the number of expanded rows for the result. |
|
BasicFilteredList |
getFilteredList()
Get the basic filtered list associated with this AutoCompleteField. |
|
ListField |
getListField()
Get the list field associated with this AutoCompleteField. |
|
int |
getPreferredWidth(ListField listField)
The AutoCompleteField will set the width of the list. |
|
protected int |
getSelectedExpandedOffset()
Get the currently selected expanded row offset. |
|
Object |
getSelectedObject()
Get the list item selected by the user. |
|
int |
indexOfList(ListField listField,
String prefix,
int start)
There is no prefix searching in an AutoCompleteField, so this is ignored. |
|
protected void |
onSelect(Object selection,
int type)
Called when the user selects a list item. |
|
void |
setExpansionDelay(long delay)
Set the delay before expanding a list item. |
|
void |
setFilteredList(BasicFilteredList filteredList)
Set the filtered list. |
|
void |
setFocus()
Sets the focus to this field. |
|
void |
setHintText(String hintText)
Set the hint text for the edit field. |
|
void |
setHintText(String hintText,
int hintTextColor,
Font hintTextFont)
Set the hint text for the edit field. |
|
void |
setKeystrokeForwarding(boolean forwarding)
Specifies whether or not keystrokes are forwarded to the edit field while the list field has focus. |
|
protected boolean |
usingSureType()
Return true if we're running on a device that uses SureType. |
|
| Methods inherited from class net.rim.device.api.ui.container.VerticalFieldManager |
|---|
getFieldAtLocation, getPreferredHeight, getPreferredWidth, nextFocus, sublayout, subpaint |
| Methods inherited from class net.rim.device.api.ui.ScrollView |
|---|
configurationChanged, getHorizontalAdjustment, getVerticalAdjustment, getVisibleHeight, getVisibleWidth, onDisplay, onUndisplay, setCurrentLocation, setExtent, setHorizontalAdjustment, setHorizontalScroll, setHorizontalScroll, setScrollListener, setVerticalAdjustment, setVerticalScroll, setVerticalScroll, valueChanged, waitForScrolling |
| Methods inherited from class java.lang.Object |
|---|
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
| Field Detail |
|---|
public static final long LIST_DROPDOWN
public static final long LIST_STATIC
public static final long LIST_EXPAND_ON_CLICK
public static final long LIST_EXPAND_ON_HIGHLIGHT
AutoCompleteField.setExpansionDelay(long delay).
public static final long LIST_SHOW_DATA_SET_NAME
addDataSet(int id,Object[] objects,String name)
or addDataSource(int id,int type,long searchFields,long requestedFields,long primaryField,long secondaryField,String name)
to bind data to a BasicFilteredList.
public static final long LIST_SHOW_MATCHED_FIELD_VALUE
public static final long LIST_SHOW_MATCHED_FIELD_NAME_AND_VALUE
public static final long LIST_SHOW_REQUESTED_FIELD_NAME
public static final long LIST_EXPANDED_ROWS_NOT_SELECTABLE
public static final long LIST_HIDDEN
public static final int SELECT_TRACKWHEEL_CLICK
public static final int SELECT_TRACKBALL_CLICK
public static final int SELECT_ENTER
| Constructor Detail |
|---|
public AutoCompleteField(BasicFilteredList filteredList)
filteredList - A BasicFilteredList object bound to the data to compare against.
public AutoCompleteField(BasicFilteredList filteredList,
long style)
filteredList - A BasicFilteredList object bound to the data to compare against.style - Style attributes for the field.
public AutoCompleteField(BasicFilteredList filteredList,
long styleAutoCompleteField,
long styleBasicEditField,
long styleListField)
filteredList - A BasicFilteredList object bound to the data to compare against.styleAutoCompleteField - Style attributes for the AutoCompleteField.styleBasicEditField - Style attributes for the internal BasicEditField. Currently, the following styles are always included: BasicEditField.NO_NEWLINE | BasicEditField.NO_LOOKUP | BasicEditField.IM_NO_PREDICTION.styleListField - Style attributes for the internal ListField.| Method Detail |
|---|
public BasicFilteredList getFilteredList()
public BasicEditField getEditField()
public ListField getListField()
public Object getSelectedObject()
public void setFilteredList(BasicFilteredList filteredList)
filteredList - A BasicFilteredList object containing all the data.public void setKeystrokeForwarding(boolean forwarding)
forwarding - True forwards keystrokes. False does not.public void setFocus()
This method removes the focus from the field that currently has it (if any) and moves it to this field. The screen performs any necessary scrolling to ensure the new focus region is visible.
This method gives the focus to the BasicEditField if it is focusable, otherwise to the ListField.
If this field already has the focus, invoking this method has no effect.
setFocus in class FieldIllegalStateException - If the field is not attached to a screen.public void setExpansionDelay(long delay)
LIST_EXPAND_ON_HIGHLIGHT was set.
delay - The delay in milliseconds
IllegalStateException - if the LIST_EXPAND_ON_HIGHLIGHT is not set.protected XYEdges getDropMargin()
XYEdges class only
has its left and right fields
set. Each represents the distance from the field extent to the margin on the specified side in pixels.
protected boolean usingSureType()
true if the current input method supports SureType input, false otherwise- Since:
- BlackBerry API 5.0.0
protected void onSelect(Object selection,
int type)
selection - The selected itemtype - The method of selection. This will be one of
SELECT_TRACKWHEEL_CLICK
SELECT_TRACKBALL_CLICK
SELECT_ENTERpublic void setHintText(String hintText)
hintText - The hint text, null will remove the hint text.
public void setHintText(String hintText,
int hintTextColor,
Font hintTextFont)
hintText - The hint text, null will remove the hint text.hintTextColor - The color the hint text will be in. Default color 0xB5B2B5 will be used if invalid value (less than 0, or greater than 0xFFFFFF).hintTextFont - The font the hint text will be in. Default font will be used if hintTextColor is null.
public void fieldChanged(Field field,
int context)
fieldChanged in interface FieldChangeListenerfield - The field that changedcontext - Extra information about the field change (e.g. PROGRAMMATIC)
public void drawListRow(ListField listField,
Graphics g,
int index,
int y,
int width)
drawListRow in interface ListFieldCallbacklistField - List field that requires repainting.g - Graphics context for the list.index - Row index to display.y - Distance from the top of the list field at which to start
painting.width - Width of the field.
public Object get(ListField listField,
int index)
get in interface ListFieldCallbacklistField - List field to search through.index - Row index containing desired item.
public int getPreferredWidth(ListField listField)
getPreferredWidth in interface ListFieldCallbacklistField - List field for which to determine preferred width.
public int indexOfList(ListField listField,
String prefix,
int start)
indexOfList in interface ListFieldCallbacklistField - List field in which to search.prefix - Prefix to search for.start - List item at which commence the search.
protected void drawExpandedListRow(ListField listField,
Graphics graphics,
int index,
int offset,
int y,
int width)
The graphics context passed to this method represents the entire list, not just the row for repainting. Accordingly, the y parameter indicates how far down in the list the repaint should occur.
listField - List field that requires repainting.graphics - Graphics context for the list.index - Row index to display.offset - Expanded row offset to display.y - Distance from the top of the list field at which to start painting.width - Width of the field.protected int getExpandedSize(BasicFilteredListResult result)
result - List item
protected int getSelectedExpandedOffset()
-1 will be returned.
public AccessibleContext getAccessibleContext()
getAccessibleContext in class Manager
|
|||||||||
| 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.