net.rim.device.api.ui
Class ConvenienceKeyUtilities

java.lang.Object
  extended by 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
Category: Signed static String getConvenienceKeyAppName(int key)
          Returns the unique name of the module that is mapped to a convenience key
Category: Signed static boolean isKeySupported(int key)
          Determines whether a specified key is supported.
Category: Signed 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





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.