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.

Device Capability API

You can query the capabilities of a BlackBerry device by using the Device Capability API that is provided in the net.rim.device.api.system.capability package. You can use the DeviceCapability class to query whether specific features, such as a virtual keyboard or a physical keyboard, are supported on the device, whether the feature is currently available to the BlackBerry device user (for example, if the slider on a device is open and the user can use the physical keyboard), and whether your application can currently access the feature.

For example, DeviceCapability.isVirtualKeyboardAvailable() returns true if the device has a virtual keyboard currently displayed. Otherwise the method returns false.

You can define a listener to notify your application of changes to the specified capabilities of the device by implementing the DeviceCapabilityListener interface.

For an example of how to use the Device Capability API, see the cradle detection section below.

For more information about the Device Capability API, see the API reference for the .

Cradle detection

You can detect when a BlackBerry device is connected to a cradle (such as a car kit cradle) by using the DeviceCapability.TYPE_CRADLE capability type that is part of the Device Capability API.

You can use DeviceCapability.isSupported() and DeviceCapability.isAvailable() to detect the cradle status. Devices that are running BlackBerry Device Software 6.0 return true for isSupported(DeviceCapability.TYPE_CRADLE). When a device that is running BlackBerry Device Software 6.0 is connected to a cradle, isAvailable(DeviceCapability.TYPE_CRADLE) returns true.

When you detect a cradle connection, you can use the CradleProtocol class to detect the cradle type and properties. CradleProtocol is provided in the net.rim.device.api.accessory package. The class provides fields for a cradle's type (such as a car kit cradle, a holster, or a charging pod) and a cradle's properties (such as whether a cradle has a light or buttons that can be changed programmatically).

CradleProtocol.getCradleType() returns the cradle type that the cradle itself provides. A cradle might not provide its precise type. For example, a car kit cradle might return CradleProtocol.TYPE_SIMPLE, instead of CradleProtocol.TYPE_CAR_KIT.

The following code sample tests whether the device is connected to a cradle. If it is, the type of cradle is displayed.

import net.rim.device.api.accessory.CradleProtocol;
import net.rim.device.api.system.capability.DeviceCapability;
import net.rim.device.api.ui.component.RichTextField;
import net.rim.device.api.ui.container.MainScreen;

class CradleDemoScreen extends MainScreen 
{
    public CradleDemoScreen()
    {   
        setTitle("Cradle Demo");
        RichTextField statusField = new RichTextField();
        add(statusField);
        
        boolean isConnected = 
            DeviceCapability.isAvailable(DeviceCapability.TYPE_CRADLE);
        
        if (isConnected)
        {
            CradleProtocol myCradle = CradleProtocol.getInstance();
            int cradleType = myCradle.getCradleType();
            
            switch (cradleType)
            {
                case CradleProtocol.TYPE_CAR_KIT:
                    statusField.setText("Device is connected to a car kit cradle.");
                    break;
                case CradleProtocol.TYPE_AUDIO:
                    statusField.setText("Device is connected to an audio cradle.");
                    break;
                case CradleProtocol.TYPE_BEDSIDE:
                    statusField.setText("Device is connected to a charging pod cradle.");
                    break;
                case CradleProtocol.TYPE_CHARGER:
                    statusField.setText("Device is connected to a charger cradle.");
                    break;
                case CradleProtocol.TYPE_DESKTOP:
                    statusField.setText("Device is connected to a desktop cradle.");
                    break;
                case CradleProtocol.TYPE_HOLSTER:
                    statusField.setText("Device is connected to a holster cradle.");
                    break;
                case CradleProtocol.TYPE_MULTIMEDIA:
                    statusField.setText("Device is connected to a multimedia cradle.");
                    break;
                case CradleProtocol.TYPE_SIMPLE:
                    statusField.setText("Device is connected to a simple cradle.");
                    break;
                default:
                    statusField.setText("Can't determine type of cradle.");
            }
        }
        else
        {
            statusField.setText("Device is not connected.");
        }
    }            
}

Cradle handling

You can register your application as a cradle handler. A cradle handler is an application that can start when a BlackBerry device is connected to a cradle of a specified type. For example, if your application provides local travel information, you might want to register it as a handler for a car kit cradle, so that it can start automatically when the device is connected to a car kit cradle.

To register your application as a cradle handler, use CradleHandlerRegistry.registerHandler(). The CradleHandlerRegistry class is provided in the net.rim.blackberry.api.cradle package. When you register your application, you specify the type of cradle that you want to handle and your application descriptor. Cradle types are defined as fields in the CradleProtocol class that is provided in the net.rim.device.api.accessory package.

Registration as a cradle handler is persistent. You need to register your application only once after it is installed on the device.

If any handlers are registered for a cradle type, the user is presented with a dialog box when that type of cradle is connected.


This diagram shows an example dialog box.

The user can select which handler to use, if any, and the selected handler application is started. The user can also indicate that the selected handler application should start automatically the next time the cradle of the specified type is connected.

