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

Use the Scandit Scan Case

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.

ScanditLicense.setAppKey(sScanditSdkAppKey);
ScanCaseSettings settings = ScanCaseSettings.create();
settings.setSymbologyEnabled(Barcode.SYMBOLOGY_EAN13, true);
ScanCase scanCase = ScanCase.acquire(context, settings, this);

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:

In order to start scanning, you just need to change the state to ScanCase.STATE_ACTIVE:

scanCase.setState(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.setScanCaseMode(ScanCase.MODE_FACE_DOWNWARD, runnable);

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:

settings.setSymbologyEnabled(Barcode.SYMBOLOGY_EAN13, true, ScanCase.MODE_FACE_FORWARD);
settings.setSymbologyEnabled(Barcode.SYMBOLOGY_EAN8, true, ScanCase.MODE_FACE_DOWNWARD);

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.

@Override
public void didInitializeScanCase(final ScanCase scanCase) {
// ScanCase is ready, and the state is ScanCase.STATE_STANDBY
}

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 .

@Override
public int didScan(ScanCase scanCase, final ScanCaseSession session) {
runOnUiThread(new Runnable() {
@Override
public void run() {
// switch to the UI thread if you need to (like for updating graphical user interface)
}
});
return ScanCase.STATE_STANDBY;
}

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.

@Override
public int didProcess(byte[] imageBuffer, int width, int height, ScanCaseSession session) {
return ScanCase.STATE_ACTIVE;
}

Whenever the state of ScanCase changes the following method is called. There are multiple reasons for which the state can be changed:

@Override
public void didChangeState(ScanCase scanCase, int state, int reason) {
// state: the new state of the ScanCase
// reason: the reason for the state change
}

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:

@Override
public boolean onKeyUp(int keyCode, KeyEvent event) {
return scanCase.onKeyUp(keyCode, event) || super.onKeyUp(keyCode, event);
}
@Override
public boolean onKeyDown(int keyCode, KeyEvent event) {
return scanCase.onKeyDown(keyCode, event) || super.onKeyDown(keyCode, event);
}

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.

scanCase.setTimeout(ScanCase.STATE_STANDBY, ScanCase.STATE_OFF, 60000);

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:

@Override
public void didChangeState(ScanCase scanCase, int state, final int reason) {
switch (state) {
case ScanCase.STATE_STANDBY:
break;
case ScanCase.STATE_ACTIVE:
break;
case ScanCase.STATE_OFF:
runOnUiThread(new Runnable() {
@Override
public void run() {
if (reason == ScanCaseListener.STATE_CHANGE_REASON_TIMEOUT) {
Toast.makeText(MainActivity.this, "State changed to ScanCase.STATE_OFF to save power", Toast.LENGTH_SHORT).show();
}
}
});
break;
}
}