Class QrCode

Namespace: Net.Codecrete.QrCodeGenerator

Assembly: QrCodeGenerator.dll

Represents a QR code containing text or binary data.

QR codes are a type of two-dimensional barcodes, invented by Denso Wave and described in the ISO/IEC 18004 standard "QR code bar code symbology specification".

The data is represented as square grid of dark and light pixels (called modules by the QR code specification).

Depending on the amount of data, different sizes of the QR code are used. The QR code specification calls them version. Versions 1 (smallest) to 40 (largest) are available.

QR codes includes error correction data to ensure the QR code can be read despite difficult lighting conditions (e.g. reflections), dirt or partially covered pixels. Four error correction levels are available. The highest can recover about 30% of missing or damaged data.

A QR code instance can be converted to a PNG (ToPngBitmap(int, int, int, int)), SVG (ToSvgString(int, string, string)) or BMP ToBmpBitmap(int, int, int, int)) image. Or the QR code can be drawn or printed with custom code by either processing a list of rectangles covering the dark modules (ToRectangles()), or by querying the color of individual modules with GetModule(int, int).

public class QrCode

Inheritance: object

QrCode

Inherited Members: object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Remarks

To create a QR code instance, use one of the static factory methods:

For even more control about the QR code contents, first create the data segments and then use EncodeSegments(List<DataSegment>, Ecc, int, int, bool) to create the QR code.

Fields

MaxVersion

The maximum version (size) supported in the QR code standard – namely 40.

public const int MaxVersion = 40

Field Value

int: The maximum version.

MinVersion

The minimum version (size) supported in the QR code standard – namely 1.

public const int MinVersion = 1

Field Value

int: The minimum version.

Properties

ErrorCorrectionLevel

The error correction level used for this QR code.

public QrCode.Ecc ErrorCorrectionLevel { get; }

Property Value

QrCode.Ecc: The error correction level.

Mask

The index of the mask pattern used fort this QR code (between 0 and 7).

public int Mask { get; }

Property Value

int: The mask pattern index.

Size

The width and height of this QR code, in modules (pixels).

The size is a value between 21 and 177. This is equal to version × 4 + 17.

The size does not include the border. The QR code should be displayed or printed such that it has a light area around it, which is at least 4 pixels wide.

public int Size { get; }

Property Value

int: The QR code size.

Version

The version (size) of this QR code (between 1 for the smallest and 40 for the biggest).

public int Version { get; }

Property Value

int: The QR code version (size).

Methods

EncodeBinary(byte[], Ecc, bool)

Creates a QR code representing the specified binary data using the specified error correction level.

The smallest possible QR code version (size) is automatically chosen. The resulting ECC level will be higher than the one specified if it can be achieved without increasing the QR code size (version).

Unless omitEci is true, the QR code segments will start with an extended channel interpretation (ECI) code indicating binary data.

public static QrCode EncodeBinary(byte[] data, QrCode.Ecc ecl, bool omitEci = false)

Parameters

data byte[]: The binary data to encode.
ecl QrCode.Ecc: The minimum error correction level to use.
omitEci bool: If true, noe ECI is inserted to indicate binary data.

Returns

QrCode: A QR code representing the specified data.

Exceptions

ArgumentNullException: data is null.
DataTooLongException: The specified data is too long to fit in the largest QR code size (version) at the specified error correction level.

EncodeSegments(List<DataSegment>, Ecc, int, int, bool)

Creates a QR code representing the specified data segments.

The smallest possible QR code version (size) is used. The range of versions can be restricted by the minVersion and maxVersion parameters.

If boostEcl is true, the resulting ECC level will be higher than the one specified if it can be achieved without increasing the QR code size (version).

public static QrCode EncodeSegments(List<DataSegment> segments, QrCode.Ecc ecl, int minVersion = 1, int maxVersion = 40, bool boostEcl = true)

Parameters

segments List<DataSegment>: The segments to encode.
ecl QrCode.Ecc: The minimal or fixed error correction level to use .
minVersion int: The minimum version (size) of the QR code (between 1 and 40).
maxVersion int: The maximum version (size) of the QR code (between 1 and 40).
boostEcl bool: If true the ECC level wil be increased if it can be achieved without increasing the size (version).

Returns

QrCode: A QR code representing the segments.

Exceptions

ArgumentNullException: segments or any list element is null.
ArgumentOutOfRangeException: 1 ≤ minVersion ≤ maxVersion ≤ 40 is violated.
DataTooLongException: The segments are too long to fit in a QR code with the specified maximum size (version) and at the specified error correction level.

EncodeText(string, Ecc)

Creates a QR code representing the specified text using the specified error correction level.

public static QrCode EncodeText(string text, QrCode.Ecc ecl)

Parameters

text string: The text to be encoded.
ecl QrCode.Ecc: The minimum error correction level to use.

Returns

QrCode: A QR code instance representing the specified text.

