Application Integration

This category contains the packages that you can use to integrate your applications with the BlackBerry Device Software applications, such as the contacts application, the phone application, and the media application.

Invoking BlackBerry Device Software applications from your application [back to top]

Using the Invoke API

Package: net.rim.blackberry.api.invoke

You can use the BlackBerry Invoke API to invoke BlackBerry Device Software applications and optionally pass in data. To use this API, invoke invokeApplication() and pass in the application type and any relevant arguments. You can use the Invoke API to invoke the following BlackBerry Device Software applications:

Invoke contains APP_TYPE fields that enumerate the applications.

For each BlackBerry Device Software application that can be invoked with the Invoke API, there is a corresponding subclass of the ApplicationArguments class. For example, to invoke the phone application, you can invoke invokeApplication() and pass in the phone application type and a PhoneArguments argument. To invoke an application with no arguments, you can pass in null instead of an ApplicationArguments object.

Click for code sample: Invoke the phone application on a BlackBerry device

// A menu item to make a phone call
MenuItem menu1 = new MenuItem("Make phone call",1,1) 
{
    public void run () 
    {
        //Get the value that the user entered
        String phoneNum = _phonefield.getText(); // _phonefield is an EditField
        Invoke.invokeApplication(Invoke.APP_TYPE_PHONE,
            new PhoneArguments(PhoneArguments.ARG_CALL, phoneNum));
    }
};

Click for code sample: Invoke the contacts application on a BlackBerry device

// A menu item that invokes the contacts application to add a new contact
MenuItem menu2 = new MenuItem("Create contact",2,2) 
{
    public void run () 
    {
        Invoke.invokeApplication(Invoke.APP_TYPE_ADDRESSBOOK,
            new AddressBookArguments(AddressBookArguments.ARG_NEW));
    }
};

Using the Content Handler API

Packages: javax.microedition.content, net.rim.device.api.content

You can use the Content Handler API (CHAPI) to invoke BlackBerry Device Software applications and third-party applications. JSR 211 defines CHAPI as a Java ME optional API. For general information about CHAPI, see the javax.microedition.content package overview.

To use CHAPI to invoke applications, you can provide a URL, a content type, or a content ID with one of the constructors in the javax.microedition.content.Invocation class. When you use CHAPI with the RIM provided content IDs for invoking RIM content handlers, CHAPI can be a good way to set invocation parameters for BlackBerry Device Software applications, including the media application.

You can also use CHAPI to invoke third-party applications that register as content handlers.

Click for code sample: Start the media application on a BlackBerry device to view the picture library by using CHAPI

Registry registry = Registry.getRegistry(MyApplication.class.getName());
Invocation invocation = 
    new Invocation(null, 
                   null, 
                   BlackBerryContentHandler.ID_MEDIA_CONTENT_HANDLER,  
                   false, 
                   ContentHandler.ACTION_OPEN);
 
invocation.setArgs(new String[] 
    {BlackBerryContentHandler.MEDIA_ARGUMENT_VIEW_PICTURES});
 
registry.invoke(invocation);

For more information about invoking the media application on a BlackBerry device, see the BlackBerry Java Application Multimedia Development Guide.

To see a sample application that demonstrates how to use CHAPI to register and invoke a third-party application, see the CHAPIDemo sample application that is provided with the BlackBerry® Java® Development Environment.

Invoking the BlackBerry Browser

Package: net.rim.blackberry.api.browser

You can invoke the BlackBerry Browser and open a web page by using the methods in the Browser class and the BrowserSession class. For example:

BrowserSession bSession = Browser.getDefaultSession();
bSession.displayPage("http://www.blackberry.com");

For more information about invoking a browser on a BlackBerry device, including how to invoke a browser that is not specified as the default browser, see the BlackBerry Developer Knowledge Base article DB-00701.

Note: You can also embed web content in your application by using the BrowserField class. For more information, see Browser field.

Using the Application Manager

Package: net.rim.device.api.system

You can start a BlackBerry Device Software application by using the ApplicationManager class and specifying the code module of the application. Use this technique only if the application cannot be invoked by using any of the techniques described above. You cannot pass application arguments to a BlackBerry Device Software application by using this technique. You can use ApplicationManager to invoke the following BlackBerry Device Software applications:

Application Module name
clock net_rim_bb_clock
sounds net_rim_bb_profiles_app
BlackBerry Messenger net_rim_bb_qm_peer
options net_rim_bb_options_app

