net.rim.device.api.collection.util
Class BasicFilteredList

java.lang.Object
  extended by net.rim.device.api.collection.util.BasicFilteredList
All Implemented Interfaces:
Collection, CollectionEventSource, ReadableList, FilteredList

public class BasicFilteredList
extends Object
implements FilteredList

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:

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.

Since:
BlackBerry API 5.0.0

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

SORT_BY_DATASET_ID

public static final long SORT_BY_DATASET_ID
Sort results by the dataset or datasource ID.

See Also:
Constant Field Values
Since:
BlackBerry API 6.0.0

SORT_BY_PRIMARY_FIELD

public static final long SORT_BY_PRIMARY_FIELD
Sort results alphabetically by the primary field.

See Also:
Constant Field Values
Since:
BlackBerry API 6.0.0

SORT_BY_SECONDARY_FIELD

public static final long SORT_BY_SECONDARY_FIELD
Sort results alphabetically by the secondary field.

See Also:
Constant Field Values
Since:
BlackBerry API 6.0.0

REFRESH_CONTINUOUSLY

public static final 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. This is useful when displaying values that continually change over time.

See Also:
Constant Field Values
Since:
BlackBerry API 6.0.0

REFRESH_IMMEDIATELY

public static final long 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.

See Also:
Constant Field Values
Since:
BlackBerry API 6.0.0

REFRESH_INTERMITTENTLY

public static final long REFRESH_INTERMITTENTLY
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. This is the default refresh style.

See Also:
Constant Field Values
Since:
BlackBerry API 6.0.0

PRIORITY_MIN

public static final long PRIORITY_MIN
Builds and updates the filtered list in a minimum-priority thread. Useful for very large datasets so as to not stall any UI. This is the default.

See Also:
Constant Field Values
Since:
BlackBerry API 6.0.0

PRIORITY_NORM

public static final long PRIORITY_NORM
Builds and updates the filtered list in a normal-priority thread. Useful for medium-sized datasets.

See Also:
Constant Field Values
Since:
BlackBerry API 6.0.0

COMPARISON_IGNORE_CASE

public static final long COMPARISON_IGNORE_CASE
Ignore case when comparing a data object's associated string with the search string.

See Also:
Constant Field Values
Since:
BlackBerry API 5.0.0

DATA_SOURCE_CONTACTS

public static final int DATA_SOURCE_CONTACTS
Use contacts as the data source. A BlackBerryContact object will be stored in the BasicFilteredResult object.

See Also:
Constant Field Values
Since:
BlackBerry API 5.0.0

DATA_SOURCE_MEMOS

public static final int DATA_SOURCE_MEMOS
Use memos as the data source. A BlackBerryMemo object will be stored in the BasicFilteredResult object.

See Also:
Constant Field Values
Since:
BlackBerry API 5.0.0

DATA_SOURCE_MUSIC

public static final int DATA_SOURCE_MUSIC
Use music as the data source. A URL will be stored in the BasicFilteredResult object.

See Also:
Constant Field Values
Since:
BlackBerry API 5.0.0

DATA_SOURCE_PICTURES

public static final int DATA_SOURCE_PICTURES
Use pictures as the data source. A URL will be stored in the BasicFilteredResult object.

See Also:
Constant Field Values
Since:
BlackBerry API 5.0.0

DATA_SOURCE_RINGTONES

public static final int DATA_SOURCE_RINGTONES
Use ring tones as the data source. A URL will be stored in the BasicFilteredResult object.

See Also:
Constant Field Values
Since:
BlackBerry API 5.0.0

DATA_SOURCE_TASKS

public static final int DATA_SOURCE_TASKS
Use tasks as the data source. A BlackBerryToDo object will be stored in the BasicFilteredResult object.

See Also:
Constant Field Values
Since:
BlackBerry API 5.0.0

DATA_SOURCE_VIDEOS

public static final int DATA_SOURCE_VIDEOS
Use videos as the data source. A URL will be stored in the BasicFilteredResult object.

See Also:
Constant Field Values
Since:
BlackBerry API 5.0.0

DATA_SOURCE_VOICENOTES

public static final int DATA_SOURCE_VOICENOTES
Use voice notes as the data source. A URL will be stored in the BasicFilteredResult object.

See Also:
Constant Field Values
Since:
BlackBerry API 5.0.0

