BlackBerry_Java_SDK-New_In_This_Release--1245181-0730084733-001-6.0-US by Odane P. Hamilton

BlackBerry Java SDK Version: 6.0

New In This Release

Published: 2010-08-16 SWD-1245181-1119093109-001

Contents 1

Overview.......................................................................................................................................................................................

2 What's new in BlackBerry 6.......................................................................................................................................................

3 What's new in BlackBerry Java SDK 6.0.................................................................................................................................. UI...................................................................................................................................................................................................... Activity indicators................................................................................................................................................................... Command framework............................................................................................................................................................. Home screen shortcuts.......................................................................................................................................................... Image scrolling enhancements............................................................................................................................................. Layout managers.................................................................................................................................................................... Pickers...................................................................................................................................................................................... Pop-up menus and submenus.............................................................................................................................................. Title bar enhancements......................................................................................................................................................... Toolbars................................................................................................................................................................................... Convenience key access........................................................................................................................................................ Device interaction support.................................................................................................................................................... BlackBerry Browser......................................................................................................................................................................... WebKit browser engine.......................................................................................................................................................... Graphics and animation................................................................................................................................................................. Location-based services................................................................................................................................................................. Support to query GPS and geolocation services that are available on the device......................................................... Geocoding and reverse geocoding enhancements............................................................................................................ GPS mode retrieval................................................................................................................................................................ Geolocation modes................................................................................................................................................................. GPS and geolocation request enhancements..................................................................................................................... GPS and geolocation optimal fixes...................................................................................................................................... Maps API................................................................................................................................................................................. Travel time estimation........................................................................................................................................................... Multimedia....................................................................................................................................................................................... Autofocus enhancements...................................................................................................................................................... Application integration.................................................................................................................................................................. Search integration.................................................................................................................................................................. Message list enhancements..................................................................................................................................................

6 6 6 7 8 8 9 13 14 16 17 17 18 21 21 21 23 23 23 24 24 25 25 25 26 26 26 27 27 27

Personal Information Management..................................................................................................................................... Phone screen enhancements................................................................................................................................................ Support for setting a default content handler.................................................................................................................... Network connections...................................................................................................................................................................... Network API enhancement................................................................................................................................................... Communication API............................................................................................................................................................... Message Processing API........................................................................................................................................................

28 30 31 31 31 32 33

4 System requirements..................................................................................................................................................................

5 Find more information................................................................................................................................................................

6 Glossary.........................................................................................................................................................................................

7 Provide feedback.........................................................................................................................................................................

8 Document revision history.........................................................................................................................................................

9 Legal notice..................................................................................................................................................................................

New In This Release

Overview

BlackBerry® APIs provide you with the classes and interfaces that you can use to create an application with features that are designed specifically for a BlackBerry device. You can use the BlackBerry APIs to create applications that perform the following functions: • • • •

interact with specific built-in features of a BlackBerry device, such as the GPS and mapping functions, the camera and video recorder, the phone, and peripherals that use Bluetooth® technology respond to interaction with the input methods on the BlackBerry device, such as the trackball, touch screen, or keyboard integrate with BlackBerry® Device Software applications, such as the contacts application, the messages application, the BlackBerry® Browser, and BlackBerry® Maps interact with the components of the BlackBerry solution, including the BlackBerry® Enterprise Server, push services, and server-side resources

What's new in BlackBerry 6

New In This Release

What's new in BlackBerry 6

BlackBerry® 6 is the latest version of the BlackBerry® Device Software. It offers a new user experience with many enhancements and new applications. Feature

Description

Intuitive, fluid design

BlackBerry 6 uses a new theme that is clean, sleek, and more intuitive. BlackBerry device users can group applications into views for quick access. For example, users can tap or slide their finger on the navigation bar to see other views. Users can easily interact with the device by using touch gestures such as swipes and pinches. BlackBerry 6 emphasizes a quick and easy setup. After the user starts the device, the user can view short introductory videos and go straight to the new setup process. In the new setup process, users can set up their social networking accounts (for example, a Facebook® account or Twitter® account). The accounts are added to the new Social Feeds application. BlackBerry 6 introduces the Social Feeds application. Users can stay up-to-date with their social networks and receive the latest news and information from their favorite blogs and web sites, and from their instant messaging applications and BlackBerry® Messenger. Users have one location where they can post a tweet, and update their social networking and instant messaging statuses. BlackBerry 6 introduces a new browsing experience for users. The BlackBerry® Browser has been rebuilt upon the WebKit browser engine. The browser offers a better layout with enhancements such as tabbed browsing and an optimized web page layout that makes web pages easier to read on the device. On devices with a touch screen, users can zoom and pan web page content with gestures such as swipes and pinches.

Simplified setup

Social feeds and views

Enhanced browsing experience

Universal search

The browser is also more efficient. As with previous versions of the browser, content is compressed and optimized to provide a more efficient browsing experience. However, the new browser actually has faster loading times for web pages. BlackBerry 6 introduces a new search capability that allows users to search all the data on the device at once, and extends the search to the Internet. For example, a user can search for a contact's name and see the results that relate to that contact such as emails, meetings, and the contacts entry in the Contacts application.

New In This Release

What's new in BlackBerry 6

Related topics Home screen shortcuts, 8

Pop-up menus and submenus You can add a pop-up menu and a submenu to your application by using the classes provided in the net.rim.device.api.ui.menu package. Menu

