net.rim.device.api.system.capability
Class DeviceCapability

java.lang.Object
  extended by net.rim.device.api.system.capability.DeviceCapability

public final class DeviceCapability
extends Object

Provides a way to query the host device's capabilities. You can use this class to determine capability in three ways: to find out if a feature is supported, allowed, or available.

Difference between software and hardware. Software features can have all three capability states: they can be supported, allowed, or available. Hardware features, however, can have only two capability states: they can be supported or available.

Since:
BlackBerry API 6.0.0

Field Summary
static int HIGH_QUALITY
          Display color quality value returned by DeviceCapability.getDisplayColorQuality() when the primary display supports high quality color (thousands of colors).
static int TRUE_COLOR
          Display color quality value returned by DeviceCapability.getDisplayColorQuality() when the primary display supports true color (millions of colors).
static long TYPE_CRADLE
          Cradle connection capability type.
static long TYPE_KEYBOARD_PHYSICAL
          Physical keyboard capability type.
static long TYPE_KEYBOARD_VIRTUAL
          Virtual keyboard capability type.
static long TYPE_NFC
          NFC capability type.
static long TYPE_ROTATION
          Rotation capability type.
static long TYPE_TOUCH_CLICK
          Touch-click capability type.
 
Method Summary
static void addListener(long type, DeviceCapabilityListener listener)
          Registers a new device capability listener (for this application) to listen for changes in support for the specified capability type.
static void addListener(Application application, long type, DeviceCapabilityListener listener)
          Registers a new device capability listener to listen for changes in support for a specified capability type.
static void addNFCListener(Application application, DeviceCapabilityListener listener)
          Registers a new device capability listener to listen for changes in support for NFC capabilities.
static void addNFCListener(DeviceCapabilityListener listener)
          Registers a new device capability listener (for this application) to listen for changes in support for NFC capabilities.
static void addPhysicalKeyboardListener(Application application, DeviceCapabilityListener listener)
          Registers a new device capability listener to listen for changes in support for physical keyboard capabilities.
static void addPhysicalKeyboardListener(DeviceCapabilityListener listener)
          Registers a new device capability listener (for this application) to listen for changes in support for physical keyboard capabilities.
static void addRotationListener(Application application, DeviceCapabilityListener listener)
          Registers a new device capability listener to listen for changes in support for rotation capabilities.
static void addRotationListener(DeviceCapabilityListener listener)
          Registers a new device capability listener (for this application) to listen for changes in support for rotation capabilities.
static void addVirtualKeyboardListener(Application application, DeviceCapabilityListener listener)
          Registers a new device capability listener to listen for changes in support for virtual keyboard capabilities.
static void addVirtualKeyboardListener(DeviceCapabilityListener listener)
          Registers a new device capability listener (for this application) to listen for changes in support for virtual keyboard capabilities.
static int getDisplayColorQuality()
          Returns the color quality of the primary display.
static boolean isAllowed(long type)
          Determines if the device allows a capability identified by a specified type value.
static boolean isAvailable(long type)
          Determines if the device can currently make available a capability identified by a specified type value.
static boolean isNFCAvailable()
          Determines if this device's NFC is currently available.
static boolean isNFCSupported()
          Determines if this device has a NFC capabilities.
static boolean isPhysicalKeyboardAvailable()
          Determines if this device's physical keyboard is currently available.
static boolean isPhysicalKeyboardSupported()
          Determines if this device has a physical keyboard.
static boolean isRotationAllowed()
          Determines if you can use rotation in the device's current state.
static boolean isRotationSupported()
          Determines if this device supports rotation.
static boolean isSupported(long type)
          Determines if the device supports a capability identified by a specified type value.
static boolean isTouchClickSupported()
          Determines if this device supports clicking on the touch screen, as opposed to touching only.
static boolean isVirtualKeyboardAllowed()
          Determines if you can use the device's virtual keyboard.
static boolean isVirtualKeyboardAvailable()
          Determines if this device's virtual keyboard is currently available.
static boolean isVirtualKeyboardSupported()
          Determines if this device has a virtual keyboard.
static void removeListener(long type, DeviceCapabilityListener listener)
          Unregisters a specified device capability listener of a specified capability type.
static void removeNFCListener(DeviceCapabilityListener listener)
          Removes a listener from the list of NFC capability listeners.
static void removePhysicalKeyboardListener(DeviceCapabilityListener listener)
          Removes a listener from the list of physical keyboard capability listeners.
static void removeRotationListener(DeviceCapabilityListener listener)
          Removes a listener from the list of rotation capability listeners.
static void removeVirtualKeyboardListener(DeviceCapabilityListener listener)
          Removes a listener from the list of virtual keyboard capability listeners.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 



Field Detail

TYPE_KEYBOARD_VIRTUAL

