net.rim.device.api.system
Class MagnetometerSensor

java.lang.Object
  extended by net.rim.device.api.system.MagnetometerSensor

public final class MagnetometerSensor
extends Object

Provides query and listener registration methods to access the magnetometer sensor.

Overview

The MagnetometerSensor is the main entry point for retrieving information from the magnetometer sensor in the BlackBerry device. You can use one of the following ways for retrieving magnetometer data:

  1. Periodically retrieve magnetometer data in a dedicated thread.
  2. Use a listener to notify your application when specific data changes.

Battery Considerations

Subscribing to magnetometer sensor readings is costly for the device battery, and should therefore only be used only when necessary. To turn on the magnetometer sensor, invoke the MagnetometerSensor.openChannel(Application) method. While the returned channel is open, the magnetometer sensor is powered and is sampled for changes. When the returned channel is closed, the magnetometer sensor is not queried.

Code Samples

The following code sample illustrates how to periodically retrieve magnetometer data from a dedicated thread.

 public void run()
 {
     // open channel
     Channel magChannel = MagnetometerSensor.openChannel( Application.getApplication() );
     
     while( running ) {
         // read raw magnetometer data
         double direction = 0;
         MagnetometerData data = magChannel.getData();
         synchronized( data ) {
             direction = data.getDirection();
         }    
         // process the direction
         process( direction );
         // sleep for maintaining query rate
         Thread.sleep( 500 );
     }
     // close the channel to stop sensor query routine
     magChannel.close();
 }
 

The following code sample illustrates how to use a magnetometer listener:

 private Channel magChannel;

 public void register()
 {
     // open channel
     magChannel = MagnetometerSensor.openChannel( Application.getApplication() );
     magChannel.addMagnetometerListener( this );
 }

 public void onData( MagnetometerData magData )
 {
     // get the new orientation
     int direction = magData.getDirection();
     // process the direction
     process( direction );
 }

 public void unregister()
 {
     // close the channel to save power
     magChannel.close();
 }
 

The following code sample illustrates how to specify background raw data listening:

 // create channel config
 MagnetometerChannelConfig channelConfig = new MagnetometerChannelConfig();
 // specify background mode support
 channelConfig.setBackgroundMode( true );
 // open accelerometer channel that is active in background
 Channel channel = MagnetometerSensor.openChannel( Application.getApplication(), channelConfig );
 

Since:
BlackBerry API 7.0.0

Nested Class Summary
static class MagnetometerSensor.Channel
          Encapsulates an active connection to the magnetometer sensor.
 
Method Summary
static boolean isSupported()
          Indicates whether the magnetometer sensor is supported on this device.
static MagnetometerSensor.Channel openChannel(Application app)
          Turns on the magnetometer sensor with the current application.
static MagnetometerSensor.Channel openChannel(Application app, MagnetometerChannelConfig cfg)
          Turns on the magnetometer sensor with the specified application and channel configuration.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 



Method Detail

isSupported

public static boolean isSupported()
Indicates whether the magnetometer sensor is supported on this device. If there is no magnetometer sensor, the channel registration methods throw an IllegalStateException.

Returns:
true if the magnetometer sensor is supported, false otherwise.
Since:
BlackBerry API 7.0.0

openChannel

public static MagnetometerSensor.Channel openChannel(Application app)
Turns on the magnetometer sensor with the current application. This uses the default channel configuration.

Parameters:
app - The current application.
Returns:
An open magnetometer channel.
Throws:
IllegalStateException - if MagnetometerSensor.isSupported() returns false.
IllegalStateException - if Channel is already open for application
NullPointerException - if the application is null.
Since:
BlackBerry API 7.0.0

openChannel

public static MagnetometerSensor.Channel openChannel(Application app,
                                                     MagnetometerChannelConfig cfg)
                                              throws IllegalStateException,
                                                     IllegalArgumentException
Turns on the magnetometer sensor with the specified application and channel configuration.

Parameters:
app - The application.
cfg - The magnetometer channel configuration.
Returns:
An open magnetometer channel.
Throws:
IllegalStateException - if MagnetometerSensor.isSupported() returns false.
IllegalStateException - if Channel is already open for application
IllegalArgumentException - if the channel configuration is not in background or foreground mode.
NullPointerException - if the application is null.
NullPointerException - if the config is null.
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