Note: The module names for BlackBerry Device Software applications are subject to change. Invoking modules directly can have unintended side-effects.

For more information about the Application Manager, see Application Life Cycle.

Enabling BlackBerry Device Software applications to invoke your application [back to top]

Adding menu items to a BlackBerry Device Software application

Package: net.rim.blackberry.api.menuitem

You can add menu items to a BlackBerry Device Software application by using the net.rim.blackberry.api.menuitem package. For example, you can add a menu item called View Sales Order to the contacts application on a BlackBerry device. When the user clicks View Sales Order, your application opens and displays a list of sales orders for that contact.

The ApplicationMenuItemRepository class provides the constants that specify the BlackBerry Device Software application that your menu item appears in. For example, the MENUITEM_MESSAGE_LIST constant specifies that the menu item appears in the messages application. The MENUITEM_SYSTEM constant specifies that your menu item appears in most BlackBerry Device Software applications.

When you create an instance of the ApplicationMenuItem class, you can specify the position of the item on the menu. Positions are relative. A lower number corresponds to a higher position on the menu. A separator line is drawn for every 0x10000 increment. Use the following guidelines when you specify the position of an item on the menu.

Position Description
0x00000-0x22FFFF used by BlackBerry Device Software applications
0x230000-0x99FFFF mostly unused, a good place for your menu items
0x1000000-0x104FFFF used by BlackBerry Device Software applications
0x1050000-0x1000FFFF mostly unused, a good place for your menu items
0x10010000-0x1001FFFF used by BlackBerry Device Software applications
0x10020000-0x7FFFFFFF not recommended for your use

When an ApplicationMenuItem is invoked, the BlackBerry Device Software application passes a context object to your application as follows:

Application Context object
contacts BlackBerryContact or BlackBerryContactGroup
browser String for URL of current page
calendar BlackBerryEvent
messages

net.rim.blackberry.api.mail.Message for email messages and PIN messages

TextMessage for SMS messages

MultipartMessage for MMS messages

PhoneCallLog for phone history

file explorer String for URI of the file
BlackBerry Maps MapView
memos BlackBerryMemo
tasks BlackBerryToDo
media null
phone

PhoneCallLog for phone history

String for number selected or dialed

BlackBerryContact for contact selected while dialing

messages search null

Click for code sample: Create and register a menu item by using the ApplicationMenuItemRepository

// Create menu item
int placement = 0x350100;
ApplicationMenuItem ami = new ApplicationMenuItem(placement) 
{
    public Object run(Object context) 
    {
        // do something 
        return null; 
    }
 
    public String toString() 
    {
        return "My menu item";
    }
};

// Register menu item
ApplicationMenuItemRepository amir = 
    ApplicationMenuItemRepository.getInstance();

amir.addMenuItem(ApplicationMenuItemRepository.MENUITEM_SYSTEM, ami, 
    ad_menuhandler); // ad_menuhandler is an ApplicationDescriptor

Matching string patterns in active fields [Back to top]

Packages: net.rim.device.api.ui.component, net.rim.blackberry.api.stringpattern, net.rim.blackberry.api.menuitem

The applications on a BlackBerry device that use the ActiveAutoTextEditField or the ActiveRichTextField field (for example, the calendar application and the messages application) can recognize string patterns and provide specific items for those string patterns in the menu on the BlackBerry device. For example, if a message contains a phone number, the number is highlighted. If the BlackBerry device user selects the number and presses the Menu key, the special menu item Call number displays.

You can define your own string patterns and associate the patterns with custom menu items. The custom menu items display when a user selects a matching string in an ActiveAutoTextEditField or ActiveRichTextField field and opens the menu. The custom menu items can perform any action, such as starting your application.

You can use the PatternRepository class to register a Perl-style regular expression or a specific string with the pattern repository on the BlackBerry device. You can use the ApplicationMenuItem class to define a menu item that is associated with the string pattern.

Click for code sample: Register a string pattern and a menu item

String pattern = “[Bb]lack[Bb]erry [Ss]martphone";

int patternType = PatternRepository.PATTERN_TYPE_REGULAR_EXPRESSION;
PatternRepository.addPattern(ad_menuhandler, pattern, patternType, 
    new ApplicationMenuItem[] { ami });

