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.

Pickers

You can use pickers to help users choose an item from a list easily.

Type of picker

Description

File

This picker allows users to browse for files on their BlackBerry devices.


This screen shows an example of a file picker.

Location

This picker allows users to choose a location from a list that you define. For example, you can allow users to choose their GPS location or a previously selected location.


This screen shows an example of a location picker.

Date

This picker allows users to choose a specific day, month, or year. For example, you can allow users to choose a month and year to specify when their credit card expires.


This screen shows an example of a date picker.

Time

This picker allows users to choose a specific hour, minute, or second.


This screen shows an example of a time picker.

Best practice: Implementing pickers

To create pickers, use the FilePicker, LocationPicker, and DateTimePicker classes

Guidelines for file pickers

  • Specify a specific view to display the types of files that match the user's goal. For example, if a user is browsing pictures, display pictures in the file picker.
  • Allow users to start browsing from an appropriate default folder if possible.

Create a date picker

  1. Import the required classes and interfaces.

    import net.rim.device.api.ui.*;
    import net.rim.device.api.ui.component.*;
    import net.rim.device.api.ui.container.*;
    import net.rim.device.api.ui.picker.*;
    import java.util.*;
  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 DatePickScreen class represents the custom screen that is described in step 3.

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

    class DatePickScreen extends MainScreen
    {
        public DatePickScreen()
        {
            setTitle("Date Picker Sample");
            add(new RichTextField("Trying Date Picker"));
        }
    }
  4. Add a section of code to the event queue of the application by invoking invokeLater(). Create a Runnable object and pass it as a parameter to invokeLater(). Override run() in the definition of Runnable.

    class DatePickScreen extends MainScreen
    {
        public DatePickScreen()
        {
            setTitle("Date Picker Sample");
            add(new RichTextField("Trying Date Picker"));
            
            UiApplication.getUiApplication().invokeLater(new Runnable()
            {
                public void run()
                {
                }
            });
        }
    }
  5. In run(), invoke DateTimePicker.getInstance() to return a DateTimePicker object. Invoke doModal() to display the date picker. Invoke getDateTime() to return a Calendar object that represents the date and time the user selects. Use getTime() to return the date and time as a Date object. Use Dialog.alert() to display the selected date and time.

    class DatePickScreen extends MainScreen
    {
        public DatePickScreen()
        {
            setTitle("Date Picker Sample");
            add(new RichTextField("Trying Date Picker"));
            
            UiApplication.getUiApplication().invokeLater(new Runnable()
            {
                public void run()
                {
                    DateTimePicker datePicker = DateTimePicker.getInstance();
                    datePicker.doModal();
                    Calendar cal = datePicker.getDateTime();
                    Date date = cal.getTime();
                    Dialog.alert("You selected " + date.toString());
                }
            });
        }
    }

Create a file picker

  1. Import the required classes and interfaces.

    import net.rim.device.api.ui.*;
    import net.rim.device.api.ui.picker.*;
    import net.rim.device.api.ui.component.*;
    import net.rim.device.api.ui.container.*;
    import java.util.*;
  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 application constructor, invoke pushScreen() to display the custom screen for the application. The FilePickScreen class represents the custom screen that is described in step 3.

    public class FilePick extends UiApplication
    {
        public static void main(String[] args)
        {    
            FilePick theApp = new FilePick();
            theApp.enterEventDispatcher();
        }
        public FilePick()
        {
            pushScreen(new FilePickScreen());
        }
    }
  3. Create the custom screen for the application by extending the MainScreen class. In the screen constructor, invoke setTitle() to specify a title for the screen. Invoke add() to add a label field to the screen.

    class FilePickScreen extends MainScreen
    {
        public FilePickScreen()
        {
            setTitle("File Picker Sample");
            add(new LabelField("Trying File Picker"));
        }
    }
  4. In the screen constructor, invoke invokeLater() to add a section of code to the event queue of the application. Create a Runnable object and pass it as a parameter to invokeLater().

    class FilePickScreen extends MainScreen
    {
        public FilePickScreen()
        {
            setTitle("File Picker Sample");
            add(new LabelField("Trying File Picker"));
            
            UiApplication.getUiApplication().invokeLater(new Runnable()
            {
                public void run()
                {  
                }
            });
        }
    }
  5. Override run() in the definition of Runnable. In run(), invoke FilePicker.getInstance() to return a FilePicker object. Create a FilePickListener object, which is described in step 6. Invoke setListener() to register the listener for the file picker. Invoke show() to display the file picker on the screen.

    class FilePickScreen extends MainScreen
    {
        public FilePickScreen()
        {
            setTitle("File Picker Sample");
            add(new LabelField("Trying File Picker"));
            
            UiApplication.getUiApplication().invokeLater(new Runnable()
            {
                public void run()
                {
                    FilePicker fp = FilePicker.getInstance();
                    FilePickListener fileListener = new FilePickListener();
                    fp.setListener(fileListener);           
                    fp.show();  
                }
            });
        }
    }
  6. Invoke Dialog.alert to create a dialog box with a message that displays which file was selected. Invoke Dialog.alert in a class that implements the FilePicker.Listener interface by overriding selectionDone(). The application calls selectionDone() when the user selects a file using the file picker.

    class FilePickListener implements FilePicker.Listener 
    {   
        public void selectionDone(String str)
        {
            Dialog.alert("You selected " + str);
        }
    }