public static final long TYPE_KEYBOARD_VIRTUAL
Virtual keyboard capability type.

Used to register or query VirtualKeyboardCapabilityProvider instances.

See Also:
DeviceCapability.isVirtualKeyboardAvailable(), DeviceCapability.isVirtualKeyboardAllowed(), DeviceCapability.isVirtualKeyboardSupported(), Constant Field Values
Since:
BlackBerry API 6.0.0

TYPE_KEYBOARD_PHYSICAL

public static final long TYPE_KEYBOARD_PHYSICAL
Physical keyboard capability type.

Used to register or query PhysicalKeyboardCapabilityProvider instances.

See Also:
DeviceCapability.isPhysicalKeyboardAvailable(), DeviceCapability.isPhysicalKeyboardSupported(), Constant Field Values
Since:
BlackBerry API 6.0.0

TYPE_ROTATION

public static final long TYPE_ROTATION
Rotation capability type.

Used to register or query RotationCapabilityProvider instances.

See Also:
DeviceCapability.isRotationAllowed(), DeviceCapability.isRotationSupported(), Constant Field Values
Since:
BlackBerry API 6.0.0

TYPE_TOUCH_CLICK

public static final long TYPE_TOUCH_CLICK
Touch-click capability type.

Used to register or query TouchClickCapabilityProvider instances.

See Also:
DeviceCapability.isTouchClickSupported(), Constant Field Values
Since:
BlackBerry API 6.0.0

TYPE_CRADLE

public static final long TYPE_CRADLE
Cradle connection capability type.

To detect cradle properties and perform communications, refer to the CradleProtocol class.

See Also:
Constant Field Values
Since:
BlackBerry API 6.0.0

HIGH_QUALITY

public static final int HIGH_QUALITY
Display color quality value returned by DeviceCapability.getDisplayColorQuality() when the primary display supports high quality color (thousands of colors).

See Also:
Constant Field Values
Since:
BlackBerry API 7.0.0

TRUE_COLOR

public static final int TRUE_COLOR
Display color quality value returned by DeviceCapability.getDisplayColorQuality() when the primary display supports true color (millions of colors).

See Also:
Constant Field Values
Since:
BlackBerry API 7.0.0

TYPE_NFC

public static final long TYPE_NFC
NFC capability type.

Used to register or query NFCCapabilityProvider instances.

See Also:
Constant Field Values
Since:
BlackBerry API 7.0.0


Method Detail

isSupported

public static boolean isSupported(long type)
Determines if the device supports a capability identified by a specified type value.

This method iterates through all the registered DeviceCapabilityProvider instances of the provided type, querying each in turn. Should any of the registered instances report that this device supports their associated capability type, then this method returns true.

Parameters:
type - The capability type to query, specified by one of this class's "TYPE_" constants (or a custom type value).
Returns:
true if one of the registered capability providers of your provided type reports that the device supports the capability type, false otherwise.
Since:
BlackBerry API 6.0.0

isAllowed

public static boolean isAllowed(long type)
Determines if the device allows a capability identified by a specified type value.

This method iterates through all the registered DeviceCapabilityProvider instances of the provided type, querying each in turn. Should any of the registered instances report that this device allows their associated capability type, then this method returns true.

Parameters:
type - The capability type to query, specified by one of this class's "TYPE_" constants (or a custom type value).
Returns:
true if one of the registered capability providers of your provided type reports that the device allows the capability type, false otherwise.
Since:
BlackBerry API 6.0.0

isAvailable

public static boolean isAvailable(long type)
Determines if the device can currently make available a capability identified by a specified type value.

This method iterates through all the registered DeviceCapabilityProvider instances of the provided type, querying each in turn. Should any of the registered instances report that this device can currently make available the associated capability type, then this method returns true.

Parameters:
type - The capability type to query, specified by one of this class's "TYPE_" constants (or a custom type value).
Returns:
true if any of the registered capability providers of your provided type report that the device can currently make available the capability type, false otherwise.
Since:
BlackBerry API 6.0.0

addListener

public static void addListener(Application application,
                               long type,
                               DeviceCapabilityListener listener)
Registers a new device capability listener to listen for changes in support for a specified capability type.

When the device changes its capability state for a particular capability type, it will notify all the listeners registered to notice state changes for that capability type.

Typically you use this method to register listeners that will get processed on event threads other than the one hosted by the current application. To register listeners on the current application's event thread use DeviceCapability.addListener(long,DeviceCapabilityListener) instead.

Parameters:
application - The application instance whose event thread will host the listener notifications.
type - The capability type to notice, specified by one of this class's "TYPE_" constants (or a custom type value).
listener - The listener to register.
Throws:
IllegalArgumentException - if application or listener is null.
Since:
BlackBerry API 6.0.0

addListener