To see a sample application that demonstrates how to use PatternRepository and active text fields, see the ActiveTextFieldsDemo sample application that is provided with the BlackBerry JDE.

Registering content handlers that invoke your application

Package: javax.microedition.content

You can register the content handlers that invoke your application by using the Registry class, which is provided in the Content Handler API.

When you register a content handler, you can provide an array to specify the actions that invoke the handler. Note the following information:

Click for code sample: Register a content handler

private static void registerApp()
{
    try
    {
        // This application will be a handler for csv files 
        // and will be invoked with ACTION_OPEN
        String[] types = {"text/csv"};
        String[] suffixes = {".csv"};            
        String[] actions = {ContentHandler.ACTION_OPEN};   
 
        // Get access to the registry and register as a content handler
        // CLASSNAME is the fully qualified name of the application
         Registry registry = Registry.getRegistry(CLASSNAME);       
         registry.register(CLASSNAME,types,suffixes,actions,null,ID,null);
         
    }
    catch (ContentHandlerException che)
    {   
        errorDialog("Registry#register() threw " + che.toString());
    }
    catch (ClassNotFoundException cnfe)
    {        
        errorDialog("Registry#register() threw " + cnfe.toString());
    }
} 

Click for code sample: Invoke the content handler

private static final String URL = "file:///SDCard/rim.csv";    
 
private void doInvoke()
{
    try
    { 
        // Create the Invocation with the hard-coded URL
        Invocation invoc = new Invocation(URL);
        invoc.setResponseRequired(false);  // We don't require a response
        
        // We want to invoke a handler that has registered with ACTION_OPEN
        invoc.setAction(ContentHandler.ACTION_OPEN); 
        
        // Get access to the Registry and pass it the Invocation
        // CLASSNAME is the fully qualified name of the application
        Registry registry = Registry.getRegistry(CLASSNAME); 
        registry.invoke(invoc); 
    } 
    catch (IOException ioe)
    { 
        errorDialog("Registry#invoke() threw " + ioe.toString());
    }
}

For more information, see Using the Content Handler API.

Embedding content in BlackBerry Device Software applications [back to top]

You can embed content in BlackBerry Device Software applications in many ways, including the following:

Adding application messages to the messages application

Package: net.rim.blackberry.api.messagelist

You can use the messagelist package to create application messages. An ApplicationMessage is a custom message that displays in the messages application and invokes your application when the user opens it or chooses a menu item that you provide for the message. An application message is not an email message.

Application messages can be stored in folders. You can define indicators for your application messages that display on the Home screen.

Click for code sample: Register an application message folder

ApplicationMessageFolderRegistry amfr = 
    ApplicationMessageFolderRegistry.getInstance();
ApplicationMessageFolder folder = 
    amfr.registerFolder(folderId, "My Folder", collection, true);
ApplicationIcon icon = 
    new ApplicationIcon(EncodedImage.getEncodedImageResource("img/message_icon.jpg"), true);
int status = ApplicationMessage.Status.INCOMING | ApplicationMessage.Status.UNOPENED;

amfr.registerMessageIcon(0, status, icon);
folder.setSearchProperties(new ApplicationMessageSearchProperties(true));
folder.addListener(
    myApplicationMessageFolderListener,
    ApplicationMessageFolderListener.MESSAGE_DELETED | 
        ApplicationMessageFolderListener.MESSAGE_MARKED_OPENED | 
        ApplicationMessageFolderListener.MESSAGE_MARKED_UNOPENED, 
    ad_menuhandler);
amfr.registerMessageMenuItems(0, status, 
    new ApplicationMenuItem[] {createAMI("MSG INTEGRATION", 0)}, ad_menuhandler);
amfr.setBulkMarkOperationsSupport(0, status, true, false);

Click for code sample: Register an indicator and add an application message

// Register icon for indicator
ApplicationIndicatorRegistry air = ApplicationIndicatorRegistry.getInstance();
air.register(icon, false, false);
 
// Add a message
// MyApplicationMessage implements ApplicationMessage
ApplicationMessage myMessage = new MyApplicationMessage(); 
collection.addMessage(myMessage);
folder.fireElementAdded(myMessage);
 
// Update indicator
ApplicationIndicator ai = air.getApplicationIndicator();
int size = collection.size();
ai.setValue(size);
ai.setVisible(size > 0);

To see a sample application that demonstrates how to use the Message List API, see the MessageListDemo sample application that is provided with the BlackBerry JDE.

