net.rim.device.api.system
Class KeyHandlerRegistry

java.lang.Object
  extended by 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
Category: Signed static boolean isKeySupported(int key)
          Determines whether a specified key is a supported global key
Category: Signed 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.
Category: Signed 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





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.