net.rim.device.api.system
Class ApplicationDescriptor

java.lang.Object
  extended by net.rim.device.api.system.ApplicationDescriptor

public final class ApplicationDescriptor
extends Object

Encapsulates descriptive information for an application.

See Also:
Application, ApplicationManager

Field Summary
static int DO_NOT_POWER_ON
          If the device is off, DO NOT power on the device when this application is scheduled to be run.
static byte FLAG_AUTO_RESTART
          Automatically restart this application if it exits.
static byte FLAG_RUN_ON_STARTUP
          Run this application on device startup.
static byte FLAG_SYSTEM
          Do not present this application on the device's ribbon.
static int POWER_ON
          If the device is off, power on the device when this application is scheduled to be run.
static int POWER_ON_ALWAYS
          If the device is off, power on the device when this application is scheduled to be run, only if it's in a list of preregistered applications that are to power on.
static int POWER_ON_FOR_AUTO_ON
          If the device is off, power on the device when this application is scheduled to be run, only if it's in a list of preregistered applications that are to power on.
 
Constructor Summary
ApplicationDescriptor(ApplicationDescriptor original, String name, String[] args)
          Constructs a new ApplicationDescriptor with the specified name using another ApplicationDescriptor as a template.
ApplicationDescriptor(ApplicationDescriptor original, String name, String[] args, int position, String nameResourceBundle, int nameResourceId)
          Constructs a new ApplicationDescriptor instance with the specified name and initial settings using another ApplicationDescriptor as a template.
ApplicationDescriptor(ApplicationDescriptor original, String name, String[] args, int position, String nameResourceBundle, int nameResourceId, int flags)
          Constructs a new ApplicationDescriptor instance with the specified name and initial settings using another ApplicationDescriptor as a template.
ApplicationDescriptor(ApplicationDescriptor original, String name, String[] args, int position, String nameResourceBundle, int nameResourceId, int flags, String folderName)
          Constructs a new ApplicationDescriptor instance with the specified name and initial settings using another ApplicationDescriptor as a template.
ApplicationDescriptor(ApplicationDescriptor original, String name, String[] args, Bitmap icon, int position, String nameResourceBundle, int nameResourceId)
          Deprecated. The caching of icon Bitmap objects is no longer supported. Use ApplicationDescriptor.ApplicationDescriptor(ApplicationDescriptor,String,String[],int,String,int) instead.
ApplicationDescriptor(ApplicationDescriptor original, String name, String[] args, Bitmap icon, int position, String nameResourceBundle, int nameResourceId, int flags)
          Deprecated. The caching of icon Bitmap objects is no longer supported. Use ApplicationDescriptor.ApplicationDescriptor(ApplicationDescriptor,String,String[],int,String,int,int) instead.
ApplicationDescriptor(ApplicationDescriptor original, String[] args)
          Constructs a new ApplicationDescriptor instance using another ApplicationDescriptor as a template.
 
Method Summary
static ApplicationDescriptor currentApplicationDescriptor()
          Retrieves the descriptor for the application that started the current process.
 boolean equals(Object o)
          Compares this descriptor to another object for equivalency.
 String[] getArgs()
          Retrieves the argument array from this descriptor.
 StringProvider getDescription()
          Retrieves the StringProvider object containing the description of the application.
 EncodedImage getEncodedIcon()
          Retrieves the icon from this descriptor.
 int getFlags()
          Retrieves the flags from this descriptor.
 String getFolderName()
          Returns the suggested folder name to place this application in.
 Bitmap getIcon()
          Deprecated. Use ApplicationDescriptor.getEncodedIcon() instead.
 int getIndex()
          Retrieves the application index from this descriptor.
 StringProvider getKeywords()
          Retrieves the StringProvider object containing the keywords for the application.
 String getKeywordsResourceBundle()
          Retrieves the keywords resource bundle from this descriptor.
 int getKeywordsResourceId()
          Retrieves the keywords resource ID from this descriptor.
 String getLocalizedName()
          Retrieves the localized name of the application.
 int getModuleHandle()
          Retrieves the handle for this descriptor's code module.
 String getModuleName()
          Retrieves the name of this descriptor's code module.
 String getName()
          Retrieves the application name from this descriptor.
 String getNameResourceBundle()
          Retrieves the resource bundle from this descriptor.
 int getNameResourceId()
          Retrieves the resource ID from this descriptor.
 int getPosition()
          Returns the application's suggested position on the Home screen.
 int getPowerOnBehavior()
          Retrieves the application's "power on" behavior.
 StringProvider getTitle()
          Retrieves the StringProvider object containing the name of the application.
 String getVersion()
          Retrieves the version from this descriptor.
 void setPowerOnBehavior(int behavior)
          Sets the application's "power on" behavior.
 
