BasicFilteredList (BlackBerry JDE 6.0.0 API Reference)

Overview

Package

Class

Tree

Deprecated

Index

Help

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

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

java.lang.Object
  net.rim.device.api.collection.util.BasicFilteredList

All Implemented Interfaces:: Collection, CollectionEventSource, ReadableList, FilteredList

public class BasicFilteredList
extends Object
implements FilteredList
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:

an array of Strings
an array of Objects
an array of Strings and a corresponding array of Objects
a supported data source such as contacts, tasks or voice notes

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

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)

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)

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)

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)

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.

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

Overview

Package

Class

Tree

Deprecated

Index

Help

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.

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

SORT_BY_DATASET_ID

SORT_BY_PRIMARY_FIELD

SORT_BY_SECONDARY_FIELD

REFRESH_CONTINUOUSLY

REFRESH_IMMEDIATELY

REFRESH_INTERMITTENTLY

PRIORITY_MIN

PRIORITY_NORM

COMPARISON_IGNORE_CASE

DATA_SOURCE_CONTACTS

DATA_SOURCE_MEMOS

DATA_SOURCE_MUSIC

DATA_SOURCE_PICTURES

DATA_SOURCE_RINGTONES

DATA_SOURCE_TASKS

DATA_SOURCE_VIDEOS

DATA_SOURCE_VOICENOTES

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_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_OTHER

DATA_FIELD_CONTACTS_PHONE_WORK

DATA_FIELD_CONTACTS_PHONE_WORK2

DATA_FIELD_CONTACTS_PIN

DATA_FIELD_CONTACTS_FAX2

DATA_FIELD_CONTACTS_PHONE_MOBILE2

DATA_FIELD_MEMOS_TITLE

DATA_FIELD_MUSIC_ALL

DATA_FIELD_MUSIC_ALBUM

DATA_FIELD_MUSIC_ARTIST

DATA_FIELD_MUSIC_GENRE

DATA_FIELD_MUSIC_SONG

DATA_FIELD_PICTURES_TITLE

DATA_FIELD_RINGTONES_TITLE

DATA_FIELD_TASKS_TITLE

DATA_FIELD_VIDEOS_TITLE

DATA_FIELD_VOICENOTES_TITLE

BasicFilteredList

BasicFilteredList

BasicFilteredList

getStyle

setComparator

clear

addDataSet

addDataSet

addDataSet

addDataSet

addDataSet

addDataSet

addDataSource

addDataSource

removeDataSet

removeDataSource

removeValue

setCriteria

getCriteria

waitForComplete

getFields

getRequestedFields

getMatchedFields

getMatchedKeywords

preProcessData

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