Description

Pop-up menu

A pop-up menu, similar to a context menu, contains a list of the most common actions that BlackBerry device users can perform within the current context. An item in the pop-up menu can include the text, an application icon, and a command.

New In This Release

Description A pop-up menu replaces a context menu, or a short menu, that was available in previous versions of the BlackBerry® Java® SDK. The BlackBerry® Device Software automatically converts an existing context menu into a pop-up menu.

Submenu

A submenu is a group of related menu items. A submenu appears as a subset of a menu item in the full menu. When you include items in a submenu, users can find frequently-used items or important items more easily in the full menu.

Find out more • • • •

API reference for the BlackBerry Java SDK Command Framework sample application that is included in the BlackBerry Java SDK BlackBerry Java SDK UI and Navigation Development Guide UI Guidelines for BlackBerry Smartphones

New In This Release

Title bar enhancements You can add useful information to your application's title bar by using the StandardTitleBar class that is provided in the net.rim.device.api.ui.component package. With earlier versions of the BlackBerry® Java® SDK, you can invoke MainScreen.setTitle() to add text to the title bar of your application's screen. By using the new StandardTitleBar, you can easily display the following additional information: • • • • •

Application icon, descriptive title, and time Application notifications, such as a new message indicator Wireless connection indicators, including the network coverage indicator, wireless coverage area indicator, GPS indicator, Bluetooth® indicator, and Wi-Fi® connection indicator Battery power level indicator Active call indicator

Find out more • • •

API reference for the BlackBerry Java SDK BlackBerry Java SDK UI Quick Reference Guide BlackBerry Java SDK UI Guidelines for BlackBerry Smartphones

New In This Release

Toolbars On BlackBerry® devices with a touch screen, you can provide BlackBerry device users with quick and easy access to frequent actions in an application or on a screen by using the Toolbar API that is provided in the net.rim.device.api.ui.toolbar package. Each toolbar consists of buttons that appear at the bottom of the screen. The toolbar is visible when the user interacts with the application. The buttons can consist of an icon and text. If you provide both an icon and text, when the user selects the button, the text appears above the button.

Find out more • • •

API reference for the BlackBerry Java SDK BlackBerry Java SDK UI Quick Reference Guide UI Guidelines for BlackBerry Smartphones

Convenience key access Convenience keys are typically located on the left and right sides of the BlackBerry® device. You can access convenience keys on the device by registering your application with the KeyHandlerRegistry class that is provided in the net.rim.device.api.system package. When a BlackBerry device user presses a convenience key on the device, your application can respond while it is running in the background. You can programmatically set your application as the default application that opens when a user presses a convenience key, regardless of whether the application that is running in the foreground consumes the corresponding convenience key event. You can listen for convenience key events by implementing the KeyListener interface.

Find out more •

API reference for the BlackBerry® Java® SDK

New In This Release

Device interaction support Feature

Description

Slider detection

You can check whether the BlackBerry速 device has a slider and what state the slider is by using the Sensor class that is provided in the net.rim.device.api.system package. If the device has a slider, Sensor.isSupported(Sensor.SLIDE) returns true. If not, the method returns false. On devices that have a slider, Sensor.getState(Sensor.SLIDE) returns Sensor.STATE_SLIDE_CLOSED, Sensor.STATE_SLIDE_OPEN, or Sensor.STATE_SLIDE_IN_TRANSITION.

Detection of device capabilities

Cradle detection and handling

You can define a listener to notify your application of changes to the state of the slider by implementing the SensorListener interface. You can query the capability of a device by using the Device Capability API that is provided in the net.rim.device.api.system.capability package. The DeviceCapability class allows you 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. You can define a listener to notify your application of changes to the specified capabilities of the device by implementing the DeviceCapabilityListener interface. You can detect when a 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. BlackBerry devices that are running BlackBerry速 Device Software 6.0 return true for

New In This Release

Feature

Description isSupported(DeviceCapability.TYPE_CRADLE). When a device

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 new CradleProtocol class to detect the cradle type and properties. CradleProtocol is provided in the net.rim.device.api.accessory package. You can register your application as a cradle handler. A cradle handler is an application that is a candidate to start when a BlackBerry device is connected to a cradle of a specified type. To register your application as a cradle handler, use the CradleHandlerRegistry.registerHandler() method. CradleHandlerRegistry 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. If any handlers are registered for a cradle type, the user is presented with a dialog box when such a cradle is connected. 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 is automatically started the next time the cradle of the specified type is connected.

Pinch gestures

The user can change the cradle handler settings on the device by using the Third Party Applications section in Options. BlackBerry devices that are running BlackBerry Device Software 6.0 and that have a touch screen support pinch gestures. Pinch gestures typically zoom in to and out from of an item. A pinch begins when two touch points are detected on the touch screen. At that time, a TouchGesture.PINCH_BEGIN event is sent. As the user moves one or both touch points, a series of TouchGesture.PINCH_UPDATE events are sent. When the user completes the gesture, a TouchGesture.PINCH_END event is sent.

New In This Release

Feature

Description You can retrieve the zoom values during the pinch gesture by using the TouchGesture.getPinchMagnitude() method.

Swipe gesture across the trackpad

