Create a spin box

Development Guide

Search This Document

Download PDF

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;

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());
    }
}
```
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()
    {
    }
}
```

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"};

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);
```
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 (...).

Next topic: Text fields

Previous topic: Spin boxes

Was this information helpful? Send us your comments.

Global Navigation

Development Guide

Local Navigation

Create a spin box

Best practice: Implementing spin boxes