Creating User Interfaces in BlackBerry Applications

• Download demo project - 12.41 KB
• Download source - 1.11 KB

Introduction

BlackBerry Java Development Environment (JDE) is used to develop applications that run on BlackBerry handheld devices.

There are two sets of APIs for creating user interfaces:

• MIDP UI APIs
• BlackBerry UI APIs

The MIDP UI APIs are used when you want to develop applications to run on MIDP compliant devices while BlackBerry UI APIs are used when you want to develop applications to specifically run on BlackBerry handheld devices. When a BlackBerry Java source code is compiled, it generates a .cod file. This .cod file is copied onto the device and executed by the virtual machine (vm) of the device.

In this article, I have focused on developing applications using BlackBerry UI APIs. At the end, I have created a simple application for demonstration of the basic concepts.

Background

Components

The main element of the user interface in a BlackBerry application is the Screen class. Only one screen can be displayed at a time. Screen objects are stored in a stack. A screen is pushed on top of the stack in order to be displayed and popped off the stack in order to be closed.

User interface components are represented by fields. All UI components are present in the net.rim.device.api.ui.component package.

The commonly used fields are:

• Label field - This is an instance of the LabelField class and is used to display static text.
• Text field - The TextField class is used to create an editable field in which a user can enter a value.

  

• Button field - The ButtonField class is used to create a clickable field for performing an action.

  

• Numeric choice field - The NumericChoice class is used to allow users to select a numeric value from a range of numbers.

  

• Object choice field - The ObjectChoice class is used to allow users to select any object from a list of objects.

  

• Checkbox field - The CheckboxField class is used to allow a user to select one of two choices.

  

• RadioButton field - The RadioButtonField class is used to allow a user to select a single value from multiple options.

  

• Gauge field - The GaugeField class is used to display a progress bar.

  

Layouts

Layout of components on the screen can be managed by using Layout Managers. There are four layout manager classes as follows:

• VerticalFieldManager
• HoriziontalFieldManager
• FlowFieldManager
• DialogFieldManager

The following code can be used to create a vertical layout and add items to it.

VerticalFieldManager manager=new VerticalFieldManager(Manager.VERTICAL_SCROLL);
manager.add(button1);
manager.add(button2);
screen.add(manager);

Menus

Menus can be created for performing actions. The MenuItem class can be used to create menus as follows:

private MenuItem viewItem = new MenuItem("Show Message", 100, 10)
{
    public void run()
    {
        Dialog.inform("Welcome to BlackBerry JDE");
    }
};

The makeMenu() function of the Screen class is overridden to add menuitems to the screen.

protected void makeMenu(Menu menu,int n)
{
    menu.add(closeItem);
}

Events

Events can be handled by implementing the FieldChangeListener interface and fieldChanged method. For example:

class MyClass extends MainScreen implements FieldChangeListener
...
...
...
public void fieldChanged(Field field,int context)

Changes to fields can be monitored by calling setChangeListener method of the field as follows:

buttonfield.setChangeListener(this);

Using the Code

The following program demonstrates the use of different fields.

// Importing the required packages.

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

class UIExample extends UiApplication	// Extending from UIApplication class.
{
    public static void main(String args[])	// main function.
    {
        new UIExample().enterEventDispatcher();	// Start event handling process
    }
    UIExample()	// Constructor.
    {
        pushScreen(new MyClass());	// Push screen on top of the stack
    }
}
class MyClass extends MainScreen implements FieldChangeListener	// User defined 
							// screen class.
{
    // Declaring fields.

    LabelField lfield;
    TextField tfield;
    ButtonField bField;
    NumericChoiceField nfield;
    ObjectChoiceField ofield;
    CheckboxField chkfield;
    RadioButtonField rfield1,rfield2,rfield3;
    GaugeField gfield;

    // Declaring Close Menu.

    private MenuItem closeItem = new MenuItem("Close", 100, 10)
    {
        public void run()
        {
            onClose();
        }
    };

    // Adding menu to screen.

    protected void makeMenu(Menu menu,int n)
    {
        menu.add(closeItem);
    }

    public MyClass()	// Constructor.
    {

        // Initializing fields and creating user interface

        VerticalFieldManager manager=new VerticalFieldManager
        	(Manager.VERTICAL_SCROLL);	// Layout Manager
        lfield=new LabelField("Enter a value: ");	// LabelField
        tfield=new TextField();			// TextField
        bField=new ButtonField("OK");		// ButtonField
        bField.setChangeListener(this);
        nfield=new NumericChoiceField("Select a number",1,20,1);//NumericChoiceField
        nfield.setChangeListener(this);
        String[] objects={"A","B","C","D","E","F","G","H","I","J"};// List of objects for 
							//the ObjectChoiceField
        ofield=new ObjectChoiceField("Select a value",objects);	// ObjectChoiceField
        ofield.setChangeListener(this);
        chkfield=new CheckboxField("Select",false);		// CheckboxField
        chkfield.setChangeListener(this);
        RadioButtonGroup group=new RadioButtonGroup();		// RadioButtonGroup to 
							// select a single option
        rfield1=new RadioButtonField("Option 1",group,true);	// RadioButtonField
        rfield2=new RadioButtonField("Option 2",group,false);	// RadioButtonField
        rfield3=new RadioButtonField("Option 3",group,false);	// RadioButtonField
        rfield1.setChangeListener(this);
        rfield2.setChangeListener(this);
        rfield3.setChangeListener(this);
        gfield=new GaugeField("Select a value: ",1,100,1,
			GaugeField.FOCUSABLE|GaugeField.EDITABLE);
							// GaugeField
        gfield.setChangeListener(this);
        manager.add(lfield);
        manager.add(tfield);
        manager.add(bField);
        manager.add(nfield);
        manager.add(ofield);
        manager.add(chkfield);
        manager.add(rfield1);
        manager.add(rfield2);
        manager.add(rfield3);
        manager.add(gfield);
        add(manager);
    }
    public void fieldChanged(Field field,int context)	// Handling events.
    		// The Dialog.inform method is used to display an alert message.
    {
        if(field==bField)
        {
            Dialog.inform("You have clicked the button");
        }
        if(field==nfield)
        {
            int n=nfield.getSelectedValue();
            Dialog.inform("You have selected "+Integer.toString(n));
        }
        if(field==ofield)
        {
            String s=ofield.getChoice(ofield.getSelectedIndex()).toString();
            Dialog.inform("You have selected "+s);
        }
        if(field==chkfield)
        {
            boolean b=chkfield.getChecked();		// Check Status of checkbox.
            Dialog.inform("Option "+(b?"selected":"unselected"));
        }
        if(field==rfield1)
        {
            if(rfield1.isSelected())			// Check RadioButton status.
            {
                Dialog.inform("Option 1 selected");
            }
        }
        if(field==rfield2)
        {
            if(rfield2.isSelected())			// Check RadioButton status.
            {
                Dialog.inform("Option 2 selected");
            }
        }
        if(field==rfield3)
        {
            if(rfield3.isSelected())			// Check RadioButton status.
            {
                Dialog.inform("Option 3 selected");
            }
        }
        if(field==gfield)
        {
            int value=gfield.getValue();		// Get value of Gauge
            Dialog.inform("You have selected "+value+" value");
        }
    }
}

Points of Interest

When the project is executed in the BlackBerry JDE, it is opened in the BlackBerry Simulator and can be selected from the downloads section.

I hope this article will provide users with the basic information to start developing for the BlackBerry handheld devices.

History

• 10^th September, 2011: Initial version