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.

Tutorial: Creating an advanced app

Following this tutorial, you will create an app that displays a drop-down menu on the BlackBerry device screen, from which the BlackBerry device user can select a city. The user then clicks the More Info button to display information about the city. When the user selects Close from the menu of the CityInfo app, the app displays a dialog box with the text ‘Goodbye!’.

Create a project for the CityInfo app

  1. On the File menu, click New > BlackBerry Project.
  2. In the Project name field, type CityInfo.
  3. Click Next.
  4. Click Finish.

Set the application type and properties

  1. In the Package Explorer view, expand the CityInfo project.
  2. Double-click the BlackBerry_App_Descriptor.xml file.
  3. Click the Application tab.
  4. In the Title field, type City Info Sample.
  5. In the Version field, type a version number.
  6. In the Vendor field, type a vendor name, for example, Research In Motion Ltd.
  7. In the Application type drop-down list, select BlackBerry Application.
  8. Click Close.
  9. Click Yes.

Add Java source files to the CityInfo project

The Java source file name must match the name of the public class or interface in the file. It must also be located in a folder structure that matches its package name. For example, if the package name is com.Mycompany.MyClass, you must name the .java file MyClass.java, and store it in ...\CityInfo\src\com\mycompany\MyClass.java (for Windows) or .../CityInfo/src/com/mycompany/MyClass.java (for Mac OS).

  1. In the Package Explorer view, right-click the CityInfo project. Click New > Class.
  2. In the Name field, type CityInfo.
  3. In the Package field, type com.mycompany.
  4. Next to the SuperClass field, click Browse.
  5. In the Choose a type field, type UI.
  6. Click UIApplication.
  7. Click OK.
  8. In the Which method stubs would you like to create section, select the following stubs:
    • public static void main (String[] args)
    • Constructors from superclass
    • Inherited abstract methods
  9. Click Finish.

Import Java resources into the CityInfo app

The net.rim.device.api.ui package provides the fundamental components for constructing the UI of an app.

The net.rim.device.api.ui.component package provides a library of prebuilt interface components and controls for constructing a UI for an app.

The net.rim.device.api.ui.container package provides a library of prebuilt interface component managers for constructing a UI for an app.

The net.rim.device.api.system package provides system-level functionality.

The net.rim.device.api.i18n package provides support for the internationalization of an app.

In the Text Editor window, below the line that begins with the word package, type the names of the packages to import:

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.system.*;
import net.rim.device.api.i18n.*;

Send and receive events in the CityInfo app

The UiApplication class is the base class for all BlackBerry applications that provide a UI.

To provide a UI, the app must extend the net.rim.device.api.ui.UiApplication class. This class provides methods for an app to register event listeners, manage threads, and manage UI components.

A UI maintains a stack of screen objects. As an app pushes screens onto the stack, the UI draws them on top of screens that are already on the stack. When an app pops a screen off the stack, the UI redraws the underlying screens as necessary. The screen that is on the top of the stack receives input events.

Within the main() method, create the CityInfo object and start the event dispatcher:

CityInfo theApp = new CityInfo();
theApp.enterEventDispatcher();

The main method for the app is created automatically if you select public static void main (String[ ] args) when you add new .java files to the CityInfo project.

Create a screen for the CityInfo app

  1. Create a class that extends the MainScreen class:
    final class CityInfoScreen extends MainScreen {
    }
  2. Create a constructor for the CityInfoScreen class:
    public CityInfoScreen() {
    }

Display a drop down-list in the CityInfo app

  1. In the class that extends the MainScreen class, create instance variables for the InfoScreen, choiceField and user selection.
    private InfoScreen _infoScreen;
    private ObjectChoiceField choiceField;
    private int select;
    
  2. In the constructor for the class that extends the MainScreen class, add a LabelField with the text "City Information Kiosk".
    LabelField title = new LabelField("City Information Kiosk",LabelField.ELLIPSIS
     | LabelField.USE_ALL_WIDTH);
    setTitle(title);
  3. In the constructor for the class that extends the MainScreen class, add a RichTextField with the text "Major U.S. Cities":
    add(new RichTextField("Major U.S. Cities"));
  4. In the constructor for the class that extends the MainScreen class, create a drop-down list that displays three cities as choice items. An ObjectChoiceField is a UI field that displays a list of objects that a BlackBerry device user can choose from.
    String choices[] = {"Los Angeles", "Chicago", "New York"};
    choiceField = new ObjectChoiceField("Select a City", choices);
    
  5. Add a choiceField to the Manager object of the CityInfoScreen screen.
    add(choiceField);