You must set the screen property TouchscreenSettings.DETECT_PINCH to enable the detection of pinch gestures on a screen. BlackBerry devices that are running BlackBerry Device Software 6.0 and that have a trackpad support swipe gestures across the trackpad. A TouchGesture.NAVIGATION_SWIPE event is sent when the user swipes across the trackpad. You can retrieve information about the trackpad swipe by using getSwipe methods in the TouchGesture class. You must set the navigation property NavigationDeviceSettings.DETECT_SWIPE to enable the generation of

Touch screen interaction models

trackpad swipe gestures on a screen. BlackBerry devices with a touch screen and a trackpad, such as the BlackBerry® Torch™ 9800 smartphone, use a forceless click interaction model, where the user taps the screen or uses the trackpad to perform an action. This model differs from previous BlackBerry devices with a SurePress™ touch screen, where the user clicks (presses) the screen to perform an action. For more information about the events that are generated on each type of device when the user interacts with the touch screen, see the BlackBerry Java SDK UI and Navigation Development Guide.

Find out more • • •

API reference for the BlackBerry® Java® SDK BlackBerry Java SDK UI and Navigation Development Guide UI Guidelines for BlackBerry Smartphones

BlackBerry Browser

New In This Release

BlackBerry Browser WebKit browser engine In BlackBerry® 6, the BlackBerry® Browser is built upon the WebKit browser engine. The browser engine is the underlying processing layer of the BlackBerry Browser, BlackBerry® WebWorks™ applications, and BlackBerry Java® applications that use an embedded browser object (for example, BrowserField or BrowserField2). The browser engine is responsible for parsing the web content, applying styles, executing JavaScript® code, and laying out the content. WebKit is an open-source browser engine that is developed by contributors from several different organizations, whose primary focus is on implementing key W3C® and ECMA standards. Non-standard technologies, such as images, media, or functionality that is specific to the BlackBerry device, must be managed by plug-ins or BlackBerry extensions to WebKit.

Find out more •

BlackBerry Browser Feature and Technical Overview

Graphics and animation Feature

Description

Animation API

You can add sophisticated animations to your BlackBerry® device applications by using the Animation API that is provided in the net.rim.device.api.animation package. The Animation API provides the following support: • • • • •

OpenVG™ 1.1

Quick setup of common animation scenarios Scheduling animations to start and stop in response to application and animation events Animation groups to contain and manage several animations together Blocking and non-blocking animation control Common and custom easing curves

You can include high-quality 2-D vector graphics in your applications by using the OpenVG 1.1 API that is provided in the net.rim.device.api.openvg package. The API uses hardware acceleration that can reduce device power consumption and smooth graphics that scale fluidly.

Graphics and animation

New In This Release

Feature

Description

OpenGL® ES 1.1

With BlackBerry® Java® SDK 5.0, you can create 2-D and 3-D hardware-accelerated graphics for your application by using the JSR 239 Java binding for OpenGL ES. With BlackBerry Java SDK 6.0, OpenGL ES 1.1 is supported. You can simplify OpenGL ES and OpenVG graphics development and help optimize performance by using the Graphics Utility API and Math API. The APIs are implemented in the net.rim.device.api.opengles, net.rim.device.api.openvg, and net.rim.device.api.math packages and provide the following support:

Graphics Utility API and Math API

• •

•

• SVG API

Built-in support for OpenGL ES and OpenVG graphics rendering by using the VGField and GLField classes Support for creating an OpenVG image from a bitmap, appending path segments and complex polygons to OpenVG paths, computing complex 2-D transformation matrices to apply warps and other special effects to paths or images, and querying OpenVG version information by using the VGUtils class Support for projecting and undoing a production (unprojecting) between 2-D and 3-D spaces, and generating 2-D mipmap textures by using the new methods that are provided in the GLUtils class Support for vector math and bounding volume to assist with viewing frustum culling and testing intersections by using the provided math classes

You can create superior SVG graphics to display on the device by using the SVG API and JSR 226 enhancements. The runtime on the device now uses an accelerated OpenVG 1.1 based rendering engine resulting in new SVG Tiny™ 1.1 and 1.2 functionality, improved rendering quality, and faster performance. The SVG API and runtime changes provides the following features: • • • •

Improved fill and stroke painting functionality on linear and radial gradients Support for all fill and stroke properties High-quality anti-aliased path rendering High quality image rendering even when the image has been transformed in some way

Location-based services

New In This Release

Feature

Description •

Improved smooth text rendering and functionality to fill and stroke paints and arbitrary transformations

Find out more • • •

API reference for the BlackBerry Java SDK OpenGL sample application that is included in the BlackBerry Java SDK BlackBerry Java SDK Graphics and Animation Development Guide

Location-based services Support to query GPS and geolocation services that are available on the device You can verify which location sources (internal GPS receiver, external GPS receiver, or geolocation) are supported or available on the BlackBerry® device by using the methods available in the LocationInfo class that is provided in the net.rim.device.api.gps package. For example, before you retrieve location data, you can invoke LocationInfo.getSupportedLocationSources() to verify which location sources the device supports.

Find out more • •

API reference for the BlackBerry® Java® SDK BlackBerry Java SDK Location-Based Services Development Guide

Geocoding and reverse geocoding enhancements With BlackBerry® Java® SDK 5.0, you can retrieve information about a location on a map by invoking the Locator.geocode () and Locator.reverseGeocode() methods that are provided in the net.rim.device.api.lbs package. For example, you can use geocoding to retrieve information for a known landmark by using a street address or city. You can use reverse geocoding to find an approximate street address by using the latitudinal and longitudinal coordinates. With BlackBerry Java SDK 6.0, you can retrieve landmark information by using a postal code or zip code and the Locator.POSTAL_ZIP_CODE constant. This constant returns the postal/zip code, province/state, and country.

