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

A scanner intended for barcode scanning. See com.google.zxing for the detection and decoding libraries.

Add the Field returned by BarcodeScanner.getViewfinder() to your screen before scanning is started. This Field can be configured through the VideoControl supplied by BarcodeScanner.getVideoControl().

You are notified of the decoded text by the BarcodeDecoderListener when a barcode is detected by the zxing library. Alternatively, you can use ImageDecoderListener which will give you access to all the decoded information via Result.

Typical usage for scanning 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);
   BarcodeDecoder decoder = new BarcodeDecoder(hints); 
 
 
   MainScreen screen = new MainScreen();
   BarcodeScanner scanner = new BarcodeScanner( decoder, listener );
   screen.add( scanner.getViewfinder() );
   UiApplication.getUiApplication().pushScreen( screen );
   scanner.startScan(); 
 

You might try hints.put(DecoderHintType.TRY_HARDER, Boolean.TRUE) as well for a more thorough detection, especially when decoding 1D barcodes.

Notes

Scanning is stopped automatically when the following occurs:

The camera Player will still be in the started state after BarcodeScanner.stopScan() is called, but the decoder is no longer processing until BarcodeScanner.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 BarcodeScanner.startScan() again a short delay after being notified that a barcode has been processed. Note that you must call BarcodeScanner.startScan() from your event thread.

 
   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, ImageDecoderListener listener)
          Creates a new instance of BarcodeScanner.
BarcodeScanner(BarcodeDecoder decoder, BarcodeDecoderListener listener)
          Creates a new instance of BarcodeScanner.
 
Method Summary
 Player getPlayer()
          Retrieves the camera player.
 Field getVanillaViewfinder()
          Retrieves a non-augmented viewfinder for the player returned by BarcodeScanner.getPlayer().
 VideoControl getVideoControl()
          Retrieves the VideoControl for the player returned by BarcodeScanner.getPlayer().
 Field getViewfinder()
          Retrieves the viewfinder for the player returned by BarcodeScanner.getPlayer().
 void setBarcodeDecoder(BarcodeDecoder decoder)
          Sets the BarcodeDecoder.
 void startScan()
          Starts scanning for a barcode.
 void stopScan()
          Stops scanning for a barcode.
 
Methods inherited from class net.rim.device.api.amms.control.camera.ImageScanner
getDecoder, isColorIncluded, isScanning, setDecoder, setHint
 
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
Creates a new instance of BarcodeScanner. This class sets a hint setHint with ImageScannerHint.BARCODE_SCANNING.

Parameters:
decoder - BarcodeDecoder that can be configured to detect barcodes.
listener - BarcodeDecoderListener to be notified when a barcode has been detected.
Throws:
IllegalArgumentException - if decoder or listener is null.
SecurityException - if the caller does not have security permission to create the Player.
MediaException - if Manager.createPlayer(java.lang.String) specifies capture://video?encoding=image/jpeg as its encoding.
IOException - if there was a problem connecting with the source.
Since:
BlackBerry API 6.0.0

BarcodeScanner

public BarcodeScanner(BarcodeDecoder decoder,
                      ImageDecoderListener listener)
               throws IOException,
                      MediaException
Creates a new instance of BarcodeScanner. When used in conjunction with the zxing library, your ImageDecoderListener will get notified via ImageDecoderListener.imageDecoded(Object) with an object of type Result. This class sets a hint setHint with ImageScannerHint.BARCODE_SCANNING.

Parameters:
decoder - BarcodeDecoder that can be configured to detect barcodes.
listener - BarcodeDecoderListener to be notified when a barcode has been detected.
Throws:
IllegalArgumentException - if decoder or listener is null
SecurityException - if the caller does not have security permission to create the Player.
MediaException - if Manager.createPlayer(java.lang.String) specifies capture://video?encoding=image/jpeg as its encoding.
IOException - if there was a problem connecting with the source pointed to by the Locator.
Since:
BlackBerry API 7.0.0


Method Detail

getPlayer

public Player getPlayer()
Retrieves the camera player.

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 BarcodeScanner.getPlayer().

Overrides:
getVideoControl in class ImageScanner
Returns:
VideoControl The VideoControl associated with this BarcodeScanner.
Since:
BlackBerry API 6.0.0

getViewfinder

public Field getViewfinder()
Retrieves the viewfinder for the player returned by BarcodeScanner.getPlayer(). This viewfinder is a ViewfinderOverlay. If getDecoder returns an instance of BarcodeDecoder at the time this method is called, the ViewfinderOverlay will also contain a single BarcodeScannerOverlayField.

Overrides:
getViewfinder in class ImageScanner
Returns:
A viewfinder that can be added to the screen directly. Invoking this method multiple times will return the same ViewfinderOverlay.
Since:
BlackBerry API 6.0.0

getVanillaViewfinder

public final Field getVanillaViewfinder()
Retrieves a non-augmented viewfinder for the player returned by BarcodeScanner.getPlayer().

Returns:
A viewfinder that can be added to the screen directly. Invoking this method multiple times will return the same Viewfinder.
See Also:
ImageScanner.getViewfinder()
Since:
BlackBerry API 7.0.0

startScan

public void startScan()
               throws MediaException
Starts scanning for a barcode.

Overrides:
startScan in class ImageScanner
Throws:
MediaException - if the Player cannot be started or scanning cannot be started.
IllegalStateException - if no BarcodeDecoder has been set, or if the Player is in the CLOSED state.
SecurityException - if the caller does not have security permission to start the Player.
Since:
BlackBerry API 6.0.0

stopScan

public void stopScan()
              throws MediaException
Stops scanning for a barcode. Note that scanning is automatically stopped after a barcode has been detected and decoded.

Overrides:
stopScan in class ImageScanner
Throws:
MediaException - if the Player cannot be stopped or scanning cannot be stopped.
IllegalStateException - if the Player is in the CLOSED state.
Since:
BlackBerry API 6.0.0

setBarcodeDecoder

public void setBarcodeDecoder(BarcodeDecoder decoder)
                       throws IllegalArgumentException
Sets the BarcodeDecoder. This method can be called if scanning has already been started.

Parameters:
decoder - The barcode decoder.
Throws:
IllegalArgumentException - if decoder is null.
See Also:
ImageScanner.setDecoder(net.rim.device.api.amms.control.camera.ImageDecoder)
Since:
BlackBerry API 6.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