Skip to main content

Barcode Scanner UI Components | Flutter Document Scanner

Introduction

The Scanbot SDK comes with an essential camera view, additional views for extending the camera functionality and a detector classes that handle all the camera and detection implementation details for you.

It provides a UI for document scanning guidance as well as a UI and functionality for manual and automatic shutter release on barcode detection.

RTU-UI Component

The Barcode scanner is available as an RTU-UI and Classic component (types of components are explained here).

Take a look at our Example Apps to see how to integrate the Barcode Scanner.

Barcode Scanner

ScanbotSdkUi.startBarcodeScanner(config)

Opens a Scanning UI for barcodes and QR codes.

alt

var config = BarcodeScannerConfiguration(
barcodeFormats: [BarcodeFormat.CODE_128, BarcodeFormat.DATA_MATRIX],
topBarBackgroundColor: Colors.blueAccent,
cameraOverlayColor: Colors.black.withAlpha(150),
finderTextHint: "Please align a barcode in the frame to scan it.",
cancelButtonTitle: "Cancel",
flashEnabled: true,
...
);
var result = await ScanbotSdkUi.startBarcodeScanner(config);
// result.barcodeItems[n].barcodeFormat
// result.barcodeItems[n].text
// result.barcodeItems[n].formattedResult
  • result.operationResult:
    • SUCCESS if a barcode was detected
    • ERROR if an error occurred
    • CANCELED if the user has canceled the operation (tapped on the "cancel" button)
  • barcodeItems[n] - a list of detected barcodes/QR codes as BarcodeItems:
    • item.barcodeFormat - Format of detected barcode/QR code (e.g. "CODE_128", "EAN_13", "QR_CODE", etc).
    • item.text - Raw text value of detected barcode/QR code.
    • item.rawBytes - Raw bytes of detected barcode/QR code.
    • item.formattedResult - Optional, formatted/parsed result. See implementations of BarcodeFormattedResult.
BarcodeScannerConfiguration

All settings are optional.

  • barcodeFormats is an optional array of barcode formats that act as a detection filter. By default all supported formats will be detected.

  • acceptedDocumentFormats is an optional array of accepted barcode formats that acts as a detection filter. By default all supported formats will be detected.

  • Further configs:

/// The configuration object should be applied for this screen
String? screen;

/// An optional array of barcode document formats that act as a detection filter. By default all supported document formats will be detected.
List<BarcodeDocumentFormat>? acceptedDocumentFormats;

/// The extension filter for EAN and UPC barcodes.
BarcodesExtensionFilter? barcodesExtensionFilter;

/// Background color of the detection overlay.
Color? cameraOverlayColor;

/// Background color of the detection overlay.
CameraModule? cameraModule;

/// The relative initial zoom level of the camera in the range (0,1), where 0 is zoomed out and 1 is zoomed in. Default value is 0.0.
double? cameraZoomFactor;

/// Whether the cancel button is hidden or not. iOS only.
bool? cancelButtonHidden;

/// String being displayed on the cancel button.
String? cancelButtonTitle;

/// String being displayed on the cancel button.
EngineMode? engineMode;

/// Title of the button that opens the screen where the user can allow the usage of the camera by the app.
String? enableCameraButtonTitle;

/// Text that will be displayed when the app is not allowed to use the camera, prompting the user to enable the usage of the camera.
String? enableCameraExplanationText;

/// Foreground color of the detection overlay.
Color? finderLineColor;

/// Width of finder frame border. Default is 2.
double? finderLineWidth;

/// String being displayed as description.
String? finderTextHint;

/// Foreground color of the description label.
Color? finderTextHintColor;

/// Aspect ratio of finder frame (width \ height), which is used to build actual finder frame. Default is 1 - it is a square frame, which is good for QR capturing.
AspectRatio? finderAspectRatio;

/// Controls whether the flash toggle button is hidden or not. iOS only.
bool? flashButtonHidden;

/// String being displayed on the flash button. iOS only.
String? flashButtonTitle;

/// Foreground color of the flash button when flash is off.
Color? flashButtonInactiveColor;

/// Whether flash is toggled on or off.
bool? flashEnabled;

/// Disables auto-focus and locks the lens at the specified focus lock lens position. Default value is false. iOS only. For Android, minFocusDistanceLock can be used.
bool? focusLockEnabled;

/// The position of the lens. Values can be between 0.0f (minimum focusing distance) and 1.0f (maximum focusing distance). The default value is 0.0 iOS only. For Android, minFocusDistanceLock can be used.
double? focusLockPosition;

/// Whether touch-to-focus is enabled on camera preview. Enabled by default. Android only.
bool? touchToFocusEnabled;