The user can change the cradle handler settings on the device by clicking Options > Third Party Applications on the Home screen.

The following code sample registers the current application as a handler for car kit cradles.

CradleHandlerRegistry.registerHandler(
   CradleProtocol.TYPE_CAR_KIT, 
   ApplicationDescriptor.currentApplicationDescriptor());

Working with sensors on a device

You can use the Sensor class that is included in the net.rim.device.api.system package, to determine the existence and the states of sensors on a BlackBerry device. Sensors that you can work with include the holster sensors, slider sensors, and flip sensors.

You can use the SensorListener class that is also included in net.rim.device.api.system, to let a BlackBerry device application receive notifications when the state of a sensor changes.

import net.rim.device.api.system.*;
import net.rim.device.api.ui.UiApplication;
import net.rim.device.api.ui.component.RichTextField;
import net.rim.device.api.ui.container.MainScreen;

public class SensorDemo extends UiApplication 
{
    public SensorDemo() 
    {
        SensorDemoScreen screen = new SensorDemoScreen();
        pushScreen(screen);
    }
    public static void main(String[] args) 
    {
        SensorDemo app = new SensorDemo();
        app.enterEventDispatcher();
    }

//Create a class that implements the SensorListener interface.
    class SensorDemoScreen extends MainScreen implements SensorListener 
    {
        private RichTextField statusField1;
        private RichTextField statusField2;

        public SensorDemoScreen() 
        {
            setTitle("Sensor Demo");
            statusField1 = new RichTextField();
            statusField2 = new RichTextField();
            add(statusField1);
            add(statusField2);

//Invoke Sensor.isSupported() and specify the type of sensor
//that you want to check for. The sensor types are defined as 
//constants in the Sensor class. This code sample checks 
//to see whether a device has a slider.   
            boolean hasFlipSensor, hasHolsterSensor, hasSliderSensor;

//The method returns true if the device contains the specified sensor,
//and returns false otherwise.
            hasFlipSensor = Sensor.isSupported(Sensor.FLIP);
            hasHolsterSensor = Sensor.isSupported(Sensor.HOLSTER);
            hasSliderSensor = Sensor.isSupported(Sensor.SLIDE);
            statusField1.setText("Flip: " + hasFlipSensor + "\nHolster: "
                    + hasHolsterSensor + "\nSlider: " + hasSliderSensor + "\n");
            // Check for the state of a sensor
            if (Sensor.isSupported(Sensor.SLIDE)) 
            {

//Invoke Sensor.getState() and specify the type of sensor
//that you want to check. The sensor types are defined as 
//constants in the Sensor class. This code sample 
//checks the state of the slider on a BlackBerry
//device.
                int sliderState = Sensor.getState(Sensor.SLIDE);
                switch (sliderState)

//The method returns the sensor's state as an int constant. 
//The constants that can be returned are defined in the 
//Sensor class. You can use this method to determine 
//whether the sensor is in a given state: Sensor.isSlideClosed(), 
//Sensor.isSlideOpen(), Sensor.isSlideInTransition(). 
                {
                    case Sensor.STATE_SLIDE_CLOSED:
                        // do something if slider is closed
                        statusField2.setText("Slider is closed.");
                        break;
                    case Sensor.STATE_SLIDE_IN_TRANSITION:
                        // do something if slider in transition
                        statusField2.setText("Slider is between open and closed.");
                        break;
                    case Sensor.STATE_SLIDE_OPEN:
                        // do something if slider is open
                        statusField2.setText("Slider is open.");
                        break;
                    default:
                        statusField2.setText("Can't determine state of slider.");
                }
            }

//Invoke SensorListener.addListener() to add the listener to
//your application. Specify the application, the listener to add, 
//and the types of sensor changes to listen for. This code 
//sample adds a listener for slider changes to the current application. 
//You can invoke Sensor.removeListener() to remove a listener.
            Sensor.addListener(Application.getApplication(), this,
                    Sensor.SLIDE);
        }

//In the class, implement SensorListener.onSensorUpdate() and perform actions
//based on the type of sensor (the method's first parameter) and the new 
//state of the sensor (the second parameter). The following code sample 
//checks the state of the slider on a BlackBerry device.
        public void onSensorUpdate(int sensorID, int update) 
        {
            if (sensorID == Sensor.SLIDE) 
            {
                if (update == Sensor.STATE_SLIDE_OPEN) 
                {
                    // do something if slider is now open
                    statusField2.setText("Slider is now open.");
                } 
                else if (update == Sensor.STATE_SLIDE_IN_TRANSITION) 
                {
                    // do something if slider is now transitioning
                    statusField2.setText("Slider state is changing.");
                }
                else if (update == Sensor.STATE_SLIDE_CLOSED) 
                {
                    // do something if slider is now closed
                    statusField2.setText("Slider is now closed.");
                }
            }
        }
    }
//To listen for changes to multiple sensors, update the third
//argument of addListener() to add additional sensor state flags.
}