Create a menu item to display more information

The choiceField.getSelectedIndex() method allows an app to retrieve the index number of the choice item that a BlackBerry device user selects from a choiceField drop-down list. Invoking UiApplication.getUiApplication().pushScreen(_infoScreen) allows an app to use an instance of itself to display a screen with information about the city that a BlackBerry device user selects from a choiceField drop-down list.

When a BlackBerry device user selects a menu item from the menu of an app, the code in the run() method for the menu item executes.

  1. In the CityInfoScreen class, create a MenuItem with a name that reflects the action that occurs when a BlackBerry device user selects the menu item.
    private MenuItem _viewItem = new MenuItem("More Info", 110, 10) {
    
  2. In the CityInfoScreen class, create a run() method for the MenuItem that displays information about the city that a BlackBerry device user selects.
    public void run() {
    
    //Store the index for the city that a BlackBerry device user selects
    
    select = choiceField.getSelectedIndex();
    
    //Create an instance of the screen that displays information about the city that
     the BlackBerry device user selects
    
    _infoScreen = new InfoScreen(); 
    
    //Push the screen with information about the city that the BlackBerry device user
     selects to the display stack and paint this screen
    
    UiApplication.getUiApplication().pushScreen(_infoScreen);
    }
    
    

Create a menu item to close the CityInfo app

  1. In the CityInfoScreen class, create a MenuItem that has a name that reflects the action that occurs when a BlackBerry device user selects the menu item.
    private MenuItem _closeItem = new MenuItem("Close", 200000, 10) {
    
    
  2. In the CityInfoScreen class, create a run() method that calls the app’s onClose() method when a BlackBerry device user selects the Close menu item.
    public void run(){
     onClose();
    }
    };
    

Add a menu item to the CityInfo app menu

The makeMenu() method is inherited from the MainScreen class and allows your app to add menu items to a BlackBerry device. To add menu items to the main screen menu of the BlackBerry device, you must override the makeMenu() method.

In the CityInfoScreen class, override the makeMenu() method.
protected void makeMenu(Menu menu,int instance)
{ menu.add(_viewItem);
menu.add(_closeItem);
}

Create a screen that displays information about a city

  1. Within the CityInfoScreen class, create an inner class that extends MainScreen.
    private class InfoScreen extends MainScreen
    }
  2. In the first line of the constructor for the inner class, invoke the constructor of the MainScreen class.
    super();
  3. Display a label with the name of the city that the BlackBerry device user selects. In the constructor for the inner class, create a LabelField.
    LabelField lf = new LabelField();
  4. Display the population of the city that the BlackBerry device user selects. In the constructor for the inner class, create a BasicEditField. A BasicEditField is an editable simple text field with no formatting.
    BasicEditField popField = new BasicEditField("Population: ", null, 20, Field.READONLY);
  5. Display the state where the city that the BlackBerry device user selects is located. In the constructor for the inner class, create a BasicEditField.
    BasicEditField stateField = new BasicEditField("State: ", null, 20, Field.READONLY);
  6. Display tourist attraction information for the city that the BlackBerry device user selects. In the constructor for the inner class, create a BasicEditField.
    BasicEditField sightsField = new BasicEditField("Sights: ", null, 50, Field.READONLY);
  7. Add the fields to the Manager object for the CityInfoScreen class. In the constructor for the inner class, invoke Manager.add().
    add(lf);
    add(new SeparatorField());
    add(popField);
    add(stateField);
    add(sightsField);
    

Set the value of a UI field in the CityInfo app

In the constructor for the inner class, use a select clause to control the actions that the app performs when a BlackBerry device user selects a city from the menu of the CityInfo application. To set the text value of a BasicEditField invoke BasicEditField.setText().
if (select == 0) 
{
    lf.setText("Los Angeles");
    popField.setText("3,694,820");
    stateField.setText("California");
    sightsField.setText("Hollywood");
} 
else if (select == 1) 
{
    lf.setText("Chicago");
    popField.setText("2,896,016");
    stateField.setText("Illinois");	
    sightsField.setText("Blues Clubs");
} 
else if (select == 2) 
{
    lf.setText("New York");
    popField.setText("8,008,278");
    stateField.setText("New York");
    sightsField.setText("Broadway");
}

          }//close the constructor code block
     }//close the InfoScreen class code block
}//close the CityInfoScreenclass code block

