net.rim.device.api.system
Class AccelerometerSensor.Channel

java.lang.Object
  extended by net.rim.device.api.system.AccelerometerSensor.Channel
Enclosing class:
AccelerometerSensor

public static class AccelerometerSensor.Channel
extends Object

Encapsulates an active connection to accelerometer sensor. While the channel remains open the sensor is queried for samples. Invoke the AccelerometerSensor.Channel.close() method to close the channel and stop querying the sensor in order to preserve battery power.

Since:
BlackBerry API 4.7.0

Method Summary
 void addAccelerometerListener(AccelerometerListener l)
          Registers an accelerometer listener.
 void close()
          Closes the channel and stops querying the sensor.
 AccelerometerData getAccelerometerData()
          Returns the last acceleration data along with optional historical samples.
 void getLastAccelerationData(short[] xyz)
          Returns last accelerometer raw reading
 int getOrientation()
          Returns current orientation.
 boolean isActive()
          Returns if the channel is currently active and collecting requested data.
 boolean isOpen()
          Determines if the channel is open or is closed
 void removeAccelerometerListener()
          Deprecated. use AccelerometerSensor.Channel.removeAccelerometerListener( AccelerometerListener l )
 void removeAccelerometerListener(AccelerometerListener l)
          Deregisters an accelerometer listener.
 void setAccelerometerListener(AccelerometerListener l)
          Deprecated. use AccelerometerSensor.Channel.addAccelerometerListener( AccelerometerListener l ). Historically this has behaved like you'd expect AccelerometerSensor.Channel.addAccelerometerListener( AccelerometerListener l ) to, that is, support for multiple listeners.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 



Method Detail

setAccelerometerListener

public void setAccelerometerListener(AccelerometerListener l)
Deprecated. use AccelerometerSensor.Channel.addAccelerometerListener( AccelerometerListener l ). Historically this has behaved like you'd expect AccelerometerSensor.Channel.addAccelerometerListener( AccelerometerListener l ) to, that is, support for multiple listeners.

Registers an accelerometer listener. If the channel is opened for orientation, the listener is notified on the orientation change. If the channel is opened for raw data, the listener is notified when new raw data is retrieved from the sensor. If the raw data has not changed, the listener is notified with duplicate data and the historial arrays will also contain duplicates. The notification is performed in the application dispatcher thread. Multiple registrations of the same listener are ignored.

Parameters:
l - Listener for orientation or raw acceleration data, must not be null.
Since:
BlackBerry API 4.7.0

addAccelerometerListener

public void addAccelerometerListener(AccelerometerListener l)
Registers an accelerometer listener. If the channel is opened for orientation, the listener is notified on the orientation change. If the channel is opened for raw data, the listener is notified when new raw data is retrieved from the sensor. If the raw data has not changed, the listener is notified with duplicate data and the historial arrays will also contain duplicates. The notification is performed in the application dispatcher thread. Multiple registrations of the same listener are ignored.

Parameters:
l - Listener for orientation or raw acceleration data, must not be null.
Throws:
NullPointerException - if listener is null
IllegalStateException - if the application that owns this channel no longer exists
Since:
BlackBerry API 7.0.0

removeAccelerometerListener

public void removeAccelerometerListener()
Deprecated. use AccelerometerSensor.Channel.removeAccelerometerListener( AccelerometerListener l )

Deregisters the first AccelerometerListener in the list of registered listeners.

Since:
BlackBerry API 4.7.0

removeAccelerometerListener

public void removeAccelerometerListener(AccelerometerListener l)
Deregisters an accelerometer listener. This method does nothing if the listener isn't registered.

Parameters:
l - Listener for orientation or raw acceleration data, could be null
Since:
BlackBerry API 7.0.0

close

public void close()
Closes the channel and stops querying the sensor. Invoke this method as soon as accelerometer data is not required in order to preserve battery power.

Since:
BlackBerry API 4.7.0

getLastAccelerationData

public void getLastAccelerationData(short[] xyz)
                             throws IllegalArgumentException,
                                    IllegalStateException
Returns last accelerometer raw reading

Parameters:
xyz - an allocated array of three elements to store x, y and z axis acceleration information.
Throws:
IllegalArgumentException - if passed argument is NULL, or its length is not equal to 3.
IllegalStateException - if called on a closed channel OR the channel was opened for orientation data only
Since:
BlackBerry API 4.7.0

getAccelerometerData

public AccelerometerData getAccelerometerData()
                                       throws IllegalStateException
Returns the last acceleration data along with optional historical samples. The resulting data object is populated based on the channel configuration.

Throws:
IllegalStateException - if called on a closed channel
Since:
BlackBerry API 4.7.0

getOrientation

public int getOrientation()
                   throws IllegalStateException
Returns current orientation.

Returns:
One of the orientation constants, such as AccelerometerSensor.ORIENTATION_BACK_UP
Throws:
IllegalStateException - if called on a closed channel OR the channel was opened for RAW data only
Since:
BlackBerry API 4.7.0

isActive

public boolean isActive()
Returns if the channel is currently active and collecting requested data. The channel can be inactive when the application is in background mode, and the channel was not requested to remain open in the background.

Returns:
true if channel is open and active; false otherwise.
See Also:
AccelerometerSensor.Channel.isOpen()
Since:
BlackBerry API 4.7.0

isOpen

public boolean isOpen()
Determines if the channel is open or is closed

Returns:
true if open; false otherwise.
See Also:
AccelerometerSensor.Channel.isActive()
Since:
BlackBerry API 4.7.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