Linking contacts in your application with contacts in the contacts application

Package: net.rim.blackberry.api.pdap.contactlinking

You can use the LinkedContactUtilities class to link a contact in your application with a contact in the contacts application on the BlackBerry device. You can use the AddressBookFieldFactory interface to add a custom field that displays in the contacts application when a BlackBerry device user selects a contact that is linked with a contact in your application. You can also create menu items that display in the contacts application when a user views a contact that is linked with one of your contacts.

Click for code sample: Link a contact

String contactID = contact.getString(Contact.UID,0); //contact is a BlackBerryContact
LinkedContactUtilities.linkContact(contact, 
    new DefaultLinkableContact(contactID, APPLICATION_ID));

LinkedContactUtilities.registerMenuItems(new ApplicationMenuItem[] {ami}, 
    APPLICATION_ID, LinkedContactConstants.COMPOSE_SN_MENU_GROUP, ad_menuhandler);

AddressBookFieldFactory factory = new AddressBookFieldFactory() 
{
    public Field createAddressBookField(String contactID) {
        return new MyDisplayField(contactID);
    }
};
LinkedContactUtilities.registerAddressBookFieldFactory(factory, APPLICATION_ID);

To see a sample application that demonstrates how to link contacts, see the ContactLinkingDemo sample application that is provided with the BlackBerry JDE.

Adding content to phone screens

Package: net.rim.blackberry.api.phone.phonegui

You can use the PhoneScreen class with the PhoneListener interface to display information in the phone application for incoming, outgoing, or active calls.

Click for code sample: Add an image to the Incoming Call screen

if (PhoneScreen.isSupported()) 
{
    Phone.addPhoneListener(
        new AbstractPhoneListener() 
        {
            public void callIncoming(int callId) 
            {
                PhoneScreen ps = new PhoneScreen(callId, 
                    Application.getApplication());
                ps.add(new BitmapField(Bitmap.getBitmapResource("img/my.jpg")));
                ps.sendDataToScreen(); 
            }
        });
}

To see a sample application that demonstrates how to use PhoneScreen, see the PhoneScreenDemo sample application that is provided with the BlackBerry JDE.

Adding options for your application

Package: net.rim.blackberry.api.options

You can use the OptionsProvider interface to add options for your application to the options application on the BlackBerry device.

Click for code sample: Add application options

OptionsManager.registerOptionsProvider(new OptionsProvider()
{
    public void populateMainScreen(MainScreen mainScreen) 
    {
        // Add one or more fields to display options
    }
    
    public String getTitle() 
    {
        return "Options Demo"; 
    }

    public void save() 
    {
        // Save changes
    }
});

To see a sample application that demonstrates how to use OptionsProvider, see the OptionsProviderDemo sample application that is provided with the BlackBerry JDE.

Registering your application as a notification source

Package: net.rim.device.api.notification

You can use the Notification API to register your application as an event notification source and to trigger notifications. Custom notification sources appear in the sounds application, under Other in Set Ring Tones/Alerts. Custom notifications respect the settings that the user selects in the sounds application.

Click for code sample: Register a notification source and trigger notification

// Register notification source
NotificationsManager.registerSource( sourceID, “Notifications Demo”, 
    NotificationsConstants.IMPORTANT );

// Trigger notification
NotificationsManager.triggerImmediateEvent(sourceID, ...);

To see a sample application that demonstrates how to use the Notification API, see the NotificationsDemo sample application that is provided with the BlackBerry JDE.

Embedding BlackBerry Device Software UI components in your application [back to top]

You can include in your applications many of the specialized UI components that the BlackBerry Device Software applications use. Below are some examples. For more information about using these and other UI components, see the BlackBerry Java Application UI and Navigation Development Guide.

Autocomplete text field

Package: net.rim.device.api.ui.component

The AutoCompleteField class compares the text that a user types in the field against the items in a data source, and displays the matches in a drop-down list below the field.

Click for code sample: Use an AutoCompleteField

