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.

Drop-down lists

Use drop-down lists to provide a set of mutually exclusive values.

Users can perform the following action with a drop-down list:

Action

BlackBerry devices with a trackpad only

BlackBerry devices with a touch screen and a trackpad

Click a value from a drop-down list.

Press the Enter key or click the trackpad.

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

This screen shows a drop-down list.

Best practice: Implementing drop-down lists

  • Use a drop-down list for two or more choices when space is an issue. If space is not an issue, consider using radio buttons instead so that users can view the available options on the screen.
  • Use the ObjectChoiceField or NumericChoiceField class to create drop-down lists.
  • For the default values, use the value that users are most likely to click.
  • Use the highlighted option as the default focus when users scroll through the list.
  • If users are not required to click a value, include a "None" value in the drop-down list. Always place "None" at the top of the list.
  • Group and order values logically (for example, group related values together or include the most common values first). Avoid ordering values alphabetically; alphabetical order is language-specific.

Guidelines for labels

  • Use clear, concise labels for drop-down lists and for the values in drop-down lists. Verify that the label clearly describes what occurs when users click the value.
  • Avoid using the labels "Yes" and "No" as drop-down list values. Rephrase the option and use a check box instead.
  • Place the label on the left side of a drop-down list.
  • Use title case capitalization for drop-down list labels and values (unless the values read more like a sentence).
  • Punctuate labels for drop-down lists with a colon (:).

Code sample: Creating a drop-down list

import net.rim.device.api.ui.*;
import net.rim.device.api.ui.component.*;
import net.rim.device.api.ui.container.*;

//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.
public class MyUi extends UiApplication 
{ 
    public static void main(String[] args) 
    { 
        MyUi theApp = new MyUi(); 
        theApp.enterEventDispatcher(); 
    } 
    public MyUi() 
    { 
        pushScreen(new MyUiScreen()); 
    } 
}

//Create the custom screen for the application by extending the 
//MainScreen class. In the screen constructor, invoke setTitle() to 
//specify the title for the screen.
class MyUiScreen extends MainScreen 
{
    public MyUiScreen() 
    {
        setTitle("UI Component Sample");

//In the screen constructor, create a drop-down list that displays a 
//list of words or phrases by using the ObjectChoiceField class. 
//Create a String array to store the items that you want to display in 
//the drop-down list.  Create an int to store the default item to 
//display in the drop-down list. In the ObjectChoiceField constructor, 
//specify the label for the drop-down list, the array of items to 
//display, and the default item. In example, Wednesday is the default.
//Invoke  add()  to add the drop-down list to the screen. 
        String choices[] = {"Monday","Tuesday","Wednesday","Thursday",
                            "Friday","Saturday","Sunday"};
        int iSetTo = 2;
        add(new ObjectChoiceField("First Drop-down List",choices,iSetTo));

//In the screen constructor, create a second drop-down list that 
//displays a list of numbers by using the NumericChoiceField class. 
//In the NumericChoiceField constructor, specify the label for the 
//drop-down list, the first and last number to display in the 
//drop-down list, the increment to use for the list of numbers, and 
//the default number. In the following code sample, the numeric parameters 
//are stored in int objects.  The numbers 1 to 31 are included in the 
//drop-down list and by default the number 10 is displayed. 
//Invoke  add()  to add the second drop-down list to the screen.
        int iStartAt   = 1;
        int iEndAt     = 31;
        int iIncrement = 1;
        iSetTo         = 10;
        add(new NumericChoiceField(
             "Numeric Drop-Down List",iStartAt,iEndAt,iIncrement,iSetTo));
    }

//To override the default functionality that prompts the user to save 
//changes before the application closes, in the extension of the 
//MainScreen class, override the MainScreen.onSavePrompt() method. 
//In the following code sample,  the return value is true which 
//indicates that the application does not prompt the user before closing.
    public boolean onSavePrompt()
    {
        return true;
    }
}