/// UI Interface orientation lock mode
OrientationLockMode? orientationLockMode;

/// Optional minimum required text length of the detected barcode. The default is 0 (setting is turned off). NOTE - This feature works on ITF barcodes only.
int? minimumTextLength;

/// Optional maximum text length of the detected barcode. The default is 0 (setting is turned off). NOTE - This feature works on ITF barcodes only.
int? maximumTextLength;

/// Lock focus distance withing minimum possible range
bool? minFocusDistanceLock;

/// Optional minimum required quiet zone on the barcode. Measured in modules (the size of minimal bar on the barcode). The default is 10. NOTE - This feature works on ITF barcodes only.
int? minimum1DBarcodesQuietZone;

/// With this option enabled, the scanner removes checks digits for UPC, EAN and MSI Plessey codes. Has no effect if both single and double digit MSI Plessey checksums are enabled. The default is `false`
bool? stripCheckDigits;

/// Whether scanner screen should make a sound on successful barcode or MRZ detection.
bool? successBeepEnabled;

/// Background color of the top bar.
Color? topBarBackgroundColor;

/// Foreground color of the cancel button.
Color? topBarButtonsColor;

/// Accepted barcode formats
List<BarcodeFormat>? barcodeFormats;

/// Controls whether buttons should use all capitals style, as defined by the Android Material Design. Defaults to TRUE. Android only.
bool? useButtonsAllCaps;

/// If `true`, replaces the cancel button in the top bar with a back arrow icon. The default value is FALSE. Android only.
bool? replaceCancelButtonWithIcon;

/// Preview mode of the camera. FILL_IN or FIT_IN. Default is FILL_IN. Android only
CameraPreviewMode? cameraPreviewMode;

/// The range of valid camera zoom factors. Default value is (1.0; 12.0).
ZoomRange? cameraZoomRange;

/// Sets auto close timer in seconds. 0 = disabled and it is the default value.
int? autoCancelTimeout;

/// The GS1 handling mode. The default value is PARSE.
Gs1HandlingMode? gs1HandlingMode;

/// The checksum algorithm for MSI Plessey barcodes. The default value is MOD_10.
MSIPlesseyChecksumAlgorithm? msiPlesseyChecksumAlgorithm;

/// If `true`, enabled the mode which slightly decreases the scanning quality and the energy consumption, and increases the scanning speed. If `false` - mode is disabled. The default is `false`. Android only.
bool? lowPowerMode;

/// The expected density of QR codes in an image.
CodeDensity? codeDensity;

/// The type of barcode image generation.
BarcodeImageGenerationType? barcodeImageGenerationType;

/// Scanning delay after scanner appearance in seconds. Defaults to 0 secs.
double? initialScanDelay;

/// Freezes a preview after a scan for a given amount of seconds. Defaults to 0 secs. Android only.
double? delayAfterScan;

/// When this property is set to true, the zoom can be activated by double tapping somewhere in the receivers view. iOS only.
bool? doubleTapToZoomEnabled;

/// When this property is set to true, the zoom can be activated by a pinch gesture somewhere in the receivers view. iOS only.
bool? pinchToZoomEnabled;

/// Defines, if zooming in or out should be animated. iOS only.
bool? shouldAnimateZooming;

/// Display the region of interest. The default value is TRUE.
bool? viewFinderEnabled;

/// The confirmation dialog configuration.
ConfirmationDialogConfiguration? confirmationDialogConfiguration;

/// The selection overlay configuration.
SelectionOverlayConfiguration? overlayConfiguration;

Barcode additional params details:

  /// GS1 handling mode
Gs1HandlingMode? gs1HandlingMode;

/// Minimum required text length of the detected barcode.
/// The default is 0.
/// NOTE: Currently works for ITF and MSI Plessey barcodes only!
int? minimumTextLength;

/// Maximum text length of the detected barcode. Setting to zero removes the limit.
/// The default is 0.
/// NOTE: Currently works for ITF and MSI Plessey barcodes only!
int? maximumTextLength;

/// Minimum required quiet zone on the barcode. Measured in modules (the size of minimal bar on the barcode).
/// The default is 10.
/// NOTE: Currently works for ITF and MSI Plessey barcodes only!
int? minimum1DBarcodesQuietZone;

Selection Overlay details:

    /// Whether the barcode selection overlay is enabled or not.
bool? overlayEnabled;

/// Whether the barcode is selected automatically when being detected or not.
bool? automaticSelectionEnabled;

/// Define the way of how to show barcode data with selection overlay.
BarcodeOverlayTextFormat? textFormat;