Exceptions

ArgumentNullException: Thrown if text is null.
DataTooLongException: The text is too long to fit in the largest QR code size (version) at the specified error correction level.

EncodeTextAdvanced(string, Ecc, bool, int, int, ECI, Encoding, KanjiStrategy, EncodingInfo)

Creates a QR code representing the specified text.

This method offers several optional parameters to control the QR code creation.

The text will be embedded as a sequence of data segments using different modes. They are chosen such that the smallest number of bits is needed to represent the text.

If eci is null or Automatic, then Latin-1 / ISO-8859-1 character encoding is used if the text can be encoded without loss in this encoding. If so, no ECI segment is added. Otherwise, the text is encoded in UTF-8 and an ECI segment is added. The parameter encoding will be ignored.

If eci is None, then no ECI segment is added. The text will be encoded using the specified encoding. The parameter encoding is mandatory in this case.

In all other cases, the specified ECI segment is added. The text is encoded using the specified encoding. If encoding is null, then the encoding is derived from eci.

kanjiStrategy controls if Kanji mode is considered for encoding data segments. For the best compatibility, it should only be used if the text is encoded in Shift-JIS.

[SuppressMessage("csharpsquid", "S107")]
public static QrCode EncodeTextAdvanced(string text, QrCode.Ecc minimumEcl, bool boostEcl = true, int minVersion = 1, int maxVersion = 40, ECI eci = null, Encoding encoding = null, KanjiStrategy kanjiStrategy = KanjiStrategy.Automatic, EncodingInfo encodingInfo = null)

Parameters

text string: The text to encode.
minimumEcl QrCode.Ecc: The minimal error correction level.
boostEcl bool: If true, the error correction level will be increased if it is possible without increasing the QR code size. If false, the minimal error correction level will be used.
minVersion int: The minimal QR code version to consider.
maxVersion int: The maximal QR code version to consider.
eci ECI: The extended character set indicator segment to add, or null if it should be automatically determined.
encoding Encoding: The character set encoding to use, or null if it should be derived from the ECI.
kanjiStrategy KanjiStrategy: Controls if Kanji mode is used for data segments.
encodingInfo EncodingInfo: If an instance is provided, it will be filled with information about the QR code encoding. Collecting the encoding information will slow down the QR code generation.

Returns

QrCode: A QR code instance representing the specified text.

Remarks

Most encodings other than Latin-1 / ISO-8859-1 and the UTF encodings require that the encoding is registered (except for .NET Framework 4.x), typically using:

Encoding.RegisterProvider(CodePagesEncodingProvider.Instance);

Exceptions

ArgumentNullException: Thrown if text is null.
ArgumentOutOfRangeException: 1 ≤ minVersion ≤ maxVersion ≤ 40 is violated.
DataTooLongException: The text is too long to fit into a QR code of the specified maximum size (version).

EncodeTextInMultipleCodes(string, Ecc, int)

Creates multiple QR codes representing the specified text.

The result will consist of the minimal number of QR codes needed to encode the text with the given error correction level and version (size of QR code). If multiple QR codes are required, Structured Append data is included to link the QR codes.

If the text can be losslessly encoded in Latin-1, the encoding will be used and no extended channel indicators (ECI) will be added as Latin-1 is the default QR code text encoding. Otherwise, the text will be encoded in UTF-8, and the required ECI will be added to each QR code.

UTF-8 text will be split just that the splits are at character boundaries and not in the middle of a multibyte encoding of a character. Even though this is not explicitly mandated by the QR code specification, it increases compatibility with QR code scanners.

public static List<QrCode> EncodeTextInMultipleCodes(string text, QrCode.Ecc ecl, int version = 29)

Parameters

text string: The text to be encoded. The full range of Unicode characters may be used.
ecl QrCode.Ecc: The minimum error correction level to use.
version int: The version (size of QR code) to use. Default is 29.

Returns

List<QrCode>: A list of QR codes representing the specified text.

Exceptions

ArgumentNullException: text is null.
DataTooLongException: The text is too long to fit the maximum of 16 QR codes with the given parameters.

GetModule(int, int)

Gets the color of the module (pixel) at the specified coordinates.

The top left corner has the coordinates (x=0, y=0). x-coordinates extend from left to right, y-coordinates extend from top to bottom.

If coordinates outside the bounds of this QR code are specified, light (false) is returned.

public bool GetModule(int x, int y)

Parameters

x int: The x coordinate.
y int: The y coordinate.

Returns

bool: The color of the specified module: true for dark modules and false for light modules (or if the coordinates are outside the bounds).

RgbColor(byte, byte, byte)

Creates an RGB color value in little endian format.

public static int RgbColor(byte red, byte green, byte blue)

Parameters

red byte: Red component.
green byte: Green component.
blue byte: Blue component.

Returns

int: RGB color value

ToBmpBitmap(int, int, int, int)