Find out more • •

API reference for the BlackBerry® Java® SDK BlackBerry Java SDK Location-Based Services Development Guide

Location-based services

New In This Release

GPS mode retrieval With BlackBerry® Java® SDK 5.0, you can retrieve the default GPS mode by invoking GPSInfo.getDefaultGPSMode() that is provided in the net.rim.device.api.gps package. In BlackBerry Java SDK 6.0, the method returns the modes in the following order: assisted, autonomous, and cell site. The assisted mode is selected as the default mode when assisted GPS mode can be provided to the application without requiring additional credentials from the application. If you do not specify a GPS mode when you request a location update, the default mode is selected based on the GPS capability that the wireless network supports.

Find out more • •

API reference for the BlackBerry Java SDK BlackBerry Java SDK Location-Based Services Development Guide

Geolocation modes You can retrieve geolocation information from a geolocation service by using the LocationInfo class that is provided in the net.rim.device.api.gps package. The geolocation service provides the approximate location of the BlackBerry® device by using the position of cell towers and WLAN access points. Mode

Description

GEOLOCATION_MODE

This mode retrieves a location from among the currently available geolocation sources, based on factors such as network connectivity, location accuracy, and data availability. This mode retrieves a location based on cell tower positioning.

GEOLOCATION_MODE_CE LL GEOLOCATION_MODE_WL

This mode retrieves a location based on WLAN access point positioning.

Find out more • •

API reference for the BlackBerry® Java® SDK BlackBerry Java SDK Location-Based Services Development Guide

New In This Release

Location-based services

GPS and geolocation request enhancements You can request both GPS updates and geolocation updates in parallel by creating two threads and requesting separate instances of the BlackBerryLocationProvider class from each thread. One thread specifies a GPS mode, and the other thread specifies a geolocation mode. For example, you can use this method to provide a BlackBerry® device user with an approximate location quickly before a GPS fix is available.

Find out more • •

API reference for the BlackBerry® Java® SDK BlackBerry Java SDK Location-Based Services Development Guide

GPS and geolocation optimal fixes To retrieve an optimal location fix you can request geolocation updates along with GPS updates by using the BlackBerryCriteria.enableGeolocationWithGPS() methods that are provided in the net.rim.device.api.gps package. The optimal fix provides a geolocation fix when a GPS fix cannot be retrieved during the specified timeout period. You can use this feature in an application that requires the location of a BlackBerry® device at all times, and you are not concerned with how the location is retrieved.

Find out more • •

API reference for the BlackBerry® Java® SDK BlackBerry Java SDK Location-Based Services Development Guide

Maps API You can embed a map in an application, add data to a map, display KML overlays, and create static images of a map by using the Maps API that is provided in the net.rim.device.api.lbs.maps package and subpackages. The Maps API includes the MapField class that provides the following support: • • •

Adding your own data to a map, that is rendered directly on the map Panning and zooming map views Generating static images based on the current map view, including any data on the map

The RichMapField class that is provided in the net.rim.device.lbs.maps.ui package extends the functionality of the MapField class and provides the following support: • •

Adding fields on top of a map, that are not rendered directly on the map Allowing BlackBerry® device users to navigate through MapField components to other components on the screen

Find out more •

API reference for the BlackBerry® Java® SDK

New In This Release

• •

Multimedia

Enhanced Map Field sample application that is included in the BlackBerry Java SDK BlackBerry Java SDK Location-Based Services Development Guide

Travel time estimation You can request the estimated trip duration and trip distance for automobile travel to destinations in the United States and Canada by using the Travel Time API, which is provided in the net.rim.device.api.lbs.travel package. For example, you can create a social networking application that provides the BlackBerry® device user's current location and the estimated time of arrival at a friend's location. The request for a travel time estimate is forwarded to a remote Travel Time server, which plots a route between the starting and ending locations. The Travel Time server uses current and historical traffic information to calculate the estimated trip duration and distance. You can create a request for the estimated trip duration and trip distance by creating an instance of the TravelTimeEstimator class and specifying the geographic coordinates for the starting and ending locations, and the starting time of the trip. You can use the current time or a future time for the starting time of the trip.

Find out more • • •

API reference for the BlackBerry® Java® SDK Travel Time sample application that is included in the BlackBerry Java SDK BlackBerry Java SDK Location-Based Services Developer Guide

Multimedia Autofocus enhancements You can start and stop the autofocus on the camera by using the EnhancedFocusControl interface that is provided in the net.rim.device.api.amms.control.camera package. With previous versions of the BlackBerry® Java® SDK, you have limited access to the camera's autofocus by using the FocusControl class that is provided in the javax.microedition.amms.control.camera package. For example, with previous versions you can query if the camera supports autofocus. The EnhancedFocusControl interface extends FocusControl to provide more control over the camera's autofocus.

Find out more • • •

API reference for the BlackBerry Java SDK Camera sample application that is included in the BlackBerry Java SDK BlackBerry Java SDK Multimedia Development Guide

New In This Release

Application integration

Application integration Search integration You can make your data discoverable in searches that are performed through the universal search application on the BlackBerry® device and you can integrate search functionality into your application by using the Unified Search API. The Unified Search API is provided in the net.rim.device.api.unifiedsearch package and subpackages. You can permit your data to appear in search results from: • • •