DATA_FIELD_CONTACTS_ALL

public static final long DATA_FIELD_CONTACTS_ALL
All fields of DATA_SOURCE_CONTACTS.

See Also:
Constant Field Values
Since:
BlackBerry API 5.0.0

DATA_FIELD_CONTACTS_ADDRESS_ALL

public static final long DATA_FIELD_CONTACTS_ADDRESS_ALL
All address fields of DATA_SOURCE_CONTACTS.

See Also:
Constant Field Values
Since:
BlackBerry API 5.0.0

DATA_FIELD_CONTACTS_ADDRESS_HOME

public static final long DATA_FIELD_CONTACTS_ADDRESS_HOME
The home address field of DATA_SOURCE_CONTACTS.

See Also:
Constant Field Values
Since:
BlackBerry API 5.0.0

DATA_FIELD_CONTACTS_ADDRESS_WORK

public static final long DATA_FIELD_CONTACTS_ADDRESS_WORK
The work address field of DATA_SOURCE_CONTACTS.

See Also:
Constant Field Values
Since:
BlackBerry API 5.0.0

DATA_FIELD_CONTACTS_ANNIVERSARY

public static final long DATA_FIELD_CONTACTS_ANNIVERSARY
The anniversary field of DATA_SOURCE_CONTACTS.

See Also:
Constant Field Values
Since:
BlackBerry API 5.0.0

DATA_FIELD_CONTACTS_BIRTHDAY

public static final long DATA_FIELD_CONTACTS_BIRTHDAY
The birthday field of DATA_SOURCE_CONTACTS.

See Also:
Constant Field Values
Since:
BlackBerry API 5.0.0

DATA_FIELD_CONTACTS_CATEGORIES

public static final long DATA_FIELD_CONTACTS_CATEGORIES
The categories field of DATA_SOURCE_CONTACTS.

See Also:
Constant Field Values
Since:
BlackBerry API 5.0.0

DATA_FIELD_CONTACTS_COMPANY

public static final long DATA_FIELD_CONTACTS_COMPANY
The company field of DATA_SOURCE_CONTACTS.

See Also:
Constant Field Values
Since:
BlackBerry API 5.0.0

DATA_FIELD_CONTACTS_EMAIL

public static final long DATA_FIELD_CONTACTS_EMAIL
The email field of DATA_SOURCE_CONTACTS.

See Also:
Constant Field Values
Since:
BlackBerry API 5.0.0

DATA_FIELD_CONTACTS_FAX

public static final long DATA_FIELD_CONTACTS_FAX
The fax number field of DATA_SOURCE_CONTACTS.

See Also:
Constant Field Values
Since:
BlackBerry API 5.0.0

DATA_FIELD_CONTACTS_JOB_TITLE

public static final long DATA_FIELD_CONTACTS_JOB_TITLE
The job title field of DATA_SOURCE_CONTACTS.

See Also:
Constant Field Values
Since:
BlackBerry API 5.0.0

DATA_FIELD_CONTACTS_NAME_FULL

public static final long DATA_FIELD_CONTACTS_NAME_FULL
The full name field of DATA_SOURCE_CONTACTS.

See Also:
Constant Field Values
Since:
BlackBerry API 5.0.0

DATA_FIELD_CONTACTS_NAME_FIRST

public static final long DATA_FIELD_CONTACTS_NAME_FIRST
The first name field of DATA_SOURCE_CONTACTS.

See Also:
Constant Field Values
Since:
BlackBerry API 5.0.0

DATA_FIELD_CONTACTS_NAME_LAST

public static final long DATA_FIELD_CONTACTS_NAME_LAST
The last name field of DATA_SOURCE_CONTACTS.

See Also:
Constant Field Values
Since:
BlackBerry API 5.0.0

DATA_FIELD_CONTACTS_NOTES

public static final long DATA_FIELD_CONTACTS_NOTES
The notes field of DATA_SOURCE_CONTACTS.

See Also:
Constant Field Values
Since:
BlackBerry API 5.0.0

DATA_FIELD_CONTACTS_PAGER

public static final long DATA_FIELD_CONTACTS_PAGER
The pager number field of DATA_SOURCE_CONTACTS.

See Also:
Constant Field Values
Since:
BlackBerry API 5.0.0