Methods inherited from class java.lang.Object
getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 



Field Detail

DO_NOT_POWER_ON

public static final int DO_NOT_POWER_ON
If the device is off, DO NOT power on the device when this application is scheduled to be run.

See Also:
Constant Field Values
Since:
BlackBerry API 4.1.0

POWER_ON

public static final int POWER_ON
If the device is off, power on the device when this application is scheduled to be run.

See Also:
Constant Field Values
Since:
BlackBerry API 4.1.0

POWER_ON_FOR_AUTO_ON

public static final int POWER_ON_FOR_AUTO_ON
If the device is off, power on the device when this application is scheduled to be run, only if it's in a list of preregistered applications that are to power on.

See Also:
Constant Field Values
Since:
BlackBerry API 4.1.0

POWER_ON_ALWAYS

public static final int POWER_ON_ALWAYS
If the device is off, power on the device when this application is scheduled to be run, only if it's in a list of preregistered applications that are to power on.

See Also:
Constant Field Values
Since:
BlackBerry API 4.1.0

FLAG_RUN_ON_STARTUP

public static final byte FLAG_RUN_ON_STARTUP
Run this application on device startup.

See Also:
Constant Field Values

FLAG_SYSTEM

public static final byte FLAG_SYSTEM
Do not present this application on the device's ribbon.

Applications that should hide from the ribbon because they're not really meant for user interaction can use this flag.

See Also:
Constant Field Values

FLAG_AUTO_RESTART

public static final byte FLAG_AUTO_RESTART
Automatically restart this application if it exits.

See Also:
Constant Field Values
Since:
BlackBerry API 3.6.0


Constructor Detail

ApplicationDescriptor

public ApplicationDescriptor(ApplicationDescriptor original,
                             String[] args)
Constructs a new ApplicationDescriptor instance using another ApplicationDescriptor as a template.

This method builds a new application descriptor but does not provide it with a name.

Parameters:
original - The application descriptor from which to build this new one.
args - The initial arguments for this new descriptor.
Since:
BlackBerry API 3.6.0

ApplicationDescriptor

public ApplicationDescriptor(ApplicationDescriptor original,
                             String name,
                             String[] args)
Constructs a new ApplicationDescriptor with the specified name using another ApplicationDescriptor as a template.

Parameters:
original - The application descriptor from which to build this new one.
name - The name for this new descriptor.
args - The initial arguments for this new descriptor.
Since:
BlackBerry API 3.6.0

ApplicationDescriptor

public ApplicationDescriptor(ApplicationDescriptor original,
                             String name,
                             String[] args,
                             Bitmap icon,
                             int position,
                             String nameResourceBundle,
                             int nameResourceId)
Deprecated. The caching of icon Bitmap objects is no longer supported. Use ApplicationDescriptor.ApplicationDescriptor(ApplicationDescriptor,String,String[],int,String,int) instead.

Constructs a new ApplicationDescriptor instance with the specified name and initial settings using another ApplicationDescriptor as a template.

Parameters:
original - The application descriptor from which to build this new one.
name - The name for this new descriptor.
args - The initial arguments for this new descriptor.
icon - The display icon for this new descriptor.
position - The Home screen position for this new descriptor's icon.
nameResourceBundle - The resource bundle containing a localized version of this descriptor's name.
nameResourceId - The resource ID containing a localized version of this descriptor's name.
Since:
BlackBerry API 3.6.0

ApplicationDescriptor

public ApplicationDescriptor(ApplicationDescriptor original,
                             String name,
                             String[] args,
                             Bitmap icon,
                             int position,
                             String nameResourceBundle,
                             int nameResourceId,
                             int flags)