The universal search application on the Home screen Other applications on the device Your application

You can integrate search functionality into your application and permit BlackBerry device users to search other applications that make their data discoverable. You can also permit users to extend their search to an external search provider. An external search provider could be an application that provides its own search functionality, or a networked server on the Internet or behind an organization's firewall. The universal search application on the Home screen displays results from external search providers at the end of search.

Find out more • • •

API reference for the BlackBerry Java SDK Unified Search sample application that is included in the BlackBerry Java SDK BlackBerry Java SDKIntegration Development Guide

Message list enhancements With BlackBerry® Java® SDK 4.6, you can create custom messages and folders that your application manages, and that are included in the Messages application on the BlackBerry device, by using the Message List API that is provided in the net.rim.blackberry.api.messagelist package. With BlackBerry Java SDK 6.0, you can display a new-message indicator by using the methods provided in the ApplicationMessageFolder class. For example, you can display the newmessage indicator when your application adds new messages to your message folder. You display a new message by using the new newMessage parameter in the ApplicationMessageFolder.fireElementAdded() method or the hasNewMessages parameter in the ApplicationMessageFolder.fireReset() method. By default, messages that have the UNREAD status are treated as new. You can override this behavior by specifying the parameter as false.

New In This Release

Application integration

When a BlackBerry device user opens the Messages application, the new-message indicator is cleared and the ApplicationMessageFolderListener indicates that messages are partially viewed by using the new MESSAGE_MARKED_OLD field. Your application should listen for events from the listener so that you can clear the new-message indicator appropriately. You can display or remove the new-message indicator by using the ApplicationIndicator.setNotificationState() method. With BlackBerry Java SDK 6.0, you can invoke the Messages application and view an application message folder by using the new MessageArguments(folder) constructor, where folder is a registered application message folder.

Find out more • •

API reference for the BlackBerry Java SDK Message List sample application that is included in the BlackBerry Java SDK Integration Development Guide

Personal Information Management Calendar entry enhancements You can update or delete an entry in the Calendar application on the BlackBerry® device without sending a notification to the meeting's attendees. (Notifications are always sent to all attendees if a new meeting entry is added, or to new attendees if attendees are added after the last update, to make sure that attendees are notified about a meeting and can accept or decline the meeting.) To update a calendar entry without notifying attendees, you use the BlackBerryPIMItem interface that is provided in the net.rim.blackberry.api.pdap package. For example, when you save the changes to a calendar entry, you can pass in the new BlackBerryEvent.DO_NOT_NOTIFY_ATTENDEES field when you implement BlackBerryPIMItem.commit () so that a notification is not sent. To delete a calendar entry without notifying attendees, pass in the BlackBerryEventList.removeElement() field.

Find out more • •

API reference for the BlackBerry® Java® SDK BlackBerry Java SDK Integration Development Guide

Application integration

New In This Release

Contact list enhancements Feature

Description

Creating and deleting contact lists

You can create and delete contact lists by using new methods in the BlackBerryPIM class that is provided in the net.rim.blackberry.api.pdap package. For example, you can create a contact list that includes only the contacts from your application. Contacts from all contact lists appear in the Contacts application on the BlackBerry速 device. A contact list that you create does not include service records and does not support wireless synchronization.

Searching for contact information associated with a call or phone number

You cannot delete a contact list if it includes a service record, is the last contact list on the device, or is the default contact list. You can search for a contact that corresponds to a phone call or phone number. For example, when a BlackBerry device user receives a call, you can search for the contact and display custom content about that contact on the incoming phone screen. For an active call, you can search for the contact by using the PhoneCall.getContact() method. For a completed call, you can search for the contact from the call log on the device by using the PhoneCallLogID.getContact() method. These classes are provided in the net.rim.blackberry.api.phone.phone and net.rim.blackberry.api.phone.phonelogs packages. To search all the contact lists for a matching phone number, you can use the Phone.getContactsByPhoneNumber() method. This class is provided in the net.rim.blackberry.api.phone package. You can search for a contact in a specific contact list by a phone number by using one of the BlackBerryContactList.itemsByPhoneNumber() methods. This class is provided in the net.rim.blackberry.api.pdap package.

Application integration

New In This Release

Feature

Description

Accessing a secondary phone number

You can access a secondary mobile phone number or fax number that is associated with a contact by using the new contact attributes in the BlackBerryContact class. This class is provided in the net.rim.blackberry.api.pdap package.

Find out more • • •

API reference for the BlackBerry® Java® SDK Create Contact and Phone Screen sample applications that are included in the BlackBerry Java SDK BlackBerry Java SDK Integration Development Guide

Phone screen enhancements With BlackBerry® Java® SDK 5.0, you can customize the incoming and the active phone screens on a BlackBerry device to display content about a caller by using the Phone Screen API that is provided in the net.rim.blackberry.api.phone.phonegui package. For example, when a BlackBerry device user receives a call, you can display information about the caller that is provided by your application. With BlackBerry Java SDK 6.0, the Phone Screen API enhancements make is easier for you to display content on a phone screen. • • •

You can access phone screen objects, the device orientation (portrait or landscape), and the type of phone screen (incoming or active) by using the ScreenModel class. Previously, you used multiple instances of PhoneScreen objects. You can make your content look like the default content that the Phone application displays on the incoming and the active phone screens by invoking PhoneScreen.getCallerInfoFont(). You can easily get the dimensions of a phone screen by invoking PhoneScreen.getDimensions(). With BlackBerry Java SDK 5.0, you invoked this method for each orientation of the phone screen and each type of phone screen.

