net.rim.blackberry.api.homescreen
Class HomeScreen

java.lang.Object
  net.rim.blackberry.api.homescreen.HomeScreen

public abstract class HomeScreen
extends Object

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.

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 4.1.0

Method Summary
	static void	addShortcut(Shortcut shortcut, Location location) Adds the shortcut to the Home screen.
	static boolean	doesShortcutExist(String shortcutID) Checks whether the shortcut was added to the Home screen by the calling application
	static String	getActiveThemeName() Returns the name of the active theme on the device.
	static int	getPreferredIconHeight() Returns the preferred height of Home screen icons with respect to the active theme.
	static int	getPreferredIconWidth() Returns the preferred width of Home screen icons with respect to the active theme.
	static Shortcut	getShortcut(String shortcutID) Retrieves an instance of a shortcut with the specified ID that belongs to the calling application.
	static String[]	getShortcutIDs() Retrieves all the shortcuts of the calling application.
	static void	removeShortcut(String shortcutID) Removes the shortcut from the Home screen.
	static void	setBackgroundImage(String uri) Specifies the background image for the Home screen.
	static void	setName(String name) Updates the current application's name.
	static void	setName(String name, int index) Updates the name of an application's entry point.
	static void	setName(String name, ApplicationDescriptor descriptor) Updates the name of the application specified by the ApplicationDescriptor parameter.
	static void	setNewState(boolean newState) Specifies the state flag to indicate that there is something new for the application.
	static void	setNewState(boolean newState, ApplicationDescriptor appDescr) Specifies the state flag to indicate that there is something new for the application.
	static void	setRolloverIcon(Bitmap rollovericon) Updates the icon to use when this application is in focus.
	static void	setRolloverIcon(Bitmap rollovericon, int index) Updates the icon to use when this application entry point is in focus.
	static void	setRolloverIcon(Bitmap rollovericon, ApplicationDescriptor descriptor) Updates the icon to use when the application specified by the ApplicationDescriptor parameter is in focus.
	static boolean	supportsIcons() Returns whether the current theme supports icons.
	static void	updateIcon(Bitmap newIcon) Updates the current application's icon.
	static void	updateIcon(Bitmap newIcon, int index) Updates the icon to use for an application entry point.
	static void	updateIcon(Bitmap newIcon, ApplicationDescriptor descriptor) Updates the icon for the application specified by the ApplicationDescriptor parameter.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

getActiveThemeName

public static final String getActiveThemeName()

Returns the name of the active theme on the device.

Returns:

The name of the active theme.

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 4.1.0

setBackgroundImage

public static final void setBackgroundImage(String uri)

Specifies the background image for the Home screen. The image file must be in flash memory or on a memory card. Typical format for the URI would be "file:///store/home/user/pictures/file.jpg".

Parameters:

uri - Resource identifier for the image file to be used as the Home screen background. A null value or an invalid path/filename resets the background to the default image.

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 4.7.0

getPreferredIconHeight

public static final int getPreferredIconHeight()

Returns the preferred height of Home screen icons with respect to the active theme.

Returns:

Preferred icon height (in pixels). Returns 0 if there is no active theme. If the active theme does not support icons (that is, if supportsIcons() returns false) then the value returned by this method is undefined.

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 4.1.0

getPreferredIconWidth

public static final int getPreferredIconWidth()

Returns the preferred width of Home screen icons with respect to the active theme.

Returns:

Preferred icon width (in pixels). Returns 0 if there is no active theme. If the active theme does not support icons (that is, if supportsIcons() returns false) then the value returned by this method is undefined.

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 4.1.0

setName

public static final void setName(String name)

Updates the current application's name. If the name is null, then the application's default name, as specified in the original project workspace, is used.

Note: Changes made using this API do not persist across resets.

Parameters:

name - The new name or null if the application's default name is to be used.

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 4.2.0

setName

public static final void setName(String name,
                                 int index)

