Application integration APIs
The Application integration APIs contain packages you can use to integrate your apps with core applications such as the Contacts application, the Phone application, and the Media application.
You can use the Invoke API to invoke core applications and optionally pass in data. To use this API, call invokeApplication and pass in the application type and any relevant arguments. You can use the Invoke API to invoke the following core applications:
- BlackBerry Maps
Invoke contains APP_TYPE fields that enumerate the applications.
For each core 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, call invokeApplication and pass in the Phone application type and a PhoneArguments argument. To invoke an application with no arguments, pass in null instead of an ApplicationArguments object.
Content Handler API
You can use the Content Handler API (CHAPI) to invoke both core applications and third-party apps. JSR 211 defines CHAPI as a Java ME-optional API. For more information about CHAPI, see the javax.microedition.content package overview.
To use CHAPI to invoke applications, 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 core applications, including the Media application. You can also use CHAPI to invoke third-party apps that register as content handlers.
For more information about invoking a browser, including how to invoke a browser that is not specified as the default browser, see the Knowledge Base article Invoke the browser.
You can also embed web content in your app with the BrowserField class.
You can start a core application with the ApplicationManager class, specifying the code module of the application. Use this technique only if the application cannot be invoked with any of the techniques described above. You cannot pass application arguments to a core application with this technique. You can use ApplicationManager to invoke the following core applications:
The module names for core applications are subject to change. Invoking modules directly can have unintended side-effects.
Enabling core applications to invoke your application
You can add menu items to a core application with the menuitem package. For example, you can add a menu item called View Sales Order to the Contacts application. 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 core 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 core applications.
The applications that use the ActiveAutoTextEditField or the ActiveRichTextField field (for example, the Calendar and Messages applications) can recognize string patterns and provide specific items for those string patterns in the menu on the smartphone. For example, if a message contains a phone number, the number is highlighted. If the smartphone 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 app.
You can use the PatternRepository class to register a Perl-style regular expression or a specific string with the pattern repository on the smartphone. You can use the ApplicationMenuItem class to define a menu item that is associated with the string pattern.
For more information about PatternRepository and active text fields, see Active Text Fields sample application.
You can register the content handlers that invoke your app 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. ContentHandler.ACTION_OPEN content handlers for the MIME types that are not supported by the smartphone are used in the BlackBerry Browser, file explorer, and in the Open Attachment menu item in the Messages application. ContentHandler.ACTION_SEND content handlers for the image or video MIME types are used in the file explorer (including in the Media application) and in the Send As menu in the Camera application.
Embedding content in BlackBerry applications
You can embed content in apps in several ways, including the following:
- Add apps to the Messages application using the messagelist package
- Link contacts in your app with contacts in the Contacts application using the contactlinking package
- Add content to phone screens using the phonequi package
- Add options for your app using the options package
- Register your app as a notification source using the notification package
Embedding UI components in your app
You can include in your apps many specialized UI components. For example, you can implement:
- Autocomplete fields using the component package
- Location pickers (which allow users to select a location using such means as contacts, GPS, recent locations, and suggestions from your app) using the picker package in the LBS API
- File pickers (which allow users to select a file from a folder) using the picker package in the UI API
- Embedded maps using the MapField class
- Embedded web content using the BrowserField class
- Embedded media players and media recorders using the Mobile Media API (JSR 135), as implemented in javax.microedition.media and javax.microedition.media.control
The Unified Search Service is a search engine that is included with BlackBerry Device Software 6 and later. You can use the Unified Search API (net.rim.device.api.unifiedsearch) to include your application data in the Unified Search Service's content repository, and to search the content index from your application.