README.md

qzxing

Qt/QML wrapper library for the ZXing barcode image processing library.

Supports barcode decoding for the following types:

• UPC-A
• UPC-E
• EAN-8
• EAN-13
• ITF
• Code 39
• Code 93
• Code 128 (GS1)
• Codabar
• QR Code
• Data Matrix
• Aztec (beta)
• PDF 417

Supports barcode encoding for the following types:

• QR Code

Table of contents

1. How to include
   1. Embed the source code
   2. Compile the project as an external library
   3. Control dependencies
      1. QZXing (core)
      2. QZXing (core + QML)
      3. QZXing + QZXingFilter
2. How to use
   1. Decoding operation
      1. C++/Qt
      2. Qt Quick
   2. Encoding operation
      1. C++/Qt
      2. Qt Quick
   3. Encoded text format Information
3. Unit test dependency
4. Qt 6 limitations
5. Contact

How to include

The project can be used in two ways:

Embed the source code.

Copy source code folder of QZXing to the root of your project. Add the following line to your .pro file. For more information see here.

include(QZXing/QZXing.pri)

Compile the project as an external library

Open QZXing project (QZXing.pro) and compile. If it is needed to compile as static library, uncomment the following line in the .pro file.

CONFIG += staticlib

Control dependencies

Project file config tags are now introduced to be able to control the dependencies of the library accoring to the needs. The core part requires only "core" and "gui" Qt modules. Though for backward compatibility "quick" Qt module is also required. The 3 level of dependencies are:

QZXing (core)

By including QZXing.pri or by building QZXing.pro you get the core functionality of QZXing which requires only QtCore and QtGui (because of QImage).

Warning! The initial default configuration till 20/03/2017 was including qzxing_qml. This tag could not be removed once added, so it was needed to be removed from the defaults.

QZXing (core + QML)

If an application is going to use QML functionality, it is now possible to add the dependency to it. This can be done by adding the folloing line to the .pro file of its project:

CONFIG += qzxing_qml

QZXing + QZXingFilter

QZXing includes QZXingFilter, an implementation to provide live feed to the decoding library. It automatically includes QML implementation as well. This option requires "multimedia" Qt module this is why it is considered as a separate configuration. It can be used by adding the following line to the .pro file of a project:

CONFIG += qzxing_multimedia

For examples on how to use QZXingFilter, it is advised to see QZXingLive example project. For Qt 5.x versions check main.qml file, whereas for Qt 6.2 (or newer) check main_qt6_2.qml.

(Pending task: a wiki page should be written to better explain the usage of the QZXingFilter component)

How to use

Follows simple code snippets that briefly show the use of the library. For more details advise the examples included in the repository and the wiki.

Decoding operation

C++/Qt

#include "QZXing.h"

int main()
{
	QImage imageToDecode("file.png");
	QZXing decoder;
        //mandatory settings
	decoder.setDecoder( DecoderFormat_QR_CODE | DecoderFormat_EAN_13 );

        //optional settings
        //decoder.setSourceFilterType(QZXing::SourceFilter_ImageNormal | QZXing::SourceFilter_ImageInverted);
        decoder.setSourceFilterType(QZXing::SourceFilter_ImageNormal);
        decoder.setTryHarderBehaviour(QZXing::TryHarderBehaviour_ThoroughScanning | QZXing::TryHarderBehaviour_Rotate);

        //trigger decode
	QString result = decoder.decodeImage(imageToDecode);
}

Qt Quick

First register QZXing type to the QML engine.

#include "QZXing.h"

int main()
{
	...
	QZXing::registerQMLTypes();
	...
}

The in the QML file

import QZXing 3.3

function decode(preview) {
	imageToDecode.source = preview
	decoder.decodeImageQML(imageToDecode);
}

Image{
	id:imageToDecode
}