public static void addListener(long type,
                               DeviceCapabilityListener listener)
Registers a new device capability listener (for this application) to listen for changes in support for the specified capability type.

This method invokes DeviceCapability.addListener(Application,long,DeviceCapabilityListener) providing a reference to the current application (retrieved from Application.getApplication()) to use as the hosting application.

Parameters:
type - The capability type to notice, specified by one of this class's "TYPE_" constants (or a custom type value).
listener - The listener to register.
Throws:
IllegalArgumentException - if listener is null.
Since:
BlackBerry API 6.0.0

removeListener

public static void removeListener(long type,
                                  DeviceCapabilityListener listener)
Unregisters a specified device capability listener of a specified capability type.

Use this method to remove a listener from the list of listeners registered for your specified device capability type.

Parameters:
type - The capability type associated with the listener, specified by one of this class's "TYPE_" constants (or a custom type value).
listener - The listener to unregister.
Throws:
IllegalArgumentException - if type specifies a listener type that was not registered previously, or if listener is null.
Since:
BlackBerry API 6.0.0

isVirtualKeyboardSupported

public static boolean isVirtualKeyboardSupported()
Determines if this device has a virtual keyboard.

Convenience method wrapping isSupported(TYPE_KEYBOARD_VIRTUAL).

Returns:
true if the device supports a virtual keyboard, false otherwise.
Since:
BlackBerry API 6.0.0

isVirtualKeyboardAllowed

public static boolean isVirtualKeyboardAllowed()
Determines if you can use the device's virtual keyboard.

Convenience method wrapping isAllowed(TYPE_KEYBOARD_VIRTUAL).

Returns:
true if this device has a virtual keyboard and you can use it, false otherwise.
Since:
BlackBerry API 6.0.0

isVirtualKeyboardAvailable

public static boolean isVirtualKeyboardAvailable()
Determines if this device's virtual keyboard is currently available.

Convenience method wrapping isAvailable(TYPE_KEYBOARD_VIRTUAL).

Returns:
true if this device has a keyboard and it's currently available for use, false otherwise.
Since:
BlackBerry API 6.0.0

isPhysicalKeyboardSupported

public static boolean isPhysicalKeyboardSupported()
Determines if this device has a physical keyboard.

Convenience method wrapping isSupported(TYPE_KEYBOARD_PHYSICAL).

Returns:
true if the device supports a physical keyboard, false otherwise.
Since:
BlackBerry API 6.0.0

isPhysicalKeyboardAvailable

public static boolean isPhysicalKeyboardAvailable()
Determines if this device's physical keyboard is currently available.

Convenience method wrapping isAvailable(TYPE_KEYBOARD_PHYSICAL).

Returns:
true if the device has a physical keyboard and it's currently available for use, false otherwise.
Since:
BlackBerry API 6.0.0

isRotationSupported

public static boolean isRotationSupported()
Determines if this device supports rotation.

Convenience method for isSupported(TYPE_ROTATION).

Returns:
true if this device supports rotation, false otherwise.
Since:
BlackBerry API 6.0.0

isRotationAllowed

public static boolean isRotationAllowed()
Determines if you can use rotation in the device's current state.

Convenience method for isAllowed(TYPE_ROTATION).

Returns:
true if the device will let you use rotation in its current state, false otherwise.
Since:
BlackBerry API 6.0.0

isTouchClickSupported

public static boolean isTouchClickSupported()
Determines if this device supports clicking on the touch screen, as opposed to touching only.

Convenience method wrapping isSupported(TYPE_TOUCH_CLICK).

Returns:
true if this device supports clicking on the touch screen, false otherwise.
Since:
BlackBerry API 6.0.0

getDisplayColorQuality

public static int getDisplayColorQuality()
Returns the color quality of the primary display.

Returns:
DeviceCapability.TRUE_COLOR if the display supports millions of colors, otherwise DeviceCapability.HIGH_QUALITY.
Since:
BlackBerry API 7.0.0

isNFCSupported

public static boolean isNFCSupported()
Determines if this device has a NFC capabilities.

Convenience method wrapping isSupported(TYPE_NFC).

Returns:
true if the device supports NFC; false otherwise.
Since:
BlackBerry API 7.0.0

isNFCAvailable

public static boolean isNFCAvailable()
Determines if this device's NFC is currently available.

Convenience method wrapping isAvailable(TYPE_NFC).

Returns:
true if the device has NFC and it's currently available for use; false otherwise.
Since:
BlackBerry API 7.0.0

addVirtualKeyboardListener

public static void addVirtualKeyboardListener(Application application,
                                              DeviceCapabilityListener listener)
Registers a new device capability listener to listen for changes in support for virtual keyboard capabilities.

Convenience method wrapping addListener(application,TYPE_KEYBOARD_VIRTUAL,listener).

