Would you like to tell us how we are doing?

You bet No thanks

Sorry about the red box, but we really need you to update your browser. Read this excellent article if you're wondering why we are no longer supporting this browser version. Go to Browse Happy for browser suggestions and how to update.

Lists and tables

Use lists and tables to display items that users can highlight and open. If the list is long, items are fetched and displayed in batches. When users reach the last item in the list, the next batch of items displays at the end of the list.

Use a simple list to easily display text in rows.


This screen shows a simple list.

Use a rich list to easily display rows of text and icons.


This screen shows a rich list.

If you want to present items in columns and rows, use a table.


This screen shows a table.

You can group items under headers to help users navigate through long lists. For example, you can create headers that collapse, making it easier for users to find items in the list.


This screen shows a list with a collapsible header.

You can also group items under headers that always appear at the top of the list. For example, you can add a date as a header and group messages received on that date under the header. Users can highlight a header to perform an action on the group of items or they can use shortcut keys to move through the list.


This screen shows a list with a header that always appears at the top of the list.

Users can perform the following actions in lists and tables:

Action

BlackBerry devices with a trackpad only

BlackBerry devices with a touch screen and a trackpad

Scroll through items in the list.

Move a finger vertically on the trackpad.

  • Drag a finger vertically on the screen.
  • Swipe up or down on the screen.
  • Move a finger vertically on the trackpad.

Highlight an item in the list.

Move a finger vertically on the trackpad.

  • Touch the item lightly.
  • Move a finger vertically on the trackpad.

Open an item in the list.

  • Click the trackpad.
  • Press the Enter key.
  • Tap the item.
  • Click the trackpad.
  • Press the Enter key.

Best practice: Implementing lists and tables

  • Use the SimpleList class to create a list with text. Use the RichList class to create a display-only list with text and icons. Use the TableView class to create an interactive rich list with text and icons.

  • Use the TableView class to create a table with rows and columns. You can use the GridFieldManager if the number of rows and columns in the table are fixed.

  • If the list is long and you want to display the items on separate screens, include Next and Previous buttons at the bottom of the screen. Alternatively, if the list is very long (for example, thousands of items), provide screen numbers instead.

  • If you expect users to move through the items in the list (for example, in a message list or a feed), assign shortcut keys for moving to the next or previous item in the list. Where possible, in English, allow users to press "N" to move to the next item in the list and "P" to move to the previous item in the list.

Create a list box

Use a list box to display a list from which users can select one or more values.

  1. Import the following classes:

    import net.rim.device.api.system.*;
    import net.rim.device.api.ui.*;
    import net.rim.device.api.ui.component.*;
    import net.rim.device.api.ui.container.*;
    import java.util.Vector;
  2. 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 CreateMenuScreen class represents the custom screen which is described in step 3.

    public class ListFields extends UiApplication
    {
         public static void main(String[] args)
         {
             ListFields theApp = new ListFields();
             theApp.enterEventDispatcher();
         }
         public ListFields()
         {
             pushScreen(new ListFieldScreen());
         }
    } 
  3. Create the custom screen for the application by extending the MainScreen class. In the constructor, invoke setTitle(), to display the title for the screen. Invoke add(), to display a text field on the screen. Invoke addMenuItem(), to add a menu item to the menu that MainScreen creates.

    class ListFieldScreen extends MainScreen
    {
        private ListField _listField;
        private Vector _listElements;
    
        public ListFieldScreen() 
        {
            setTitle("List Field Sample");
        }
    }
  4. In the screen constructor, create the list box. Create an array for the items that you want to add to the list box by using the Vector class. Create the list box by using the ListField() class. Invoke add(), to add the list box to the screen. Invoke initializeList(), which is described in step 4, to add build the list box.

    _listElements = new Vector(); 
    _listField = new ListField();
    ListCallback _callback = new ListCallback();
    _listField.setCallback(_callback);
    add(_listField);
    initializeList();
  5. Create a method to specify the items that you want to appear in the list box by using the String object. Invoke addElement() to add the items to the list. Invoke setSize(), to specify the number of items in the list box.

    private void initializeList()
    {
        String itemOne = "List item one";
        String itemTwo = "List item two";
        _listElements.addElement(itemOne);
        _listElements.addElement(itemTwo);
        reloadList();
    }
    private void reloadList()
    {
        _listField.setSize(_listElements.size());
    }
  6. Create a class that implements the ListFieldCallback interface. Implement drawListRow(), to add the list box items to the screen. Implement get(), to return the list box item at the specified index. Implement indexOfList(), to return the first occurrence of a given string. Implement getPreferredWidth(), to retrieve the width of the list box.

    private class ListCallback implements ListFieldCallback 
    {
        public void drawListRow(ListField list, Graphics g, int index, int y, int w) 
        { 
            String text = (String)_listElements.elementAt(index); 
            g.drawText(text, 0, y, 0, w); 
        } 
        public Object get(ListField list, int index) 
        {
            return _listElements.elementAt(index); 
        } 
        public int indexOfList(ListField list, String prefix, int string) 
        { 
            return _listElements.indexOf(prefix, string); 
        } 
        public int getPreferredWidth(ListField list) 
        { 
            return Display.getWidth(); 
        } 
    }