|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectnet.rim.device.api.system.capability.DeviceCapability
public final class DeviceCapability
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.
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
.
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.
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.
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 |
---|
public static final long TYPE_KEYBOARD_VIRTUAL
Used to register or query VirtualKeyboardCapabilityProvider
instances.
DeviceCapability.isVirtualKeyboardAvailable()
,
DeviceCapability.isVirtualKeyboardAllowed()
,
DeviceCapability.isVirtualKeyboardSupported()
,
Constant Field Valuespublic static final long TYPE_KEYBOARD_PHYSICAL
Used to register or query PhysicalKeyboardCapabilityProvider
instances.
DeviceCapability.isPhysicalKeyboardAvailable()
,
DeviceCapability.isPhysicalKeyboardSupported()
,
Constant Field Valuespublic static final long TYPE_ROTATION
Used to register or query RotationCapabilityProvider
instances.
DeviceCapability.isRotationAllowed()
,
DeviceCapability.isRotationSupported()
,
Constant Field Valuespublic static final long TYPE_TOUCH_CLICK
Used to register or query TouchClickCapabilityProvider
instances.
DeviceCapability.isTouchClickSupported()
,
Constant Field Valuespublic static final long TYPE_CRADLE
To detect cradle properties and perform communications, refer to the
CradleProtocol
class.
Method Detail |
---|
public static boolean isSupported(long type)
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
.
type
- Capability type to query, specified by one of this class's
"TYPE_" constants (or a custom type value).
true
if one of the registered capability providers of your
provided type reports that the device supports the capability type;
false
otherwise.public static boolean isAllowed(long type)
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
.
type
- Capability type to query, specified by one of this class's
"TYPE_" constants (or a custom type value).
true
if one of the registered capability providers of your
provided type reports that the device allows the capability type;
false
otherwise.public static boolean isAvailable(long type)
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
.
type
- Capability type to query, specified by one of this class's
"TYPE_" constants (or a custom type value).
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.public static void addListener(Application application, long type, DeviceCapabilityListener listener)
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.
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.public static void addListener(long type, DeviceCapabilityListener listener)
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.
type
- Capability type to notice, specified by one of this class's
"TYPE_" constants (or a custom type value).listener
- Listener to register.public static void removeListener(long type, DeviceCapabilityListener listener)
Use this method to remove a listener from the list of listeners registered for your specified device capability type.
type
- Capability type associated with listener, specified by one of
this class's "TYPE_" constants (or a custom type value).listener
- Listener to unregister.public static boolean isVirtualKeyboardSupported()
Convenience method wrapping
isSupported(TYPE_KEYBOARD_VIRTUAL)
.
true
if the device supports a virtual keyboard;
false
otherwise.public static boolean isVirtualKeyboardAllowed()
Convenience method wrapping
isAllowed(TYPE_KEYBOARD_VIRTUAL)
.
true
if this device has a virtual keyboard and you can use it;
false
otherwise.public static boolean isVirtualKeyboardAvailable()
Convenience method wrapping
isAvailable(TYPE_KEYBOARD_VIRTUAL
).
true
if this device has a keyboard and it's currently available
for use; false
otherwise.public static boolean isPhysicalKeyboardSupported()
Convenience method wrapping
isSupported(TYPE_KEYBOARD_PHYSICAL)
.
true
if the device supports a physical keyboard;
false
otherwise.public static boolean isPhysicalKeyboardAvailable()
Convenience method wrapping
isAvailable(TYPE_KEYBOARD_PHYSICAL)
.
true
if the device has a physical keyboard and it's currently
available for use; false
otherwise.public static boolean isRotationSupported()
Convenience method for
isSupported(TYPE_ROTATION)
.
true
if this device supports rotation; false
otherwise.public static boolean isRotationAllowed()
Convenience method for
isAllowed(TYPE_ROTATION)
.
true
if the device will let you use rotation in its current
state; false
otherwise.public static boolean isTouchClickSupported()
Convenience method wrapping
isSupported(TYPE_TOUCH_CLICK)
.
true
if this device supports clicking on the touch screen;
otherwise, false
.public static void addVirtualKeyboardListener(Application application, DeviceCapabilityListener listener)
Convenience method wrapping
addListener(application,TYPE_KEYBOARD_VIRTUAL,listener)
.
application
- Application instance whose event thread will host the
listener notifications.listener
- Listener to register.public static void addVirtualKeyboardListener(DeviceCapabilityListener listener)
Convenience method wrapping
#addVirtualKeybaordListener(Application,DeviceCapabilityListener)
providing a reference to the current application (retrieved from
Application.getApplication()
) to use as the hosting application.
listener
- Listener to register.public static void addPhysicalKeyboardListener(Application application, DeviceCapabilityListener listener)
Convenience method wrapping
addListener(application,TYPE_KEYBOARD_PHYSICAL,listener)
.
application
- Application instance whose event thread will host the
listener notifications.listener
- Listener to register.public static void addPhysicalKeyboardListener(DeviceCapabilityListener listener)
Convenience method wrapping
DeviceCapability.addPhysicalKeyboardListener(Application,DeviceCapabilityListener)
providing a reference to the current application (retrieved from
Application.getApplication()
) to use as the hosting application.
listener
- Listener to register.public static void addRotationListener(Application application, DeviceCapabilityListener listener)
Convenience method wrapping
addListener(application,TYPE_ROTATION,listener)
.
application
- Application instance whose event thread will host the
listener notifications.listener
- Listener to register.public static void addRotationListener(DeviceCapabilityListener listener)
Convenience method wrapping
DeviceCapability.addRotationListener(Application,DeviceCapabilityListener)
providing a reference to the current application (retrieved from
Application.getApplication()
) to use as the hosting application.
listener
- Listener to register.public static void removeVirtualKeyboardListener(DeviceCapabilityListener listener)
Convenience method wrapping
removeListener(TYPE_KEYBOARD_VIRTUAL,listener)
.
listener
- Listener to remove from the list.public static void removePhysicalKeyboardListener(DeviceCapabilityListener listener)
Convenience method wrapping
removeListener(TYPE_KEYBOARD_PHYSICAL,listener)
.
listener
- Listener to remove from the list.public static void removeRotationListener(DeviceCapabilityListener listener)
Convenience method wrapping
removeListener(TYPE_ROTATION,listener)
.
listener
- Listener to remove from the list.
|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
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.