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

java.lang.Object
  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.

• Supported features are those that the device can perform. You can use the isSupported() family of methods to find out about them. These methods return values that are not likely to change, but might. For example, if the device's user connects a peripheral keyboard to a device that doesn't normally have a physical keyboard, then invoking DeviceCapability.isPhysicalKeyboardSupported() will return true instead of false.
• Allowed features are those that the device should let you use. You can use the isAllowed() family of methods to determine if your code can use the feature at the moment. Values this method returns might change frequently, depending upon the device. For example, on devices with a slider, the virtual keyboard might be allowed only when the slider is closed.

  Note that if an isAllowed() method returns false, this doesn't mean you cannot use the capability, but that we strongly recommend you do not at that time. You should use an isSupported() method to determine whether the device can at all support a feature if you chose to proceed in the face of a false return from an isAllowed() call.

• Available features are those that the user can interact with. You can use the isAvailable() family of methods to determine the feature's current availability. As with isAllowed() methods, the value an isAvailable() call returns can change frequently. For example, on a device with a virtual keyboard, the virtual keyboard feature is available only when it is displayed to the user.

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 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_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 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	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 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	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	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

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 - 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 - 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 - 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 - Application instance whose event thread will host the listener notifications.

type - Capability type to notice, specified by one of this class's "TYPE_" constants (or a custom type value).

listener - Listener to register.

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 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 - Capability type to notice, specified by one of this class's "TYPE_" constants (or a custom type value).

listener - Listener to register.

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 - Capability type associated with listener, specified by one of this class's "TYPE_" constants (or a custom type value).

listener - Listener to unregister.

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; otherwise, false.

Since:

BlackBerry API 6.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 - Application instance whose event thread will host the listener notifications.

listener - 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 - 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 - Application instance whose event thread will host the listener notifications.

listener - 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 - 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 - Application instance whose event thread will host the listener notifications.

listener - 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 - Listener to register.

Since:

BlackBerry API 6.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 - 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 - 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 - Listener to remove from the list.

Since:

BlackBerry API 6.0.0