QZXing{
	id: decoder

	enabledDecoders: QZXing.DecoderFormat_QR_CODE

        /////////////
        //optional
        tryHarderType: QZXing.TryHarderBehaviour_ThoroughScanning | QZXing.TryHarderBehaviour_Rotate

        imageSourceFilter: QZXing.SourceFilter_ImageNormal //| QZXing.SourceFilter_ImageInverted
        /////////////

	onDecodingStarted: console.log("Decoding of image started...")

	onTagFound: console.log("Barcode data: " + tag)

	onDecodingFinished: console.log("Decoding finished " + (succeeded==true ? "successfully" :    "unsuccessfully") )
}

Encoding operation

To begin with, make sure the Encoder feature is enabled. If QZXing.pri is used, then the feature is already enabled. If your project uses QZXing-compoents.pri instead, do add the following CONFIG in your .pro file:

CONFIG += enable_encoder_qr_code

include(QZXing/QZXing-components.pri)

C++/Qt

The encoding function has been written as static as it does not have any dependencies to data other than the ones provided by the arguments.

Use the encoding function with its default settings:

• Format: QR Code
• Size: 240x240
• Error Correction Level: Low (L)

#include "QZXing.h"

int main()
{
    QString data = "text to be encoded";
    QImage barcode = QZXing::encodeData(data);
}

Or use the encoding function with custom settings:

QString data = "text to be encoded";
QImage barcode = QZXing::encodeData(data, QZXing::EncoderFormat_QR_CODE,
								QSize(width.toInt(), height.toInt()), QZXing::EncodeErrorCorrectionLevel_H);

Qt Quick

The encoding function can be easily used in QML through QZXing's Image Provider: "image://QZXing/encode/<data_to_be_encoded>". As with the C++ example, it can either be used with the default settings or with custom settings.

First register the custom Image Provider in the main.cpp:

QQmlApplicationEngine engine;

QZXing::registerQMLTypes();
QZXing::registerQMLImageProvider(engine);

Default settings:

import QZXing 3.3

TextField {
	id: inputField
	text: "Hello world!"
}

Image{
	source: "image://QZXing/encode/" + inputField.text;
	cache: false;
}

Or use the encoding function with the optional custom settings that are passed like URL query parameters:

attribute name	value	description
border	true, false	image has border (white 1px)
correctionLevel	L, M, Q, H	the error correction level
format	qrcode	the encode formatter. Currently only QR Code.
transparent	true, false	whether the black pixels are transparent
explicitSize	int	if provided, it will be the size of the Qr rectangle

the size of the image can be adjusted by using the Image.sourceWidth and Image.sourceHeight properties of Image QML element.

import QZXing 3.3

TextField {
	id: inputField
	text: "Hello world!"
}

Image{
	source: "image://QZXing/encode/" + inputField.text +
					"?correctionLevel=M" +
					"&format=qrcode"
	sourceSize.width: 320
	sourceSize.height: 320
}

Encoded text format Information

Here is a list of contents that have been encoded and tested to be recognizable by the Android ZXing decoding application: QR Code encoding wiki page

Unit test dependency

In order to run Unit tests in /test folder, the git submodule containing the test resoucres needs to be initialized and/or updated:

cd qzxing
git submodule update --init --recursive

Qt 6 limitations

On Qt 6, a number of modules have been removed or not yet supported. The list of removed modules includes two important features that directly affect QZXing:

Text codecs

QZXing used QTextCodec to re-interpret the parsed strings into their proper encoding. In Qt6, QTextCodec has been moved to core5compat module. After testing, it seems that QTextCodec, if used through core5compat in Qt 6, it does not support many of the encoding that it did in Qt 5 (for instance, Shift-JIS encoding). To avoid the dependency of an extra module (that also does not work as supposed to), QTextCodec has been replaced by QStringDecoder only when building for Qt 6. If QZXing if build for Qt 5, QTextCodec is used as it was.

Contact

In case of bug reports or feature requests feel free to open an issue.