BasicFilteredList bfl = new BasicFilteredList(); 
bfl.addDataSource(0, 
                  BasicFilteredList.DATA_SOURCE_CONTACTS,
                  BasicFilteredList.DATA_FIELD_CONTACTS_NAME_FULL | 
                      BasicFilteredList.DATA_FIELD_CONTACTS_COMPANY,
                  BasicFilteredList.DATA_FIELD_CONTACTS_NAME_FULL |
                      BasicFilteredList.DATA_FIELD_CONTACTS_COMPANY | 
                      BasicFilteredList.DATA_FIELD_CONTACTS_EMAIL,
                  -1,
                  -1, 
                  null, 
                  BasicFilteredList.COMPARISON_IGNORE_CASE);
 
AutoCompleteField autoCompleteFieldContacts = new AutoCompleteField( bfl, 
    AutoCompleteField.LIST_DROPDOWN | AutoCompleteField.LIST_EXPAND_ON_CLICK);

To see a sample application that demonstrates how to use an autocomplete text field, see the AutoCompleteFieldDemo sample application that is provided with the BlackBerry JDE.

Location picker

Package: net.rim.device.api.lbs.picker

The LocationPicker class enables users to select a location by using sources such as contacts, GPS coordinates, recent locations, and application suggestions.

Click for code sample: Use a LocationPicker

LocationPicker.Picker[] locationPickersArray = new LocationPicker.Picker[] 
{
    EnterLocationPicker.getInstance(false),
    SuggestedLocationPicker.getInstance("App specific...", landmarks ),            
    RecentLocationPicker.getInstance(),
    GPSLocationPicker.getInstance(),
    MapsLocationPicker.getInstance(),
    ContactsLocationPicker.getInstance(false)
};            
LocationPicker locationPicker = LocationPicker.getInstance(locationPickersArray);
locationPicker.setListener(this); 
locationPicker.show();

To see a sample application that demonstrates how to use a location picker, see the LocationPickerDemo sample application that is provided with the BlackBerry JDE.

File picker

Package: net.rim.device.api.ui.picker

The FilePicker class enables users to select a file by navigating to a folder.

Click for code sample: Use a FilePicker

// Get the FilePicker instance
FilePicker filePicker = FilePicker.getInstance();
           
// Set the file picker to only display mp3 files
filePicker.setFilter(".mp3");

// Obtain the default system music directory 
String path = System.getProperty(
                    "fileconn.dir.memorycard.music");
                
// Set the directory to open the file picker in 
filePicker.setPath(path);  

filePicker.setListener(this);
filePicker.show();

To see a sample application that demonstrates how to use a file picker, see the FilePickerDemo sample application that is provided with the BlackBerry JDE.

Map field

Package: net.rim.device.api.lbs

You can use the MapField class to embed a map in your application.

Click for code sample: Use a MapField

MapField mapField = new MapField();
mapField.moveTo(initialLocation);
mapField.setZoom(initialZoom);
screen.add(mapField);

To see a sample application that demonstrates how to embed a map, see the EmbeddedMapDemo sample application that is provided with the BlackBerry JDE.

Browser field

Package: net.rim.device.api.browser.field2

You can use the BrowserField class to embed web content in your application. BrowserField provides methods to register listeners; request, execute, scale, display, debug, and navigate content; retrieve content information; and handle errors.

Click for code sample: Use a BrowserField

// Create new instance of BrowserField
BrowserField browserField = new BrowserField();
 
// Add the browser field to a ui manager or screen
screen.add( browserField );
 
// Request the content to display

browserField.requestContent("http://www.blackberry.com");

Media fields

Package: javax.microedition.media, javax.microedition.media.control

You can embed media players and media recorders in your application by using the Mobile Media API (JSR 135).

Click for code sample: Display a video control

Player player = Manager.createPlayer("capture://video");
player.realize();
videoControl = (VideoControl) player.getControl("VideoControl");
videoField = (Field) videoControl.initDisplayMode(VideoControl.USE_GUI_PRIMITIVE, 
    "net.rim.device.api.ui.Field");
videoControl.setDisplayFullScreen(true);
videoControl.setVisible(true);
player.start();

Accessing data on a BlackBerry device [back to top]

You can access PIM data on a BlackBerry device in your application. For more information, see the PIM overview.


Copyright 1999-2010 Research In Motion Limited. 295 Phillip Street, Waterloo, Ontario, Canada, N2L 3W8. All Rights Reserved.
Copyright 1993-2003 Sun Microsystems, Inc. 901 San Antonio Road, Palo Alto, California, 94303, U.S.A.
Copyright 2002-2003 Nokia Corporation All Rights Reserved.
Java is a trademark of Sun Microsystems, Inc.