|
|||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
| SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | ||||||||
java.lang.Object | +--net.rim.device.api.system.AccelerometerSensor
Provides accelerometer sensor query and listener registration methods.
There are two types of accelerometer data:
ORIENTATION_TOP_UP or ORIENTATION_LEFT_UP.
Acceleration sensors return G-force values along the X, Y, and Z axes, relative to the ground, as follows:
For example, if the handheld is lying flat on a table, the X and Y values are equal to 0, while Z is equal to 1000
(which represents G-Force, or 9.80665m/sec2). In freefall, all three values are equal to 0. The G-Force value is
specified by G_FORCE_VALUE constant.
Accelerometer sensor hardware is limited by the following factors:
Subscribing to accelerometer sensor readings is costly for the device battery, and should
therefore only be used only when necessary. To turn on the accelerometer sensor, invoke the
openRawDataChannel(Application) or
openOrientationDataChannel(Application) methods. While the returned
channel is open, the accelerometer sensor is powered and is sampled for
changes. When the returned channel is closed, the accelerometer sensor is not queried.
The following code sample illustrates how to retrieve periodic acceleration data in a dedicated
thread:
public void run()
{
// open channel
Channel rawDataChannel = AccelerometerSensor.openRawDataChannel( Application.getApplication() );
// create raw sample vector with three components - X, Y, Z
short[] xyz = new short[ 3 ];
while( running ) {
// read acceleration
rawDataChannel.getLastAccelerationData( xyz );
// process the acceleration
process( xyz );
// sleep for maintaining query rate
Thread.sleep( 500 );
}
// close the channel to stop sensor query routine
rawDataChannel.close();
}
When using orientation values instead of raw sample values, the most efficient
way is to receive orientation change notifications using a listener. This approach
avoids having to create another applications thread for periodic orientation checks.
The following code sample illustrates how to use an orientation listener:
private Channel orientationChannel;
public void register()
{
// open channel
orientationChannel = AccelerometerSensor.openOrientationDataChannel( Application.getApplication() );
orientationChannel.setAccelerometerListener( this );
}
public void onData( AccelerometerData accData )
{
// get the new orientation
int newOrientation = accData.getOrientation();
// relayout accordingly
relayout( newOrientation );
}
public void unregister()
{
// close the channel to save power
orientationChannel.close();
}
The following code sample illustrates how to specify
background raw data listening:
// create channel config
AccelerometerChannelConfig channelConfig = new AccelerometerChannelConfig( AccelerometerChannelConfig.TYPE_RAW );
// specify background mode support
channelConfig.setBackgroundMode( true );
// open accelerometer channel that is active in background
Channel channel = AccelerometerSensor.openChannel( Application.getApplication(), channelConfig );
The following code sample illustrates how to configure channel to accumulate samples
in a buffer:
The following code sample illustrates how to query for accumulated raw acceleration
samples:
// create channel config
AccelerometerChannelConfig channelConfig = new AccelerometerChannelConfig( AccelerometerChannelConfig.TYPE_RAW );
// specify number of raw acceleration samples to keep in buffer
channelConfig.setSamplesCount( 500 );
// open accelerometer channel
Channel bufferedChannel = AccelerometerSensor.openChannel( Application.getApplication(), channelConfig );
AccelerometerData accData;
while( running ) {
// query for buffered accelerometer data
accData = bufferedChannel.getAccelerometerData();
// get the number of new acceleration samples
int newBatchSize = accData.getNewBatchLength();
// get samples buffers
short[] xAccel = accData.getXAccHistory();
short[] yAccel = accData.getYAccHistory();
short[] zAccel = accData.getZAccHistory();
// process new batch
process( xAccel, yAccel, zAccel );
// sleep for some seconds
Thread.sleep( 4000 );
}
| Inner Class Summary | ||
static class |
AccelerometerSensor.Channel
Encapsulates an active connection to accelerometer sensor. |
|
| Field Summary | ||
static int |
G_FORCE_VALUE
Constant for raw acceleration value that is equal to G-Force. |
|
static int |
ORIENTATION_BACK_UP
Orientation constant indicating the BlackBerry device display is directly facing the ground. |
|
static int |
ORIENTATION_BOTTOM_UP
Orientation constant indicating the bottom side of the Blackberry device is moving upwards. |
|
static int |
ORIENTATION_FRONT_UP
Orientation constant indicating the BlackBerry device display is facing 180 degrees from the ground. |
|
static int |
ORIENTATION_LEFT_UP
Orientation constant indicating the left side of the BlackBerry device is moving upwards. |
|
static int |
ORIENTATION_RIGHT_UP
Orientation constant indicating the right side of the BlackBerry device is moving upwards. |
|
static int |
ORIENTATION_TOP_UP
Orientation constant indicating the top side of the Blackberry device is moving upwards. |
|
static int |
ORIENTATION_UNKNOWN
Orientation constant indicating an unknown BlackBerry device orientation. |
|
| Method Summary | ||
static boolean |
isSupported()
Returns if accelerometer sensor is supported on this device. |
|
static AccelerometerSensor.Channel |
openChannel(Application app,
AccelerometerChannelConfig cfg)
Turns on accelerometer sensor based on channel configuration. |
|
static AccelerometerSensor.Channel |
openOrientationDataChannel(Application app)
Turns on accelerometer sensor for orientation data. |
|
static AccelerometerSensor.Channel |
openRawDataChannel(Application app)
Turns on accelerometer sensor for raw acceleration data. |
|
| Methods inherited from class java.lang.Object |
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
| Field Detail |
public static final int G_FORCE_VALUE
public static final int ORIENTATION_BACK_UP
public static final int ORIENTATION_BOTTOM_UP
public static final int ORIENTATION_FRONT_UP
public static final int ORIENTATION_LEFT_UP
public static final int ORIENTATION_RIGHT_UP
public static final int ORIENTATION_TOP_UP
public static final int ORIENTATION_UNKNOWN
| Method Detail |
public static boolean isSupported()
IllegalStateException.true if supported; false otherwise.public static AccelerometerSensor.Channel openChannel(Application app, AccelerometerChannelConfig cfg) throws IllegalStateException, IllegalArgumentException
IllegalStateException - if the handheld does not have accelerometer sensor, or if
channel is already opened for an application, or both
foreground and background modes are off.IllegalArgumentException - if channel is configured for raw data, and count is less than 1.public static AccelerometerSensor.Channel openOrientationDataChannel(Application app)
AccelerometerSensor.Channel.getOrientation()
method. Alternatively, a listener can be registered by invoking the
AccelerometerSensor.Channel.setAccelerometerListener(AccelerometerListener) method.
An applicaton can open only one accelerometer channel.public static AccelerometerSensor.Channel openRawDataChannel(Application app)
AccelerometerSensor.Channel.getLastAccelerationData(short[]) method. An applicaton
can open only one accelerometer channel.
|
|||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
| SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | ||||||||
Copyright 1999-2009 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.
Copyright 2002-2003 Nokia Corporation All Rights Reserved.
Java is a trademark or registered trademark of Sun Microsystems, Inc. in the US and other countries.