net.rim.device.api.system
Class ApplicationDescriptor

java.lang.Object
  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