BlackBerry device application

development
Getting started guide
BlackBerry device application development Getting started guide

Last modified: 9 February 2009

Part number: 21215185

At the time of publication, this documentation is based on the BlackBerry Java Development Environment version 4.7.0.

Send us your comments on product documentation: https://www.blackberry.com/DocsFeedback.

©2008 Research In Motion Limited. All rights reserved. BlackBerry®, RIM®, Research In Motion®, SureType® and related trademarks, names,
and logos are the property of Research In Motion Limited and are registered and/or used as trademarks in the U.S., Canada, and countries
around the world.

Microsoft, ActiveX, Internet Explorer, and Windows are trademarks of Microsoft Corporation. Sun, and Java are trademarks of Sun
Microsystems, Inc. .All other trademarks are the properties of their respective owners.

The BlackBerry smartphone and other devices and/or associated software are protected by copyright, international treaties, and various
patents, including one or more of the following U.S. patents: 6,278,442; 6,271,605; 6,219,694; 6,075,470; 6,073,318; D445,428; D433,460;
D416,256. Other patents are registered or pending in the U.S. and in various countries around the world. Visit www.rim.com/patents for a list of
RIM (as hereinafter defined) patents.

This documentation including all documentation incorporated by reference herein such as documentation provided or made available at
www.blackberry.com/go/docs is provided or made accessible "AS IS" and "AS AVAILABLE" and without condition, endorsement, guarantee,
representation, or warranty of any kind by Research In Motion Limited and its affiliated companies ("RIM") and RIM assumes no responsibility
for any typographical, technical, or other inaccuracies, errors, or omissions in this documentation. In order to protect RIM proprietary and
confidential information and/or trade secrets, this documentation may describe some aspects of RIM technology in generalized terms. RIM
reserves the right to periodically change information that is contained in this documentation; however, RIM makes no commitment to provide
any such changes, updates, enhancements, or other additions to this documentation to you in a timely manner or at all.

