SearchBar

The SearchBar component can be used to provide a filter-as-you-type functionality. Assuming that a List of text items has been defined, the SearchBar can be used to match the text being typed to one of the text items in the List. The developer can then choose to initialise a new List consisting of the matched text items, remove the old List and add the new one to the Form.

There are two text matching mechanisms, a default and a custom. The default text matching can be used as an out-of-the-box solution that returns a FilterListModel. The FilterListModel is the data structure that contains the matched text items. This mechanism returns all the text items that match the typed text at any index, i.e. the text items that start, contain or end with the typed text. The default matching rule is case-insensitive. For example if we had a List with the following text items:

  • Charlie

  • Michael

the text “Ch” would match both items.

The custom matching mechanism returns only the text that is being typed on a given SearchBar. It is the developer’s responsibility to define matching rules and eventually populate a custom data structure that would contain the matched items according to a custom defined rule.

The main difference between the default and the custom matching mechanism is that the former returns a populated data structure while the latter requires that the data structure is constructed from scratch. In both cases, the developer needs to initialise a LWUIT List, if necessary apply a ListRenderer to it, remove the old List from the screen and append the new one.

The SearchBar by default can be scrolled away along with the List items. Optionally the developer can enforce the SearchBar always on the top of the Form. The SearchBar contains a hint that is displayed when there is no text typed. The hint text is the first argument in the SearchBar’s constructor. Developers can also use or override the default SearchBar icon in the constructor.

This is how a SearchBar can be initialised:

SearchBar(java.lang.String hint, Image img, String[] itemList, boolean useDefaultMatching);

Figure 1. SearchBar with the default search icon, default matching mechanism and a hint text

In order to use the default SearchBar icon, the second argument in the constructor should be set to null. The following snippet instantiates a SearchBar with the default SearchBar icon and the default matching mechanism, provided that an array of Strings, itemList, containing all text items is already defined:

Display.init(this);
form = new Form("Search bar");

searchBar = new SearchBar("Search", null, itemList, true);
allContacts = new List(itemList);


form.addComponent(searchBar);
form.addComponent(allContacts);
form.show();

searchBar.setActionListener(new SearchBarListener() {
    public void notifyFilterSearchDataListener(FilterListModel flm) {
        if (allContacts.size() > 0) {
            form.removeComponent(allContacts);
            allContacts = new List(flm);
            form.addComponent(allContacts);
            form.revalidate();
        }
    }

    public void notifySearchBarListener(SearchBar sb, String string) {
        // custom matching mechanism to be implemented
    }

});

The above code will construct a scrollable SearchBar. If we want the SearchBar to remain always on top, we need to add the following line to our code:

form.setScrollableY(false);
Note:

The search icon changes to a delete-all icon, when at least one character is typed into the SearchBar. However, it is only the search icon that can be customised.

If we need to override the default matching mechanism, we need to implement the notifySearchBarListener method and change the SearchBar constructor so that the forth boolean argument is set to false. The following snippet demonstrates how we can implement a SearchBar with a custom search icon and a custom matching mechanism, that displays only the text items that begin with the text typed in the search field (case-sensitive):

Display.init(this);
form = new Form("Search bar");

Image image = null;
try {
    image = Image.createImage("/categorybar_sync_m_light.png");
} catch (IOException ex) {
    ex.printStackTrace();
}

searchBar = new SearchBar("Search", image, itemList, false);
allContacts = new List(itemList);
form.setScrollableY(false);

form.addComponent(searchBar);
form.addComponent(allContacts);
form.show();

searchBar.setActionListener(new SearchBarListener() {
    public void notifyFilterSearchDataListener(FilterListModel flm) {
        // default matching mehanism, to be implemented
    }

    public void notifySearchBarListener(SearchBar sb, String string) {
        if (!string.equals("")) {
            Vector matches = new Vector();

            // fills up the vector with the matched Strings
            for (int i = 0; i < itemList.length; i++) {
                if (itemList[i].indexOf(string) == 0) {
                    matches.addElement(itemList[i]);
                }
            }

            // if at least one match is found
            if (matches.size() > 0) {
                // converts the vector to array of Strings
                String[] matchedStrings = new String[matches.size()];
                for (int i = 0; i < matchedStrings.length; i++) {
                    matchedStrings[i] = (String)matches.elementAt(i);
                }
                // updates the displayable list
                form.removeComponent(allContacts);
                allContacts = new List(matchedStrings);
                form.addComponent(allContacts);
                form.revalidate();
            }
            //if no match is found, the empty list is displayed
            else {
                form.removeComponent(allContacts);
                allContacts = new List(new String[0]);
                form.addComponent(allContacts);
                form.revalidate();
            }
        }
        // if no search text has been typed, then show all list items
        else {
            form.removeComponent(allContacts);
            allContacts = new List(itemList);
            form.addComponent(allContacts);
            form.revalidate();
        }
    }

});

Figure 2. SearchBar with a custom search icon and a custom search mechanism


Last updated 29 July 2013

Back to top

Was this page helpful?

Your feedback about this content is important. Let us know what you think.

 

Thank you!

We appreciate your feedback.

×