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 a basic app

Following this tutorial, you will create an app that displays the text ‘Hello World!’ on the BlackBerry device screen. When a BlackBerry device user selects Close from the menu of the Hello World app, the Hello World app displays a dialog box with the text ‘Goodbye!’.

Create a project for the Hello World app

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

Specify the Application type and properties for the HelloWorld application project

  1. In the Package Explorer view, expand a BlackBerry project.
  2. Double-click the BlackBerry_App_Descriptor.xml file.
  3. Click the Application tab and enter the following information.
    • In the Title field, type HelloWorld 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.
  4. Click Close.
  5. Click Yes.

Add Java source files to the HelloWorld 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 one of the following folders:

  • For Windows:...\HelloWorld\src\com\mycompany\MyClass.java
  • For Mac: .../HelloWorld/src/com/mycompany/MyClass.java.

To add the Java source files to the project, follow these steps:

  1. In the Package Explorer view, right-click the HelloWorld project. Click New > Class.
  2. In the Name field, type HelloWorld.
  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 HelloWorld 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 a BlackBerry device application.

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

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

The net.rim.device.api.i18n package provides support for the internationalization of a BlackBerry device application.

In Eclipse, 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 Hello World app

The UiApplication class is the base class for all apps 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. Only the screen that is on the top of the stack receives input events.

  • Within the main() method, create the HelloWorld object and start the event dispatcher:
    HelloWorld theApp = new HelloWorld();
    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 HelloWorld project.

Create a screen for the Hello World app

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.

A LabelField allows an app to display a label on a UI.

A RichTextField is a read-only text field that you can use to display text in a variety of fonts and formats on a BlackBerry device screen.

Invoking add(RichTextField("Hello World!")) adds the RichTextField to the Manager object of the HelloWorldScreen screen.

  1. Create a class that extends the MainScreen class.
    final class HelloWorldScreen extends MainScreen {
    }
  2. Create a constructor for the HelloWorldScreen class.
    public HelloWorldScreen(){
    }
    
  3. In the constructor, add the code to create and display the title and text field.
    super();
    LabelField title = new LabelField("HelloWorld Sample", LabelField.ELLIPSIS
     | LabelField.USE_ALL_WIDTH);
    setTitle(title);
    add(new RichTextField("Hello World!"));
    

Display a screen in the Hello World app

In the HelloWorld constructor, add the code that displays a screen:

pushScreen(new HelloWorldScreen());

The HelloWorld constructor is created automatically if you select Constructors from superclass when you add new .java files to the Hello World project.

The pushScreen() method is inherited from the UiApplication class and pushes a screen onto the display stack and paints it. The BlackBerry Java Virtual Machine maintains screens in a display stack.

Display a message when the Hello World app closes

The onClose() method is inherited from the Screen class and indicates to a BlackBerry device application that a close event has occurred.

The Dialog.alert() method creates an alert dialog box that an app can use to notify a BlackBerry device user of an event or important information. The dialog displays an exclamation mark bitmap.

In the HelloWorldScreen class, override the onClose()method to create an alert dialog box and display text.

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

Test the Hello World 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 Hello World app.
    • The Hello World app displays the text HelloWorld!.
  4. On the menu of the Hello World app, click Close.
    • The Hello World app displays a dialog box with the text Goodbye!.
  5. Click OK.

Code sample: Creating a Hello World app

/**
* HelloWorld.java
* Copyright (C) 2012 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.*;

/*
* Apps 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 app
          //and start the app 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 apps.

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);

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

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

     //To display a dialog box to a BlackBerry device user with the text
     //"Goodbye!" when the BlackBerry device user closes the app, 
     //override the onClose() method.

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