Deprecated. The caching of icon Bitmap objects is no longer supported. Use ApplicationDescriptor.ApplicationDescriptor(ApplicationDescriptor,String,String[],int,String,int,int) instead.

Constructs a new ApplicationDescriptor instance with the specified name and initial settings using another ApplicationDescriptor as a template.

Parameters:
original - The application descriptor from which to build this new one.
name - The name for this new descriptor.
args - The initial arguments for this new descriptor.
icon - The display icon for this new descriptor.
position - The Home screen position for this new descriptor's icon.
nameResourceBundle - The resource bundle containing a localized version of this descriptor's name.
nameResourceId - The resource ID containing a localized version of this descriptor's name.
flags - The application flags for this new descriptor.
Since:
BlackBerry API 3.6.0

ApplicationDescriptor

public ApplicationDescriptor(ApplicationDescriptor original,
                             String name,
                             String[] args,
                             int position,
                             String nameResourceBundle,
                             int nameResourceId)
Constructs a new ApplicationDescriptor instance with the specified name and initial settings using another ApplicationDescriptor as a template.

Parameters:
original - The application descriptor from which to build this new one.
name - The name for this new descriptor.
args - The initial arguments for this new descriptor.
position - The Home screen position for this new descriptor's icon.
nameResourceBundle - The resource bundle containing a localized version of this descriptor's name.
nameResourceId - The resource ID containing a localized version of this descriptor's name.
Since:
BlackBerry API 4.7.0

ApplicationDescriptor

public ApplicationDescriptor(ApplicationDescriptor original,
                             String name,
                             String[] args,
                             int position,
                             String nameResourceBundle,
                             int nameResourceId,
                             int flags)
Constructs a new ApplicationDescriptor instance with the specified name and initial settings using another ApplicationDescriptor as a template.

Parameters:
original - The application descriptor from which to build this new one.
name - The name for this new descriptor.
args - The initial arguments for this new descriptor.
position - The Home screen position for this new descriptor's icon.
nameResourceBundle - The resource bundle containing a localized version of this descriptor's name.
nameResourceId - The resource ID containing a localized version of this descriptor's name.
flags - The application flags for this new descriptor.
Since:
BlackBerry API 4.7.0

ApplicationDescriptor

public ApplicationDescriptor(ApplicationDescriptor original,
                             String name,
                             String[] args,
                             int position,
                             String nameResourceBundle,
                             int nameResourceId,
                             int flags,
                             String folderName)
Constructs a new ApplicationDescriptor instance with the specified name and initial settings using another ApplicationDescriptor as a template.

Parameters:
original - The application descriptor from which to build this new one.
name - The name for this new descriptor.
args - The initial arguments for this new descriptor.
position - The Home screen position for this new descriptor's icon.
nameResourceBundle - The resource bundle containing a localized version of this descriptor's name.
nameResourceId - The resource ID containing a localized version of this descriptor's name.
flags - The application flags for this new descriptor.
folderName - The suggested folder location for this new descriptor's icon.
Since:
BlackBerry API 5.0.0


Method Detail

getModuleHandle

public int getModuleHandle()
Retrieves the handle for this descriptor's code module.

Returns:
The handle for the code module containing this descriptor's application.

getModuleName

public String getModuleName()
Retrieves the name of this descriptor's code module.

Returns:
The name of the code module containing this descriptor's application.

getName

public String getName()
Retrieves the application name from this descriptor.

Returns:
The name of this descriptor's application.

getIndex

public int getIndex()
Retrieves the application index from this descriptor.

Each application in a code module has a unique index.

Returns:
The index of this descriptor's application.

getNameResourceBundle

public String getNameResourceBundle()
Retrieves the resource bundle from this descriptor.

Returns:
The name of the resource bundle containing a localized version of the application name, or null if no localized version exists.

getNameResourceId

public int getNameResourceId()
Retrieves the resource ID from this descriptor.

Returns:
The resource ID containing a localized version of the application name.

getKeywordsResourceBundle

public String getKeywordsResourceBundle()
Retrieves the keywords resource bundle from this descriptor.

Returns:
The name of the resource bundle containing a localized version of the application keywords, or null if no localized version exists.
Since:
BlackBerry API 7.1.0

getKeywordsResourceId

public int getKeywordsResourceId()
Retrieves the keywords resource ID from this descriptor.

