|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectnet.rim.device.api.collection.util.BasicFilteredList
public class BasicFilteredList
An implementation of FilteredList
that lets you specify criteria to search for within data objects. You specify
the search criteria using setCriteria()
and specify the data objects using either
addDataSet()
or addDataSource()
.
The data objects can be:
Strings
Objects
Strings
and a corresponding array of Objects
The maximum number of objects that can be added is 65535. Attempts to add more will not throw an exception but will have no effect.
You can use a BasicFilteredList
with AutoCompleteField
, which will use it to compare against what the user has typed and display the results in a list. Alternatively,
you can use BasicFilteredList
on its own in any application that requires comparing strings with the supported data objects.
Implementations that read this list must synchronize on the lock obtained by getLock()
for thread-safe execution.
Field Summary | ||
---|---|---|
static long |
COMPARISON_IGNORE_CASE
Ignore case when comparing a data object's associated string with the search string. |
|
static long |
DATA_FIELD_CONTACTS_ADDRESS_ALL
All address fields of DATA_SOURCE_CONTACTS. |
|
static long |
DATA_FIELD_CONTACTS_ADDRESS_HOME
The home address field of DATA_SOURCE_CONTACTS. |
|
static long |
DATA_FIELD_CONTACTS_ADDRESS_WORK
The work address field of DATA_SOURCE_CONTACTS. |
|
static long |
DATA_FIELD_CONTACTS_ALL
All fields of DATA_SOURCE_CONTACTS. |
|
static long |
DATA_FIELD_CONTACTS_ANNIVERSARY
The anniversary field of DATA_SOURCE_CONTACTS. |
|
static long |
DATA_FIELD_CONTACTS_BIRTHDAY
The birthday field of DATA_SOURCE_CONTACTS. |
|
static long |
DATA_FIELD_CONTACTS_CATEGORIES
The categories field of DATA_SOURCE_CONTACTS. |
|
static long |
DATA_FIELD_CONTACTS_COMPANY
The company field of DATA_SOURCE_CONTACTS. |
|
static long |
DATA_FIELD_CONTACTS_EMAIL
The email field of DATA_SOURCE_CONTACTS. |
|
static long |
DATA_FIELD_CONTACTS_FAX
The fax number field of DATA_SOURCE_CONTACTS. |
|
static long |
DATA_FIELD_CONTACTS_FAX2
The secondary fax number field of DATA_SOURCE_CONTACTS. |
|
static long |
DATA_FIELD_CONTACTS_JOB_TITLE
The job title field of DATA_SOURCE_CONTACTS. |
|
static long |
DATA_FIELD_CONTACTS_NAME_FIRST
The first name field of DATA_SOURCE_CONTACTS. |
|
static long |
DATA_FIELD_CONTACTS_NAME_FULL
The full name field of DATA_SOURCE_CONTACTS. |
|
static long |
DATA_FIELD_CONTACTS_NAME_LAST
The last name field of DATA_SOURCE_CONTACTS. |
|
static long |
DATA_FIELD_CONTACTS_NOTES
The notes field of DATA_SOURCE_CONTACTS. |
|
static long |
DATA_FIELD_CONTACTS_PAGER
The pager number field of DATA_SOURCE_CONTACTS. |
|
static long |
DATA_FIELD_CONTACTS_PHONE_ALL
All phone number fields of DATA_SOURCE_CONTACTS. |
|
static long |
DATA_FIELD_CONTACTS_PHONE_HOME
The first home phone number of DATA_SOURCE_CONTACTS. |
|
static long |
DATA_FIELD_CONTACTS_PHONE_HOME2
The second home phone number of DATA_SOURCE_CONTACTS. |
|
static long |
DATA_FIELD_CONTACTS_PHONE_MOBILE
The mobile phone number of DATA_SOURCE_CONTACTS. |
|
static long |
DATA_FIELD_CONTACTS_PHONE_MOBILE2
The secondary mobile phone number of DATA_SOURCE_CONTACTS. |
|
static long |
DATA_FIELD_CONTACTS_PHONE_OTHER
The other phone number of DATA_SOURCE_CONTACTS. |
|
static long |
DATA_FIELD_CONTACTS_PHONE_WORK
The first work phone number of DATA_SOURCE_CONTACTS. |
|
static long |
DATA_FIELD_CONTACTS_PHONE_WORK2
The second work phone number of DATA_SOURCE_CONTACTS. |
|
static long |
DATA_FIELD_CONTACTS_PIN
The PIN field of DATA_SOURCE_CONTACTS. |
|
static long |
DATA_FIELD_MEMOS_TITLE
The title field of DATA_SOURCE_MEMOS. |
|
static long |
DATA_FIELD_MUSIC_ALBUM
The album field of DATA_SOURCE_MUSIC. |
|
static long |
DATA_FIELD_MUSIC_ALL
All fields of DATA_SOURCE_MUSIC. |
|
static long |
DATA_FIELD_MUSIC_ARTIST
The artist field of DATA_SOURCE_MUSIC. |
|
static long |
DATA_FIELD_MUSIC_GENRE
The genre field of DATA_SOURCE_MUSIC. |
|
static long |
DATA_FIELD_MUSIC_SONG
The song field of DATA_SOURCE_MUSIC. |
|
static long |
DATA_FIELD_PICTURES_TITLE
The title field of DATA_SOURCE_PICTURES. |
|
static long |
DATA_FIELD_RINGTONES_TITLE
The title field of DATA_SOURCE_RINGTONES. |
|
static long |
DATA_FIELD_TASKS_TITLE
The title field of DATA_SOURCE_TASKS. |
|
static long |
DATA_FIELD_VIDEOS_TITLE
The title field of DATA_SOURCE_VIDEOS. |
|
static long |
DATA_FIELD_VOICENOTES_TITLE
The title field of DATA_SOURCE_VOICENOTES. |
|
static int |
DATA_SOURCE_CONTACTS
Use contacts as the data source. |
|
static int |
DATA_SOURCE_MEMOS
Use memos as the data source. |
|
static int |
DATA_SOURCE_MUSIC
Use music as the data source. |
|
static int |
DATA_SOURCE_PICTURES
Use pictures as the data source. |
|
static int |
DATA_SOURCE_RINGTONES
Use ring tones as the data source. |
|
static int |
DATA_SOURCE_TASKS
Use tasks as the data source. |
|
static int |
DATA_SOURCE_VIDEOS
Use videos as the data source. |
|
static int |
DATA_SOURCE_VOICENOTES
Use voice notes as the data source. |
|
static long |
PRIORITY_MIN
Builds and updates the filtered list in a minimum-priority thread. |
|
static long |
PRIORITY_NORM
Builds and updates the filtered list in a normal-priority thread. |
|
static long |
REFRESH_CONTINUOUSLY
Like REFRESH_INTERMITTENTLY except that after the list has finished building, it still refreshes on a continual basis regardless of whether the list size changes. |
|
static long |
REFRESH_IMMEDIATELY
Causes an immediate refresh whenever data is added or removed during the initial building of the list and afterwards. |
|
static long |
REFRESH_INTERMITTENTLY
Refreshes the list according to the interval specified with setMinimumRefreshInterval() until the list has finished building. |
|
static long |
SORT_BY_DATASET_ID
Sort results by the dataset or datasource ID. |
|
static long |
SORT_BY_PRIMARY_FIELD
Sort results alphabetically by the primary field. |
|
static long |
SORT_BY_SECONDARY_FIELD
Sort results alphabetically by the secondary field. |
Constructor Summary | ||
---|---|---|
BasicFilteredList()
Instantiate the class and assume the data will be set later. |
||
BasicFilteredList(long style)
Instantiate the class with specified style and assume the data will be set later. |
||
BasicFilteredList(long style,
Comparator comparator)
Instantiate the class with specified comparator and assume the data will be set later. |
Method Summary | ||
---|---|---|
void |
addCollectionListener(Object listener)
Registers a listener to receive collection events. |
|
void |
addDataSet(int id,
Object[] objects,
String name)
Adds an array of objects to compare against. |
|
void |
addDataSet(int id,
Object[] objects,
String name,
long style)
Adds an array of objects to compare against. |
|
void |
addDataSet(int id,
String[] strings,
Object[] objects,
String name)
Adds an array of objects and an array of strings that are linked pairwise by corresponding indices. |
|
void |
addDataSet(int id,
String[] strings,
Object[] objects,
String name,
long style)
Adds an array of objects and an array of strings that are linked pairwise by corresponding indices. |
|
void |
addDataSet(int id,
String[] strings,
String name)
Adds a list of strings to match against. |
|
void |
addDataSet(int id,
String[] strings,
String name,
long style)
Adds a list of strings to match against. |
|
void |
addDataSource(int id,
int type,
long searchFields,
long requestedFields,
long primaryField,
long secondaryField,
String name)
Adds a supported data source to match against. |
|
void |
addDataSource(int id,
int type,
long searchFields,
long requestedFields,
long primaryField,
long secondaryField,
String name,
long style)
Adds a supported data source to match against. |
|
void |
clear()
Removes all datasets and datasources. |
|
void |
fillResultForValue(BasicFilteredListResult result,
Object value)
Wraps a data object in a BasicFilteredListResult object which provides
access to its dataset name as well as its fields, if it is a data source. |
|
boolean |
firstWordMatched(Object value)
This method works only if you specify a custom comparator by using setComparator(Comparator) . |
|
Object |
getAt(int index)
Retrieves element from filtered list by index. |
|
int |
getAt(int index,
int count,
Object[] elements,
int destIndex)
Retrieves range of elements from filtered list starting at provided index. |
|
Object |
getCriteria()
Gets the search criteria. |
|
String[] |
getFields(BasicFilteredListResult result,
long field)
Retrieves the values of the specified field. |
|
int |
getIDForValue(Object value)
Returns the ID of the data set or data source of the data object. |
|
int |
getIndex(Object element)
Retrieves index of element in filtered list by element. |
|
Object |
getLock()
All synchronized operations should use this lock. |
|
void |
getMatchedFields(BasicFilteredListResult result)
Populates the values of the matched fields in a BasicFilteredListResult object. |
|
String[] |
getMatchedKeywords(BasicFilteredListResult result)
Gets the keywords that matched for the provided data object. |
|
int |
getOrderForValue(Object value)
Returns the order (or position) in which the specified data object was added. |
|
void |
getRequestedFields(BasicFilteredListResult result)
Populates the values of the requested fields in a BasicFilteredListResult object. |
|
long |
getStyle()
Retrieves the set style bits. |
|
int |
getTotalSize()
Gets the total size of the list before any filtering. |
|
void |
haltSearch()
Halts the search. |
|
boolean |
isFilteringInProgress()
Determines if there is a filtering task in progress. |
|
boolean |
isLoadingInProgress()
Determines if the data is being loaded. |
|
Object |
preProcessCriteria(Object criteria)
Allows pre-processing of the search criteria. |
|
boolean |
preProcessData(BasicFilteredListResult result)
Allows pre-processing of data objects so you can include or exclude specific objects from the data to be searched. |
|
String[] |
preProcessStrings(BasicFilteredListResult result,
String[] searchStrings)
Allows pre-processing of data field values so you can modify them before they are added to the data to be searched. |
|
void |
removeCollectionListener(Object listener)
Removes a listener object from the list of those receiving events. |
|
void |
removeDataSet(int id)
Removes the specified data set. |
|
void |
removeDataSource(int id)
Removes the specified data source. |
|
boolean |
removeValue(Object value)
Removes the specified data object from the searchable data. |
|
void |
reset()
Start a new search with the current criteria. |
|
void |
setComparator(Comparator comparator)
Sets the custom comparator used to sort the matching data objects. |
|
void |
setCriteria(Object criteria,
FilterStatusListener listener)
Sets the filtering criteria for the collection and performs the filtering asynchronously. |
|
void |
setMinimumRefreshInterval(long interval)
Sets the minimimum refresh interval. |
|
int |
size()
Retrieves the number of elements in this collection. |
|
void |
waitForComplete()
Waits for filtering tasks to complete. |
Methods inherited from class java.lang.Object |
---|
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
Field Detail |
---|
public static final long SORT_BY_DATASET_ID
public static final long SORT_BY_PRIMARY_FIELD
public static final long SORT_BY_SECONDARY_FIELD
public static final long REFRESH_CONTINUOUSLY
public static final long REFRESH_IMMEDIATELY
public static final long REFRESH_INTERMITTENTLY
public static final long PRIORITY_MIN
public static final long PRIORITY_NORM
public static final long COMPARISON_IGNORE_CASE
public static final int DATA_SOURCE_CONTACTS
public static final int DATA_SOURCE_MEMOS
public static final int DATA_SOURCE_MUSIC
public static final int DATA_SOURCE_PICTURES
public static final int DATA_SOURCE_RINGTONES
public static final int DATA_SOURCE_TASKS
public static final int DATA_SOURCE_VIDEOS
public static final int DATA_SOURCE_VOICENOTES
public static final long DATA_FIELD_CONTACTS_ALL
public static final long DATA_FIELD_CONTACTS_ADDRESS_ALL
public static final long DATA_FIELD_CONTACTS_ADDRESS_HOME
public static final long DATA_FIELD_CONTACTS_ADDRESS_WORK
public static final long DATA_FIELD_CONTACTS_ANNIVERSARY
public static final long DATA_FIELD_CONTACTS_BIRTHDAY
public static final long DATA_FIELD_CONTACTS_CATEGORIES
public static final long DATA_FIELD_CONTACTS_COMPANY
public static final long DATA_FIELD_CONTACTS_EMAIL
public static final long DATA_FIELD_CONTACTS_FAX
public static final long DATA_FIELD_CONTACTS_JOB_TITLE
public static final long DATA_FIELD_CONTACTS_NAME_FULL
public static final long DATA_FIELD_CONTACTS_NAME_FIRST
public static final long DATA_FIELD_CONTACTS_NAME_LAST
public static final long DATA_FIELD_CONTACTS_NOTES
public static final long DATA_FIELD_CONTACTS_PAGER
public static final long DATA_FIELD_CONTACTS_PHONE_ALL
public static final long DATA_FIELD_CONTACTS_PHONE_HOME
public static final long DATA_FIELD_CONTACTS_PHONE_HOME2
public static final long DATA_FIELD_CONTACTS_PHONE_MOBILE
public static final long DATA_FIELD_CONTACTS_PHONE_OTHER
public static final long DATA_FIELD_CONTACTS_PHONE_WORK
public static final long DATA_FIELD_CONTACTS_PHONE_WORK2
public static final long DATA_FIELD_CONTACTS_PIN
public static final long DATA_FIELD_CONTACTS_FAX2
public static final long DATA_FIELD_CONTACTS_PHONE_MOBILE2
public static final long DATA_FIELD_MEMOS_TITLE
public static final long DATA_FIELD_MUSIC_ALL
public static final long DATA_FIELD_MUSIC_ALBUM
public static final long DATA_FIELD_MUSIC_ARTIST
public static final long DATA_FIELD_MUSIC_GENRE
public static final long DATA_FIELD_MUSIC_SONG
public static final long DATA_FIELD_PICTURES_TITLE
public static final long DATA_FIELD_RINGTONES_TITLE
public static final long DATA_FIELD_TASKS_TITLE
public static final long DATA_FIELD_VIDEOS_TITLE
public static final long DATA_FIELD_VOICENOTES_TITLE
Constructor Detail |
---|
public BasicFilteredList()
public BasicFilteredList(long style)
style
- The sorting and refresh styles. The sorting styles can be one of:
SORT_BY_DATASET_ID |
SORT_BY_PRIMARY_FIELD |
SORT_BY_SECONDARY_FIELD |
REFRESH_CONTINUOUSLY |
REFRESH_IMMEDIATELY |
REFRESH_INTERMITTENTLY |
The default refresh style is REFRESH_INTERMITTENTLY, which refreshes the list according to the interval specified with setMinimumRefreshInterval() until the list has finished building. Afterwards, it still checks intermittently to see if the list size has changed and if so refreshes. This is a good choice for very large datasets, as it improves performance by not sending reset events every few milliseconds as data is added.
REFRESH_CONTINUOUSLY is like REFRESH_INTERMITTENTLY except that after the list has finished building, it still refreshes on a continual basis regardless of whether the list size changes. This is useful when displaying values that continually change over time.
REFRESH_IMMEDIATELY causes an immediate refresh whenever data is added or removed during the initial building of the list and afterwards. The interval specified with setMinimumRefreshInterval() is ignored. This is good for relatively small datasets.
public BasicFilteredList(long style, Comparator comparator)
style
- The refresh style. The refresh style can be one of:
REFRESH_CONTINUOUSLY |
REFRESH_IMMEDIATELY |
REFRESH_INTERMITTENTLY |
The default refresh style is REFRESH_INTERMITTENTLY, which refreshes the list according to the interval specified with setMinimumRefreshInterval() until the list has finished building. Afterwards, it still checks intermittently to see if the list size has changed and if so refreshes. This is a good choice for very large datasets, as it improves performance by not sending reset events every few milliseconds as data is added.
REFRESH_CONTINUOUSLY is like REFRESH_INTERMITTENTLY except that after the list has finished building, it still refreshes on a continual basis regardless of whether the list size changes. This is useful when displaying values that continually change over time.
REFRESH_IMMEDIATELY causes an immediate refresh whenever data is added or removed during the initial building of the list and afterwards. The interval specified with setMinimumRefreshInterval() is ignored. This is good for relatively small datasets.
comparator
- The custom comparator. Any sorting style provided is ignored.Method Detail |
---|
public final long getStyle()
public void setComparator(Comparator comparator)
Sets the custom comparator used to sort the matching data objects. It is null by default.
If not set, the default behaviour is to preserve the order in which data objects were added.
When searching, it will put matches whose first word matched the
search string at the top of the list. If set, first-word-matches will "not" be put
at the top of the list so as to not interfere with the comparator. Instead, the
firstWordMatched(Object value)
method is provided so that a comparator
can determine if the first word of string data in a data object matched so that the comparator can
handle that itself if it chooses to.
Note that setting a custom comparator will override any sorting styles (SORT_BY_DATASET_ID, SORT_BY_PRIMARY_FIELD and SORT_BY_SECONDARY_FIELD) that were set. Also, just as setting those sorting styles will slow down the speed at which data objects are loaded (and thus ready to be searched), so too will setting a custom comparator.
An example of a comparator that sorts by data set ID is:
class ResultComparator implements Comparator { BasicFilteredList _list; public ResultComparator(BasicFilteredList list) { _list = list; } public int compare( Object value1, Object value2 ) { int id1 = _list.getIDForValue(value1); int id2 = _list.getIDForValue(value2); if (id1 != id2) { // Sort by dataset ID. return id1 - id2; } else { // Same dataset. Preserve original order within dataset. return _list.getOrderForValue(value1) - _list.getOrderForValue(value2); } } }
Note that the above code is just an example and can be more easily accomplished using the SORT_BY_DATASET_ID sorting style.
comparator
- The Comparator used to sort the search results.public void clear()
public void addDataSet(int id, String[] strings, String name)
id
- A unique ID for this data set.strings
- An array of strings.name
- A unique name for this data set. Used, for example, by
AutoCompleteField
which displays it to the
user when LIST_SHOW_DATA_SET_NAME
is specified in the AutoCompleteField
constructor.
IllegalArgumentException
- if strings
is null
.public void addDataSet(int id, String[] strings, String name, long style)
id
- A unique ID for this data set.strings
- An array of strings.name
- A unique name for this data set. Used, for example, by
AutoCompleteField
which displays it to the
user when LIST_SHOW_DATA_SET_NAME
is specified in the AutoCompleteField
constructor.style
- The search style. Supported styles are:
COMPARISON_IGNORE_CASE
IllegalArgumentException
- if strings
is null
.public void addDataSet(int id, Object[] objects, String name)
toString()
method of the object. You should override toString()
to return an appropriate
string to use in comparisons. If you specify an id
already assigned to an existing data
set, the data you specify will be added to the existing data set. Otherwise, a new data set will be created.
This method spawns its own thread and calls reset() if a CollectionListener was added via addCollectionListener(), allowing
the BasicFilteredList to be used while data is still being added. The AutoCompleteField automatically does this.
Note that only a single instance of a type of data object can occur across all of the data sets and data sources.
Also not that the maximum number of objects from all data sets and data sources is 65535. Attempting to add more
objects will not throw an exception but will have no effect.
id
- A unique ID for this data set.objects
- An array of objects to compare against. Comparisons are made against the string returned by toString()
.name
- A unique name for this data set. Used, for example, by
AutoCompleteField
which displays it to the
user when LIST_SHOW_DATA_SET_NAME
is specified in the AutoCompleteField
constructor.
IllegalArgumentException
- if objects
is null
.public void addDataSet(int id, Object[] objects, String name, long style)
toString()
method of the object. You should override toString()
to return an appropriate
string to use in comparisons. If you specify an id
already assigned to an existing data
set, the data you specify will be added to the existing data set. Otherwise, a new data set will be created.
This method spawns its own thread and calls reset() if a CollectionListener was added via addCollectionListener(), allowing
the BasicFilteredList to be used while data is still being added. The AutoCompleteField automatically does this.
Note that only a single instance of a type of data object can occur across all of the data sets and data sources.
Also not that the maximum number of objects from all data sets and data sources is 65535. Attempting to add more
objects will not throw an exception but will have no effect.
id
- A unique ID for this data set.objects
- An array of objects to compare against. Comparisons are made against the string returned by toString()
.name
- A unique name for this data set. Used, for example, by
AutoCompleteField
which displays it to the
user when LIST_SHOW_DATA_SET_NAME
is specified in the AutoCompleteField
constructor.style
- The search style. Supported styles are:
COMPARISON_IGNORE_CASE
IllegalArgumentException
- if objects
is null
.public void addDataSet(int id, String[] strings, Object[] objects, String name)
If you specify an id
already assigned to an existing data
set, the data you specify will be added to the existing data set. Otherwise, a new data set will be created.
This method spawns its own thread and calls reset() if a CollectionListener was added via addCollectionListener(), allowing
the BasicFilteredList to be used while data is still being added. The AutoCompleteField automatically does this.
Note that only a single instance of a type of data object can occur across all of the data sets and data sources.
Also not that the maximum number of objects from all data sets and data sources is 65535. Attempting to add more
objects will not throw an exception but will have no effect.
id
- A unique ID for this data set.strings
- A String
array associated, by indices, to an Object
array.objects
- An Object
array associated, by indices, to a String
array.name
- A unique name for this data set. Used, for example, by
AutoCompleteField
which displays it to the
user when LIST_SHOW_DATA_SET_NAME
is specified in the AutoCompleteField
constructor.
IllegalArgumentException
- if strings
and objects
arrays are not the same size.public void addDataSet(int id, String[] strings, Object[] objects, String name, long style)
If you specify an id
already assigned to an existing data
set, the data you specify will be added to the existing data set. Otherwise, a new data set will be created.
This method spawns its own thread and calls reset() if a CollectionListener was added via addCollectionListener(), allowing
the BasicFilteredList to be used while data is still being added. The AutoCompleteField automatically does this.
Note that only a single instance of a type of data object can occur across all of the data sets and data sources.
Also not that the maximum number of objects from all data sets and data sources is 65535. Attempting to add more
objects will not throw an exception but will have no effect.
id
- A unique ID for this data set.strings
- A String
array associated, by indices, to an Object
array.objects
- An Object
array associated, by indices, to a String
array.name
- A unique name for this data set. Used, for example, by
AutoCompleteField
which displays it to the
user when LIST_SHOW_DATA_SET_NAME
is specified in the AutoCompleteField
constructor.style
- The search style. Supported styles are:
COMPARISON_IGNORE_CASE
IllegalArgumentException
- if strings
and objects
arrays are not the same size.public void addDataSource(int id, int type, long searchFields, long requestedFields, long primaryField, long secondaryField, String name)
id
- A unique ID for this data source.type
- The data source type to match the search string against. Can be one of:
DATA_SOURCE_CONTACTS |
DATA_SOURCE_MEMOS |
DATA_SOURCE_MUSIC |
DATA_SOURCE_PICTURES |
DATA_SOURCE_RINGTONES |
DATA_SOURCE_TASKS |
DATA_SOURCE_VIDEOS |
DATA_SOURCE_VOICENOTES |
searchFields
- The fields of the data source to match against. It must be compatible with the dataSource.
Note that more search fields results in a slower search. The supported fields are:
Contacts |
---|
DATA_FIELD_CONTACTS_ALL |
DATA_FIELD_CONTACTS_ADDRESS_ALL |
DATA_FIELD_CONTACTS_ADDRESS_HOME |
DATA_FIELD_CONTACTS_ADDRESS_WORK |
DATA_FIELD_CONTACTS_ANNIVERSARY |
DATA_FIELD_CONTACTS_BIRTHDAY |
DATA_FIELD_CONTACTS_CATEGORIES |
DATA_FIELD_CONTACTS_COMPANY |
DATA_FIELD_CONTACTS_EMAIL |
DATA_FIELD_CONTACTS_FAX |
DATA_FIELD_CONTACTS_FAX2 |
DATA_FIELD_CONTACTS_JOB_TITLE |
DATA_FIELD_CONTACTS_NAME_FULL |
DATA_FIELD_CONTACTS_NAME_FIRST |
DATA_FIELD_CONTACTS_NAME_LAST |
DATA_FIELD_CONTACTS_NOTES |
DATA_FIELD_CONTACTS_PAGER |
DATA_FIELD_CONTACTS_PHONE_ALL |
DATA_FIELD_CONTACTS_PHONE_HOME |
DATA_FIELD_CONTACTS_PHONE_HOME2 |
DATA_FIELD_CONTACTS_PHONE_MOBILE |
DATA_FIELD_CONTACTS_PHONE_MOBILE2 |
DATA_FIELD_CONTACTS_PHONE_OTHER |
DATA_FIELD_CONTACTS_PHONE_WORK |
DATA_FIELD_CONTACTS_PHONE_WORK2 |
DATA_FIELD_CONTACTS_PIN |
Memos |
---|
DATA_FIELD_MEMOS_TITLE |
Music |
---|
DATA_FIELD_MUSIC_ALL |
DATA_FIELD_MUSIC_ALBUM |
DATA_FIELD_MUSIC_ARTIST |
DATA_FIELD_MUSIC_GENRE |
DATA_FIELD_MUSIC_PLAYLIST |
DATA_FIELD_MUSIC_SONG |
Pictures |
---|
DATA_FIELD_PICTURES_TITLE |
Ringtones |
---|
DATA_FIELD_RINGTONES_TITLE |
Tasks |
---|
DATA_FIELD_TASKS_TITLE |
Videos |
---|
DATA_FIELD_VIDEOS_TITLE |
Voice Notes |
---|
DATA_FIELD_VOICENOTES_TITLE |
requestedFields
- The data source fields to return when a match is found. The specified fields must be
compatible with the data source.primaryField
- Field to set as the primary field. Usually specified to mark this field for display purposes. For example, the
AutoCompleteField
class makes use of this. It must be one of the requested fields.secondaryField
- Field to set as the secondary field. Usually specified to mark this field for display purposes. For example, the
AutoCompleteField
class makes use of this. It must be one of the requested fields.name
- A unique name for this data set. Used, for example, by
AutoCompleteField
which displays it to the
user when LIST_SHOW_DATA_SET_NAME
is specified in the AutoCompleteField
constructor. If you do not specify a name for the data source, a
default name is set.public void addDataSource(int id, int type, long searchFields, long requestedFields, long primaryField, long secondaryField, String name, long style)
id
- A unique ID for this data source.type
- The data source type to match the search string against. Can be one of:
DATA_SOURCE_CONTACTS |
DATA_SOURCE_MEMOS |
DATA_SOURCE_MUSIC |
DATA_SOURCE_PICTURES |
DATA_SOURCE_RINGTONES |
DATA_SOURCE_TASKS |
DATA_SOURCE_VIDEOS |
DATA_SOURCE_VOICENOTES |
searchFields
- The fields of the data source to match against. It must be compatible with the dataSource.
Note that more search fields results in a slower search. The supported fields are:
Contacts |
---|
DATA_FIELD_CONTACTS_ALL |
DATA_FIELD_CONTACTS_ADDRESS_ALL |
DATA_FIELD_CONTACTS_ADDRESS_HOME |
DATA_FIELD_CONTACTS_ADDRESS_WORK |
DATA_FIELD_CONTACTS_ANNIVERSARY |
DATA_FIELD_CONTACTS_BIRTHDAY |
DATA_FIELD_CONTACTS_CATEGORIES |
DATA_FIELD_CONTACTS_COMPANY |
DATA_FIELD_CONTACTS_EMAIL |
DATA_FIELD_CONTACTS_FAX |
DATA_FIELD_CONTACTS_FAX2 |
DATA_FIELD_CONTACTS_JOB_TITLE |
DATA_FIELD_CONTACTS_NAME_FULL |
DATA_FIELD_CONTACTS_NAME_FIRST |
DATA_FIELD_CONTACTS_NAME_LAST |
DATA_FIELD_CONTACTS_NOTES |
DATA_FIELD_CONTACTS_PAGER |
DATA_FIELD_CONTACTS_PHONE_ALL |
DATA_FIELD_CONTACTS_PHONE_HOME |
DATA_FIELD_CONTACTS_PHONE_HOME2 |
DATA_FIELD_CONTACTS_PHONE_MOBILE |
DATA_FIELD_CONTACTS_PHONE_MOBILE2 |
DATA_FIELD_CONTACTS_PHONE_OTHER |
DATA_FIELD_CONTACTS_PHONE_WORK |
DATA_FIELD_CONTACTS_PHONE_WORK2 |
DATA_FIELD_CONTACTS_PIN |
Memos |
---|
DATA_FIELD_MEMOS_TITLE |
Music |
---|
DATA_FIELD_MUSIC_ALL |
DATA_FIELD_MUSIC_ALBUM |
DATA_FIELD_MUSIC_ARTIST |
DATA_FIELD_MUSIC_GENRE |
DATA_FIELD_MUSIC_PLAYLIST |
DATA_FIELD_MUSIC_SONG |
Pictures |
---|
DATA_FIELD_PICTURES_TITLE |
Ringtones |
---|
DATA_FIELD_RINGTONES_TITLE |
Tasks |
---|
DATA_FIELD_TASKS_TITLE |
Videos |
---|
DATA_FIELD_VIDEOS_TITLE |
Voice Notes |
---|
DATA_FIELD_VOICENOTES_TITLE |
requestedFields
- The data source fields to return when a match is found. The specified fields must be
compatible with the data source.primaryField
- Field to set as the primary field. Usually specified to mark this field for display purposes. For example, the
AutoCompleteField
class makes use of this. It must be one of the requested fields.secondaryField
- Field to set as the secondary field. Usually specified to mark this field for display purposes. For example, the
AutoCompleteField
class makes use of this. It must be one of the requested fields.name
- A unique name for this data set. Used, for example, by
AutoCompleteField
which displays it to the
user when LIST_SHOW_DATA_SET_NAME
is specified in the AutoCompleteField
constructor. If you do not specify a name for the data source, a
default name is set.style
- The search style. Supported styles are:
COMPARISON_IGNORE_CASEpublic void removeDataSet(int id)
id
- The unique ID of the data set.public void removeDataSource(int id)
id
- The unique ID of the data source.public boolean removeValue(Object value)
value
- The data object to be removed from the searchable data.
public void setCriteria(Object criteria, FilterStatusListener listener)
setCriteria
in interface FilteredList
criteria
- Criteria to compare data objects against. This
criteria must be a String, String[] or String[][] instance. The different formats are supported for convenience.
The string arrays are flattened before the comparison.
An empty string generates no search results.
A value of null generates all search results (the entire collection).listener
- Listener to be notified when the filtering is complete.public Object getCriteria()
getCriteria
in interface FilteredList
null
, String
, String[]
,
or String[][]
. If preProcessCriteria() is implemented, getCriteria() will return its result.public void waitForComplete()
This method blocks until all the filtering tasks have completed.
waitForComplete
in interface FilteredList
public String[] getFields(BasicFilteredListResult result, long field)
result
- The BasicFilteredListResult object.field
- The data field whose value will be retrieved from the data object contained in the result object.public void getRequestedFields(BasicFilteredListResult result)
BasicFilteredListResult
object.
When you use getAt()
to return BasicFilteredListResult
objects, the requested fields and
matched fields are not populated. Use this method to populate the requested fields.
result
- The BasicFilteredListResult object whose _requestedFieldNames and _requestedFieldValues
will be filled in using the fields specified in _requestedFields.public void getMatchedFields(BasicFilteredListResult result)
BasicFilteredListResult
object.
When you use getAt()
to return BasicFilteredListResult
objects, the requested fields and
matched fields are not populated. Use this method to populate the matched fields.
result
- The BasicFilteredListResult object whose _matchedFields,
_matchedFieldNames and _matchedFieldValues will be filled in.public String[] getMatchedKeywords(BasicFilteredListResult result)
result
- The BasicFilteredListResult object.
public boolean preProcessData(BasicFilteredListResult result)
BasicFilteredList
, you can override this method to process data objects
in some way before they are set. Incoming data objects are wrapped in a
BasicFilteredListResult
to provide as much information as possible to make decisions.
result
- A BasicFilteredListResult object.
public String[] preProcessStrings(BasicFilteredListResult result, String[] searchStrings)
BasicFilteredList
, you can override this method to process data fields
in some way before they are set. The associated data objects are wrapped in a
BasicFilteredListResult
to provide as much information as possible to make decisions.
Note that this method only gets called if preProcessData() did not return false for this result object.
searchStrings
- An array of strings to be added to the searchable data.result
- The associated BasicFilteredListResult object.
public Object preProcessCriteria(Object criteria)
setCriteria()
method calls
this method. If you extend BasicFilteredList
, you can override this method to process the criteria in some way
before it is used to filter the list.
criteria
- The search criteria.
public void haltSearch()
public void reset()
reset
in interface FilteredList
public boolean isFilteringInProgress()
public boolean isLoadingInProgress()
public Object getLock()
getLock
in interface FilteredList
public void addCollectionListener(Object listener)
addCollectionListener
in interface CollectionEventSource
listener
- Object to register as a listener (must implement
CollectionListener
or be a
WeakReference
to a CollectionListener
).public void removeCollectionListener(Object listener)
removeCollectionListener
in interface CollectionEventSource
listener
- Object to register as a listener (must implement
CollectionListener
or be a
WeakReference
to a CollectionListener
).public int size()
size
in interface ReadableList
public Object getAt(int index)
getAt
in interface ReadableList
index
- Index of the element to retrieve.
BasicFilteredListResult
object.
ArrayIndexOutOfBoundsException
- If index parameter is not valid.public int getAt(int index, int count, Object[] elements, int destIndex)
getAt
in interface ReadableList
index
- Index of first element to retrieve.count
- Number of elements to retrieve.elements
- Object array to contain returned elements. Must
have enough space to hold the number of elements you requested.destIndex
- Index within destination array to contain the first
element retrieved (the destination array must therefore be at least
destIndex + count
elements long).
ArrayIndexOutOfBoundsException
- If index parameter is not valid.public int getIndex(Object element)
Note: this operation may be linear with respect to the number of elements in the list.
getIndex
in interface ReadableList
element
- Element of filtered list to locate.
public void fillResultForValue(BasicFilteredListResult result, Object value)
BasicFilteredListResult
object which provides
access to its dataset name as well as its fields, if it is a data source.
Commonly used in a comparator specified with setComparator()
when the
comparator requires the extra information available in a BasicFilteredListResult
.
value
- A data object from one of the data sets or data sources.public int getIDForValue(Object value)
setComparator
when the
ID is needed by the comparator.
value
- A data object from one of the data sets or data sources.
public int getOrderForValue(Object value)
value
- A data object within the tree.
public boolean firstWordMatched(Object value)
setComparator(Comparator)
.
It indicates if the search string specified as criteria matched the first word in the data of a matched data
object. The data associated with any data object is in string format when it is compared with the criteria. If you
treat the string like a sentence, this method indicates whether the criteria matched the first word of that sentence.
value
- A matching data object from one of the data sets or data sources.
public void setMinimumRefreshInterval(long interval)
interval
- The refresh interval, in milliseconds. Must be between 250ms and 30,000ms. If you attempt to set this lower then 250ms, it
will default to 250ms. If you attempt to set this higher than 30,000ms, it will default to 30,000ms.public int getTotalSize()
|
|||||||||
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.