net.rim.device.api.system
Class KeyHandlerRegistry

java.lang.Object
  net.rim.device.api.system.KeyHandlerRegistry

public class KeyHandlerRegistry
extends Object

This class allows an application to register as a handler for global key events. A KeyListener added to an Application which has registered with this API will receive key events for a registered key regardless of what another application running in the foreground may do in terms of processing the event. Note that RIM reserves the right to reserve usage of otherwise supported keys to certain native applications. This means that registration may fail for this reason or that an application registered using this registry may become de-registered at a later time if the key in question becomes a restricted key as a result of a native application gaining exclusive control over the 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

Method Summary
	static boolean	isKeySupported(int key) Determines whether a specified key is a supported global key
	static void	register(Application app, int key) Allows an Application to register to receive global key events, regardless of whether a given event is consumed by a foreground process.
	static void	unregister(Application app, int key) Unregisters an Application as a handler of global key events

Methods inherited from class java.lang.Object

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

Method Detail

register

public static void register(Application app,
                            int key)
                     throws IllegalArgumentException,
                            KeyHandlerRegistryException

Allows an Application to register to receive global key events, regardless of whether a given event is consumed by a foreground process. In order to trap these events, an application also must add a KeyListener to itself. Applications should use {Application.addKeyListener(KeyListener, boolean) and specify true for the boolean parameter so as not to receive duplicate events should a foreground application fail to consume a given key event. This API is intended for use by background apps, therefore an exception will be thrown if the application being registered is capable of obtaining the foreground. For example, Applications that extend a class that can obtain the foreground (e.g. UiApplication) need to override the Application.acceptsForeground() method to return false. It is possible that a native application has reserved the right to use a global key for its exclusive use. In this case registration will fail with a KeyHandlerRegistryException. It is also possible that a native application will gain exclusive control over a global key subsequent to an application being registered with this method in which case the application will be de-registered.

Parameters:

app - The application to be registered

keys - The global key to register the application for. See Keypad.

Throws:

IllegalArgumentException - Thrown if specified key is not a supported global key or if app can accept foreground

KeyHandlerRegistryException - Thrown if specified key has been reserved for exclusive use by another application

NullPointerException - If app paramater is null

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

unregister

public static void unregister(Application app,
                              int key)

Unregisters an Application as a handler of global key events

Parameters:

app - The application to be unregistered

keys - The global key to unregister. See Keypad.

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 a supported global key

Parameters:

key - The key to check for KeyHandlerRegistry support

Returns:

true if the specified key is supported, 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