SHIP:Sail:qr

Function	Returns	Introduced	Description
qr	nothing	v5.1	Generates a QR code image in a canvas object.

See Also:

• Sail Home
• Sail Functions

Prototype

qr(Node canvas, Dimension size, Dimension x, Dimension y, Byte type, Byte redundancy, String src, Node intVar, [Color fg [, Color bg ]]);

qr(Node canvas, Dimension size, Dimension x, Dimension y, Byte type, Byte redundancy, Buffer src, Node intVar, [Color fg [, Color bg ]]);

Parameters/Return Value

Parameter	Data Type	Description
canvas	Node	Node of type canvas to render into
size	Dimension	Output size (width, height) in pixels
x	Dimension	Horizontal offset in canvas for bottom right corner of QR code
y	Dimension	Vertical offset in canvas for bottom right corner of QR code
mode	Byte	Type of QR code 0...127
redundancy	Byte	Data redundancy desired in QR image 0..100 as a percentage
src	String or Buffer	String or Buffer object for source data
intVar	Integer	Integer variable for completion event and error code return
fg	Color	ARGB8888 color used for rendering the foreground; if not specified default is 0xFF000000 (opaque black)
bg	Color	ARGB8888 color used for rendering the background; if not specified default is 0xFFFFFFFF (opaque white)

Detailed Description

The qr function renders a QR code image into a canvas node based on runtime data held in a binary Buffer or String.

Since QR codes are always square, the size parameter indicates the pixel width and pixel height of the QR code. Since canvas dimensions are positive up-and-to-the-right (vs. box/frame which are down and to the right) the offset specified in the qr functions x and y parameters indicate the bottom-left corner of the QR code's target location. In the canvas, the QR code will be rendered at [x,y..(x+size-1),(y+size-1)].

QR Code Types

The type parameter sets the type of QR code generated. There are many different types of QR codes, and this table summarizes the values, built-in names, and behaviours of the different types:

Type #	Type Name	Description
0	SHIP.QR.TYPE.BINARY	src will be processed as a binary object in a binary QR code; String types will include the trailing 0, Buffer types will include index 0 through occupied-1 inclusive.
1	SHIP.QR.TYPE.ASCII	src will be processed as an 8-bit ASCII string object; Buffer source objects will be processed from offset 0 up until the first 0 byte is encountered or occupied-1, whichever comes first.
2	SHIP.QR.TYPE.UTF8	src will be processed as an UTF-8 string object; Buffer source objects will be processed from offset 0 up until the first 0 character is encountered or occupied-1, whichever comes first. If an UTF-8 decoding error is encountered, no QR code will be rendered and the error code will be generated SHIP.ERR.DECODING.

Completion and Error Codes

The qr function executes in the background and the function call is non-blocking. Larger QR codes, depending on the platform capabilities and system loading, may take some noticable time to completely render.

When the function execution is complete, the intVar specified in the function call will experience a change event, irrespective of whether its value changed from one function invocation to the next. A listener on this intVar will always wake up and run its attached script when the function completes.

The intVar, on this event, will contain a value indicated the completion status of the function as one of the standard SHIP Runtime Error Codes. 0, or SHIP.ERR.NONE, for the whole value always indicates an error-free completion.