Returns:
The resource ID containing a localized version of the application keywords.
Since:
BlackBerry API 7.1.0

getArgs

public String[] getArgs()
Retrieves the argument array from this descriptor.

Returns:
The appplication arguments.

getLocalizedName

public String getLocalizedName()
Retrieves the localized name of the application.

If the user has not set a valid title resource for the application, this method returns the default name.

Returns:
The localized application name, or the default name if the localized version is not available.
Since:
BlackBerry API 4.2.1

getDescription

public StringProvider getDescription()
Retrieves the StringProvider object containing the description of the application.

Returns:
A StringProvider object containing the description of the application.
Since:
BlackBerry API 7.0.0

getTitle

public StringProvider getTitle()
Retrieves the StringProvider object containing the name of the application.

Returns:
A StringProvider object containing the name of the application.
Since:
BlackBerry API 7.0.0

getKeywords

public StringProvider getKeywords()
Retrieves the StringProvider object containing the keywords for the application.

Returns:
A StringProvider object containing the keywords for the application.
Since:
BlackBerry API 7.1.0

getVersion

public String getVersion()
Retrieves the version from this descriptor.

Returns:
The application version.

getFlags

public int getFlags()
Retrieves the flags from this descriptor.

Returns:
The application flags.

getIcon

public Bitmap getIcon()
Deprecated. Use ApplicationDescriptor.getEncodedIcon() instead.

Retrieves the icon from this descriptor.

Returns:
The application icon as a Bitmap, or null if there is no application icon.

getEncodedIcon

public EncodedImage getEncodedIcon()
Retrieves the icon from this descriptor.

Returns:
The application icon as an EncodedImage, or null if there is no application icon.
Since:
BlackBerry API 4.7.0

getPosition

public int getPosition()
Returns the application's suggested position on the Home screen.

Applications with identical positions are placed on a first-come, first-serve basis. A lower position value means that the application is placed closer to the start of the Home screen, which is normally the top-left.

Returns:
The position specified in the descriptor's constructor.

getFolderName

public String getFolderName()
Returns the suggested folder name to place this application in.

Returns:
The application's suggested folder name on the Home screen, or null if there is no suggested folder name.
Since:
BlackBerry API 5.0.0

equals

public boolean equals(Object o)
Compares this descriptor to another object for equivalency.

The specified object is considered equivalent to this descriptor if the specified object is an application descriptor, has the same module handle, and has the same list of arguments.

Overrides:
equals in class Object
Parameters:
o - The object to compare to this descriptor.
Returns:
true if the specified object is equivalent to this descriptor, false otherwise.
See Also:
Boolean.hashCode(), Hashtable

currentApplicationDescriptor

public static ApplicationDescriptor currentApplicationDescriptor()
Retrieves the descriptor for the application that started the current process.

Returns:
The descriptor for the application that started the current process.

setPowerOnBehavior

public void setPowerOnBehavior(int behavior)
Sets the application's "power on" behavior. If an invalid behavior is provided, the "power on" behavior is set to ApplicationDescriptor.DO_NOT_POWER_ON.

Parameters:
behavior - The application's new "power on" behavior (one of the POWER_ON behavior flags).
See Also:
ApplicationDescriptor.DO_NOT_POWER_ON, ApplicationDescriptor.POWER_ON, ApplicationDescriptor.POWER_ON_FOR_AUTO_ON, ApplicationDescriptor.POWER_ON_ALWAYS
Since:
BlackBerry API 4.1.0

getPowerOnBehavior

public int getPowerOnBehavior()
Retrieves the application's "power on" behavior.

Returns:
The application's current "power on" behavior (one of the POWER_ON behavior flags).
See Also:
ApplicationDescriptor.DO_NOT_POWER_ON, ApplicationDescriptor.POWER_ON, ApplicationDescriptor.POWER_ON_FOR_AUTO_ON, ApplicationDescriptor.POWER_ON_ALWAYS
Since:
BlackBerry API 4.1.0





Copyright 1999-2011 Research In Motion Limited. 295 Phillip Street, Waterloo, Ontario, Canada, N2L 3W8. All Rights Reserved.
Java is a trademark of Oracle America Inc. in the US and other countries.
Legal