DATA_FIELD_CONTACTS_PHONE_ALL

public static final long DATA_FIELD_CONTACTS_PHONE_ALL
All phone number fields of DATA_SOURCE_CONTACTS.

See Also:
Constant Field Values
Since:
BlackBerry API 5.0.0

DATA_FIELD_CONTACTS_PHONE_HOME

public static final long DATA_FIELD_CONTACTS_PHONE_HOME
The first home phone number of DATA_SOURCE_CONTACTS.

See Also:
Constant Field Values
Since:
BlackBerry API 5.0.0

DATA_FIELD_CONTACTS_PHONE_HOME2

public static final long DATA_FIELD_CONTACTS_PHONE_HOME2
The second home phone number of DATA_SOURCE_CONTACTS.

See Also:
Constant Field Values
Since:
BlackBerry API 5.0.0

DATA_FIELD_CONTACTS_PHONE_MOBILE

public static final long DATA_FIELD_CONTACTS_PHONE_MOBILE
The mobile phone number of DATA_SOURCE_CONTACTS.

See Also:
Constant Field Values
Since:
BlackBerry API 5.0.0

DATA_FIELD_CONTACTS_PHONE_OTHER

public static final long DATA_FIELD_CONTACTS_PHONE_OTHER
The other phone number of DATA_SOURCE_CONTACTS.

See Also:
Constant Field Values
Since:
BlackBerry API 5.0.0

DATA_FIELD_CONTACTS_PHONE_WORK

public static final long DATA_FIELD_CONTACTS_PHONE_WORK
The first work phone number of DATA_SOURCE_CONTACTS.

See Also:
Constant Field Values
Since:
BlackBerry API 5.0.0

DATA_FIELD_CONTACTS_PHONE_WORK2

public static final long DATA_FIELD_CONTACTS_PHONE_WORK2
The second work phone number of DATA_SOURCE_CONTACTS.

See Also:
Constant Field Values
Since:
BlackBerry API 5.0.0

DATA_FIELD_CONTACTS_PIN

public static final long DATA_FIELD_CONTACTS_PIN
The PIN field of DATA_SOURCE_CONTACTS.

See Also:
Constant Field Values
Since:
BlackBerry API 5.0.0

DATA_FIELD_CONTACTS_FAX2

public static final long DATA_FIELD_CONTACTS_FAX2
The secondary fax number field of DATA_SOURCE_CONTACTS.

See Also:
Constant Field Values
Since:
BlackBerry API 6.0.0

DATA_FIELD_CONTACTS_PHONE_MOBILE2

public static final long DATA_FIELD_CONTACTS_PHONE_MOBILE2
The secondary mobile phone number of DATA_SOURCE_CONTACTS.

See Also:
Constant Field Values
Since:
BlackBerry API 6.0.0

DATA_FIELD_MEMOS_TITLE

public static final long DATA_FIELD_MEMOS_TITLE
The title field of DATA_SOURCE_MEMOS.

See Also:
Constant Field Values
Since:
BlackBerry API 5.0.0

DATA_FIELD_MUSIC_ALL

public static final long DATA_FIELD_MUSIC_ALL
All fields of DATA_SOURCE_MUSIC.

See Also:
Constant Field Values
Since:
BlackBerry API 5.0.0

DATA_FIELD_MUSIC_ALBUM

public static final long DATA_FIELD_MUSIC_ALBUM
The album field of DATA_SOURCE_MUSIC.

See Also:
Constant Field Values
Since:
BlackBerry API 5.0.0

DATA_FIELD_MUSIC_ARTIST

public static final long DATA_FIELD_MUSIC_ARTIST
The artist field of DATA_SOURCE_MUSIC.

See Also:
Constant Field Values
Since:
BlackBerry API 5.0.0

DATA_FIELD_MUSIC_GENRE

public static final long DATA_FIELD_MUSIC_GENRE
The genre field of DATA_SOURCE_MUSIC.

See Also:
Constant Field Values
Since:
BlackBerry API 5.0.0

DATA_FIELD_MUSIC_SONG

public static final long DATA_FIELD_MUSIC_SONG
The song field of DATA_SOURCE_MUSIC.

See Also:
Constant Field Values
Since:
BlackBerry API 5.0.0

DATA_FIELD_PICTURES_TITLE