Test the CityInfo app

  1. Choose one of the following steps, depending on whether you're testing the app using a device or the BlackBerry Smartphone Simulator (Windows only):
    • On the Run menu, click Run As > BlackBerry Simulator
    • Right-click the app and click BlackBerry > Load Project on Device.
  2. On the BlackBerry Smartphone Simulator or the BlackBerry device, open the Downloads folder.
  3. Click the CityInfo application.
  4. On the drop-down list of the CityInfo app, click a city.
  5. On the menu of the CityInfo app, click More Info.
    • The CityInfo app displays information about the city.
  6. On the menu of the CityInfo app, click Close.
    • The CityInfo app closes the More Info screen.
  7. On the menu of the CityInfo app, click Close.
    • The CityInfo app displays a dialog box with the text "Goodbye!"
  8. Click OK.

Code sample: Display information about a city

/**
* CityInfo.java
* Copyright (C) 2012 Research In Motion Limited. All rights reserved.
*/

package com.rim.samples.cityinfo;

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.system.*;
import net.rim.device.api.i18n.*;

public class CityInfo extends UiApplication
{

     public static void main(String[] args)  
     {
          //Create a new instance of the app
          //and start the app on the event thread.

          CityInfo app = new CityInfo();
          app.enterEventDispatcher();
     }

     public CityInfo()
     {
          //Display a new screen.
          pushScreen(new CityInfoScreen());
     }
}

//Create a new screen that extends MainScreen and provides
//behaviour similar to that of other apps.

final class CityInfoScreen extends MainScreen
{
     //declare variables for later use
     private InfoScreen _infoScreen;
     private ObjectChoiceField choiceField;
     private int select;

     public CityInfoScreen()
     {
          //Invoke the MainScreen constructor.

          super();

          //Add a screen title.

          LabelField title = new LabelField("City Information Kiosk",
                         LabelField.ELLIPSIS | LabelField.USE_ALL_WIDTH);
          setTitle(title);

          //Add a text label.

          add(new RichTextField("Major U.S. Cities"));

          //Add a drop-down list with the names of three cities as choice items:
          //Los Angeles, Chicago, or New York.

          String choices[] = {"Los Angeles", "Chicago", "New York"};
          choiceField = new ObjectChoiceField("Select a City", choices);
          add(choiceField);
     }

     //To display a dialog box when a BlackBerry device user
     //closes the app, override the onClose() method.

     public boolean onClose()
     {
          Dialog.alert("Goodbye!");
          System.exit(0);
          return true;
     }

     //Create a menu item for BlackBerry device users to click to see more 
     //information about the city they select.

     private MenuItem _viewItem = new MenuItem("More Info", 110, 10) 
     {
          public void run() 
          {
               //Store the index of the city the BlackBerry device user selects

               select = choiceField.getSelectedIndex();

               //Display a new screen with information about the
               //city the BlackBerry device user selects

                   _infoScreen = new InfoScreen();
																		 UiApplication.getUiApplication().pushScreen(_infoScreen);
          }
     };

     //Create a menu item for BlackBerry device users to click to close 
     //the app.

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

     //To add menu items to the menu of the app, 
     //override the makeMenu method.

     protected void makeMenu( Menu menu, int instance )
     {
          menu.add(_viewItem);
          menu.add(_closeItem);
     }

     //Create an inner class for a new screen that displays
     //information about the city a BlackBerry device user selects.

     private class InfoScreen extends MainScreen
     {
          public InfoScreen() 
          {
               super();

               //Add fields to display a screen label that identifies the city
               //as well as information on population, state, and attractions.

               LabelField lf = new LabelField();
               BasicEditField popField = new BasicEditField("Population: ", null, 20,
																 Field.READONLY);
               BasicEditField stateField = new BasicEditField("State: ", null, 20,
																 Field.READONLY);
               BasicEditField sightsField = new BasicEditField("Sights: ", null, 50,
																 Field.READONLY);
               add(lf);
               add(new SeparatorField());
               add(popField);
               add(stateField);
               add(sightsField);

               //Populate fields with data for the city the BlackBerry device user
               //selects. The 'select' variable stores the value for the city.

               if (select == 0) 
               {
                    lf.setText("Los Angeles");
                    popField.setText("3,694,820");
                    stateField.setText("California");
                    sightsField.setText("Hollywood");
               } 
               else if (select == 1) 
               {
                    lf.setText("Chicago");
                    popField.setText("2,896,016");
                    stateField.setText("Illinois");
                    sightsField.setText("Blues Clubs");
               } 
               else if (select == 2) 
               {
                    lf.setText("New York");
                    popField.setText("8,008,278");
                    stateField.setText("New York");
                    sightsField.setText("Broadway");
               }
          }
     }
}