net.rim.blackberry.api.homescreen
Class HomeScreen

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

public abstract class HomeScreen
extends Object

APIs for accessing the home screen.

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 String getActiveThemeName()
          Returns the name of the active theme.
Category: Signed static int getPreferredIconHeight()
          Returns the preferred icon height with respect to the active theme.
Category: Signed static int getPreferredIconWidth()
          Returns the preferred icon width with respect to the active theme.
Category: Signed static void setBackgroundImage(String uri)
          Sets the background image for the home screen.
Category: Signed static void setName(String name)
          Update the current application's name.
Category: Signed static void setName(String name, int index)
          If the current module has multiple application entry points, use this method to update the name for one particular entry point.
Category: Signed static void setName(String name, ApplicationDescriptor descriptor)
          Sets name for application specified by ApplicationDescriptor parameter.
Category: Signed static void setRolloverIcon(Bitmap rollovericon)
          Sets the rollover icon for use with this application.
Category: Signed static void setRolloverIcon(Bitmap rollovericon, int index)
          Sets the rollover icon for use with this application entry point.
Category: Signed static void setRolloverIcon(Bitmap rollovericon, ApplicationDescriptor descriptor)
          Sets the rollover icon for use with application specified by ApplicationDescriptor parameter.
Category: Signed static boolean supportsIcons()
          Returns true if the current theme supports icons
Category: Signed static void updateIcon(Bitmap newIcon)
          Update the current application's icon.
Category: Signed static void updateIcon(Bitmap newIcon, int index)
          If the current module has multiple application entry points, use this method to update the icon for one particular entry point.
Category: Signed static void updateIcon(Bitmap newIcon, ApplicationDescriptor descriptor)
          Updates 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.

Returns:
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)
Sets the background image for the home screen. Must be an image file residing in flash memory or SD 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 results in the default background image being reset.
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 icon height 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 HomeScreen.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 icon width 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 HomeScreen.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)
Update the current application's name. If name is null, then the application's default name, as specified in the original project workspace, is used.

Note: Changes made using this API are NOT persisted across resets.

Parameters:
name - 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)
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 name is null, then the application's default name, as specified in the original project workspace, is used.

Note: Changes made using this API are NOT persisted across resets.

Parameters:
name - New name, or null if the application's default name 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.2.0

setRolloverIcon

public static final void setRolloverIcon(Bitmap rollovericon)
Sets the rollover icon for use with this application. 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 are NOT persisted 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)
Sets the rollover icon for use with this application 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 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 are NOT persisted 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 true if 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)
Update 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 are NOT persisted across resets.

Parameters:
newIcon - 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)
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 are NOT persisted across resets

Parameters:
newIcon - 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 icon for the application specified by the ApplicationDescriptor parameter. This method should be called when 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 are NOT persisted across resets.

Parameters:
newIcon - 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)
Sets the rollover icon for use with application specified by ApplicationDescriptor parameter.

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 are NOT persisted 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)
Sets name for application specified by ApplicationDescriptor parameter. If name is null, then the application's default name, as specified in the original project workspace, is used.

Note: Changes made using this API are NOT persisted 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





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.