Updates the name of an application's entry point. If the current module has multiple application entry points, use this method to update the name for one particular entry point. The index corresponds to the order in which alternate entry points were created in the original project workspace, and can be determined using the .rapc file generated for the project. If the name is null, then the application's default name, as specified in the original project workspace, is used.

Note: Changes made using this API do not persist across resets.

Parameters:

name - The new name or null if the application's default name is to be used.

index - Index of the entry point to update starting from 0.

Throws:

IllegalArgumentException - if the index doesn't correspond to a valid entry point.

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 4.2.0

setRolloverIcon

public static final void setRolloverIcon(Bitmap rollovericon)

Updates the icon to use when this application is in focus. If rollovericon is null, then the application's default rollover icon, as specified in the original project workspace, is used.

Note: If you have not specified a main application icon for the application, you must call updateIcon() and provide an icon before setting the rollover icon. Otherwise, the system will override the main icon and the rollover icon as set by this method with the default icons for the current theme.

Note: Changes made using this API do not persist across resets.

Parameters:

rollovericon - Icon to use when the application icon is in focus on the Home screen, or null if the application's default rollover icon is to be used.

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 4.1.0

setRolloverIcon

public static final void setRolloverIcon(Bitmap rollovericon,
                                         int index)

Updates the icon to use when this application entry point is in focus. The index corresponds to the order in which alternate entry points were created in the original project workspace, and can be determined using the .rapc file generated for the project. If rollovericon is null, then the application's default rollover icon, as specified in the original project workspace, is used.

Note: If you have not specified a main application icon for the application, you must call updateIcon() and provide an icon before setting the rollover icon. Otherwise, the system will override the main icon and the rollover icon as set by this method with the default icons for the current theme.

Note: Changes made using this API do not persist across resets.

Parameters:

rollovericon - Icon to use when the application icon is in focus on the Home screen, or null if the application's default rollover icon is to be used.

index - Index of the application entry point to update.

Throws:

IllegalArgumentException - if the index doesn't correspond to a valid entry point

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 4.1.0

supportsIcons

public static final boolean supportsIcons()

Returns whether the current theme supports icons.

Returns:

true if the current theme supports icons, false otherwise.

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 4.1.0

updateIcon

public static final void updateIcon(Bitmap newIcon)

Updates the current application's icon. If newIcon is null, then the application's default icon, as specified in the original project workspace, is used.

Note: Changes made using this API do not persist across resets.

Parameters:

newIcon - The new icon or null if the application's default icon is to be used.

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 4.1.0

updateIcon

public static final void updateIcon(Bitmap newIcon,
                                    int index)

Updates the icon to use for an application entry point. If the current module has multiple application entry points, use this method to update the icon for one particular entry point. The index corresponds to the order in which alternate entry points were created in the original project workspace, and can be determined using the .rapc file generated for the project. If newIcon is null, then the application's default icon, as specified in the original project workspace, is used.

Note: Changes made using this API do not persist across resets.

Parameters:

newIcon - The new icon or null if the application's default icon is to be used.

index - Index of the entry point to update, from 0.

Throws:

IllegalArgumentException - if the index doesn't correspond to a valid entry point

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 4.1.0

updateIcon

public static final void updateIcon(Bitmap newIcon,
                                    ApplicationDescriptor descriptor)

Updates the icon for the application specified by the ApplicationDescriptor parameter. Call this method when the current application is different from the one specified by the ApplicationDescriptor. This may occur in some types of listener callbacks that are performed by a system module.

Note: Changes made using this API do not persist across resets.

Parameters:

newIcon - The new icon or null if the application's default icon is to be used.

descriptor - Application descriptor that points to the application.

Throws:

NullPointerException - if descriptor is null

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 4.7.0

setRolloverIcon

public static final void setRolloverIcon(Bitmap rollovericon,
                                         ApplicationDescriptor descriptor)