public static final long DATA_FIELD_PICTURES_TITLE
The title field of DATA_SOURCE_PICTURES.

See Also:
Constant Field Values
Since:
BlackBerry API 5.0.0

DATA_FIELD_RINGTONES_TITLE

public static final long DATA_FIELD_RINGTONES_TITLE
The title field of DATA_SOURCE_RINGTONES.

See Also:
Constant Field Values
Since:
BlackBerry API 5.0.0

DATA_FIELD_TASKS_TITLE

public static final long DATA_FIELD_TASKS_TITLE
The title field of DATA_SOURCE_TASKS.

See Also:
Constant Field Values
Since:
BlackBerry API 5.0.0

DATA_FIELD_VIDEOS_TITLE

public static final long DATA_FIELD_VIDEOS_TITLE
The title field of DATA_SOURCE_VIDEOS.

See Also:
Constant Field Values
Since:
BlackBerry API 5.0.0

DATA_FIELD_VOICENOTES_TITLE

public static final long DATA_FIELD_VOICENOTES_TITLE
The title field of DATA_SOURCE_VOICENOTES.

See Also:
Constant Field Values
Since:
BlackBerry API 5.0.0


Constructor Detail

BasicFilteredList

public BasicFilteredList()
Instantiate the class and assume the data will be set later.

Since:
BlackBerry API 5.0.0

BasicFilteredList

public BasicFilteredList(long style)
Instantiate the class with specified style and assume the data will be set later.

Parameters:
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
The refresh styles 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.

Since:
BlackBerry API 6.0.0

BasicFilteredList

public BasicFilteredList(long style,
                         Comparator comparator)
Instantiate the class with specified comparator and assume the data will be set later.

Parameters:
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.
Since:
BlackBerry API 6.0.0


Method Detail

getStyle

public final long getStyle()
Retrieves the set style bits.

Returns:
Combination of the style bits.
Since:
BlackBerry API 6.0.0

setComparator

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.

Parameters:
comparator - The Comparator used to sort the search results.
Since:
BlackBerry API 5.0.0

clear

public void clear()
Removes all datasets and datasources.

Since:
BlackBerry API 5.0.0

addDataSet

public void addDataSet(int id,
                       String[] strings,
                       String name)
Adds a list of strings to match against. If an existing data set has this ID, the data will be added to it. 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 a particular instance of a data object must only occur once in 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.

Parameters:
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.
Throws:
IllegalArgumentException - if strings is null.
Since:
BlackBerry API 5.0.0

addDataSet

public void addDataSet(int id,
                       String[] strings,
                       String name,
                       long style)
Adds a list of strings to match against. If an existing data set has this ID, the data will be added to it. 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 a particular instance of a data object must only occur once in 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.

Parameters:
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
Throws:
IllegalArgumentException - if strings is null.
Since:
BlackBerry API 5.0.0

addDataSet

public void addDataSet(int id,
                       Object[] objects,
                       String name)
Adds an array of objects to compare against. Comparisons are made against the string returned by invoking the 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.

Parameters:
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.
Throws:
IllegalArgumentException - if objects is null.
Since:
BlackBerry API 5.0.0

addDataSet

public void addDataSet(int id,
                       Object[] objects,
                       String name,
                       long style)
Adds an array of objects to compare against. Comparisons are made against the string returned by invoking the 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.

Parameters:
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
Throws:
IllegalArgumentException - if objects is null.
Since:
BlackBerry API 5.0.0

addDataSet

public 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. Comparisons are made against the strings and the result of a match is the object with the same index as the matched string.

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.

Parameters:
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.
Throws:
IllegalArgumentException - if strings and objects arrays are not the same size.
Since:
BlackBerry API 5.0.0

addDataSet

public 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. Comparisons are made against the strings and the result of a match is the object with the same index as the matched string.

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.

Parameters:
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
Throws:
IllegalArgumentException - if strings and objects arrays are not the same size.
Since:
BlackBerry API 5.0.0

addDataSource

public void addDataSource(int id,
                          int type,
                          long searchFields,
                          long requestedFields,
                          long primaryField,
                          long secondaryField,
                          String name)
Adds a supported data source to match against. 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 a particular data source type must only be added once. 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.

Parameters:
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.
Since:
BlackBerry API 5.0.0

