net.rim.device.api.amms.control.camera
Class ImageScanner

java.lang.Object
  extended by net.rim.device.api.amms.control.camera.ImageScanner
Direct Known Subclasses:
BarcodeScanner

public class ImageScanner
extends Object

This class is intended for scanning camera frames.

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

You are notified via the ImageDecoderListener when something has been detected by the set ImageDecoder.

Notes

Scanning is stopped automatically in the following scenarios:

The camera player will still be in the started state after ImageScanner.stopScan() is called, but the decoder is no longer processing until ImageScanner.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 an image has been processed.

startScan and stopScan should be called from your application's event thread. The startScan method is non blocking and the scanning API is executed by a background thread already.

 
   ImageDecoderListener listener = new ImageDecoderListener() {
       private Runnable _restart = new Runnable() {
           public void run() {
               _scanner.startScan();
           }
       };

       public void imageDecoded( Object decoded ) {
           // restart the scanner in 250ms
           Application.getApplication.invokeLater( _restart, 250, false );
           // process what's been decoded
       }
  };
 

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

Since:
BlackBerry API 7.0.0

Constructor Summary
ImageScanner(ImageDecoder decoder, ImageDecoderListener listener)
          Constructs an ImageScanner.
 
Method Summary
 ImageDecoder getDecoder()
          Returns the decoder.
 Player getPlayer()
          Retrieves the camera player.
 VideoControl getVideoControl()
          Retrieves the VideoControl for the player returned by getPlayer().
 Field getViewfinder()
          Retrieves the viewfinder for the VideoControl returned by getVideoControl().
static boolean isColorIncluded()
          Whether there's a U & V component provided to ImageDecoder.
 boolean isScanning()
          Queries if scanning is started.
 void setDecoder(ImageDecoder decoder)
          Set the decoder.
 void setHint(ImageScannerHint hint)
          Sets a scanning hint that is applied when scanning is started.
 void startScan()
          Starts scanning for something your decoder can decode.
 void stopScan()
          Stops scanning.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 



Constructor Detail

ImageScanner

public ImageScanner(ImageDecoder decoder,
                    ImageDecoderListener listener)
             throws IOException,
                    MediaException
Constructs an ImageScanner.

Parameters:
decoder - decoder responsible for decoding.
listener - listener notified when decoder is successful.
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) throws it when specified "capture://video?encoding=image/jpeg".
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.

Returns:
camera player, will not be null.
Since:
BlackBerry API 7.0.0

getVideoControl

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

Returns:
the VideoControl for the player returned by getPlayer(), will not be null.
Since:
BlackBerry API 7.0.0

getViewfinder

public Field getViewfinder()
Retrieves the viewfinder for the VideoControl returned by getVideoControl().

Returns:
the viewfinder for the VideoControl returned by getVideoControl(), will not be null.
Since:
BlackBerry API 7.0.0

startScan

public void startScan()
               throws MediaException
Starts scanning for something your decoder can decode. This method does nothing if scanning has already been started.

Throws:
MediaException - if the Player cannot be started or scanning cannot be started.
IllegalStateException - if no ImageDecoder 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 7.0.0

stopScan

public void stopScan()
              throws MediaException
Stops scanning. Scanning is automatically stopped after an image has been detected and decoded. This method does nothing if scanning has already been stopped.

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 7.0.0

isScanning

public boolean isScanning()
Queries if scanning is started.

Returns:
true if scanning is started, false otherwise.
Since:
BlackBerry API 7.0.0

isColorIncluded

public static boolean isColorIncluded()
Whether there's a U & V component provided to ImageDecoder.

Returns:
true if U & V channels are provided, false otherwise.
Since:
BlackBerry API 7.0.0

setDecoder

public void setDecoder(ImageDecoder decoder)
                throws IllegalArgumentException
Set the decoder. This method can be called if scanning has already been started.

Parameters:
decoder - the image decoder.
Throws:
IllegalArgumentException - if decoder is null.
See Also:
ImageScanner.getDecoder()
Since:
BlackBerry API 7.0.0

getDecoder

public ImageDecoder getDecoder()
Returns the decoder.

Returns:
the image decoder.
See Also:
ImageScanner.setDecoder(net.rim.device.api.amms.control.camera.ImageDecoder)
Since:
BlackBerry API 7.0.0

setHint

public void setHint(ImageScannerHint hint)
Sets a scanning hint that is applied when scanning is started. There is no hint set by default.

Parameters:
hint - A hint from ImageScannerHint, can be null for no hints.
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