Find out more

Network connections

New In This Release

• • •

API reference for the BlackBerry Java SDK Phone Screen sample application that is included in the BlackBerry Java SDK BlackBerry Java SDK Integration Development Guide

Support for setting a default content handler You can register your application as the default handler for a content type by using the DefaultContentHandlerRegistry class that is provided in the net.rim.device.api.content package. For example, you can register your application as the default handler for certain types of documents. If multiple content handlers are registered for a content type, BlackBerry® device users can choose the content handler that they want to set as the default content handler.

Find out more • •

API reference for the BlackBerry Java SDK CHAPI sample application that is included in the BlackBerry Java SDK

Network connections Network API enhancement With BlackBerry® Java® SDK 5.0, you can specify how your application opens a connection to a wireless network by using the Network API that is provided in the net.rim.device.api.io.transport and net.rim.device.api.io.transport.options packages. The Network API simplifies how your application opens a connection to a wireless network, and enables you to find the wireless transport types that are available on the BlackBerry device. For example, you can specify an ordered list of transports you want to use to establish a network connection, and let the Network API choose the first available transport. In BlackBerry Java SDK 6.0, enhancements have been made to the Network API. Feature

Description

Datagram protocol

You can take advantage of UDP by using the network connection functionality that was introduced in BlackBerry Java SDK 5.0. With BlackBerry Java SDK 6.0, calls to the ConnectionFactory.getConnection() method in the net.rim.device.api.io.transport package accept UDP (unicast only) and datagram URLs. This feature is supported only when you use the TRANSPORT_TCP_CELLULAR and TRANSPORT_TCP_WIFI transports.

Network connections

New In This Release

Feature

Description

Detect changes in network transport coverage

You can listen for changes in network transport coverage by implementing the CoverageStatusListener interface. A change in coverage can have several sources, including the addition or deletion of service books, changes to signal strength, transport specific communication requirements, and others. You can check if the default APN is configured for the device in the device's TCP/IP options by using the TcpCellularOptions.isDefaultAPNSet() method in the net.rim.device.api.io.transport.options package.

Detect a default APN

Find out more • •

API reference for the BlackBerry Java SDK Network API sample application that is included in the BlackBerry Java SDK

Communication API Your application can communicate with server-side services by using the Communication API. The Communication API is implemented in the net.rim.device.api.io.messaging package. The API provides a communication library on the BlackBerry® device that is designed to make it easy to communicate with server-side services such as web services. Your application can use the Communication API to communicate with other BlackBerry device applications that include the required listeners. For example, your application can use the Communication API to listen for push messages and be notified by a callback when a message arrives. The Communication API includes support for the following functionality: • • • • • •

Synchronous and asynchronous communications Queuing incoming messages until they are processed by an application Starting an application in response to an incoming message Handling incoming messages as streams Authenticating a device Using a single application to communicate with multiple endpoints

Find out more • •

API reference for the BlackBerry® Java® SDK Communication API sample application that is included in the BlackBerry Java SDK

New In This Release

Network connections

Message Processing API You can build, parse, and query network messages in various formats by using the Message Processing API that is provided in the net.rim.device.api.io.parser and org.json packages. You can use the Message Processing API in conjunction with the Communication API to create end-to-end network communications. The Message Processing API supports the following formats: XML, RSS (RDF, Atom), SOAP, and JSON.

Find out more • •

API reference for the BlackBerry® Java® SDK Communication API sample application that is included in the BlackBerry Java SDK

System requirements

New In This Release

System requirements

Item

Requirement

development environment

One of the following development environments: • • •

BlackBerry® Java® Plug-in for Eclipse® 1.1 or later with BlackBerry® Java® SDK 6.0 BlackBerry® Java® Development Environment 6.0 another third-party development environment, such as NetBeans™, that is running BlackBerry Java SDK 6.0

BlackBerry Smartphone Simulator Any BlackBerry Smartphone Simulator or device that is running BlackBerry® Device or BlackBerry device Software 6.0 or later

New In This Release

Find more information • • • • •

Find more information

www.blackberry.com/go/apiref: View the latest version of the API reference for the BlackBerry® Java® SDK. www.blackberry.com/go/devguides: Find development guides, release notes, and sample application overviews for the BlackBerry Java SDK. www.blackberry.com/developers: Visit the BlackBerry® Developer Zone for resources on developing BlackBerry device applications. www.blackberry.com/go/developerkb: View knowledge base articles on the BlackBerry Development Knowledge Base. www.blackberry.com/developers/downloads: Find the latest development tools and downloads for developing BlackBerry device applications.

New In This Release

Glossary 2-D two-dimensional 3-D three-dimensional AES Advanced Encryption Standard API application programming interface CDMA Code Division Multiple Access CRM customer relationship management DOM Document Object Model DTMF Dual Tone Multiple-frequency EXIF Exchangeable Image File Format GPS Global Positioning System GSM Global System for Mobile Communications速 HTTP Hypertext Transfer Protocol HTTPS Hypertext Transfer Protocol over Secure Sockets Layer JSON JavaScript速 Object Notation

Glossary

New In This Release

Glossary

