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.

Spin boxes

Use a spin box to allow users to choose an item from an ordered list easily. For example, use spin boxes to allow users to find a number or to change the day of the week.

Action

BlackBerry devices with a trackpad only

BlackBerry devices with a touch screen and a trackpad

Find an item 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.

Move a finger up or down on the screen or the trackpad.

Choose an item from the list.

Click the trackpad.

  • Lift a finger from the screen.
  • Click the trackpad.

Move to another spin box.

Move a finger vertically on the trackpad.

  • Drag a finger vertically on the screen.
  • Move a finger vertically on the trackpad.

This screen shows an example of a spin box.

Create a spin box

  1. Import the required classes and interfaces.
    import net.rim.device.api.ui.UiApplication;
    import net.rim.device.api.ui.component.Dialog;
    import net.rim.device.api.ui.component.TextSpinBoxField;
    import net.rim.device.api.ui.container.MainScreen;
    import net.rim.device.api.ui.container.SpinBoxFieldManager;
    
  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 HomeScreen class represents the custom screen that is described in step 3.
    public class SpinBoxApp extends UiApplication 
    {
        public static void main(String[] args) 
        {
            SpinBoxApp app = new SpinBoxApp();
            app.enterEventDispatcher();
        }
    	
        public SpinBoxApp()
        {
            pushScreen(new HomeScreen());
        }
    }
  3. Create the custom screen for the application by extending the MainScreen class. Declare a variable for each field in the spin box and declare a variable for the spin box field manager.
    class HomeScreen extends MainScreen
    {
        TextSpinBoxField spinBoxDays;
    	   TextSpinBoxField spinBoxMonths;
    	   SpinBoxFieldManager spinBoxMgr;
    
        public HomeScreen()
        {
        }
    }
  4. In the screen constructor, create an array of String objects for each of the spin box fields.
    final String[] DAYS   = {"Monday","Tuesday","Wednesday","Thursday","Friday","Saturday","Sunday"};
    
    final String[] MONTHS = {"January","February","March","April","May","June","July","August","September","October","November","December"};
  5. In the screen constructor, create new instances of the spin box field manager and the two spin box fields. Pass the appropriate array of strings as arguments to each of the spin box field constructors.
    spinBoxMgr = new SpinBoxFieldManager();		
    
    spinBoxDays   = new TextSpinBoxField(DAYS);
    spinBoxMonths = new TextSpinBoxField(MONTHS);
  6. In the screen constructor, add the spin box fields to the spin box field manager. Invoke add() to add the manager, and the fields that it contains, to the screen.
    spinBoxMgr.add(spinBoxDays);
    spinBoxMgr.add(spinBoxMonths);
    add(spinBoxMgr);

Best practice: Implementing spin boxes

  • Use spin boxes for a list of sequential items.
  • Use drop-down lists for non-sequential items or items with irregular intervals. For a short list of non-sequential items, you can use a spin box to provide a more interactive experience for users.
  • Avoid using a spin box if several other components appear on the screen.
  • Use the SpinBoxField class and the SpinBoxFieldManager class to create spin boxes.
  • Add spin boxes to dialog boxes instead of screens where possible.
  • When users highlight a spin box, display three to five items vertically.
  • Use an identifiable pattern for the sequence of items (for example, 5, 10, 15) so that users can estimate how much they need to scroll to find the target item.
  • Avoid making users scroll horizontally to view multiple spin boxes. If necessary, separate spin boxes into multiple fields.
  • If the text in a spin box is too long, use an ellipsis (...).