This documentation might contain references to third-party sources of information, hardware or software, products or services including
components and content such as content protected by copyright and/or third-party web sites (collectively the "Third Party Products and
Services"). RIM does not control, and is not responsible for, any Third Party Products and Services including, without limitation the content,
accuracy, copyright compliance, compatibility, performance, trustworthiness, legality, decency, links, or any other aspect of Third Party Products
and Services. The inclusion of a reference to Third Party Products and Services in this documentation does not imply endorsement by RIM of
the Third Party Products and Services or the third party in any way.

EXCEPT TO THE EXTENT SPECIFICALLY PROHIBITED BY APPLICABLE LAW IN YOUR JURISDICTION, ALL CONDITIONS, ENDORSEMENTS,
GUARANTEES, REPRESENTATIONS, OR WARRANTIES OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING WITHOUT LIMITATION, ANY
CONDITIONS, ENDORSEMENTS, GUARANTEES, REPRESENTATIONS OR WARRANTIES OF DURABILITY, FITNESS FOR A PARTICULAR
PURPOSE OR USE, MERCHANTABILITY, MERCHANTABLE QUALITY, NON-INFRINGEMENT, SATISFACTORY QUALITY, OR TITLE, OR ARISING
FROM A STATUTE OR CUSTOM OR A COURSE OF DEALING OR USAGE OF TRADE, OR RELATED TO THE DOCUMENTATION OR ITS USE,
OR PERFORMANCE OR NON-PERFORMANCE OF ANY SOFTWARE, HARDWARE, SERVICE, OR ANY THIRD PARTY PRODUCTS AND
SERVICES REFERENCED HEREIN, ARE HEREBY EXCLUDED. YOU MAY ALSO HAVE OTHER RIGHTS THAT VARY BY STATE OR PROVINCE.
SOME JURISDICTIONS MAY NOT ALLOW THE EXCLUSION OR LIMITATION OF IMPLIED WARRANTIES AND CONDITIONS. TO THE EXTENT
PERMITTED BY LAW, ANY IMPLIED WARRANTIES OR CONDITIONS RELATING TO THE DOCUMENTATION TO THE EXTENT THEY CANNOT
BE EXCLUDED AS SET OUT ABOVE, BUT CAN BE LIMITED, ARE HEREBY LIMITED TO NINETY (90) DAYS FROM THE DATE YOU FIRST
ACQUIRED THE DOCUMENTATION OR THE ITEM THAT IS THE SUBJECT OF THE CLAIM.

TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW IN YOUR JURISDICTION, IN NO EVENT SHALL RIM BE LIABLE FOR ANY TYPE
OF DAMAGES RELATED TO THIS DOCUMENTATION OR ITS USE, OR PERFORMANCE OR NON-PERFORMANCE OF ANY SOFTWARE,
HARDWARE, SERVICE, OR ANY THIRD PARTY PRODUCTS AND SERVICES REFERENCED HEREIN INCLUDING WITHOUT LIMITATION ANY
OF THE FOLLOWING DAMAGES: DIRECT, CONSEQUENTIAL, EXEMPLARY, INCIDENTAL, INDIRECT, SPECIAL, PUNITIVE, OR AGGRAVATED
DAMAGES, DAMAGES FOR LOSS OF PROFITS OR REVENUES, FAILURE TO REALIZE ANY EXPECTED SAVINGS, BUSINESS INTERRUPTION,
LOSS OF BUSINESS INFORMATION, LOSS OF BUSINESS OPPORTUNITY, OR CORRUPTION OR LOSS OF DATA, FAILURES TO TRANSMIT OR
RECEIVE ANY DATA, PROBLEMS ASSOCIATED WITH ANY APPLICATIONS USED IN CONJUNCTION WITH RIM PRODUCTS OR SERVICES,
DOWNTIME COSTS, LOSS OF THE USE OF RIM PRODUCTS OR SERVICES OR ANY PORTION THEREOF OR OF ANY AIRTIME SERVICES,
COST OF SUBSTITUTE GOODS, COSTS OF COVER, FACILITIES OR SERVICES, COST OF CAPITAL, OR OTHER SIMILAR PECUNIARY LOSSES,
WHETHER OR NOT SUCH DAMAGES WERE FORESEEN OR UNFORESEEN, AND EVEN IF RIM HAS BEEN ADVISED OF THE POSSIBILITY OF
SUCH DAMAGES.

TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW IN YOUR JURISDICTION, RIM SHALL HAVE NO OTHER OBLIGATION, DUTY,
OR LIABILITY WHATSOEVER IN CONTRACT, TORT, OR OTHERWISE TO YOU INCLUDING ANY LIABILITY FOR NEGLIGENCE OR STRICT
LIABILITY.

THE LIMITATIONS, EXCLUSIONS, AND DISCLAIMERS HEREIN SHALL APPLY: (A) IRRESPECTIVE OF THE NATURE OF THE CAUSE OF
ACTION, DEMAND, OR ACTION BY YOU INCLUDING BUT NOT LIMITED TO BREACH OF CONTRACT, NEGLIGENCE, TORT, STRICT LIABILITY
OR ANY OTHER LEGAL THEORY AND SHALL SURVIVE A FUNDAMENTAL BREACH OR BREACHES OR THE FAILURE OF THE ESSENTIAL
PURPOSE OF THIS AGREEMENT OR OF ANY REMEDY CONTAINED HEREIN; AND (B) TO RIM AND ITS AFFILIATED COMPANIES, THEIR
SUCCESSORS, ASSIGNS, AGENTS, SUPPLIERS (INCLUDING AIRTIME SERVICE PROVIDERS), AUTHORIZED RIM DISTRIBUTORS (ALSO
INCLUDING AIRTIME SERVICE PROVIDERS) AND THEIR RESPECTIVE DIRECTORS, EMPLOYEES, AND INDEPENDENT CONTRACTORS.

IN ADDITION TO THE LIMITATIONS AND EXCLUSIONS SET OUT ABOVE, IN NO EVENT SHALL ANY DIRECTOR, EMPLOYEE, AGENT,
DISTRIBUTOR, SUPPLIER, INDEPENDENT CONTRACTOR OF RIM OR ANY AFFILIATES OF RIM HAVE ANY LIABILITY ARISING FROM OR
RELATED TO THE DOCUMENTATION.

Prior to subscribing for, installing, or using any Third Party Products and Services, it is your responsibility to ensure that your airtime service
provider has agreed to support all of their features. Installation or use of Third Party Products and Services with RIM's products and services
may require one or more patent, trademark, copyright, or other licenses in order to avoid infringement or violation of third party rights. You are
solely responsible for determining whether to use Third Party Products and Services and if any third party licenses are required to do so. If
required you are responsible for acquiring them. You should not install or use Third Party Products and Services until all necessary licenses
have been acquired. Any Third Party Products and Services that are provided with RIM's products and services are provided as a convenience to
you and are provided "AS IS" with no express or implied conditions, endorsements, guarantees, representations, or warranties of any kind by
RIM and RIM assumes no liability whatsoever, in relation thereto. Your use of Third Party Products and Services shall be governed by and
subject to you agreeing to the terms of separate licenses and other agreements applicable thereto with third parties, except to the extent
expressly covered by a license or other agreement with RIM.

The terms of use of any RIM product or service are set out in a separate license or other agreement with RIM applicable thereto. NOTHING IN
THIS DOCUMENTATION IS INTENDED TO SUPERSEDE ANY EXPRESS WRITTEN AGREEMENTS OR WARRANTIES PROVIDED BY RIM FOR
PORTIONS OF ANY RIM PRODUCT OR SERVICE OTHER THAN THIS DOCUMENTATION.

Research In Motion Limited Research In Motion UK Limited

295 Phillip Street 200 Bath Road
Waterloo, ON N2L 3W8 Slough, Berkshire SL1 3XE
Canada United Kingdom

Published in Canada
Contents
1 Tools for creating a BlackBerry device application........................................................................................ 7
Using the BlackBerry Java Development Environment................................................................................7
Prerequisites for using the BlackBerry Java Development Environment...........................................7
Using the BlackBerry JDE Plug-in for Eclipse ...............................................................................................7
Prerequisites for using the BlackBerry JDE Plug-in for Eclipse.......................................................... 8
Development tools............................................................................................................................................ 8
BlackBerry simulators....................................................................................................................................... 9
The BlackBerry Smartphone Simulator .................................................................................................. 9
The BlackBerry MDS simulator................................................................................................................ 9
The BlackBerry email server simulator..................................................................................................10

2 Creating a BlackBerry device application....................................................................................................... 11

Create a basic BlackBerry device application ..............................................................................................11
Create a project for the HelloWorld application in an Eclipse workspace .......................................11
Set the information and type for the project for the HelloWorld application..................................11
Add .java source files to the project for the HelloWorld application................................................ 12
Import resources into HelloWorld.java.................................................................................................. 12
Provide a UI for a HelloWorld application ............................................................................................ 12
Allow the HelloWorld application start sending and receiving events when the application starts
12
Create a screen for the HelloWorld application ..................................................................................13
Allow the HelloWorld application display a screen.............................................................................14
Display a message when a BlackBerry smartphone user closes the HelloWorld application ......14
Test the HelloWorld application in the BlackBerry Smartphone Simulator ....................................14
Code sample: A HelloWorld application ...............................................................................................15
Create a BlackBerry device application with advanced UI features........................................................16
Create a project for a CityInfo application in an Eclipse workspace................................................16
Set the information and type for the project for the CityInfo application ......................................16
Add .java source files to the project for the CityInfo application ..................................................... 17
Import resources into CityInfo.java ....................................................................................................... 17
Provide a UI for the CityInfo application .............................................................................................. 17
Allow the CityInfo application start sending and receiving events when the application starts 17
Create a screen for the CityInfo application ........................................................................................18
 Allow the CityInfo application use a screen that displays a drop-down list of city names...........18
Create a menu item that a BlackBerry smartphone user clicks to display more information about
a city they select .......................................................................................................................................18
Create a menu item that a BlackBerry smartphone user clicks to close a BlackBerry device appli-
cation..........................................................................................................................................................19
Add menu items to the CityInfo application menu .............................................................................19
Create a screen that displays information about a city.....................................................................20
Allow the CityInfo application set the values of UI fields with city information ............................ 21
Test the CityInfo Application in the BlackBerry Smartphone Simulator ......................................... 21
Code sample: A BlackBerry device application that displays information on a city the user selects
22

3 Testing a BlackBerry device application ........................................................................................................25

Obfuscating a BlackBerry device application ............................................................................................ 25
Preverifying a BlackBerry device pplication ............................................................................................... 25
Testing a BlackBerry device application ..................................................................................................... 25
Testing a BlackBerry device application on a BlackBerry Smartphone Simulator ........................26
Testing a BlackBerry device application on a BlackBerry smartphone...........................................26

4 Distributing a BlackBerry device application................................................................................................29

Application distribution through a computer connection ........................................................................29
Distribute an application from a computer .........................................................................................29
Distribute an application from a web page .........................................................................................29
Distribute an application for testing ....................................................................................................29
Application distribution over the wireless network...................................................................................29
Wireless pull (user-initiated)..................................................................................................................30
Wireless push (server-initiated) ............................................................................................................30
 1
Tools for creating a BlackBerry device
application
Using the BlackBerry Java Development Environment
Using the BlackBerry JDE Plug-in for Eclipse
Development tools
BlackBerry simulators

Using the BlackBerry Java Development Environment

You can use the BlackBerry® Java® Development Environment to create, test, and package BlackBerry device
applications for BlackBerry smartphones. The BlackBerry Java Development Environment is a Mobile Information
Device Profile (MIDP) and Connected Limited Device Configuration (CLDC) compliant J2ME environment
designed to provide a complete set of APIs and tools for you to develop a BlackBerry device application that runs
on BlackBerry smartphones. The BlackBerry Integrated Development Environment, included with the BlackBerry
JDE, lets you create a BlackBerry device application using CLDC 1.1 APSI, MIDP 2.0 APIs, and BlackBerry API
extensions that provide additional capabilities specific to BlackBerry smartphones.

Prerequisites for using the BlackBerry Java Development Environment

Your system must meet the following requirements to support the BlackBerry® Java® Development Environment:
• Microsoft® Vista™, Windows® 2000, or Windows XP
• Intel® Pentium® III processor or compatible (800 MHz or higher)
• 512 MB RAM
• 100 MB free hard disk space
• Java® SE Development Kit (JDK) Version 6 (download from the Sun Microsystems web site). The <bin>
directory of the Java SDK must be part of the system's PATH environment variable.
• DirectX 8.0 or greater (for the BlackBerry Smartphone Simulator)

Using the BlackBerry JDE Plug-in for Eclipse

You can use the BlackBerry® Java® Development Environment Plug-In for Eclipse™ to develop, debug and test
BlackBerry device applications from within Eclipse™ and Eclipse-based IDEs. You can use the BlackBerry® JDE
Plug-in for Eclipse™ to develop BlackBerry device applications for BlackBerry smartphones. The BlackBerry® JDE
Plug-in for Eclipse™ contains a subset of the features and components included in the BlackBerry Java
Development Environment.
Getting started guide

Prerequisites for using the BlackBerry JDE Plug-in for Eclipse

Verify that your system meets the following requirements:
• BlackBerry® Java® Development Environment Version 4.3.0 or later.
• BlackBerry® JDE Plug-in for Eclipse™ Version 1.0
• Eclipse™ Classic 3.4
• Microsoft® Windows Vista™, or Windows® XP
• Java® SE Development Kit (JDK) Version 6 (download from the Sun Microsystems web site). The <bin>
directory of the Java SDK must be part of the system's PATH environment variable.
• DirectX 8.0 or greater (for the BlackBerry Smartphone Simulator)

Development tools
The BlackBerry® Java® Development Environment (JDE) and BlackBerry® Java® Development Environment Plug-
In for Eclipse™ include multiple tools that you can use to develop BlackBerry device applications. You can also
obtain these tools by downloading the BlackBerry Java Development Environment Component Package..

Tool Description
RAPC Use the RAPC command prompt compiler to compile .java and .jar files into .cod files that you
can run in the BlackBerry Smartphone Simulator or load onto a BlackBerry smartphone. When
you invoke RAPC, use the "-import=" option to specify the net_rim_api.jar file as an input file.
For example, the following command prompt instruction compiles the SampleApp.jar file into a
.cod file of the same name:
rapc import=net_rim_api.jar codename=SampleApp\SampleAppDriver -
midlet SampleApp.jad Samples\SamplaApp.jar
JavaLoader From a command prompt, use the JavaLoader tool to:
"Add, update, or remove a BlackBerry device aplication on a BlackBerry smartphone for testing
purposes. For production BlackBerry device applications, use the BlackBerry Desktop Software.
"View information about BlackBerry device application .cod files.
To run the JavaLoader tool, type a command with the following format:
javaloader [-u] [-p<port>|<pin>] [-b<baud>] [-d0|-d1] [-w<password>]
[-q] <command>
Signature Tool Use the Signature Tool application to send code signature requests to the BlackBerry Signing
Authority Tool. Send code signature requests when your BlackBerry device application code
requires access to controlled APIs, classes, and methods.
Preverify Use the Preverify tool to partially verify your classes before loading your BlackBerry device
application onto a BlackBerry smartphone. Completing this step will reduce the amount of
processing the smartphone must perform when you load your BlackBerry device application.
The Preverify tool receives a class path as input and produces new classes in an output directory
that you specify.
To run the Preverify tool, from the command prompt, type a command in the following format:
preverify [-d] output -classpath <directory> input; <directory>

8
 1: BlackBerry simulators

Tool Description
JDWP The Java Debug Wire Protocol (JDWP) program lets you debug BlackBerry device applications
using third-party IDEs. The BlackBerry JDE Component Package includes the files that JDWP
requires to debug BlackBerry device applications:
• DefaultBuild.rc: a configuration file
• "FixedBuild.rc: a configuration file
• "Launcher.exe: a utility tool
• "focusFlipper.exe: a utility tool
• RimUsbJni.dll: a helper file that permits the JDWP program to communicate with a
BlackBerry smartphone through a USB port

BlackBerry simulators
The BlackBerry® Java® Development Environment (JDE) and the BlackBerry® Java® Development Environment
Plug-In for Eclipse™ include three different simulators you can use to create and test a BlackBerry device
application for a BlackBerry smartphone. See the BlackBerry Simulator Guide for more information on how to use
BlackBerry Smartphone Simulators.

The BlackBerry Smartphone Simulator

The BlackBerry® Smartphone simulator enables you to run BlackBerry device applications on your computer. The
BlackBerry Smartphone Simulator includes the BlackBerry device applications that are typically available on
BlackBerry smartphones and enables you to load and test your own BlackBerry device applications. You can
simulate and test various connectivity and state changes using the BlackBerry Smartphone Simulator. When you
use the BlackBerry Smartphone Simulator to perform testing, you might need to simulate additional BlackBerry
services. The BlackBerry MDS Simulator and the BlackBerry email server simulator are available for this purpose.
You can obtain BlackBerry Smartphone Simulators by downloading the BlackBerry® Java® Development
Environment, the BlackBerry® Java® Development Environment Plug-In for Eclipse™, or the BlackBerry® Java®
Development Environment Component Package from the BlackBerry Developer Zone web site at http://
www.blackberry.com/developers.

The BlackBerry MDS simulator

The BlackBerry® MDS simulator is designed to simulate the BlackBerry MDS Connection Service component of
the BlackBerry Enterprise Server. Using the BlackBerry Smartphone Simulator with the BlackBerry MDS simulator
enables you to test network, push, and browser applications that are designed for use with a BlackBerry Enterprise
Server. If you are testing BlackBerry device applications that require an HTTP connection, you need the
BlackBerry Smartphone Simulator and the BlackBerry MDS simulator. You can obtain the BlackBerry MDS
simulator by downloading the BlackBerry® Java® Development Environment, the BlackBerry® Java® Development
Environment Plug-In for Eclipse™, or the BlackBerry Email and MDS Services Simulator Package from the
BlackBerry Developer Zone web site at http://www.blackberry.com/developers.

9
Getting started guide

The BlackBerry email server simulator

The BlackBerry® email server simulator is designed to send and receive messages between the BlackBerry
Smartphone Simulator and either a messaging application, such as Microsoft® Outlook®, or POP3 and SMTP
servers. You do not require a BlackBerry® Enterprise Server. You can obtain the BlackBerry email server simulator
by downloading the BlackBerry® Java® Development Environment, the BlackBerry® Java® Development
Environment Plug-In for Eclipse™, or the BlackBerry Email and MDS Services Simulator Package from the
BlackBerry Developer Zone web site at http://www.blackberry.com/developers.

10
 2
Creating a BlackBerry device application
Create a basic BlackBerry device application
Create a BlackBerry device application with advanced UI features

Create a basic BlackBerry device application

In this section, you create a BlackBerry® device application that displays the text ‘Hello World!’ on the BlackBerry
smartphone screen. When a BlackBerry smartphone user selects the Close menu item from the menu of the
BlackBerry device application , the BlackBerry device application displays a dialog box with the text ‘Goodbye!’.

Create a project for the HelloWorld application in an Eclipse workspace

1. On the File menu, click New > Project.
2. Expand the BlackBerry folder.
3. Select BlackBerry project.
4. Click Next.
5. In the Project name field, type HelloWorld.
6. Click Next.
7. Click Finish.

Set the information and type for the project for the HelloWorld application
1. In the Navigator view, select a BlackBerry project.
2. Right-click the project and select Properties.
3. In the Properties for pane, select BlackBerry Project Properties.
4. Click the General tab.
5. In the Title field, type Hello World Sample.
6. In the Version field, type a version number.
7. In the Vendor field, type a vendor name, for example, Research In Motion Ltd.
8. Click the Application tab.
9. In the Project type drop-down list, select the CLDC option.
10. Click OK.
Getting started guide

Add .java source files to the project for the HelloWorld application
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 workspace file is C:\name\ws.jdw and it contains a com.mycompany.MyClass class, then you
must name the project (.java) source file MyClass.java, and store it in C:\name\com\mycompany\MyClass.java.
1. In the Navigator view, select a BlackBerry project.
2. Right-click the project and select Add File to Project.
3. In the File Name field, type HelloWorld.
4. Click Open.

Import resources into HelloWorld.java

The net.rim.device.api.ui package provides a BlackBerry® device application with fundamental functionality
for constructing the UI of a BlackBerry device application.
The net.rim.device.api.ui.component package provides a library of prebuilt interface components and
controls for constructing usable UIs for BlackBerry device application.
The net.rim.device.api.ui.container package provides a library of prebuilt interface component mangers
for constructing a usable UI for BlackBerry device application.
The net.rim.device.api.system package provides a variety of system-level functionality. See
net.rim.device.api.ui in the API Reference for more information.
> In the Text Editor window and underneath the line that begins with the word package, type the following:
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.*;

Provide a UI for a HelloWorld application

1. Modify the HelloWorld class declaration to extend the UiApplication class.
public class HelloWorld extends UiApplication
2. Create a constructor for the HelloWorld class.
public HelloWorld() {
}

Allow the HelloWorld application start sending and receiving events when the
application starts
The UiApplication class is the base class for all BlackBerry® device applications that provide a UI.

12
 2: Create a basic BlackBerry device application

For a BlackBerry device applicaion to provide a UI, the BlackBerry device application must extend the
net.rim.device.api.ui.UiApplication class. This class provides methods for BlackBerry device applications
to register event listeners, manage threads, and manage UI components.
A UI maintains a stack of Screen objects. As it pushes screens onto the stack, it draws them on top of any other
screens already on the stack. When a BlackBerry device application pops a screen off the stack, it redraws the
underlying screens as necessary. Only the screen on the top of the stack receives input events.
See UiApplication in the API Reference for more information.
1. Create a main method for the BlackBerry device application. When you start a BlackBerry device application,
program exectution starts at the main() method.
public static void main(String[] args){
}
2. Within the main() method, add the following code:
HelloWorld theApp = new HelloWorld();
theApp.enterEventDispatcher();
When you invoke the enterEventDispatcher() method using an instance of the BlackBerry device
application, the BlackBerry device application enters the event thread which runs all drawing and event-
handling code and waits for events on the BlackBerry device application queue.

Create a screen for the HelloWorld application

Invoking super() invokes the constructor of the HelloWorldScreen superclass, MainScreen. The MainScreen
class provides a UI screen that contains a title section, a separator element, and a single vertical field manager for
maintaining a list of fields. See MainScreen in the API Reference for more information.
A LabelField lets a BlackBerry® device application display a label on a UI. See LabelField in the API Reference
for more information.
A RichTextField is a read-only text field you can use to show text in a variety of fonts and formats on a screen.
See RichTextField in the API Reference for more information.
Invoking add(RichTextField("Hello World!")) adds the RichTextField to the Manager object of the
HelloWorldScreen screen. See Manager in the API Reference for more information.
1. Create a class that extends the MainScreen class.
final class HelloWorldScreen extends MainScreen {
2. Create a constructor for the HelloWorldScreen class.
public HelloWorldScreen(){
}

13
Getting started guide

3. In the constructor, add the following code:

super();
LabelField title = new LabelField("HelloWorld Sample", LabelField.ELLIPSIS |
LabelField.USE_ALL_WIDTH);
setTitle(title);
add(new RichTextField("Hello World!"));

Allow the HelloWorld application display a screen

The pushScreen() method is inherited from the UiApplication class and pushes a screen onto the display stack
and paints it. The BlackBerry® JVM maintains screens in a display stack. See Screen in the API Reference for more
information.
> In the HelloWorld constructor, add the following code:
//display a new screen
pushScreen(new HelloWorldScreen());

Display a message when a BlackBerry smartphone user closes the HelloWorld

application
The onClose() method is inherited from the Screen class and indicates to an BlackBerry® device application that
a close event has occurred.
The Dialog.alert() method creates an alert dialog box that a BlackBerry device application can use to notify a
BlackBerry smartphone user of an event or some important information. The dialog uses an exclamation mark
bitmap. See Dialog in the API Reference for more information.
> In the HelloWorldScreen class, overide the onClose() method using the following code:
public boolean onClose()
{ Dialog.alert("Goodbye!");
System.exit(0);
return true;
}

Test the HelloWorld application in the BlackBerry Smartphone Simulator

1. From the Run menu, click Run As > BlackBerry Simulator.
2. In the Choose a launch Configuration dialog box, select a launch configuration.
3. Press OK.
4. From the HomeScreen of the BlackBerry® Smartphone Simulator, select and open the HelloWorld . The
BlackBerry device application displays the text HelloWorld!.
5. From the FullMenu of the BlackBerry device application, select the Close menu item. The BlackBerry device
application displays a dialog with the text Goodbye!.

14
 2: Create a basic BlackBerry device application

6. Close the BlackBerry device application.

Code sample: A HelloWorld application

The following sample code pulls together the tasks in this section into an BlackBerry® device application that
displays the text ‘Hello World!’ on the BlackBerry smartphone screen and displays a dialog box with the text
‘Goodbye!’ when the BlackBerry device application closes.

Example: /**
* HelloWorld.java
* Copyright (C) 2001-2008 Research In Motion Limited. All rights reserved.
*/
package com.rim.samples.helloworld;

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.*;

/*
* BlackBerry device applications that provide a UI
* must extend the UiApplication class.
*/
public class HelloWorld extends UiApplication
{
public static void main(String[] args)
{
//Create a new instance of the BlackBerry device pplication
//and start the BlackBerry device application on the event thread.
HelloWorld theApp = new HelloWorld();
theApp.enterEventDispatcher();
}
public HelloWorld()
{
//Display a new screen.
pushScreen(new HelloWorldScreen());
}
}

//Create a new screen that extends MainScreen and provides

//behaviour similar to that of other BlackBerry device applications.
final class HelloWorldScreen extends MainScreen
{
public HelloWorldScreen()
{

//Invoke the MainScreen constructor.

super();

//Add a title to the screen.

LabelField title = new LabelField("HelloWorld Sample", LabelField.ELLIPSIS
| LabelField.USE_ALL_WIDTH);
setTitle(title);

15
Getting started guide

//Add the text "Hello World!" to the screen.

add(new RichTextField("Hello World!"));
}

//To display a dialog box to a BlackBerry smartphone user with the text
//"Goodbye!" when the BlackBerry smartphone user closes the BlackBerry device
application, override the onClose() method.
public boolean onClose()
{
Dialog.alert("Goodbye!");
System.exit(0);
return true;
}
}

Create a BlackBerry device application with advanced UI

features
Create a project for a CityInfo application in an Eclipse workspace
1. On the File menu, click New > Project.
2. Expand the BlackBerry folder.
3. Select BlackBerry project.
4. Click Next.
5. In the Project name field, type CityInfo.
6. Click Next.
7. Click Finish.

Set the information and type for the project for the CityInfo application
1. In the Navigator view, select a BlackBerry project.
2. Right-click the project and select Properties.
3. In the Properties for pane, select BlackBerry Project Properties.
4. Click the General tab.
5. In the Title field, type City Info Sample.
6. In the Version field, type a version number.
7. In the Vendor field, type a vendor name, for example, Research In Motion Ltd.
8. Click the tab.
9. In the Project type drop-down list, select the CLDC option.

16
 2: Create a BlackBerry device application with advanced UI features

10. Click OK.

Add .java source files to the project for the CityInfo application
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 workspace file is C:\name\ws.jdw and it contains a com.mycompany.MyClass class, then you
must name the project (.java) source file MyClass.java, and store it in C:\name\com\mycompany\MyClass.java.
1. In the Navigator view, select a BlackBerry project.
2. Right-click the project and select Add File to Project.
3. In the File Name field, type CityInfo.
4. Click Open.

Import resources into CityInfo.java

The net.rim.device.api.i18n package provides support for the internationalization of BlackBerry® device
application. See net.rim.device.api.i18n in the API Reference for more information.
> In the Text Editor window and underneath the line that begins with the word package, type the following:
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.*;

Provide a UI for the CityInfo application

1. Modify the CityInfo class declaration to extend the UiApplication class.
public class CityInfo extends UiApplication
2. Create a constructor for the CityInfo class.
public CityInfo() {
}

Allow the CityInfo application start sending and receiving events when the
application starts
1. Create a main method for the BlackBerry® device application.
public static void main(String[] args){
}

17
Getting started guide

2. Within the main() method, add the following code:

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

Create a screen for the CityInfo application

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

Allow the CityInfo application use a screen that displays a drop-down list of
city names
1. In the class that extends the MainScreen class, create the following instance variables.
private InfoScreen _infoScreen;
private ObjectChoiceField choiceField;
private int select;
2. In the constructor for the extension of the MainScreen class, replace the String information in the
constructor for the LabelField with "City Information Kiosk".
LabelField title = new LabelField("City Information Kiosk",
LabelField.ELLIPSIS | LabelField.USE_ALL_WIDTH);
setTitle(title);
3. In the constructor for the extension of the MainScreen class, change add(new RichTextField("City
Info")) to add(new RichTextField("Major U.S. Cities")).
4. In the constructor for the extension of 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®
smartphone user can choose from.
String choices[] = {"Los Angeles", "Chicago", "New York"};
choiceField = new ObjectChoiceField("Select a City", choices);
5. Add the choiceField to the Manager object of the CityInfoScreen screen.
add(choiceField);
You can use an ObjectChoiceField to display a list of choices in a field on the UI of a BlackBery device
application. See ObjectChoiceField in the API Reference for more information.

Create a menu item that a BlackBerry smartphone user clicks to display more
information about a city they select
When a BlackBerry® smartphone user selects a menu item from the menu of a BlackBerry device application, the
code in the run() method for the menu item executes. See MenuItem in the API Reference for more information.

18
 2: Create a BlackBerry device application with advanced UI features

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

1. In the CityInfoScreen class, create a MenuItem with text that reflects the action that occurs when a
BlackBerry smartphone 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 a city
a BlackBerry smartphone user selects.
public void run() {
//Store the index for the city a BlackBerry smartphone user selects
select = choiceField.getSelectedIndex();
//Create an instance of the screen that displays information about a city the BlackBerry
smartphone user selects
_infoScreen = new InfoScreen();
//Push the screen with information on the city the BlackBerry smartphone user selects to
the display stack and paint this screen
UiApplication.getUiApplication.pushScreen(_infoScreen);
}

Create a menu item that a BlackBerry smartphone user clicks to close a

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

Add menu items to the CityInfo application menu

The makeMenu()method is inherited from the MainScreen class and lets a BlackBerry® device application add
menu items to a menu. If you override the makeMenu() method, to add the menu items of the main screen to the
menu of the BlackBerry device application, you must call this method on the parent class.

19
Getting started guide

> 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. To display a label with the name of the city the BlackBerry® smartphone user selects, in the constructor for
the inner class, create a LabelField.
LabelField lf = new LabelField();
4. To display the population of the city the BlackBerry smartphone 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. To display the state that the city the BlackBerry smartphone user selects is located in, in the constructor for
the inner class, create a BasicEditField.
BasicEditField stateField = new BasicEditField("State: ", null, 20, Field.READONLY);
6. To display tourist attraction information for the city the BlackBerry smartphone user selects, in the
constructor for the inner class, create a BasicEditField .
BasicEditField sightsField = new BasicEditField("Sights: ", null, 50, Field.READONLY);
To add 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);
A BasicEditField is an editable simple text field with no formatting. See BasicEditField in the API
Reference for more information.

20
 2: Create a BlackBerry device application with advanced UI features

Allow the CityInfo application set the values of UI fields with city information
> In the constructor for the inner class, use a select clause to control the actions that the BlackBerry® device
application performs when a BlackBerry smartphone user selects a city from the menu of the BlackBerry
device application. Invoke BasicEditField.setText() to set the text value of a BasicEditField.
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 Application in the BlackBerry Smartphone Simulator

1. From the Run menu, click Run As > BlackBerry Simulator.
2. In the Choose a launch Configuration dialog box, select a launch configuration.
3. Press OK.
4. From the HomeScreen of the BlackBerry® Smartphone Simulator, select and open the CityInfo.
5. From the FullMenu of the BlackBerry device application, select a city.
6. From the FullMenu of the BlackBerry device application , select More Info.
7. From the FullMenu of the BlackBerry device application, select the Close menu item.

21
Getting started guide

Code sample: A BlackBerry device application that displays information on a

city the user selects
Example: /**
* CityInfo.java
* Copyright (C) 2001-2008 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 BlackBerry® device application
//and start the BlackBerry device application 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 BlackBerry device applications.
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:

22
 2: Create a BlackBerry device application with advanced UI features

//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 smartphone user

//closes the BlackBerry device application, override the onClose() method.
public boolean onClose()
{
Dialog.alert("Goodbye!");
System.exit(0);
return true;
}

//Create a menu item for BlackBerry smartphone 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 smartphone user selects
_infoScreen = new InfoScreen();
UiApplication.getUiApplication.pushScreen(_infoScreen);

}
};

//Create a menu item for BlackBerry smartphone users to click to close the
BlackBerry device application.
private MenuItem _closeItem = new MenuItem("Close", 200000, 10) {
public void run()
{
onClose();
}
};

//To add menu items to the menu of the BlackBerry device application, 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 smartphone 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.

23
Getting started guide

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

24
 3
Testing a BlackBerry device application
Obfuscating a BlackBerry device application
Preverifying a BlackBerry device pplication
Testing a BlackBerry device application

Obfuscating a BlackBerry device application

The compiler in the BlackBerry® Java® Development Environment and the BlackBerry® JDE Plug-in for Eclipse™ is
set to minimize the size of the application. The .cod file that results provides services that are similar to those that
obfuscation packages provide in an effort to reduce the size of the .cod file. For example, the BlackBerry Java
Development Environment removes the following information from a .cod file:
• all debug information
• local variable names
• source
• private method and member names
As such, RIM does not believe it is necessary for you to provide obfuscation for your applications in addition to the
existing obfuscation that, by default, the BlackBerry® Java® Development Environment and the BlackBerry® JDE
Plug-in for Eclipse™ provide for all applications. In fact, Research In Motion does not perform any additional
obfuscation of its own products.
The BlackBerry® Java® Development Environment and the BlackBerry® JDE Plug-in for Eclipse™ do not integrate
support for obfuscation through third-party tools. As such, you must include a command-line procedure to
obfuscate .cod files for use on BlackBerry smartphones.

Preverifying a BlackBerry device pplication

To partially verify your classes before you load your application on a BlackBerry® smartphone, use the Preverify
tool. When you preverify your classes, you reduce the amount of processing that the BlackBerry smartphone must
perform when you load your application.
For more information on using the Preverify tool, see the online help for the BlackBerry® Java® Development
Environment or the BlackBerry® JDE Plug-in for Eclipse™.

Testing a BlackBerry device application

When you build a project using the BlackBerry® Java® Development Environment or the BlackBerry® JDE Plug-in
for Eclipse™, source files compile into Java® bytecode, preverification of source files occurs, and a single .cod file
and .jad file is created for the BlackBerry device application.
Getting started guide

If a BlackBerry device application contains more than 64 KB of bytecode or resource data, the BlackBerry® Java®
Development Environment or the BlackBerry® JDE Plug-in for Eclipse™ creates a .cod file that contains sibling
.cod files. To determine if a .cod file contains sibling .cod files, extract the contents of the .cod file. Any .cod files
within the original .cod file are the sibling files.

Testing a BlackBerry device application on a BlackBerry Smartphone

Simulator
After you develop and compile your application, you can test it on the BlackBerry® smartphone. The most common
first step is to set the BlackBerry® Java® Development Environment or the BlackBerry® JDE Plug-in for Eclipse™
to use a BlackBerry Smartphone Simulator for testing. The BlackBerry Smartphone Simulators run the same Java
code as the live BlackBerry smartphones, so the BlackBerry Smartphone Simulators provide an accurate
environment for testing how applications will function on a live BlackBerry smartphone. Each version of the
BlackBerry JDE comes with the BlackBerry Smartphone Simulators that were available when that version of the
BlackBerry® Java® Development Environment or the BlackBerry® JDE Plug-in for Eclipse™ was made public. You
can download additional BlackBerry Smartphone Simulators from the BlackBerry Developer Zone at http://
www.blackberry.com/developers/index.shtml.

Testing a BlackBerry device application on a BlackBerry smartphone

To load, remove, or save .cod files when testing BlackBerry® device applications, use the JavaLoader.exe tool. For
production applications, use the BlackBerry® Desktop Software. The JavaLoader.exe tool is part of the
BlackBerry® Java® Development Environment and the BlackBerry® JDE Plug-in for Eclipse™.
The Javaloader.exe tool uses the following parameters:

Parameter Description
port A BlackBerry smartphone PIN if the BlackBerry smartphone connects to a USB port. You must also specify the -usb
option.
password This paramter specifies the password for the BlackBerry smartphone, if a password for the BlackBerry smartphone is
set.
filename The name of the .cod file for the BlackBerry device application.

1. Connect the BlackBerry smartphone to the computer.

2. Open a command prompt, and navigate to the location of the JavaLoader.exe file.
3. Perform one of the following actions:

Task Steps
Load a BlackBerry device application .cod file on > Issue a command using the following format:
the BlackBerry smartphone. javaloader [-u] load .cod file
For example: javaloader.exe -u load My.cod
JavaLoader loads the .cod files listed in the .jad file on the BlackBerry smartphone
and stores the .cod files in a CodeModuleGroup.

26

Task
Load BlackBerry device application .cod files
listed in the same .jad file on the BlackBerry
smartphone.
Remove a BlackBerry device application .cod file >
from the BlackBerry smartphone.
Save a BlackBerry device application .cod file
from the BlackBerry smartphone to your
computer.
Save BlackBerry device application .cod files
listed in the same .jad file from the BlackBerry
smartphone to your computer.
Save BlackBerry device application .cod files
stored in the same CodeModuleGroup from the
BlackBerry smartphone to your computer.
3: Testing a BlackBerry device application
Steps
> Issue a command using the following format:
javaloader [-u] load .jad file
For example: javaloader.exe -u load My.jad
Javaloader loads the .cod files listed in the .jad file onto the BlackBerry
smartphone.
Issue a command using the following format:
javaloader [-u] erase [-f] module
For example: javaloader.exe -u erase My
> Issue a command using the following format:
javaloader save .cod file
For example: javaloader.exe save My.cod
> Issue a command using the following format:
javaloader save .jad file
For example: javaloader.exe save My.jad
> Issue a command using the following format:
javaloader save [-g] module
For example: javaloader.exe save -g My
27
Getting started guide

28
 4
Distributing a BlackBerry device application
Application distribution through a computer connection
Application distribution over the wireless network

Application distribution through a computer connection

Distribute an application from a computer
The BlackBerry® Desktop Manager includes a component called the Application Loader, that installs BlackBerry
device applications as well as updated system applications for the BlackBerry smartphone. The BlackBerry
Desktop Manager Application Loader approach provides a simple way for end users to download an application
from computers to BlackBerry smartphones.

Distribute an application from a web page

With the BlackBerry® Application Web Loader, you can post your compiled application on a central web site and
users can se tup the application by using Internet Explorer on their computers to the visit URL. When BlackBerry
smartphone users visit the web page, The BlackBerry Application Web Loader asks them to connect their
smartphones to the USB port. They can then install the application using an ActiveX® control. The BlackBerry
Web Loader provides BlackBerry smartphone users with a simple approach for setting up applications from their
computers without running the BlackBerry Desktop Manager.

Distribute an application for testing

The BlackBerry® Java® Development Environment and the BlackBerry® Java® Development Environment Plug-In
for Eclipse™ include a command line tool called Javaloader.exe. The executable file exists in the BIN directory
under the BlackBerry JDE directory. Use the Javaloader file to quickly install and remove compiled application
files on the BlackBerry smartphone directly over the USB port and does not require any descriptor files or web
pages. Javaloader can be useful when you are installing and removing your application frequently during testing
and development; however, the Javaloader tool is not designed for use by BlackBerry smartphone users.

Application distribution over the wireless network

Using wireless provisioning can provide a better experience to BlackBerry® smartphone users and simplify
sending the applications to a large group of people since you do not require a computer. A BlackBerry smartphone
user can install an application over the wireless network:
Getting started guide

Wireless pull (user-initiated)

You can post a compiled applications on a public or private web site, and BlackBerry® smartphone users can
download the applications over the wireless network by using the web browser on their BlackBerry smartphones
to visit the URL. When BlackBerry smartphone users visit the URL, the browser prompts them to install the
application. If the BlackBerry smartphone users accept, the application downloads over the wireless connection
and installs immediately.

Wireless push (server-initiated)

In an enterprise environment, the BlackBerry® Enterprise Server administrator can push applications to
BlackBerry smartphone users over the wireless network and enforce that the application installs. The
administrator creates a new policy and indicates that the BlackBerry smartphone requires the application. Once
the policy is setup on the BlackBerry Enterprise Server, the application is pushed to users without any user
interaction required. Enterprises might find this approach useful when sending new wireless applications to a
large number of BlackBerry smartphone users.

30
©2008 Research In Motion Limited
Published in Canada.