WT 0.3 Manual

Table of Contents

1. Overview

WT is a JavaScript QR Code encoding library. It differs from most other libraries in that it provides low-level functionality, rather than abstract data types -- users may select whichever versions, encodings, and headers they feel suit their needs -- or rely on the built-in selection algorithms to choose for them. WT was also written from the ground up in JavaScript, rather than being ported from another language.

Most modes are supported, with the exceptions of Structured Append and Kanji modes.

2. Installation

2.1. Downloading

The current version of WT can always be downloaded in minified form from the project website. Also available from the website is the current git repository for the project. WT does not require any third-party libraries to function.

2.2. Installing

Installing the WT library in your page is much like installing any other library. Simply drop the minified wt.js somewhere relative to your page, and insert a script tag into your page: <script type="text/javascript" src="wt.js"></script> Adjust the src attribute as necessary.

3. Usage

QR Code objects must be initialized in a certain order. For example: var qr = new QRCode(); qr.setVersion(0, QR__EC.M); qr.setData([{ mode: QR__Mode.ECI, data: 26 }, { mode: QR__Mode.smart, data: 'Hello, world!'}]); qr.drawSymbol(); drawQRToCanvas(qr, document.getElementById("MyCanvas"), 8); This code will draw a QR Code representing the text "Hello, world!" with UTF-8 encoding. After the object is created, the setVersion() and setData() methods must be called first in order to tell the object what kind of symbol it is drawing. Then, the drawSymbol() method will generate the symbol. Finally, the drawQRToCanvas() function will draw the QR code to a given HTML5 canvas object. It is also possible to draw to a div, using the drawQRToDiv() function.

It is preferrable to use the HTML5 canvas element when it is available. In order to determine if it is available, one can use the following code: if (typeof document.getElementById("MyCanvas").getContext === 'undefined') { drawQRToDiv(qr, document.getElementById("MyDiv"), 8); } else { drawQRToCanvas(qr, document.getElementById("MyCanvas"), 8); }

Enterprising users will find that after qr.drawSymbol() is called, the integer variable qr.dim contains the dimension (width/height, both of which are the same) of the QR code, and the array variable qr.data is a linear array of booleans representing the finalized symbol, such that qr.data[y * qr.dim + x] will yield the value at position (x, y) in the symbol, with true representing a black module, and false representing a white module.

4. User function documentation

4.1. Class QRCode

This is the primary class used by the library.

4.1.1. QRCode()

This constructor function creates a QR code object. It takes no arguments. var qr = new QRCode();

4.1.2. QRCode.setVersion(ver, ec)

This method of the QRCode class sets the version of a QR Code object.

The ver argument sets the version of the QR code. This may be set explicitly in the range 1 to 40. Alternatively, it may be set to 0, which will result in the lowest possible version being selected automatically.

The ec argument sets the error correction level of the QR Code. Valid values are:

qr.setVersion(0, QR__EC.M);

4.1.3. QRCode.setData(data)

This method of the QRCode class sets the data represented by the symbol.

The data argument is an array containing objects representing data segments and their encodings: [ { mode: QR__Mode.ECI, data: 26 }, { mode: QR__Mode.eightBit, data: 'Hello, world!' }, { mode: QR__Mode.num, data: '1234567890' }, ... ]

Available data encodings are:

qr.setData([ { mode: QR__Mode.ECI, data: 26 }, { mode: QR__Mode.smart, data: 'Hello, world!'} ]);

4.1.4. QRCode.drawSymbol()

This method of the QR code class constructs the symbol. It must only be called after QRCode.setVersion() and QRCode.setData() have been called. It takes no arguments.

Please note that the method used by this function to select a mask is not compliant with the ISO standard. A less complex, computationally cheaper method is used. Support for strict masking will be added in the future.

qr.drawSymbol();

4.1.5. QRCode.maskMethod

This variable defines the method used to select a mask pattern for the QR Code. In brief, this is a potentially very computationally expensive procedure that may or may not make your QR Code more likely to be successfully scanned. Valid values are:

qr.maskMethod = QR__MaskMethod.Canonical;

4.2. drawQRToCanvas(qr, canvas, scale, bgcolor, fgcolor)

This function draws a QR code to an HTML5 canvas.

The qr argument is a QRCode object. This object must have had the QRCode.drawSymbol() method previously called, so that the symbol has been constructed.

The canvas argument is an HTML5 canvas object. This object must exist -- make sure the window has been fully loaded and the object has been created before attempting to call this function.

The optional scale argument is the drawing scale. This value decides how many pixels wide each module will be, per side.

The optional bgcolor and fgcolor arguments define the background and foreground colors of the QR Code.

drawQRToCanvas(qr, document.getElementById('MyCanvasID'), 8);

4.3. drawQRToDiv(qr, div, scale, bgcolor, fgcolor)

This function draws a QR code to an HTML5 canvas.

The qr argument is a QRCode object. This object must have had the
QRCode.drawSymbol() method previously called, so that the symbol has been constructed.

The div argument is an HTML div object. This object must exist -- make sure the window has been fully loaded and the object has been created before attempting to call this function.

The optional scale argument is the drawing scale. This value decides how many pixels wide each module will be, per side.

The optional bgcolor and fgcolor arguments define the background and foreground colors of the QR Code.

drawQRToDiv(qr, document.getElementById('MyDivID'), 8);

5. Internal function documentation

This section will be written at a later date. For now, please see the (fairly verbose) comments in the source code.

6. Acknowledgments

This library would not have been possible without the QR Code ISO standard (ISO/IEC 18004:2000), or the excellent documentation provided by Carolyn Eby.

QR Code is registered trademark of DENSO WAVE INCORPORATED.