JSR Java速 Specification Request MIDP Mobile Information Device Profile PBX Private Branch Exchange PIN personal identification number POP Post Office Protocol RDF Resource Description Framework RMS Record Management System RSS Radio Standards Specification SIM Subscriber Identity Module SOAP Simple Object Access Protocol SMS Short Message Service SQL Structured Query Language SSL Secure Sockets Layer SVG Scalable Vector Graphics TCP Transmission Control Protocol

New In This Release

Triple DES Triple Data Encryption Standard UID unique identifier WLAN wireless local area network XML Extensible Markup Language

Glossary

New In This Release

Provide feedback

To provide feedback on this deliverable, visit www.blackberry.com/docsfeedback.

Document revision history

New In This Release

Document revision history Date

Description

3 September 2010

Added the following topics: • •

27 August 2010

Changed the Graphics and animation topic. Added the following topics: • •

16 August 2010 3 August 2010

Pop-up menus and submenus WebKit browser engine

Convenience key access Pop-up menus and submenus

Added the Device interaction support topic. Initial version.

New In This Release

Legal notice

息2010 Research In Motion Limited. All rights reserved. BlackBerry速, RIM速, Research In Motion速, and related trademarks, names, and logos are the property of Research In Motion Limited and are registered and/or used in the U.S. and countries around the world. Bluetooth is a trademark of Bluetooth SIG. Eclipse is a trademark of Eclipse Foundation, Inc. Facebook is a trademark of Facebook, Inc. GSM is a trademark of the GSM MOU Association. Intel and Pentium are trademarks of Intel Corporation. Java, JavaScript, and NetBeans are trademarks of Oracle America, Inc. OpenGL is a trademark of Silicon Graphics, Inc. OpenVG is a trademark of Khronos Group. SQLite is a trademark of Hipp, Wyrick & Company, Inc. SVG Tiny is a trademark of W3C. Twitter is a trademark of Twitter, Inc. Wi-Fi is a trademark of the Wi-Fi Alliance. All other trademarks are the property of their respective owners. This documentation including all documentation incorporated by reference herein such as documentation provided or made available at www.blackberry.com/go/docs is provided or made accessible "AS IS" and "AS AVAILABLE" and without condition, endorsement, guarantee, representation, or warranty of any kind by Research In Motion Limited and its affiliated companies ("RIM") and RIM assumes no responsibility for any typographical, technical, or other inaccuracies, errors, or omissions in this documentation. In order to protect RIM proprietary and confidential information and/or trade secrets, this documentation may describe some aspects of RIM technology in generalized terms. RIM reserves the right to periodically change information that is contained in this documentation; however, RIM makes no commitment to provide any such changes, updates, enhancements, or other additions to this documentation to you in a timely manner or at all. This documentation might contain references to third-party sources of information, hardware or software, products or services including components and content such as content protected by copyright and/or third-party web sites (collectively the "Third Party Products and Services"). RIM does not control, and is not responsible for, any Third Party Products and Services including, without limitation the content, accuracy, copyright compliance, compatibility, performance, trustworthiness, legality, decency, links, or any other aspect of Third Party Products and Services. The inclusion of a reference to Third Party Products and Services in this documentation does not imply endorsement by RIM of the Third Party Products and Services or the third party in any way. EXCEPT TO THE EXTENT SPECIFICALLY PROHIBITED BY APPLICABLE LAW IN YOUR JURISDICTION, ALL CONDITIONS, ENDORSEMENTS, GUARANTEES, REPRESENTATIONS, OR WARRANTIES OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING WITHOUT LIMITATION, ANY CONDITIONS, ENDORSEMENTS, GUARANTEES, REPRESENTATIONS OR WARRANTIES OF DURABILITY, FITNESS FOR A PARTICULAR PURPOSE OR USE, MERCHANTABILITY, MERCHANTABLE QUALITY, NONINFRINGEMENT, SATISFACTORY QUALITY, OR TITLE, OR ARISING FROM A STATUTE OR CUSTOM OR A COURSE OF DEALING OR USAGE OF TRADE, OR RELATED TO THE DOCUMENTATION OR ITS USE, OR PERFORMANCE OR NON-PERFORMANCE OF ANY SOFTWARE, HARDWARE, SERVICE, OR ANY THIRD PARTY PRODUCTS AND SERVICES REFERENCED HEREIN, ARE HEREBY EXCLUDED. YOU MAY ALSO HAVE OTHER RIGHTS THAT VARY BY STATE OR PROVINCE. SOME JURISDICTIONS MAY NOT ALLOW THE EXCLUSION OR LIMITATION OF IMPLIED WARRANTIES AND CONDITIONS. TO THE EXTENT PERMITTED BY LAW, ANY IMPLIED WARRANTIES OR CONDITIONS RELATING TO THE DOCUMENTATION TO THE EXTENT THEY CANNOT BE EXCLUDED AS SET OUT ABOVE, BUT CAN BE LIMITED, ARE HEREBY LIMITED TO NINETY (90) DAYS FROM THE DATE YOU FIRST ACQUIRED THE DOCUMENTATION OR THE ITEM THAT IS THE SUBJECT OF THE CLAIM. TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW IN YOUR JURISDICTION, IN NO EVENT SHALL RIM BE LIABLE FOR ANY TYPE OF DAMAGES RELATED TO THIS DOCUMENTATION OR ITS USE, OR PERFORMANCE OR NONPERFORMANCE OF ANY SOFTWARE, HARDWARE, SERVICE, OR ANY THIRD PARTY PRODUCTS AND SERVICES REFERENCED

