Package net.rim.blackberry.api.homescreen

Provides classes and interfaces to access Home screen items and the theme on the BlackBerry device

See:
Description

Interface Summary

Shortcut	Interface that encapsulates a Home screen shortcut.
ShortcutEventListener	The interface that you must implement if you want to add a shortcut to the Home screen on the device.

Class Summary

HomeScreen	Contains methods for accessing theme information and Home screen items, and changing properties of Home screen items (for example, icon, description, and background image), and managing shortcuts.
Location	Specifies a location on the Home screen.
ShortcutIconField	Provides the ability to add a shortcut to a UI screen.
ShortcutProvider	Used to create shortcuts on the Home screen of the device.

Package net.rim.blackberry.api.homescreen Description

Provides classes and interfaces to access Home screen items and the theme on the BlackBerry device.

Shortcut API

This package provides the Shortcut API. You can create shortcuts and add them to the Home screen on the BlackBerry® device by using the Shortcut API. When a user selects a shortcut, the application that is associated with the shortcut opens within a specified context. For example, you can create a shortcut to a contact so that when a user selects the shortcut, the Contacts application opens and displays the specified contact. You could create shortcuts for a wide variety of reasons. For example, shortcuts to a browser bookmark, map location, or playlist.

You can use the following classes and interfaces to create a shortcut:

• ShortcutProvider provides a factory method for creating shortcuts
• Shortcut interface encapsulates a shortcut and specifies information about the shortcut such as the icons to associate with the shortcut and the text to associate with the shortcut
• HomeScreen provides methods to add shortcuts to the Home screen and check if shortcuts exist
• Location specifies where the shortcut should appear on the Home screen
• ShortcutEventListener interface that provides methods to manage opening, changing, and deleting shortcuts

You can use the following classes to add functionality to your UI around creating a shortcut:

• ShortcutIconField provides users with a way to preview a shortcut's icon from your application's UI
• HomeScreenLocationPicker (in the net.rim.device.api.ui.picker package) provides a picker for user's to choose a location of the shortcut (for example, on the Home screen or in a folder) and to specify the shortcut as a favorite

Create a shortcut

1. Create a HomeScreenLocationPicker in your application's UI to allow users to choose a location for the shortcut and to specify whether the shortcut is a favorite.

   HomeScreenLocationPicker scPicker = HomeScreenLocationPicker.create();

2. Invoke HomeScreenLocationPicker.getLocation() to retrieve the location and favorite information specified by the user.

   Location scLocation = scPicker.getLocation();

3. Implement the Shortcut interface.
4. Invoke ShortcutProvider.createShortcut() to create the shortcut.

   Shortcut shortcut = ShortcutProvider.createShortcut("myDescription","myShortcutID");

5. Invoke Shortcut.setRollOverIcon() and Shortcut.setRollOverIcon() to specify the icon to use in the normal and focus states. The icon must be an encoded image.

   shortcut.setIcon(icon);
   shortcut.setRollOverIcon(focusIcon);

6. Invoke Shortcut.setDescription() to specify the descriptive text that appears when the shortcut is in focus.

   shortcut.setDescription(description);

7. Add the shortcut to the Home screen by invoking HomeScreen.addShortcut(). Pass in the location specified by the user.

   HomeScreen.addShortcut(shortcut, scLocation);

You can remove the shortcut from the Home screen by invoking HomeScreen.removeShortcut().