Package net.rim.blackberry.api.homescreen

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


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:

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

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.
  6. Invoke Shortcut.setDescription() to specify the descriptive text that appears when the shortcut is in focus.
  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().

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. All Rights Reserved.
Copyright 2002-2003 Nokia Corporation All Rights Reserved.
Java is a trademark of Sun Microsystems, Inc.