net.rim.device.api.barcodelib
Class BarcodeScanner

java.lang.Object
  net.rim.device.api.amms.control.camera.ImageScanner
      net.rim.device.api.barcodelib.BarcodeScanner

public final class BarcodeScanner
extends ImageScanner

Overview

This class is a scanner intended for barcode scanning. See com.google.zxing for the detection and decoding libraries.

You'll want to grab the Field returned by BarcodeScanner.getViewfinder() and add it to your screen before scanning is started. This Field can be configured through the VideoControl supplied by BarcodeScanner.getVideoControl().

You are notified via the BarcodeDecoderListener when a barcode has been detected by the set BarcodeDecoder.

Typical usage for scanning for QR barcodes:

 
   BarcodeDecoderListener listener = new BarcodeDecoderListener() {
       public void barcodeDecoded( String rawText ) {
           // called when a barcode has been detected.  Process the rawText here.
           // stopScan has been automatically called.
       }
  };
 

 
   Hashtable hints = new Hashtable();
   Vector formats  = new Vector();
   formats.addElement(BarcodeFormat.QR_CODE);
   hints.put(DecodeHintType.POSSIBLE_FORMATS, formats);
   hints.put(DecoderHintType.TRY_HARDER, Boolean.TRUE);
   BarcodeDecoder decoder = new BarcodeDecoder(hints);
 

 
   MainScreen screen = new MainScreen();
   BarcodeScanner scanner = new BarcodeScanner( decoder, listener );
   scanner.getVideoControl().setDisplayFullScreen( true );
   screen.add( scanner.getViewfinder() );
   UiApplication.getUiApplication().pushScreen( screen );
   scanner.startScan(); 
 

Notes

Scanning is stopped automatically in the following scenarios:

• When the Screen the viewfinder is attached to is detached from its UiEngine.
• When the Application that's displaying the viewfinder is moved to the background (and in this scenario, the Screen displaying the viewfinder is also detached from its UiEngine.
• When a barcode is successfully decoded.

The camera player will still be in the started state after stopScan is called, but the decoder is no longer processing until startScan is called again. You will know when the decoder is processing data by the LED flashing red. If you wish to enable continuous scanning, you should call startScan again a short delay after being notified that a barcode has been processed.

 
   BarcodeDecoderListener listener = new BarcodeDecoderListener() {
       private Runnable _restart = new Runnable() {
           public void run() {
               _scanner.startScan();
           }
       };
       
       public void barcodeDecoded( String rawText ) {
           // called when a barcode has been detected.  Process the rawText here.
           // restart the scanner in 250ms
           Application.getApplication.invokeLater( _restart, 250, false );
       }
  };
 

When attempting to scan 1D barcodes, barcodes are read left to right. Thus, orientation of the barcode in the viewfinder matters, and should be aligned to be read left to right.

If you don't intend to reuse the scanner object after scanning has stopped, ensure you free up resources by calling scanner.getPlayer().close(). Once a player is closed it cannot be reused for scanning.

Since:

BlackBerry API 6.0.0

Constructor Summary

BarcodeScanner(BarcodeDecoder decoder, BarcodeDecoderListener listener)
Constructor.

Method Summary
Player	getPlayer() Retrieves the camera player.
VideoControl	getVideoControl() Retrieves the VideoControl for the player returned by getPlayer().
Field	getViewfinder() Retrieves the viewfinder for the player returned by getPlayer().
void	setBarcodeDecoder(BarcodeDecoder decoder) Set the barcode decoder.
void	startScan() Starts scanning for a barcode.
void	stopScan() Stops scanning for a barcode.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

BarcodeScanner

public BarcodeScanner(BarcodeDecoder decoder,
                      BarcodeDecoderListener listener)
               throws IOException,
                      MediaException

Constructor.

Parameters:

decoder - BarcodeDecoder that can be configured to detect barcodes.

listener - BarcodeDecoderListener to be notified when a barcode has been detected.

Throws:

IllegalArgumentException - if listener is null

IOException

MediaException

Since:

BlackBerry API 6.0.0

Method Detail

getPlayer

public Player getPlayer()

Retrieves the camera player. Equivalent to javax.microedition.media.Manager.createPlayer( "capture://video?encoding=image/jpeg" );

Overrides:

getPlayer in class ImageScanner

Returns:

camera player

Since:

BlackBerry API 6.0.0

getVideoControl

public VideoControl getVideoControl()

Retrieves the VideoControl for the player returned by getPlayer().

Overrides:

getVideoControl in class ImageScanner

Returns:

VideoControl

Since:

BlackBerry API 6.0.0

getViewfinder

public Field getViewfinder()

Retrieves the viewfinder for the player returned by getPlayer().

Overrides:

getViewfinder in class ImageScanner

Returns:

viewfinder

Since:

BlackBerry API 6.0.0

startScan

public void startScan()
               throws MediaException

Starts scanning for a barcode.

Overrides:

startScan in class ImageScanner

Throws:

MediaException - if the camera cannot be started or scanning cannot be started.

IllegalStateException - if no BarcodeDecoder has been set.

Since:

BlackBerry API 6.0.0

stopScan

public void stopScan()
              throws MediaException

Stops scanning for a barcode. Scanning is automatically stopped after a barcode has been detected and decoded.

Overrides:

stopScan in class ImageScanner

Throws:

MediaException - if the camera cannot be stopped or scanning cannot be stopped.

Since:

BlackBerry API 6.0.0

setBarcodeDecoder

public void setBarcodeDecoder(BarcodeDecoder decoder)

Set the barcode decoder. Scanning must be restarted (stopped and then started again) to utilize the new decoder if decoding has already been started.

Parameters:

decoder - the barcode decoder.

Since:

BlackBerry API 6.0.0