Updates the icon to use when the application specified by the ApplicationDescriptor parameter is in focus.

Note: If you have not specified a main application icon for the application, you must call updateIcon() and provide an icon before setting the rollover icon, otherwise the system will override the main icon and the rollover icon as set by this method with the default icons for the current theme.

Note: Changes made using this API do not persist across resets.

Parameters:

rollovericon - Icon to use when the application icon is in focus on the Home screen, or null if the application's default rollover icon is to be used.

descriptor - Application descriptor that points to the application.

Throws:

IllegalArgumentException - if the index doesn't correspond to a valid entry point

NullPointerException - if descriptor is null

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 4.7.0

setName

public static final void setName(String name,
                                 ApplicationDescriptor descriptor)

Updates the name of the application specified by the ApplicationDescriptor parameter. If the name is null, then the application's default name, as specified in the original project workspace, is used.

Note: Changes made using this API do not persist across resets.

Parameters:

name - New name, or null if the application's default name is to be used.

descriptor - Application descriptor that points to the application.

Throws:

IllegalArgumentException - if the index doesn't correspond to a valid entry point.

NullPointerException - if descriptor is null

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 4.7.0

addShortcut

public static final void addShortcut(Shortcut shortcut,
                                     Location location)

Adds the shortcut to the Home screen.

This shortcut will be displayed on the Home screen with a specific name and context. The shortcut can then be launched with this specific context.

Parameters:

shortcut - The shortcut to be added.

location - The location to add the shortcut.

Throws:

IllegalArgumentException - if the shortcut instance is not created by ShortcutProvider.createShortcut().

IllegalArgumentException - if shortcut is already present on HomeScreen.

NullPointerException - if either shortcut or location is null.

See Also:

net.rim.device.api.ui.picker.HomeScreenLocationPicker.LocationPicker#getLocation

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 6.0.0

removeShortcut

public static final void removeShortcut(String shortcutID)

Removes the shortcut from the Home screen. You can only remove your own shortcuts.

Parameters:

shortcutID - ID of the shortcut to be removed.

Throws:

IllegalArgumentException - if the application did not add a shortcut with the specified shortcutID

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 6.0.0

doesShortcutExist

public static final boolean doesShortcutExist(String shortcutID)

Checks whether the shortcut was added to the Home screen by the calling application

Parameters:

shortcutID - ID of the shortcut to check.

Returns:

true if the shortcut exists and it was added by the calling application; false otherwise.

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 6.0.0

getShortcut

public static final Shortcut getShortcut(String shortcutID)

Retrieves an instance of a shortcut with the specified ID that belongs to the calling application.

Parameters:

shortcutID - ID of the shortcut to retrieve.

Returns:

Instance of the shortcut. Returns null if there is no shortcut with this ID that belongs to the calling application.

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 6.0.0

getShortcutIDs

public static final String[] getShortcutIDs()

Retrieves all the shortcuts of the calling application. HomeScreen has a shortcut instance available for each of these shortcutID.

Returns:

Array of all the shortcutIDs which belong to the calling application. Returns null if none exist.

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 6.0.0

setNewState

public static void setNewState(boolean newState)

Specifies the state flag to indicate that there is something new for the application. When there is something new, an indicator (for example, a red asterisk) is added to the icon to indicate that "new" items are available. The application that registers this shortcut should set and clear the state flag when there are new items and after they are read.

Parameters:

newState - If true there is something new for this shortcut; false otherwise.

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 6.0.0

setNewState

public static void setNewState(boolean newState,
                               ApplicationDescriptor appDescr)

Specifies the state flag to indicate that there is something new for the application. When there is something new, an indicator (for example, a red asterisk) is added to the icon to indicate that "new" items are available. The application that registers this shortcut should set and clear the state flag when there are new items and after they are read.

Parameters:

newState - If true there is something new for this shortcut; false otherwise.

appDescr - The application descriptor of the icon to flag.

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 6.0.0