/// The color of the polygon in the selection overlay.
Color? polygonColor;

/// The color of the text in the selection overlay.
Color? textColor;

/// The color of the texts background in the selection overlay.
Color? textContainerColor;

/// The color of the polygon in the selection overlay, when highlighted.
Color? highlightedPolygonColor;

/// The color of the text in the selection overlay, when highlighted.
Color? highlightedTextColor;

/// The color of the texts background in the selection overlay, when highlighted.
Color? highlightedTextContainerColor;

Batch Barcode Scanner

ScanbotSdk.startBatchBarcodeScanner(config)

Opens a scanning UI for scanning and collecting multiple barcodes.

alt

var config = BatchBarcodeScannerConfiguration(
barcodeFormats: [BarcodeFormat.CODE_128, BarcodeFormat.DATA_MATRIX],
topBarBackgroundColor: Colors.blueAccent,
finderTextHint: "Please align a barcode in the frame to scan it.",
flashEnabled: true,
...
);
var result = await ScanbotSdk.startBatchBarcodeScanner(config);
// result.barcodeItems[n] ...

Result:

  • result.operationResult - SUCCESS if a barcode was detected, ERROR if the user has canceled the operation (tapped on the "cancel" button).
  • result.barcodeItems - List of recognized barcodes as items of BarcodeItem type.

BarcodeItem structure:

  • barcodeFormat - Format of detected barcode/QR code (e.g. "CODE_128", "EAN_13", "QR_CODE", etc).
  • text - Raw text value of detected barcode/QR code.
  • rawBytes - Raw bytes of detected barcode/QR code.
  • formattedResult - Optional, formatted/parsed result. See implementations of BarcodeFormattedResult.
BatchBarcodeScannerConfiguration

Use this configuration class to customize the UI and the behavior of the Batch Barcodes Scanner UI. All config properties are optional.

BatchBarcodeScannerConfiguration:

    /// An optional array of barcode document formats that act as a detection filter. By default all supported document formats will be detected.
List<BarcodeDocumentFormat>? acceptedDocumentFormats;

/// The extension filter for EAN and UPC barcodes.
BarcodesExtensionFilter? barcodesExtensionFilter;

/// Background color of the detection overlay.
Color? cameraOverlayColor;

/// Background color of the detection overlay.
CameraModule? cameraModule;

/// The relative initial zoom level of the camera in the range (0,1), where 0 is zoomed out and 1 is zoomed in. The default value is 0.
double? cameraZoomFactor;

/// The range of valid camera zoom factors. Default value is (1.0; 12.0).
ZoomRange? cameraZoomRange;

/// Whether the cancel button is hidden or not. iOS only.
bool? cancelButtonHidden;

/// String being displayed on the cancel button.
String? cancelButtonTitle;

/// When this property is set to true, the zoom can be activated by double tapping somewhere in the receivers view. iOS only.
bool? doubleTapToZoomEnabled;

/// When this property is set to true, the zoom can be activated by a pinch gesture somewhere in the receivers view. iOS only.
bool? pinchToZoomEnabled;

/// Defines, if zooming in or out should be animated. iOS only.
bool? shouldAnimateZooming;

/// String being displayed on the cancel button.
EngineMode? engineMode;

/// Foreground color of the detection overlay.
Color? finderLineColor;

/// Width of finder frame border. Default is 2.
double? finderLineWidth;

/// String being displayed as description.
String? finderTextHint;

/// Foreground color of the description label.
Color? finderTextHintColor;

/// Aspect ratio of finder frame (width \ height), which is used to build actual finder frame. Default is 1 - it is a square frame, which is good for QR capturing.
AspectRatio? finderAspectRatio;

/// Controls whether the flash toggle button is hidden or not. iOS only.
bool? flashButtonHidden;

/// String being displayed on the flash button. iOS only.
String? flashButtonTitle;

/// Whether flash is toggled on or off.
bool? flashEnabled;

/// Disables auto-focus and locks the lens at the specified focus lock lens position. The default value is false. iOS only.
bool? focusLockEnabled;

/// The position of the lens. Values can be between 0.0f (minimum focusing distance) and 1.0f (maximum focusing distance). The default value is 0.0 iOS only. For Android, minFocusDistanceLock can be used.
double? focusLockPosition;

/// Whether touch-to-focus is enabled on camera preview. Enabled by default. Android only.
bool? touchToFocusEnabled;

/// UI Interface orientation lock mode
OrientationLockMode? orientationLockMode;

/// Optional minimum required text length of the detected barcode. The default is 0 (setting is turned off). NOTE - This feature works on ITF barcodes only.
int? minimumTextLength;

