net.rim.device.api.barcodelib
Class BarcodeScanner

java.lang.Object
  extended by net.rim.device.api.amms.control.camera.ImageScanner
      extended by 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:

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





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.