Tutorial: Creating an advanced app Following this tutorial, you will create an app that displays a drop-down menu

o n 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 On the File menu, click New > BlackBerry Project. In the Project name field, type CityInfo. Click Next. Click Finish. Set the application type and properties In the Package Explorer view, expand the CityInfo project. Double-click the BlackBerry_App_Descriptor.xml file. Click the Application tab. In the Title field, type City Info Sample. In the Version field, type a version number. In the Vendor field, type a vendor name, for example, Research In Motion Ltd . In the Application type drop-down list, select BlackBerry Application. Click Close. 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 i n the file. It must also be located in a folder structure that matches its packa ge name. For example, if the package name is com.Mycompany.MyClass, you must nam e the .java file MyClass.java, and store it in ...\CityInfo\src\com\mycompany\My Class.java (for Windows) or .../CityInfo/src/com/mycompany/MyClass.java (for Mac OS). In the Package Explorer view, right-click the CityInfo project. Click New > Class. In the Name field, type CityInfo. In the Package field, type com.mycompany. Next to the SuperClass field, click Browse. In the Choose a type field, type UI. Click UIApplication. Click OK. In the Which method stubs would you like to create section, select the follo wing stubs: public static void main (String[] args) Constructors from superclass Inherited abstract methods Click Finish. Import Java resources into the CityInfo app The net.rim.device.api.ui package provides the fundamental components for constr ucting the UI of an app. The net.rim.device.api.ui.component package provides a library of prebuilt inter face components and controls for constructing a UI for an app.

The net.rim.device.api.ui.container package provides a library of prebuilt inter face 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 internationalizatio n of an app. In the Text Editor window, below the line that begins with the word package, typ e the names of the packages to import: import import import import import net.rim.device.api.ui.*; net.rim.device.api.ui.component.*; net.rim.device.api.ui.container.*; net.rim.device.api.system.*; 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 p rovide a UI. To provide a UI, the app must extend the net.rim.device.api.ui.UiApplication cla ss. This class provides methods for an app to register event listeners, manage t hreads, and manage UI components. A UI maintains a stack of screen objects. As an app pushes screens onto the stac k, the UI draws them on top of screens that are already on the stack. When an ap p pops a screen off the stack, the UI redraws the underlying screens as necessar y. 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 dispatc her: 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 Create a class that extends the MainScreen class: final class CityInfoScreen extends MainScreen { } Create a constructor for the CityInfoScreen class: public CityInfoScreen() { } Display a drop down-list in the CityInfo app In the class that extends the MainScreen class, create instance variables fo r the InfoScreen, choiceField and user selection. private InfoScreen _infoScreen; private ObjectChoiceField choiceField; private int select;

In the constructor for the class that extends the MainScreen class, add a La belField with the text "City Information Kiosk". LabelField title = new LabelField("City Information Kiosk",LabelField.ELLIPS IS | LabelField.USE_ALL_WIDTH); setTitle(title); In the constructor for the class that extends the MainScreen class, add a Ri chTextField with the text "Major U.S. Cities": add(new RichTextField("Major U.S. Cities")); 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); 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 nu mber of the choice item that a BlackBerry device user selects from a choiceField drop-down list. Invoking UiApplication.getUiApplication().pushScreen(_infoScree n) allows an app to use an instance of itself to display a screen with informati on about the city that a BlackBerry device user selects from a choiceField dropdown list. When a BlackBerry device user selects a menu item from the menu of an app, the c ode in the run() method for the menu item executes. 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) { In the CityInfoScreen class, create a run() method for the MenuItem that dis plays 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 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) { In the CityInfoScreen class, create a run() method that calls the app s onClos e() 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 Within the CityInfoScreen class, create an inner class that extends MainScre en. private class InfoScreen extends MainScreen } In the first line of the constructor for the inner class, invoke the constru ctor of the MainScreen class. super(); Display a label with the name of the city that the BlackBerry device user se lects. In the constructor for the inner class, create a LabelField. LabelField lf = new LabelField(); Display the population of the city that the BlackBerry device user selects. In the constructor for the inner class, create a BasicEditField. A BasicEditFiel d is an editable simple text field with no formatting. BasicEditField popField = new BasicEditField("Population: ", null, 20, Field .READONLY); 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.RE ADONLY); Display tourist attraction information for the city that the BlackBerry devi ce user selects. In the constructor for the inner class, create a BasicEditField . BasicEditField sightsField = new BasicEditField("Sights: ", null, 50, Field. READONLY); Add the fields to the Manager object for the CityInfoScreen class. In the co nstructor 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 actio ns that the app performs when a BlackBerry device user selects a city from the m enu of the CityInfo application. To set the text value of a BasicEditField invok e 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 Choose one of the following steps, depending on whether you're testing the a pp 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. On the BlackBerry Smartphone Simulator or the BlackBerry device, open the Do wnloads folder. Click the CityInfo application.

On the drop-down list of the CityInfo app, click a city. On the menu of the CityInfo app, click More Info. The CityInfo app displays information about the city. On the menu of the CityInfo app, click Close. The CityInfo app closes the More Info screen. On the menu of the CityInfo app, click Close. The CityInfo app displays a dialog box with the text "Goodbye!" 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 import import import import net.rim.device.api.ui.*; net.rim.device.api.ui.component.*; net.rim.device.api.ui.container.*; net.rim.device.api.system.*; 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, 2 0, 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 us er //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"); } } } }