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
          System application.
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 named ApplicationDescriptor, using another descriptor as a template.
ApplicationDescriptor(ApplicationDescriptor original, String name, String[] args, int position, String nameResourceBundle, int nameResourceId)
          Constructs a new named ApplicationDescriptor, using another descriptor as a template, and providing initial settings.
ApplicationDescriptor(ApplicationDescriptor original, String name, String[] args, int position, String nameResourceBundle, int nameResourceId, int flags)
          Constructs a new named ApplicationDescriptor, using another descriptor as a template, and providing initial settings.
ApplicationDescriptor(ApplicationDescriptor original, String name, String[] args, int position, String nameResourceBundle, int nameResourceId, int flags, String folderName)
          Constructs a new named ApplicationDescriptor, using another descriptor as a template, and providing initial settings.
ApplicationDescriptor(ApplicationDescriptor original, String name, String[] args, Bitmap icon, int position, String nameResourceBundle, int nameResourceId)
          Deprecated. the caching of icon Bitmaps is no longer supported, use ApplicationDescriptor(ApplicationDescriptor,String,String[],int,String,int)
ApplicationDescriptor(ApplicationDescriptor original, String name, String[] args, Bitmap icon, int position, String nameResourceBundle, int nameResourceId, int flags)
          Deprecated. the caching of icon Bitmaps is no longer supported, use ApplicationDescriptor(ApplicationDescriptor,String,String[],int,String,int,int)
ApplicationDescriptor(ApplicationDescriptor original, String[] args)
          Constructs a new ApplicationDescriptor, using another descriptor as a template.
 
Method Summary
static ApplicationDescriptor currentApplicationDescriptor()
          Retrieves the descriptor used to start the current process.
 boolean equals(Object o)
          Compares this descriptor to another object for equivalency.
 String[] getArgs()
          Retrieves the argument array from this descriptor.
 EncodedImage getEncodedIcon()
          Retrieves the icon from this descriptor.
 int getFlags()
          Retrieves the flags from this descriptor.
 String getFolderName()
          Returns the application's suggested folder name to place this application in.
 Bitmap getIcon()
          Deprecated. Will be replaced with one returning an EncodedImage. use getEncodedIcon()
 int getIndex()
          Retrieves the application index from this descriptor.
 String getLocalizedName()
          Retrieves the localized name of the application.
 int getModuleHandle()
          Retrieves handle for this descriptor's code module.
 String getModuleName()
          Retrieves 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.
 String getVersion()
          Retrieves the version string 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
System application.

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, using another descriptor as a template.

Note that this builds a new application descriptor but does not provide it with a name.

Parameters:
original - Application descriptor template from which to build this new one.
args - Initial arguments for this new descriptor.
Since:
BlackBerry API 3.6.0

ApplicationDescriptor

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

Parameters:
original - Application descriptor template from which to build this new one.
name - Name for this new descriptor.
args - 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 Bitmaps is no longer supported, use ApplicationDescriptor(ApplicationDescriptor,String,String[],int,String,int)

Constructs a new named ApplicationDescriptor, using another descriptor as a template, and providing initial settings.

Parameters:
original - Application descriptor template from which to build this new one.
name - Name for this new descriptor
args - Initial arguments for this new descriptor.
icon - Display icon for this new descriptor.
position - Home screen position for this new descriptor's icon.
nameResourceBundle - Resource bundle containing localized version of this descriptor's name.
nameResourceId - Resource ID containing 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 Bitmaps is no longer supported, use ApplicationDescriptor(ApplicationDescriptor,String,String[],int,String,int,int)

Constructs a new named ApplicationDescriptor, using another descriptor as a template, and providing initial settings.

Parameters:
original - Application descriptor template from which to build this new one.
name - Name for this new descriptor
args - Initial arguments for this new descriptor.
icon - Display icon for this new descriptor.
position - Home screen position for this new descriptor's icon.
nameResourceBundle - Resource bundle containing localized version of this descriptor's name.
nameResourceId - Resource ID containing localized version of this descriptor's name.
flags - 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 named ApplicationDescriptor, using another descriptor as a template, and providing initial settings.

Parameters:
original - Application descriptor template from which to build this new one.
name - Name for this new descriptor
args - Initial arguments for this new descriptor.
position - Home screen position for this new descriptor's icon.
nameResourceBundle - Resource bundle containing localized version of this descriptor's name.
nameResourceId - Resource ID containing 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 named ApplicationDescriptor, using another descriptor as a template, and providing initial settings.

Parameters:
original - Application descriptor template from which to build this new one.
name - Name for this new descriptor
args - Initial arguments for this new descriptor.
position - Home screen position for this new descriptor's icon.
nameResourceBundle - Resource bundle containing localized version of this descriptor's name.
nameResourceId - Resource ID containing localized version of this descriptor's name.
flags - 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 named ApplicationDescriptor, using another descriptor as a template, and providing initial settings.

Parameters:
original - Application descriptor template from which to build this new one.
name - Name for this new descriptor
args - Initial arguments for this new descriptor.
position - Home screen position for this new descriptor's icon.
nameResourceBundle - Resource bundle containing localized version of this descriptor's name.
nameResourceId - Resource ID containing localized version of this descriptor's name.
flags - 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 handle for this descriptor's code module.

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

getModuleName

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

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

getName

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

Returns:
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:
Index of this descriptor's application.

getNameResourceBundle

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

Returns:
Name of 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:
Resource ID containing a localized version of the application name.

getArgs

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

Returns:
Application 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 the default name will be returned.

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

getVersion

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

Returns:
Application version.

getFlags

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

Returns:
Application flags.

getIcon

public Bitmap getIcon()
Deprecated. Will be replaced with one returning an EncodedImage. use getEncodedIcon()

Retrieves the icon from this descriptor.

Returns:
Application icon as a Bitmap.

getEncodedIcon

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

Returns:
Application icon as an EncodedImage.
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 value of position means that the application is placed closer to the start of the home screen, normally the top-left.

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

getFolderName

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

Returns:
Application's suggested folder name on the homescreen.
Since:
BlackBerry API 5.0.0

equals

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

Equivalency is ensured if your object is an application descriptor, has the same module handle, and has the same list of arguments.

Overrides:
equals in class Object
Parameters:
o - Object to compare to this descriptor.
Returns:
True if your provided object is equivalent to this descriptor; otherwise, false.
See Also:
Boolean.hashCode(), Hashtable

currentApplicationDescriptor

public static ApplicationDescriptor currentApplicationDescriptor()
Retrieves the descriptor used to start the current process.

Returns:
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-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.