/// Optional maximum text length of the detected barcode. The default is 0 (setting is turned off). NOTE - This feature works on ITF barcodes only.
int? maximumTextLength;

/// Optional minimum required quiet zone on the barcode. Measured in modules (the size of minimal bar on the barcode). The default is 10. NOTE - This feature works on ITF barcodes only.
int? minimum1DBarcodesQuietZone;

/// Lock focus distance withing minimum possible range
bool? minFocusDistanceLock;

/// With this option enabled, the scanner removes checks digits for UPC, EAN and MSI Plessey codes. Has no effect if both single and double digit MSI Plessey checksums are enabled. The default is `false`
bool? stripCheckDigits;

/// Whether scanner screen should make a sound on successful barcode or MRZ detection.
bool? successBeepEnabled;

/// Background color of the top bar.
Color? topBarBackgroundColor;

/// Foreground color of the cancel button.
Color? topBarButtonsColor;

/// Foreground color of the top bar buttons when disabled.
Color? topBarButtonsInactiveColor;

/// Accepted barcode formats
List<BarcodeFormat>? barcodeFormats;

/// Controls whether buttons should use all capitals style, as defined by the Android Material Design. Defaults to TRUE. Android only.
bool? useButtonsAllCaps;

/// The GS1 handling mode. The default value is PARSE.
Gs1HandlingMode? gs1HandlingMode;

/// The checksum algorithm for MSI Plessey barcodes. The default value is MOD_10.
MSIPlesseyChecksumAlgorithm? msiPlesseyChecksumAlgorithm;

/// If `true`, enabled the mode which slightly decreases the scanning quality and the energy consumption, and increases the scanning speed. If `false` - mode is disabled. The default is `false`. Android only.
bool? lowPowerMode;

/// The color for barcodes count text
String? barcodesCountText;

/// The color for barcodes count text
Color? barcodesCountTextColor;

/// Text of the button which clears the list of scanned barcodes.
String? clearButtonTitle;

/// The color of Submit button
Color? detailsActionColor;

/// The color of bottom sheet
Color? detailsBackgroundColor;

/// The color of text elements in bottom sheet
Color? detailsPrimaryColor;

/// String being displayed on the delete button. iOS only.
String? deleteButtonTitle;

/// Title of the button that opens the screen where the user can allow the usage of the camera by the app.
String? enableCameraButtonTitle;

/// Text that will be displayed when the app is not allowed to use the camera, prompting the user to enable the usage of the camera.
String? enableCameraExplanationText;

/// The text for the data fetching state of the barcode item in a list. Smth "Fetching info…"
String? fetchingStateText;

/// Text of the message that there are no barcodes scanned
String? noBarcodesTitle;

/// Text of the button which finishes the flow
String? submitButtonTitle;

/// The expected density of QR codes in an image.
CodeDensity? codeDensity;

/// If `true`, replaces the cancel button in the top bar with a back arrow icon. The default value is FALSE. Android only.
bool? replaceCancelButtonWithIcon;

/// Preview mode of the camera. FILL_IN or FIT_IN. Default is FILL_IN. Android only
CameraPreviewMode? cameraPreviewMode;

/// Sets auto close timer in seconds. 0 = disabled and it is the default value. Android only
int? autoCancelTimeout;

/// Scanning delay after scanner appearance in seconds. Defaults to 0 secs.
double? initialScanDelay;

/// Display the region of interest. The default value is TRUE.
bool? viewFinderEnabled;

/// The selection overlay configuration.
SelectionOverlayConfiguration? overlayConfiguration;

Barcode Scanner Classic

Integration of Barcode Scanner Classic Components

Use the classes BarcodeScannerCamera, BarcodeCameraLiveDetector and ScanbotCameraController to build a custom scanner UI for Barcode and QR-Code scanning.

Create BarcodeCameraLiveDetector instance and attach it to BarcodeScannerCamera

BarcodeCameraLiveDetector provides the ability to subscribe to barcode scanning results with 2 callbacks:

  • barcodeListener - scanning results
  • errorListener - license errors
late BarcodeCameraLiveDetector barcodeCameraDetector;

...

barcodeCameraDetector = BarcodeCameraLiveDetector(
barcodeListener: (scanningResult) {
print(scanningResult.toJson().toString());
},
errorListener: (error) {
// Error listener will inform if there is a problem with the license when opening the screen.
print(error);
},
);
Add BarcodeScannerCamera to the widget tree
 ScanbotCameraController? controller;

...

BarcodeScannerCamera(
cameraDetector: barcodeCameraDetector,
configuration: BarcodeCameraConfiguration(
scannerConfiguration: BarcodeClassicScannerConfiguration(
barcodeFormats: [BarcodeFormat.QR_CODE],
engineMode: EngineMode.NextGen,
//barcodeImageGenerationType: BarcodeImageGenerationType.CAPTURED_IMAGE
...
),
finder: FinderConfiguration(),
onWidgetReady: (controller) {
// After the camera has initialized, you are able to control the camera parameters.
this.controller = controller;
}
...
),
...
)
BarcodeScannerCamera
final BarcodeCameraLiveDetector cameraDetector;

final BarcodeCameraConfiguration configuration;

final Function(ScanbotCameraController controller) onWidgetReady;

/// Triggers when the camera plugin needs to do some heavy processing eg. saving the snap as an image.
final Function(bool)? onHeavyOperationProcessing;
BarcodeCameraConfiguration
/// Controls whether the flash should be initially enabled.
/// The default value is FALSE.
bool? flashEnabled;

/// Set current zoom by a linear zoom value ranging from 0f to 1.0f. It maps to the range of real values of 1x-12x zoom.
/// If device os not supporting some part of this range the closest value will be taken.
/// Optical Zoom Level 0f represents the minimum zoom(1x) while Optical Zoom Level 1.0f represents the maximum zoom(12x).
/// Default value is 0f.
double? cameraZoomFactor;

/// Configuration of the finder window.
FinderConfiguration? finder;

/// Configuration of the barcode scanner detection behavior eg. which barcode types to detect etc.
BarcodeClassicScannerConfiguration scannerConfiguration;

///The configuration of AR selection overlay.
SelectionOverlayScannerConfiguration? overlayConfiguration;
FinderConfiguration
/// The rectangle that perforates the background and that will be presented as the finder.
BoxDecoration decoration;

/// This widget will be drawn on top of the finder.
/// Here you can add some custom design elements, for example, a QR code watermark.
Widget? widget;

/// Something that should be shown between the top of the finder and the camera view.
Widget? topWidget;

/// Something that should be shown between the bottom of the finder and the camera view.
Widget? bottomWidget;

/// The overlay background color, surrounding the finder view rectangle.
Color? backgroundColor;

/// The finder view rectangle aspect ratio.
FinderAspectRatio? finderAspectRatio;

/// The finder view minimum padding from the bounds of the screen.
double finderMinimumPadding;

/// Triggers when the finder area is changed.
/// Can be helpful when aligning some content on top of the finder.
final OnFinderRectChange? onFinderRectChange;
BarcodeClassicScannerConfiguration
/// List of accepted Barcode Formats; any formats that are not included in this
/// list will not be detected by the `BarcodeCameraView`. By default, the list
/// includes all supported barcode types.
List<BarcodeFormat> barcodeFormats;

/// List of accepted Document Formats; any document formats that are not included
/// in this list will be ignored by the `BarcodeCameraView`. By default, the list
/// includes all supported document types.
List<AcceptedDocumentFormats> acceptedDocumentFormats;

/// The engine mode of the barcode recognizer. Defaults to NEXT_GEN.
/// To use the legacy recognizer, please specify LEGACY.
EngineMode? engineMode;

/// Additional parameters for tweaking the detection of barcodes.
BarcodeAdditionalParameters? additionalParameters;

/// Parameter that handles whether we need to save the image from the video stream
/// or to capture a photo of the barcode.
/// Image uri will be returned in [BarcodeScanningResult.snappedImage] property.
BarcodeImageGenerationType barcodeImageGenerationType
SelectionOverlayConfiguration
/// Barcode Selection Overlay configuration
class SelectionOverlayScannerConfiguration {
/// Whether the barcode selection overlay is enabled or not.
bool overlayEnabled;

/// Whether to return results from barcodeLiveDetection callback or only proceed with manual click on barcode polygon
bool automaticSelectionEnabled;

/// Define the way of how to show barcode data with selection overlay.
BarcodeOverlayTextFormat textFormat;

/// The color of the polygon in the selection overlay.
Color? polygonColor = Colors.white;

/// The color of the text in the selection overlay.
Color? textColor = Colors.black;

/// The color of the texts background in the selection overlay.
Color? textContainerColor = Colors.white;

/// Callback that will be called when barcode on screen is clicked.
Function(BarcodeItem item)? onBarcodeClicked;
ScanbotCameraController

ScanbotCameraController provides the ability to control camera functionality:

  • isFlashAvailable - to check if the flashlight is available on the device.
  • setFlashEnabled - to enable the flashlight.

Want to scan longer than one minute?

Generate your free "no-strings-attached" Trial License and properly test the Scanbot SDK.

Get your free Trial License

What do you think of this documentation?