Creates a bitmap in the BMP format.

The bitmap uses 1 bit per pixel and a color table with 2 entries.

Color values can be created with RgbColor(byte, byte, byte).

public byte[] ToBmpBitmap(int border = 0, int scale = 1, int foreground = 0, int background = 16777215)

Parameters

border int: The border width, as a factor of the module (QR code pixel) size. Defaults to 0.
scale int: The width and height, in pixels, of each module. Defaults to 1.
foreground int: The foreground color (dark modules), in RGB value (little endian). Defaults to black.
background int: The background color (light modules), in RGB value (little endian). Defaults to white.

Returns

byte[]: Bitmap data

Exceptions

ArgumentOutOfRangeException: Thrown if border is negative, scale is less than 1 or the resulting image is wider than 32,768 pixels.

ToGraphicsPath(int)

Creates a graphics path of this QR code valid in SVG or XAML.

The graphics path uses a coordinate system where each module is 1 unit wide and tall, and the top left module is offset vertically and horizontally by border units.

Note that a border width other than 0 only make sense if the bounding box of the QR code is explicitly set by the graphics using this path. If the bounding box of this path is automatically derived, at least the right and bottom border will be missing.

The path will look like this: M3,3h7v1h-7z M12,3h1v4h-1z ... M70,71h1v1h-1z. It is valid for SVG (<path d="M3,3h..." />) and for XAML (<Path Data="M3,3h..." />). For programmatic geometry creation in WPF see Geometry.Parse(String).

public string ToGraphicsPath(int border = 0)

Parameters

border int: The border width, as a factor of the module (QR code pixel) size

Returns

string: The graphics path

Exceptions

ArgumentOutOfRangeException: Thrown if border is negative

ToPngBitmap(int, int, int, int)

Creates bitmap in the PNG format data using specified foreground and background colors for dark and light modules.

public byte[] ToPngBitmap(int border = 0, int scale = 1, int foreground = 0, int background = 16777215)

Parameters

border int: The border width, as a factor of the module (QR code pixel) size. Defaults to 0.
scale int: The width and height, in pixels, of each module. Defaults to 1.
foreground int: The foreground color (dark modules), in RGB value (little endian). Defaults to black.
background int: The background color (light modules), in RGB value (little endian). Defaults to white.

Returns

byte[]: Bitmap data

ToRectangles()

Gets the dark modules of this QR code as a list of rectangles.

Adjacent dark modules are merged into larger rectangles so that most rectangles cover more than a single module, reducing the number of shapes to draw. This is the same set of rectangles used internally to render SVG and XAML output.

The rectangles use the same coordinate system as GetModule(int, int): the top-left module is at (x=0, y=0) and each unit is one module (no border is included).

The rectangles are non-overlapping and their union is exactly the set of dark modules. The order in which the rectangles appear in the list is unspecified.

This method is intended for rendering the QR code to graphics formats that are not directly supported by this library.

public IReadOnlyList<QrRectangle> ToRectangles()

Returns

IReadOnlyList<QrRectangle>: The list of rectangles covering the dark modules.

See Also: QrRectangle

ToSvgString(int, string, string)

Creates an SVG image of this QR code.

The image uses Unix newlines (\n), regardless of the platform.

Colors are specified using CSS color data type. Examples of valid values are "#339966", "fuchsia", "rgba(137, 23, 89, 0.3)".

public string ToSvgString(int border, string foreground = "#000000", string background = "#ffffff")

Parameters

border int: The border width, as a factor of the module (QR code pixel) size.
foreground string: The foreground color. Defaults to black.
background string: The background color. Defaults to white.

Returns

string

Table of Contents

Class QrCode

Remarks

Fields

MaxVersion

Field Value

MinVersion

Field Value

Properties

ErrorCorrectionLevel

Property Value

Mask

Property Value

Size

Property Value

Version

Property Value

Methods

EncodeBinary(byte[], Ecc, bool)

Parameters

Returns

Exceptions

EncodeSegments(List<DataSegment>, Ecc, int, int, bool)

Parameters

Returns

Exceptions

EncodeText(string, Ecc)

Parameters

Returns

Exceptions

EncodeTextAdvanced(string, Ecc, bool, int, int, ECI, Encoding, KanjiStrategy, EncodingInfo)

Parameters

Returns

Remarks

Exceptions

EncodeTextInMultipleCodes(string, Ecc, int)

Parameters

Returns

Exceptions

GetModule(int, int)

Parameters

Returns

RgbColor(byte, byte, byte)

Parameters

Returns

ToBmpBitmap(int, int, int, int)

Parameters

Returns

Exceptions

ToGraphicsPath(int)

Parameters

Returns

Exceptions

ToPngBitmap(int, int, int, int)

Parameters

Returns

ToRectangles()

Returns

ToSvgString(int, string, string)

Parameters

Returns

See Also