Parameters:
application - The application instance whose event thread will host the listener notifications.
listener - The listener to register.
Since:
BlackBerry API 6.0.0

addVirtualKeyboardListener

public static void addVirtualKeyboardListener(DeviceCapabilityListener listener)
Registers a new device capability listener (for this application) to listen for changes in support for virtual keyboard capabilities.

Convenience method wrapping #addVirtualKeybaordListener(Application,DeviceCapabilityListener) providing a reference to the current application (retrieved from Application.getApplication()) to use as the hosting application.

Parameters:
listener - The listener to register.
Since:
BlackBerry API 6.0.0

addPhysicalKeyboardListener

public static void addPhysicalKeyboardListener(Application application,
                                               DeviceCapabilityListener listener)
Registers a new device capability listener to listen for changes in support for physical keyboard capabilities.

Convenience method wrapping addListener(application,TYPE_KEYBOARD_PHYSICAL,listener).

Parameters:
application - The application instance whose event thread will host the listener notifications.
listener - The listener to register.
Since:
BlackBerry API 6.0.0

addPhysicalKeyboardListener

public static void addPhysicalKeyboardListener(DeviceCapabilityListener listener)
Registers a new device capability listener (for this application) to listen for changes in support for physical keyboard capabilities.

Convenience method wrapping DeviceCapability.addPhysicalKeyboardListener(Application,DeviceCapabilityListener) providing a reference to the current application (retrieved from Application.getApplication()) to use as the hosting application.

Parameters:
listener - The listener to register.
Since:
BlackBerry API 6.0.0

addRotationListener

public static void addRotationListener(Application application,
                                       DeviceCapabilityListener listener)
Registers a new device capability listener to listen for changes in support for rotation capabilities.

Convenience method wrapping addListener(application,TYPE_ROTATION,listener).

Parameters:
application - The application instance whose event thread will host the listener notifications.
listener - The listener to register.
Since:
BlackBerry API 6.0.0

addRotationListener

public static void addRotationListener(DeviceCapabilityListener listener)
Registers a new device capability listener (for this application) to listen for changes in support for rotation capabilities.

Convenience method wrapping DeviceCapability.addRotationListener(Application,DeviceCapabilityListener) providing a reference to the current application (retrieved from Application.getApplication()) to use as the hosting application.

Parameters:
listener - The listener to register.
Since:
BlackBerry API 6.0.0

addNFCListener

public static void addNFCListener(Application application,
                                  DeviceCapabilityListener listener)
Registers a new device capability listener to listen for changes in support for NFC capabilities.

Convenience method wrapping addListener(application,TYPE_NFC,listener).

Parameters:
application - Application instance whose event thread will host the listener notifications.
listener - Listener to register.
Since:
BlackBerry API 7.0.0

addNFCListener

public static void addNFCListener(DeviceCapabilityListener listener)
Registers a new device capability listener (for this application) to listen for changes in support for NFC capabilities.

Convenience method wrapping DeviceCapability.addNFCListener(Application,DeviceCapabilityListener) providing a reference to the current application (retrieved from Application.getApplication()) to use as the hosting application.

Parameters:
listener - Listener to register.
Since:
BlackBerry API 7.0.0

removeVirtualKeyboardListener

public static void removeVirtualKeyboardListener(DeviceCapabilityListener listener)
Removes a listener from the list of virtual keyboard capability listeners.

Convenience method wrapping removeListener(TYPE_KEYBOARD_VIRTUAL,listener).

Parameters:
listener - The listener to remove from the list.
Since:
BlackBerry API 6.0.0

removePhysicalKeyboardListener

public static void removePhysicalKeyboardListener(DeviceCapabilityListener listener)
Removes a listener from the list of physical keyboard capability listeners.

Convenience method wrapping removeListener(TYPE_KEYBOARD_PHYSICAL,listener).

Parameters:
listener - The listener to remove from the list.
Since:
BlackBerry API 6.0.0

removeRotationListener

public static void removeRotationListener(DeviceCapabilityListener listener)
Removes a listener from the list of rotation capability listeners.

Convenience method wrapping removeListener(TYPE_ROTATION,listener).

Parameters:
listener - The listener to remove from the list.
Since:
BlackBerry API 6.0.0

removeNFCListener

public static void removeNFCListener(DeviceCapabilityListener listener)
Removes a listener from the list of NFC capability listeners.

Convenience method wrapping removeListener(TYPE_NFC,listener).

Parameters:
listener - Listener to remove from the list.
Since:
BlackBerry API 7.0.0





Copyright 1999-2011 Research In Motion Limited. 295 Phillip Street, Waterloo, Ontario, Canada, N2L 3W8. All Rights Reserved.
Java is a trademark of Oracle America Inc. in the US and other countries.
Legal