addDataSource

public 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. 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 a particular data source type must only be added once. 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.

Parameters:
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_CASE
Since:
BlackBerry API 5.0.0

removeDataSet

public void removeDataSet(int id)
Removes the specified data set. 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 being removed. The AutoCompleteField automatically does this.

Parameters:
id - The unique ID of the data set.
Since:
BlackBerry API 5.0.0

removeDataSource

public void removeDataSource(int id)
Removes the specified data source. 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 being removed. The AutoCompleteField automatically does this.

Parameters:
id - The unique ID of the data source.
Since:
BlackBerry API 5.0.0

removeValue

public boolean removeValue(Object value)
Removes the specified data object from the searchable data. This method calls reset() if a CollectionListener was added via addCollectionListener(). The AutoCompleteField uses a listener so automatically reflects any objects that are removed.

Parameters:
value - The data object to be removed from the searchable data.
Returns:
true if the data object was found, false otherwise.
Since:
BlackBerry API 6.0.0

setCriteria

public void setCriteria(Object criteria,
                        FilterStatusListener listener)
Sets the filtering criteria for the collection and performs the filtering asynchronously.

Specified by:
setCriteria in interface FilteredList
Parameters:
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.
Since:
BlackBerry API 5.0.0

getCriteria

public Object getCriteria()
Gets the search criteria.

Specified by:
getCriteria in interface FilteredList
Returns:
The search criteria which can be one of: null, String, String[], or String[][]. If preProcessCriteria() is implemented, getCriteria() will return its result.
Since:
BlackBerry API 5.0.0

waitForComplete

public void waitForComplete()
Waits for filtering tasks to complete.

This method blocks until all the filtering tasks have completed.

Specified by:
waitForComplete in interface FilteredList
Since:
BlackBerry API 5.0.0

getFields

public String[] getFields(BasicFilteredListResult result,
                          long field)
Retrieves the values of the specified field.

Parameters:
result - The BasicFilteredListResult object.
field - The data field whose value will be retrieved from the data object contained in the result object.
Since:
BlackBerry API 6.0.0

getRequestedFields

public void getRequestedFields(BasicFilteredListResult result)
Populates the values of the requested fields in a 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.

Parameters:
result - The BasicFilteredListResult object whose _requestedFieldNames and _requestedFieldValues will be filled in using the fields specified in _requestedFields.
Since:
BlackBerry API 5.0.0

getMatchedFields

public void getMatchedFields(BasicFilteredListResult result)
Populates the values of the matched fields in a 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.

Parameters:
result - The BasicFilteredListResult object whose _matchedFields, _matchedFieldNames and _matchedFieldValues will be filled in.
Since:
BlackBerry API 5.0.0

getMatchedKeywords

public String[] getMatchedKeywords(BasicFilteredListResult result)
Gets the keywords that matched for the provided data object. This is for use with a result that came from a generic data set.

Parameters:
result - The BasicFilteredListResult object.
Returns:
The keywords that matched.
Since:
BlackBerry API 5.0.0

preProcessData

public boolean preProcessData(BasicFilteredListResult result)
Allows pre-processing of data objects so you can include or exclude specific objects from the data to be searched. If you extend 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.

Parameters:
result - A BasicFilteredListResult object.
Returns:
true if it should be added to the data to be searched, false otherwise.
Since:
BlackBerry API 5.0.0

preProcessStrings

public 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. If you extend 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.

Parameters:
searchStrings - An array of strings to be added to the searchable data.
result - The associated BasicFilteredListResult object.
Returns:
The modified array of search strings.
Since:
BlackBerry API 6.0.0

preProcessCriteria

public Object preProcessCriteria(Object criteria)
Allows pre-processing of the search criteria. The 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.

Parameters:
criteria - The search criteria.
Returns:
The modified search criteria.
Since:
BlackBerry API 5.0.0

haltSearch

public void haltSearch()
Halts the search.

Since:
BlackBerry API 5.0.0

reset

public void reset()
Start a new search with the current criteria.

Specified by:
reset in interface FilteredList
Since:
BlackBerry API 5.0.0

isFilteringInProgress

public boolean isFilteringInProgress()
Determines if there is a filtering task in progress. Filtering can still occur while data is being loaded.

