BlackBerry Java SDK 7.0 API Reference: 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

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:

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.

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

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

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.

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

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:

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

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.

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

Adding menu items to a BlackBerry Device Software application

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

// 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]

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.

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 Java SDK.

Registering content handlers that invoke your application

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:

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

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

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

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.

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

// 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 Java SDK.

Linking contacts in your application with contacts in the contacts application

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.

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 Java SDK.

Adding content to phone screens

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

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 Java SDK.

Adding options for your application

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

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 Java SDK.

Registering your application as a notification source

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.

// 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 Java SDK.

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

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.

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 Java SDK.

Location picker

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

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 Java SDK.

File picker

// 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 Java SDK.

Map field

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 Java SDK.

Browser field

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.

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

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

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.

Legal