Search
Users can use the search field on the Home screen to search for items in any application on the device, including third-party applications. The search can also include content that is not stored on the device, such as an organization's database or a website.

Users can also use a search field in an application to search for items in that application. For example, users can search for an email message in a message list, a song in the Media application, or a contact in the contact list. In some cases, you might want to display search results from other applications.
In some applications, the search field appears on the screen. In other cases, search is available from the full menu, the pop-up menu, or the toolbar. As users type text in a search field, display the search results. If a large number of search results is returned, you can allow users to narrow their search to a field or a group of fields. For example, if users search the message list, they can use the drop-down list to the right of the search field to narrow their search to the To field or the Subject field. For more information about adding a search field to your application, see the BlackBerry Java Application Integration Development Guide.

Users can perform the following actions in a search field:
Action |
BlackBerry devices with a trackpad only |
BlackBerry devices with a touch screen and a trackpad |
---|---|---|
Open a highlighted item in the search results. |
|
|
Display a pop-up menu with actions for a search result (for example, call a contact) |
Click and hold the trackpad. |
|
You can register content in your application so that it can be included in search results. You can also register your application as a way for users to extend a search. For example, if users search for a song in the Media application and do not find the song, you can allow users to search your application as an alternative source of search results. For more information about registering content or an application, see the BlackBerry Java Application Integration Development Guide.
Best practice: Implementing search
- Use the net.rim.device.api.unifiedsearch package to implement search capabilities.
- Be selective with the content that you register to be included in search results. Only register content that provides meaningful search results for users.
- Try to present the most relevant items at the beginning of the list of search results. For example, if users are looking for a restaurant that has several different locations, display the restaurant that is closest to the user's location at the beginning of the list of search results.
- In the search results, bold the text that matches the text that users type. This approach helps users see why each item appears in the list of search results.
- If users need to search for a word on a screen (for example, in a message or on a web page), use the term "Find" in the Menu.
Implementing search fields
- Set the default focus to the search field. When the search results appear, set the default focus to the first item in the list of search results.
- Use the term "Search" as hint text in the search field.
- Do not make search fields case sensitive.
- Place the search field below the title bar on an application screen.
- Do not assign shortcut keys for a screen that includes a search field. If you want to use shortcut keys, provide alternative search functionality. For example, allow users to search for messages in a message list using the menu.
Create a search field
You can create an application that uses the KeywordFilterField class, included in the net.rim.device.api.ui.component package, to provide a UI field that consists of a single text input field and a list of selectable elements. As users type text in a search field, the application filters the elements in the list that begin with the search text. For more information about using the KeywordFilterField class, see the Keyword Filter Field sample application, included with the BlackBerry Java Development Environment version 4.3.1 or later.
- Import the required classes and interfaces.
import net.rim.device.api.collection.util.SortedReadableList; import net.rim.device.api.io.LineReader; import net.rim.device.api.ui.component.KeywordFilterField; import net.rim.device.api.ui.component.KeywordProvider; import java.io.InputStream; import java.lang.String; import java.util.Vector;
- Create variables. In the following code sample,
CountryList extends the
SortedReadableList class and implements the
KeywordProvider interface.
private KeywordFilterField _keywordField; private CountryList _CountryList; private Vector _countries;
- To create a list of selectable text items, populate a vector with
data from a text file.
_countries = getDataFromFile();
- Create an instance of a class that extends the
SortedReadableList class.
_CountryList = new CountryList(StringComparator.getInstance(true),_countries);
- To specify the elements of the list, create a new instance of a
KeywordFilterField object.
_keywordField = new KeywordFilterField();
- Invoke
KeywordFilterField.setList().
_keywordField.setList(_CountryList, _CountryList);
- Set a label for the input field of the
KeywordFilterFIeld.
_keywordField.setLabel("Search: ");
- Create the main screen of the application and add a
KeywordFilterField to the main screen.
KeywordFilterDemoScreen screen = new KeywordFilterDemoScreen(this,_keywordField); screen.add(_keywordField.getKeywordField()); screen.add(_keywordField); pushScreen(screen);
- To create a method that populates and returns a vector of
Country objects containing data from text file, in
the method signature, specify
Vector as the return type.
public Vector getDataFromFile()
- Create and store a reference to a new
Vector object.
Vector countries = new Vector();
- Create an input stream to the text file.
InputStream stream = getClass().getResourceAsStream("/Data/CountryData.txt");
- Read CRLF delimited lines from the input stream.
LineReader lineReader = new LineReader(stream);
- Read data from the input stream one line at a time until you reach
the end of file flag. Each line is parsed to extract data that is used to
construct
Country objects.
for(;;){ //Obtain a line of text from the text file. String line = new String(lineReader.readLine()); //If we are not at the end of the file, parse the line of text. if(!line.equals("EOF")) { int space1 = line.indexOf(" "); String country = line.substring(0,space1); int space2 = line.indexOf(" ",space1+1); String population = line.substring(space1+1,space2); String capital = line.substring(space2+1,line.length()); // Create a new Country object. countries.addElement(new Country(country,population,capital)); } else { break; } } // End the "for" loop. return countries;
- To add a keyword to the list of selectable text items, invoke
SortedReadableList.doAdd(element).
SortedReadableList.doAdd(((Country)countries.elementAt(i)).getCountryName()) ;
- To update the list of selectable text items, invoke
KeywordFilterField.updateList().
_keywordField.updateList();
- To obtain the keyword that a
BlackBerry device user typed into the
KeywordFilterField, invoke
KeywordFilterField.getKeyword().
String userTypedWord = _keywordField.getKeyword();
Autocomplete text field
You can use an autocomplete text field to predict what a BlackBerry device user wants to type, and display a word or phrase before the user types it completely.
When you create an AutoCompleteField object, you must associate a BasicFilteredList object with it. The BasicFilteredList maintains references to data objects that are compared with to produce the list of words and phrases. You can configure which fields in the data objects are compared with and which fields are displayed when a match is found. For example, you can compare the text that the user types with the value of the DATA_FIELD_CONTACTS_BIRTHDAY field in the DATA_SOURCE_CONTACTS data source, and return the value of the corresponding DATA_FIELD_CONTACTS_NAME_FULL field.
There are four types of data that you can bind to a BasicFilteredList to use with an AutoCompleteField.
You can specify the set of strings to compare with in one of the following ways:
- an array of literal strings
- an array of objects that support toString()
- data sources on a BlackBerry device, such as contacts, memos, tasks, and various types of media files
- an array of objects and an array of strings with corresponding indexes
By default, the autocomplete text field displays the set of strings that is returned by the comparison process in a drop-down list. You can configure the appearance of this list by specifying style flags when you create the autocomplete text field. You can change how the list appears and how users can interact with the list.
Create an autocomplete text field from a data set
- Import the required classes and interfaces.
import net.rim.device.api.ui.UiApplication; import net.rim.device.api.ui.container.MainScreen; import net.rim.device.api.ui.component.AutoCompleteField; import net.rim.device.api.collection.util.*;
- Create the application framework by extending the
UiApplication class. In
main(), create an instance of the new class and
invoke
enterEventDispatcher() to enable the application to
receive events. In the constructor, invoke
pushScreen() to display the custom screen for the
application. The
HomeScreen class, described in step 3, represents
the custom screen.
public class AutoCompleteFieldApp extends UiApplication { public static void main(String[] args) { AutoCompleteFieldApp app = new AutoCompleteFieldApp(); app.enterEventDispatcher(); } AutoCompleteFieldApp() { pushScreen(new HomeScreen()); } }
- Create the custom screen by extending the
MainScreen class.
class HomeScreen extends MainScreen { public HomeScreen() { } }
- In the constructor, create a
BasicFilteredList object. Create a
String array and store the strings that you want to
match against in the array. In this example, the strings are days of the week.
Invoke
addDataSet() to bind the data in the array to the
BasicFilteredList.
BasicFilteredList filterList = new BasicFilteredList(); String[] days = {"Monday","Tuesday","Wednesday","Thursday","Friday","Saturday","Sunday"}; filterList.addDataSet(1,days,"days",BasicFilteredList.COMPARISON_IGNORE_CASE);
- In the constructor, create an
AutoCompleteField object. Pass an instance of the
BasicFilteredList to the
AutoCompleteField constructor to bind the
BasicFilteredList to the autocomplete text field.
Invoke
add() to add the field to the screen.
AutoCompleteField autoCompleteField = new AutoCompleteField(filterList); add(autoCompleteField);
Create an autocomplete text field from a data source
- Import the required classes and interfaces.
import net.rim.device.api.ui.UiApplication; import net.rim.device.api.ui.container.MainScreen; import net.rim.device.api.ui.component.AutoCompleteField; import net.rim.device.api.collection.util.*;
- Create the application framework by extending the
UiApplication class. In
main(), create an instance of the new class and
invoke
enterEventDispatcher() to enable the application to
receive events. In the application constructor, invoke
pushScreen() to display the custom screen for the
application. The
HomeScreen class represents the custom screen that
is described in step 3.
public class AutoCompleteFieldApp extends UiApplication { public static void main(String[] args) { AutoCompleteFieldApp app = new AutoCompleteFieldApp(); app.enterEventDispatcher(); } public AutoCompleteFieldApp() { pushScreen(new HomeScreen()); } }
- Create the custom screen for the application by extending the
MainScreen class.
class HomeScreen extends MainScreen { public HomeScreen() { } }
- In the screen constructor, create a
BasicFilteredList object. Invoke
addDataSource() to bind a data source to the
BasicFilteredList. In this example, the data is
contact information and the data source is the contact list. The first argument
that you pass to
addDataSource() is a unique ID. The second argument
binds the
BasicFilteredList object to a data source. The third
argument specifies the set of data source fields to compare with. The fourth
argument specifies the set of data source fields to make available when a match
is found. In this example, the fields to compare with are the same as the
fields to make available when a match is found. The fifth argument specifies
the primary display field. The sixth argument specifies the secondary display
field and is set to -1 if you do not want to use it. The final argument
specifies a name for the
BasicFilteredList; its value is generated
automatically if you specify
null.
BasicFilteredList filterList = new BasicFilteredList(); filterList.addDataSource( 1, BasicFilteredList.DATA_SOURCE_CONTACTS, BasicFilteredList.DATA_FIELD_CONTACTS_NAME_FULL | BasicFilteredList.DATA_FIELD_CONTACTS_COMPANY | BasicFilteredList.DATA_FIELD_CONTACTS_EMAIL, BasicFilteredList.DATA_FIELD_CONTACTS_NAME_FULL | BasicFilteredList.DATA_FIELD_CONTACTS_COMPANY | BasicFilteredList.DATA_FIELD_CONTACTS_EMAIL, BasicFilteredList.DATA_FIELD_CONTACTS_NAME_FULL, -1, null);
- In the screen constructor, create an
AutoCompleteField object. Pass the
BasicFilteredList object that you created in step 4
to the
AutoCompleteField constructor to bind the
BasicFilteredList to the autocomplete text field.
Invoke
add() to add the field to the screen.
AutoCompleteField autoCompleteField = new AutoCompleteField(filterList); add(autoCompleteField);
Using data sources and fields with an autocomplete text field
You can use the AutoCompleteField class and the BasicFilteredList class to compare the text that a user types in an autocomplete text field with the values of fields in a specified data source. You specify the fields to use and their data sources by using a BasicFilteredList object that you pass as an argument to the constructor of the AutoCompleteField class.
Data source |
Fields |
---|---|
DATA_SOURCE_APPOINTMENTS |
|
DATA_SOURCE_CONTACTS |
|
DATA_SOURCE_MEMOS |
|
DATA_SOURCE_MESSAGES |
|
DATA_SOURCE_MUSIC |
|
DATA_SOURCE_PICTURES |
|
DATA_SOURCE_RINGTONES |
|
DATA_SOURCE_TASKS |
|
DATA_SOURCE_VIDEOS |
|
DATA_SOURCE_VOICENOTES |
|