net.rim.device.api.ui
Class ConvenienceKeyUtilities

java.lang.Object
  net.rim.device.api.ui.ConvenienceKeyUtilities

public class ConvenienceKeyUtilities
extends Object

A class used to programatically set an Application as the application to be launched upon a convenience key click. This API is subject to the Device Settings application control.

 Sample usage:
 if(ConvenienceKeyUtilities.isKeySupported(Keypad.KEY_CONVENIENCE_1))
 {
     String oldName = ConvenienceKeyUtilities.getConvenienceKeyAppName(Keypad.KEY_CONVENIENCE_1);
     ApplicationDescriptor applicationDescriptor = new ApplicationDescriptor(ApplicationDescriptor.currentApplicationDescriptor(),"Test App",new String[] {"test arg"});
     if(ConvenienceKeyUtilities.setConvenienceKeyApp(applicationDescriptor, Keypad.KEY_CONVENIENCE_1))
     {
          System.out.println("Changed convenience key app from " + oldName + " to " + ConvenienceKeyUtilities.getConvenienceKeyAppName(Keypad.KEY_CONVENIENCE_1));
     }
 }
 

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

Method Summary
	static String	getConvenienceKeyAppName(int key) Returns the unique name of the module that is mapped to a convenience key
	static boolean	isKeySupported(int key) Determines whether a specified key is supported.
	static boolean	setConvenienceKeyApp(ApplicationDescriptor appDescriptor, int key) Sets the application to launch when a specified convenience key is clicked

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

setConvenienceKeyApp

public static boolean setConvenienceKeyApp(ApplicationDescriptor appDescriptor,
                                           int key)
                                    throws IllegalArgumentException

Sets the application to launch when a specified convenience key is clicked

Parameters:

appDescriptor - ApplicationDescriptor for the application module to be launched by the specified convenience key. If an ApplicationDescriptor with more than one command line argument is provided, an IllegalArgumentException will be thrown. This API is subject to the Device Settings application control. Users will be prompted to allow the operation performed by this method.

key - The conveneience key to set. Should be one of Keypad.KEY_CONVENIENCE_1 or Keypad.KEY_CONVENIENCE_2.

Returns:

true if the operation was successful, otherwise false (a false return value would typically indicate that a user opted to disallow the operation)

Throws:

IllegalArgumentException - Thrown if appDescriptor is null, an unsupported key is specified, or if module specified by appDescriptor cannot be found or if an ApplicationDescriptor containing more than one command line argument is specified.

ControlledAccessException - Thrown if Device Settings application control prevents the requested operation.

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

getConvenienceKeyAppName

public static String getConvenienceKeyAppName(int key)

Returns the unique name of the module that is mapped to a convenience key

Parameters:

key - The convenience key for which to retrieve the mapped module name

Returns:

The name of the module mapped to the specified convenience key

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

isKeySupported

public static boolean isKeySupported(int key)

Determines whether a specified key is supported. Applications should call this method before calling ConvenienceKeyUtilities.setConvenienceKeyApp(ApplicationDescriptor, int) as key layouts may differ between device models and software configuration may prevent the use of a given key.

Parameters:

key - The key for which to check the status

Returns:

true if the specified key is supported on the current device, otherwise false

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