Returns:
True if there is a filtering task in progress, otherwise false.
Since:
BlackBerry API 5.0.0

isLoadingInProgress

public boolean isLoadingInProgress()
Determines if the data is being loaded. Filtering can still occur while data is being loaded.

Returns:
True if there is the data is being loaded, otherwise false.
Since:
BlackBerry API 5.0.0

getLock

public Object getLock()
All synchronized operations should use this lock.

Specified by:
getLock in interface FilteredList
Returns:
lock Object
Since:
BlackBerry API 5.0.0

addCollectionListener

public void addCollectionListener(Object listener)
Registers a listener to receive collection events.

Specified by:
addCollectionListener in interface CollectionEventSource
Parameters:
listener - Object to register as a listener (must implement CollectionListener or be a WeakReference to a CollectionListener).
Since:
BlackBerry API 5.0.0

removeCollectionListener

public void removeCollectionListener(Object listener)
Removes a listener object from the list of those receiving events.

Specified by:
removeCollectionListener in interface CollectionEventSource
Parameters:
listener - Object to register as a listener (must implement CollectionListener or be a WeakReference to a CollectionListener).
Since:
BlackBerry API 5.0.0

size

public int size()
Retrieves the number of elements in this collection.

Specified by:
size in interface ReadableList
Returns:
Number of elements in the filtered list.
Since:
BlackBerry API 5.0.0

getAt

public Object getAt(int index)
Retrieves element from filtered list by index.

Specified by:
getAt in interface ReadableList
Parameters:
index - Index of the element to retrieve.
Returns:
Element at specified index in the form of a BasicFilteredListResult object.
Throws:
ArrayIndexOutOfBoundsException - If index parameter is not valid.
Since:
BlackBerry API 5.0.0

getAt

public int getAt(int index,
                 int count,
                 Object[] elements,
                 int destIndex)
Retrieves range of elements from filtered list starting at provided index.

Specified by:
getAt in interface ReadableList
Parameters:
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).
Returns:
Number of elements actually retrieved.
Throws:
ArrayIndexOutOfBoundsException - If index parameter is not valid.
Since:
BlackBerry API 5.0.0

getIndex

public int getIndex(Object element)
Retrieves index of element in filtered list by element.

Note: this operation may be linear with respect to the number of elements in the list.

Specified by:
getIndex in interface ReadableList
Parameters:
element - Element of filtered list to locate.
Returns:
Index of specified element, or -1 if the element isn't contained in the filtered list.
Since:
BlackBerry API 5.0.0

fillResultForValue

public 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. Commonly used in a comparator specified with setComparator() when the comparator requires the extra information available in a BasicFilteredListResult.

Parameters:
value - A data object from one of the data sets or data sources.
Since:
BlackBerry API 5.0.0

getIDForValue

public int getIDForValue(Object value)
Returns the ID of the data set or data source of the data object. Commonly used in a comparator specified with setComparator when the ID is needed by the comparator.

Parameters:
value - A data object from one of the data sets or data sources.
Returns:
The ID of the data set or data source. -1 if not found.
Since:
BlackBerry API 5.0.0

getOrderForValue

public int getOrderForValue(Object value)
Returns the order (or position) in which the specified data object was added. Commonly used in a comparator specified with setComparator().

Parameters:
value - A data object within the tree.
Returns:
The order (or position) of the data object. -1 if not found.
Since:
BlackBerry API 6.0.0

firstWordMatched

public boolean firstWordMatched(Object value)
This method works only if you specify a custom comparator by using 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.

Parameters:
value - A matching data object from one of the data sets or data sources.
Returns:
true if the first word of the data object's phrase matched the search string, false otherwise.
Since:
BlackBerry API 5.0.0

setMinimumRefreshInterval

public void setMinimumRefreshInterval(long interval)
Sets the minimimum refresh interval. On each refresh, all listeners are informed of any changes to the data collection and a new search is started. The default is 1000 milliseconds. When the search criteria changes, a new search is started immediately and the results are refreshed. When the search criteria does not change but the data is still loading, this specified interval controls how often the results will be automatically updated.

Parameters:
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.
Since:
BlackBerry API 5.0.0

getTotalSize

public int getTotalSize()
Gets the total size of the list before any filtering.

Returns:
The size of the unfiltered list.
Since:
BlackBerry API 5.0.0





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.