Deprecation warning
Please note that this is outdated documentation for an older release of the Scandit Barcode Scanner SDK.
We are deprecating the 5.x API on all platforms (except Linux). Release 5.19 in April 2021 will be our final. Applications running 5.x will continue to work, and we will continue to release critical bug fixes and security patches only, for one year. We encourage you to migrate to 6.x and take advantage of our latest / advanced features and improved performance.
You'll find the updated documentation at: Data Capture SDK Documentation for Android
This guide shows how to scan barcodes with the Scandit scan case using the ScanCase API.
Integrating the scan case into your application requires only a few steps: all you need to do is to create a ScanCase object and implement the ScanCaseListener interface.
Creating an instance of ScanCase
In order to create an instance of ScanCase, you first need to set the license key (if you haven't already), create a ScanCaseSettings, and enable the symbologies you need. At this point you can create a ScanCase.
Scanning with ScanCase is driven by it's state property. ScanCase initially starts in ScanCase.STATE_STANDBY and can be set to one of the following three states:
- ScanCase.STATE_OFF : camera is off, torch is off.
- ScanCase.STATE_STANDBY : camera is on but with throttled frame-rate, scanner is off, torch is off.
- ScanCase.STATE_ACTIVE : camera is on, scanner is on, torch is on.
In order to start scanning, you just need to change the state to ScanCase.STATE_ACTIVE:
Using Split View - switching between forward and downward scanning modes
Android ScanCase API provides user with two scanning methods (also called "modes"):
- forward mode - traditional forward, point-to-scan barcode reading with an aiming light,
- downward mode - scanning via the camera viewfinder for recognizing multiple barcodes at once.
By default, scan case works in the ScanCase.MODE_FACE_FORWARD mode. Switching between the modes is very easy, all you need to do is call setScanCaseMode function:
ScanCase API also allows you to enable different symbologies for each of the scanning methods. You can achieve that by calling the setSymbologyEnabled function, where the last argument specifies whether forward or downward mode should have the given symbology enabled:
Implementing the ScanCaseListener interface
ScanCaseListener consists of four methods. Please note that all these methods are called in the thread running the barcode recognition engine, so you are responsible to switch to the UI thread if needed. Let's check them one by one.
The first method is called when ScanCase finished the initialization process and it's ready to be used.
Whenever a new code is scanned the following method is called. If you want to keep scanning new codes, return ScanCase.STATE_ACTIVE , if you want to temporary pause the scanner return ScanCase.STATE_STANDBY . You can also return ScanCase.STATE_OFF if you don't plan to scan new codes relatively soon.
Please note that changing from ScanCase.STATE_OFF to ScanCase.STATE_ACTIVE takes more time than switching from ScanCase.STATE_STANDBY to ScanCase.STATE_ACTIVE .
Whenever a frame has been processed by the barcode recognition engine (regardless whether a code could be successfully decoded or not) the following method is called. It is invoked in the thread that runs the recognition engine and blocks further processing. In case codes have been recognized in the same frame, the following callback is invoked after didScan . If you want to keep scanning new codes, return ScanCase.STATE_ACTIVE , if you want to temporary pause the scanner return ScanCase.STATE_STANDBY . You can also return ScanCase.STATE_OFF if you don't plan to scan new codes relatively soon.
Note that if ScanCase.STATE_ACTIVE is returned but didScan returned ScanCase.STATE_STANDBY or ScanCase.STATE_OFF , then the state returned by didScan will take precedence.
Whenever the state of ScanCase changes the following method is called. There are multiple reasons for which the state can be changed:
- ScanCaseListener.STATE_CHANGE_REASON_MANUAL : the state has been changed programmatically by calling the setState method or by returning a different state from the didScan callback.
- ScanCaseListener.STATE_CHANGE_REASON_TIMEOUT : the state has been changed because of a timeout (check the timeout section).
- ScanCaseListener.STATE_CHANGE_REASON_VOLUME_BUTTON : the state has been changed by the volume button (check the volume & hardware button section).
- ScanCaseListener.STATE_CHANGE_REASON_HARDWARE_BUTTON : the state has been changed by the hardware button (check the volume & hardware button section).
Enabling the volume/hardware button to start scanning
It is possible to use either the volume buttons or an extra hardware button (only on supported devices) to scan in ScanCase.MODE_FACE_FORWARD mode. Keeping the volume/hardware button pressed will keep the scan case in ScanCase.STATE_ACTIVE state, while releasing it will change the state to ScanCase.STATE_STANDBY . To enable this feature, all you need to do is to override your activity onKeyUp and onKeyDown methods, so that they call the methods provided by the ScanCase API:
You know when the state changes because of a volume/hardware button if the reason of the didChangeState callback is set to ScanCaseListener.STATE_CHANGE_REASON_VOLUME_BUTTON / ScanCaseListener.STATE_CHANGE_REASON_HARDWARE_BUTTON .
Using timeouts to switch state
It is possible to switch from one state to another one automatically after a specific timeout. This could be useful, for instance, to switch the scanner off after a long time of inactivity in order to save power.
The following code changes the state from ScanCase.STATE_STANDBY to ScanCase.STATE_OFF after approximately 60 seconds.
You know when the state changes because of a timeout if the reason of the didChangeState callback is set to ScanCaseListener.STATE_CHANGE_REASON_TIMEOUT .
You could, for instance, display a toast to inform the user that the scanned has been switched off: