Skip to content

Upgrading from 3.x ​

4.0 replaces the engine and adds a new API next to the old one. Nothing has to change on the day you upgrade: the 3.x API (zx, Code, DecodeParams, ReaderWidget, WriterWidget…) still works, on the new engine, and is deprecated until its removal in 5.0. Each deprecated declaration names its replacement, so the analyzer's hints are a to-do list.

This page shows the replacements side by side. Coming from an earlier 4.0 release candidate: see From 4.0.0-rc.2.

Upgrading ​

  1. Raise the constraint in pubspec.yaml. 4.0 needs Flutter 3.41 and Dart 3.11 or newer.

    yaml
    dependencies:
      flutter_zxing: ^4.0.0-rc.4
  2. Run flutter clean once. The CMake, CocoaPods, Swift Package Manager and Gradle builds of 3.x are gone: the package's build hook compiles zxing-cpp for Android, iOS, macOS, Linux and Windows, so the first build takes longer than the next ones.

  3. Build and run. Your 3.x code keeps working; the CHANGELOG lists the few behaviour changes: image files are read on a background isolate and at full resolution, and barcodes are created with zxing-cpp's newer creator.

The 3.x API is not available on the web. The new API is, with the same engine compiled to WebAssembly. New code imports package:flutter_zxing/scanner.dart; flutter_zxing.dart adds the 3.x API to it.

At a glance ​

3.x4.0
ReaderWidget(onScan: ...)BarcodeScanner(onDetect: ...)
ReaderWidget(isMultiScan: true, onMultiScan: ...)BarcodeScanner with ScannerController(maxBarcodes: null, detection: DetectionMode.continuous), then capture.barcodes
WriterWidgetBarcodeView
zx.readBarcodeImagePath(file, params)BarcodeReader().read(await file.readAsBytes())
zx.readBarcodesImagePath(file, params)BarcodeReader().readAll(...)
zx.readBarcode(pixels, params)BarcodeReader().readPixels(PixelBuffer(...))
zx.processCameraImage(image, params)ScannerController, or readPixels
zx.encodeBarcode(contents: ..., params: ...)BarcodeWriter(format).toPng(...), .toSvg(...), .toImage(...) or .encode(...); with a style, style.encodePng(writer, ...)
Code / CodesBarcode / List<Barcode>
Format.qrCode | Format.ean13 (an int bit mask){BarcodeFormat.qrCode, BarcodeFormat.ean13}
DecodeParamsReaderOptions and formats
EncodeParams, EccLevelBarcodeWriter parameters, ErrorCorrection
PositionBarcodePosition
zx.version()zxingCppVersion

Everything in the new API that touches the engine returns a Future and runs off the UI thread; there is no init() or dispose() except on the camera controller.

Scanning with the camera ​

dart
// 3.x
ReaderWidget(
  codeFormat: Format.qrCode | Format.ean13,
  tryHarder: true,
  onScan: (Code code) => print(code.text),
)
dart
// 4.0: the controller is a field of your State, disposed with it
final ScannerController controller = ScannerController(
  formats: {BarcodeFormat.qrCode, BarcodeFormat.ean13},
);

@override
void dispose() {
  controller.dispose();
  super.dispose();
}

@override
Widget build(BuildContext context) => BarcodeScanner(
  controller: controller,
  onDetect: (BarcodeCapture capture) => print(capture.barcode.text),
);

Create the controller once, not in build: a new controller on every rebuild restarts the camera. A controller you create is yours to dispose(). It lets you change formats, options, scanWindow and detection while the camera runs, and controls the torch, zoom, focus and camera (setTorch, setZoom, setFocusPoint, switchCamera).

Without a controller, BarcodeScanner creates and disposes its own. With a template, it takes the template's formats: BarcodeScanner(template: const ScannerTemplate.minimal(formats: {BarcodeFormat.qrCode})). A template is a whole screen, not only settings: most templates read one code, pause and show a sheet with it. For ReaderWidget's behaviour, where scanning goes on and onScan gets each code, pass a controller and no template.

As with ReaderWidget, the camera stops while the app is in the background and starts again when it returns (ScannerController(stopInBackground:)).

The camera preset, ReaderOptions.camera(), already turns on tryHarder and tryRotate, so most 3.x scanner settings have no counterpart to set.

ReaderWidget4.0
codeFormatScannerController(formats:)
tryHarder, tryInverted, tryRotate, tryDownscaleScannerController(options: ReaderOptions.camera().copyWith(...)): plain ReaderOptions() is the preset for files, with tryInvert on
cropPercent, horizontalCropOffset, verticalCropOffsetScannerController(scanWindow: ScanWindow.centered(...)) or ScanWindow.fromRect(...)
scanDelay, scanDelaySuccessScannerController(detection: DetectionMode.distinct) (each code once, again after it has left the frame), .continuous or .once
maxNumberOfSymbols, isMultiScanScannerController(maxBarcodes:): 1 by default, null for all
resolutionScannerController(resolution: CameraResolution.hd)
lensDirectionScannerController(facing: CameraFacing.back)
Torch on at the startScannerController(torch: true)
Zoom at the startScannerController(initialZoom: 2)
allowPinchZoomBarcodeScanner(pinchToZoom:)
onScanFailureNot needed: frames without a code report nothing
onControllerCreatedPass your own ScannerController
scannerOverlay, showScannerOverlayBarcodeScanner(template:, theme:), or your own overlayBuilder:
showFlashlight, showToggleCamera, showGalleryButtons of the template (torchButton, switchCameraButton, photoButton)
loadingBarcodeScanner(placeholderBuilder:); ScannerPlaceholder by default
Camera errors in the logBarcodeScanner(errorBuilder:) with a typed ScannerException

A ready-made screen ​

ReaderWidget drew its own buttons and overlay. In 4.0 a template draws a whole scanner screen, in your colours:

dart
BarcodeScanner(
  template: const ScannerTemplate.minimal(),
  theme: const ScannerTheme(
    accent: Color(0xFFFF6A1A),
    buttonShape: ScannerButtonShape.roundedSquare,
  ),
)

See A ready-made screen for the 16 templates, their modes, checks and result sheets.

Several codes at once ​

dart
// 3.x
ReaderWidget(
  isMultiScan: true,
  onMultiScan: (Codes codes) => print(codes.codes.length),
)
dart
// 4.0, the controller a field of your State: every code in each frame
final controller = ScannerController(
  maxBarcodes: null,
  detection: DetectionMode.continuous,
);

Widget scanner() => BarcodeScanner(
  controller: controller,
  onDetect: (BarcodeCapture capture) {
    for (final Barcode barcode in capture.barcodes) {
      print(barcode.text);
    }
  },
);

As with onMultiScan, DetectionMode.continuous reports all the codes in view on every frame. With the default DetectionMode.distinct, capture.barcodes holds only the codes that are new in the frame: each code once, again after it has left the frame.

One code, then back ​

New in 4.0, for the common "scan and return" flow:

dart
final Barcode? barcode = await scanBarcode(
  context,
  formats: {BarcodeFormat.qrCode},
);

Reading image files ​

dart
// 3.x
final Code code = await zx.readBarcodeImagePath(file, DecodeParams());
final Codes codes = await zx.readBarcodesImagePath(file, DecodeParams());
dart
// 4.0
Future<void> read(File file) async {
  final Uint8List bytes = await file.readAsBytes();
  final Barcode? barcode = await const BarcodeReader().read(bytes);
  final List<Barcode> barcodes = await const BarcodeReader().readAll(bytes);
  print('${barcode?.text}, ${barcodes.length}');
}

JPEG, PNG, GIF and BMP files are decoded by the engine, and WebP and the other formats Flutter decodes are read too. "Not found" is null (or an empty list), not a Code with isValid == false; a file that is not an image throws ImageDecodeException. TIFF, TGA, PSD, PNM, EXR and the other formats 3.x read through package:image are not decoded: decode them yourself (for example with package:image) and pass the pixels to readPixels. 3.x applied cropLeft, cropTop, cropWidth and cropHeight to image files too; 4.0 (and the 3.x API in it) reads files whole, so crop the pixels with PixelBuffer(crop:) instead.

readBarcodeImageUrl has no counterpart: download the bytes with your HTTP client and pass them to read.

Reading raw pixels ​

dart
// 3.x
final Code code = zx.readBarcode(
  gray,
  DecodeParams(width: width, height: height, imageFormat: ImageFormat.lum),
);
dart
// 4.0
Future<Barcode?> read(Uint8List gray, int width, int height) =>
    const BarcodeReader().readPixels(
      PixelBuffer(
        gray,
        width: width,
        height: height,
        crop: const Rect.fromLTWH(100, 100, 400, 300), // 3.x: cropLeft…
      ),
    );

PixelBuffer takes layout (PixelLayout.luminance, rgb, rgba, bgra), rowStride for padded rows, and crop for the part of the image to read.

Reader options ​

dart
const BarcodeReader reader = BarcodeReader(
  formats: {BarcodeFormat.dataMatrix},
  options: ReaderOptions(tryHarder: true, tryInvert: true),
);
DecodeParams4.0
formatBarcodeReader(formats:); null reads every format
tryHarder, tryRotate, tryDownscaleReaderOptions fields of the same name, all on by default (3.x: tryHarder and tryDownscale off)
tryInvertedReaderOptions(tryInvert:), on by default (3.x: off)
maxNumberOfSymbolsreadAll(maxBarcodes:); read returns the first
maxSizeNot needed: images are read at full resolution, tryDownscale handles large ones
imageFormat, width, height, crop...PixelBuffer
isMultiScanread versus readAll

See Reader options for the rest.

The result: Code → Barcode ​

CodeBarcode
texttext (never null)
rawBytesbytes
format (int)format (BarcodeFormat, with displayName)
isValid, errorisValid, error (BarcodeError with a kind); invalid codes appear only with ReaderOptions(returnErrors: true)
positionposition (BarcodePosition: four corners, bounds, center)
isInverted, isMirroredisInverted, isMirrored
durationMeasure it around the call if you need it
imageBytes, imageWidth, imageHeightNo counterpart

New in Barcode: content (What is in a code), rotation, ecLevel, version, symbologyIdentifier, contentType and sequence (structured append; join the parts with await reader.merge(parts)).

Generating barcodes ​

dart
// 3.x
final Encode result = zx.encodeBarcode(
  contents: 'https://pub.dev',
  params: EncodeParams(format: Format.qrCode, width: 300, height: 300),
);
dart
// 4.0
Future<void> generate() async {
  const BarcodeWriter writer = BarcodeWriter(BarcodeFormat.qrCode);
  final Uint8List png = await writer.toPng('https://pub.dev', size: 300);
  final String svg = await writer.toSvg('https://pub.dev');

  // With the look of the code on screen:
  const BarcodeStyle style = BarcodeStyle(moduleShape: ModuleShape.rounded);
  final Uint8List styled = await style.encodePng(writer, 'https://pub.dev', size: 300);
  print('${png.length} ${svg.length} ${styled.length}');
}

writer.toImage(...) gives the plain grayscale pixels. writer.encode(text) and writer.encodeBytes(bytes) return a BarcodeSymbol: the module matrix, its quiet zone and the human readable text, for your own rendering. Data that cannot be encoded, such as letters in an EAN-13, throws BarcodeWriteException.

EncodeParams4.0
formatBarcodeWriter(format)
width, heighttoPng(size:) or toPng(moduleSize:); BarcodeView(width:, height:)
marginThe quiet zone the symbology requires, or none: BarcodeStyle(quietZone:), or toPng(quietZone: false)
eccLevelBarcodeWriter(errorCorrection: ErrorCorrection.high); without it, QR codes get M (3.x wrote zxing-cpp's L)

In a widget: WriterWidget → BarcodeView ​

WriterWidget was a form for typing text and creating a code. Its replacement shows a code:

dart
const BarcodeView(
  'https://pub.dev',
  width: 200,
  style: BarcodeStyle(moduleShape: ModuleShape.rounded),
)

See Barcodes as widgets and Styles and logos.

Formats ​

Format was a set of int bit flags combined with |. BarcodeFormat is an enum; pass a Set where several are allowed. A base symbology includes its variants: {BarcodeFormat.qrCode} also finds Micro QR and rMQR codes.

UPC-A and UPC-E are reported as printed: a UPC-A as BarcodeFormat.upcA with 12 digits (3.x gave an EAN-13 starting with 0), a UPC-E with its 8 digits (3.x gave 13). Asking for EAN-13 alone still gives EAN-13.

3.x4.0
Format.anynull (all formats)
Format.qrCode | Format.ean13{BarcodeFormat.qrCode, BarcodeFormat.ean13}
Format.linearCodesBarcodeFormat.linear
Format.matrixCodesBarcodeFormat.matrix
zx.barcodeFormatName(format)format.displayName

From 4.0.0-rc.2 ​

The API changed in a few places before the release. The analyzer finds each of them; this table gives the new form.

rc.2Now
BarcodeView(data, format:, errorCorrection:, gs1:, showText:)BarcodeView(data, writer: BarcodeWriter(format, errorCorrection:, gs1:, showText:))
BarcodeWriter(quietZone: false)BarcodeStyle(quietZone: false), or symbol.toPng(quietZone: false)
BarcodeWriter(options: 'ecLevel=H')BarcodeWriter(zxingOptions: 'ecLevel=H'); it wins over errorCorrection and version
symbol.toSvg(): one unit per moduletoSvg(size:, moduleSize:) in pixels, 4 per module by default; toPng(size:) is the exact long side
showText: false by defaultnull: on for EAN, UPC and ISBN
reader.readAll(bytes, limit: 5)reader.readAll(bytes, maxBarcodes: 5), also readAllPixels
Barcode.merge(parts)await reader.merge(parts)
barcode.orientationbarcode.rotation
format.input.digitsformat.input.digitsOnly
formats: {} read every formatthrows ArgumentError; null reads every format
formats: {BarcodeFormat.isbn}, ean2, ean5ean13; add-ons with ReaderOptions(eanAddOn:)
style.copyWith(logo: null) kept the logostyle.copyWith(logo: () => null) removes it
template.copyWith(title: 'Pay')template.copyWith(title: () => 'Pay')
template.copyWith(onClose: () {})template.copyWith(onClose: () => () {}); () {} alone does not compile, and onClose and onOpenSettings cannot be cleared
ScannerController(pauseInBackground:)ScannerController(stopInBackground:)
resultBuilder: (context, barcode, scanAgain) => ...resultBuilder: (context, result) => ..., with result.barcode, result.scanAgain
actionsBuilder: (context, barcode, scanAgain) => [...]actionsBuilder: (context, result) => [...result.defaultActions, ...]
BarcodeResultSheet(showIcon:, showPicture:, asCard:)BarcodeResultSheet(header: ResultHeader.icon), .picture, .card or .none
ScannerTemplate(showResultIcon:, resultAsCard:)ScannerTemplate(resultHeader:)
ScannerChip(danger: true), ScannerBadge(warning: true)ScannerChip(tone: ScannerTone.danger), ScannerBadge(tone: ScannerTone.warning)
ScanStatus.accepted, warning, rejected; verdict.statusScanVerdictKind.accept, warn, reject; verdict.kind
BarcodeContent.parse(barcode)barcode.content
expiry, bestBefore, birthday, dateOfBirthexpiryDate, bestBeforeDate, birthDate
EpcPaymentContent(text:)EpcPaymentContent(message:)
SwissQrBillContent(referenceType:, qrReference:)SwissQrBillContent(creditorReference:); the type follows from it
ProductContent.gtin as printedProductContent.number; gtin is a GTIN-14
CryptoContent.amount in wei (Ethereum)amount in ether; wei in value
An exhaustive switch on BarcodeContentadd a default: new kinds come in minor versions

Behaviour that changed without a compile error:

  • barcode.rotation of camera captures is in screen orientation, like the corners.
  • Images over 128 megapixels or 65535 pixels a side throw ImageDecodeException; a PixelBuffer.crop outside the image finds nothing.
  • zxingOptions that zxing-cpp cannot parse throw ArgumentError.
  • Phone numbers with letters, EPC codes with a wrong RF reference and SPAYD codes with a wrong CRC32 are TextContent; contacts keep only http and https web addresses.