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.

Events

Events are generated on a BlackBerry device in response to specific situations that occur on the device, including the following:

  • User input, such as pressing a key, clicking the trackball or trackpad, or touching the screen
  • System status, such as wireless coverage changes, low battery power, or backlight changes
  • Messages from other applications on the device

BlackBerry device applications that you create are typically event-driven, meaning that they monitor the device for particular events and respond accordingly. For example, if your application includes a UI with fields that a BlackBerry device user can click, your application should respond with appropriate actions when the user clicks the fields, such as displaying a new screen.

Using listeners

You can use listeners in your applications to respond to events that occur on a BlackBerry device. You can register your application as a listener for different types of events. You might want your application to close automatically if the battery level reaches a certain point, or to provide different options if the device is connected to a computer using a USB connection. You can also use listeners to monitor global events on the device and use these global events to communicate between processes. You can create your own listeners if the ones that are provided in the BlackBerry Java SDK don't suit your needs.

To be enabled as a listener, your application must implement one or more listener interfaces (for example, CoverageStatusListener or GlobalEventListener). The following table describes some common listener interfaces and the events that they listen for.

Interface

Description

SystemListener2

You can use this listener to listen for system events, such as changes to the state of the backlight or changes to the state of the USB connection.

GlobalEventListener

You can use this listener to listen for global events, such as changes to the time zone or events that are associated with interprocess communication.

CoverageStatusListener

You can use this listener to listen for changes to wireless transports, such as HTTP over WAP or the BlackBerry Mobile Data System.

WLANConnectionListener

You can use this listener to listen for changes to Wi-Fi connectivity.

LowMemoryListener

You can use this listener to determine when the amount of available memory is low.

You can also use listeners to respond to changes in fields in your application. For example, when a BlackBerry device user clicks a button in your application, you can use a listener to respond to this event by displaying a new screen. Classes that you create to handle changes to fields should implement the FieldChangeListener interface. You can set a listener for a Field object by invoking setChangeListener() of the Field class.

If you choose to use listeners in your application, it's important to remember to deregister the listeners that you use when you are done with them. For example, you can remove a FieldChangeListener from a Field object by invoking setChangeListener() with a null parameter. If you don't deregister a listener, a reference to the listener remains in memory on the device, and your application is not properly terminated.

Code sample: Adding a generic listener for a field

import net.rim.device.api.ui.UiApplication;
import net.rim.device.api.ui.container.MainScreen;

import net.rim.device.api.ui.Field;
import net.rim.device.api.ui.FieldChangeListener;
import net.rim.device.api.ui.component.ButtonField;

public class GenericListenerDemo extends UiApplication
{
    public static void main(String[] args)
    {
        GenericListenerDemo theApp = new GenericListenerDemo();
        theApp.enterEventDispatcher();
    }

    public GenericListenerDemo()
    {        
        pushScreen(new GenericListenerDemoScreen());
    } 
}

class GenericListenerDemoScreen extends MainScreen
{
    public GenericListenerDemoScreen()
    {              
        setTitle("Generic Listener Demo");
        
//In the screen constructor, create a new ButtonField object to 
//add the listener for.
        ButtonField firstButton = new ButtonField("Click me.");

//Invoke setChangeListener() to add a new instance of the 
//FieldChangeListener class as the listener for the ButtonField object.
        firstButton.setChangeListener(new FieldChangeListener()
        {

//Implement fieldChanged() inline and specify the action that should 
//occur when the BlackBerry device user clicks the button. In this 
//example, the label of the button changes when the user clicks the button.
            public void fieldChanged(Field field, int context)
			         {
				            ((ButtonField) field).setLabel("Clicked!");
			         }
        });
        
//Add the ButtonField object to the screen.
        add(firstButton);
    }
}

Code sample: Adding a custom listener for a field

In this code sample, the Field object that is passed to fieldChanged() as a parameter is tested to determine if it is a ButtonField object. When you create a custom listener, you can perform this check to use the same listener class to listen for events from multiple types of fields.

import net.rim.device.api.ui.UiApplication;
import net.rim.device.api.ui.container.MainScreen;

import net.rim.device.api.ui.Field;
import net.rim.device.api.ui.FieldChangeListener;
import net.rim.device.api.ui.component.ButtonField;

public class CustomListenerDemo extends UiApplication
{
    public static void main(String[] args)
    {
        CustomListenerDemo theApp = new CustomListenerDemo();       
        theApp.enterEventDispatcher();
    }
    
    public CustomListenerDemo()
    {        
        pushScreen(new CustomListenerDemoScreen());
    }    
}

class CustomListenerDemoScreen extends MainScreen
{
    public CustomListenerDemoScreen()
    {            
        setTitle("Custom Listener Demo");
        
//In the screen constructor, create three new ButtonField objects to add listeners for.
        ButtonField firstButton = new ButtonField("Click me, I'm first.");
        ButtonField secondButton = new ButtonField("No, click me, I'm second.");
        ButtonField thirdButton = new ButtonField("Hold on, click me, I'm third.");
        
//Create a listener object to add as a listener for the 
//ButtonField objects. In this task, the MyCustomListener class 
//represents the custom listener.
        MyCustomListener listener = new MyCustomListener();
        
//Invoke setChangeListener() to add the MyCustomListener object 
//as the listener for the ButtonField objects.
        firstButton.setChangeListener(listener);
        secondButton.setChangeListener(listener);
        thirdButton.setChangeListener(listener);
        
//Add the ButtonField objects to the screen.
        add(firstButton);
        add(secondButton);
        add(thirdButton);
    }
}

//Create the MyCustomListener class. Make sure that this 
//class implements the FieldChangeListener interface.
class MyCustomListener implements FieldChangeListener
{

//Implement fieldChanged() and specify the action that should 
//occur when the BlackBerry device user clicks the buttons. In this 
//example, the label of the button changes when the user clicks the button.
    public void fieldChanged(Field field, int context)
    {
        if (field instanceof ButtonField)
        {
            ((ButtonField) field).setLabel("Clicked!");
        }
    }
}