New In This Release

Legal notice

HEREIN INCLUDING WITHOUT LIMITATION ANY OF THE FOLLOWING DAMAGES: DIRECT, CONSEQUENTIAL, EXEMPLARY, INCIDENTAL, INDIRECT, SPECIAL, PUNITIVE, OR AGGRAVATED DAMAGES, DAMAGES FOR LOSS OF PROFITS OR REVENUES, FAILURE TO REALIZE ANY EXPECTED SAVINGS, BUSINESS INTERRUPTION, LOSS OF BUSINESS INFORMATION, LOSS OF BUSINESS OPPORTUNITY, OR CORRUPTION OR LOSS OF DATA, FAILURES TO TRANSMIT OR RECEIVE ANY DATA, PROBLEMS ASSOCIATED WITH ANY APPLICATIONS USED IN CONJUNCTION WITH RIM PRODUCTS OR SERVICES, DOWNTIME COSTS, LOSS OF THE USE OF RIM PRODUCTS OR SERVICES OR ANY PORTION THEREOF OR OF ANY AIRTIME SERVICES, COST OF SUBSTITUTE GOODS, COSTS OF COVER, FACILITIES OR SERVICES, COST OF CAPITAL, OR OTHER SIMILAR PECUNIARY LOSSES, WHETHER OR NOT SUCH DAMAGES WERE FORESEEN OR UNFORESEEN, AND EVEN IF RIM HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW IN YOUR JURISDICTION, RIM SHALL HAVE NO OTHER OBLIGATION, DUTY, OR LIABILITY WHATSOEVER IN CONTRACT, TORT, OR OTHERWISE TO YOU INCLUDING ANY LIABILITY FOR NEGLIGENCE OR STRICT LIABILITY. THE LIMITATIONS, EXCLUSIONS, AND DISCLAIMERS HEREIN SHALL APPLY: (A) IRRESPECTIVE OF THE NATURE OF THE CAUSE OF ACTION, DEMAND, OR ACTION BY YOU INCLUDING BUT NOT LIMITED TO BREACH OF CONTRACT, NEGLIGENCE, TORT, STRICT LIABILITY OR ANY OTHER LEGAL THEORY AND SHALL SURVIVE A FUNDAMENTAL BREACH OR BREACHES OR THE FAILURE OF THE ESSENTIAL PURPOSE OF THIS AGREEMENT OR OF ANY REMEDY CONTAINED HEREIN; AND (B) TO RIM AND ITS AFFILIATED COMPANIES, THEIR SUCCESSORS, ASSIGNS, AGENTS, SUPPLIERS (INCLUDING AIRTIME SERVICE PROVIDERS), AUTHORIZED RIM DISTRIBUTORS (ALSO INCLUDING AIRTIME SERVICE PROVIDERS) AND THEIR RESPECTIVE DIRECTORS, EMPLOYEES, AND INDEPENDENT CONTRACTORS. IN ADDITION TO THE LIMITATIONS AND EXCLUSIONS SET OUT ABOVE, IN NO EVENT SHALL ANY DIRECTOR, EMPLOYEE, AGENT, DISTRIBUTOR, SUPPLIER, INDEPENDENT CONTRACTOR OF RIM OR ANY AFFILIATES OF RIM HAVE ANY LIABILITY ARISING FROM OR RELATED TO THE DOCUMENTATION. Prior to subscribing for, installing, or using any Third Party Products and Services, it is your responsibility to ensure that your airtime service provider has agreed to support all of their features. Some airtime service providers might not offer Internet browsing functionality with a subscription to the BlackBerry速 Internet Service. Check with your service provider for availability, roaming arrangements, service plans and features. Installation or use of Third Party Products and Services with RIM's products and services may require one or more patent, trademark, copyright, or other licenses in order to avoid infringement or violation of third party rights. You are solely responsible for determining whether to use Third Party Products and Services and if any third party licenses are required to do so. If required you are responsible for acquiring them. You should not install or use Third Party Products and Services until all necessary licenses have been acquired. Any Third Party Products and Services that are provided with RIM's products and services are provided as a convenience to you and are provided "AS IS" with no express or implied conditions, endorsements, guarantees, representations, or warranties of any kind by RIM and RIM assumes no liability whatsoever, in relation thereto. Your use of Third Party Products and Services shall be governed by and subject to you agreeing to the terms of separate licenses and other agreements applicable thereto with third parties, except to the extent expressly covered by a license or other agreement with RIM. Certain features outlined in this documentation require a minimum version of BlackBerry速 Enterprise Server, BlackBerry速 Desktop Software, and/or BlackBerry速 Device Software.

New In This Release

Legal notice

The terms of use of any RIM product or service are set out in a separate license or other agreement with RIM applicable thereto. NOTHING IN THIS DOCUMENTATION IS INTENDED TO SUPERSEDE ANY EXPRESS WRITTEN AGREEMENTS OR WARRANTIES PROVIDED BY RIM FOR PORTIONS OF ANY RIM PRODUCT OR SERVICE OTHER THAN THIS DOCUMENTATION. Research In Motion Limited 295 Phillip Street Waterloo, ON N2L 3W8 Canada Research In Motion UK Limited Centrum House 36 Station Road Egham, Surrey TW20 9LF United Kingdom Published in Canada