net.rim.blackberry.api.homescreen
Class HomeScreen

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





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.