SHIP:Sail:qr

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

See Also:

• Sail Home
• Sail Functions

Prototype

Integer err = qr(Node canvas, Dimension size, Dimension x, Dimension y, Byte mode, Byte redundancy, String src, Node eventVar, [Color fg [, Color bg ]]);

Integer err = qr(Node canvas, Dimension size, Dimension x, Dimension y, Byte mode, Byte redundancy, Buffer src, Node eventVar, [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...2
redundancy	Byte	Data redundancy level desired in QR image 0..3
src	String/Buffer	String or Buffer object for source data
eventVar	Node	Node name of an Integer variable for completion event and error code return; the node may also be a variable of type Node which must point at an Integer variable allowing indirection.
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)
Return	Integer	Error Codes related to launching the job; SHIP.ERR.NONE if job successfully launched

Detailed Description

The qr function renders a QR code image into a canvas node based on run-time data held in a binary Buffer/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 Modes

The mode 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.

Launching, 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 noticeable time to completely render.

When the function is invoked, several tests are performed before enqueueing the background job, and the return value of the function indicates a successful or non-successful launch of the job. The job may or may not complete correctly (see below), but if the return value from the function is SHIP.ERR.NONE the job is enqueued and (successful or not) the completion event will be triggered. If the job is not successfully launched, no completion event will be triggered. Invocation-time return codes include:

• SHIP.ERR.NONE - no error, job is enqueued for background processing
• SHIP.ERR.QUEUEPUT - the job queue is full and the new job cannot be enqueued
• SHIP.ERR.PARAM - a function parameter was invalid
• SHIP.ERR.EVENT_NO_HANDLER - no valid event handler eventVar was specified

Since the job is running in the background, the GUI will need to know when the job is complete and if the job completed successfully. The eventVar parameter must be specified and ultimately reference a variable node of type Integer. When the function execution is complete, the Integer variable will experience a change event, irrespective of whether its value changed from one function invocation to the next. A listener on this variable will always wake up and run its attached script when the function completes.

The eventVar parameter can be the name of an Integer variable, or it can reference a variable of type Node (or a consecutive series of those references) that eventually end up pointing at an Integer variable.

The eventVar on this event, will contain a value corresponding to 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 error-free completion. Error values include:

• SHIP.ERR.NONE - no error, job completed successfully

• SHIP.ERR.INSUFFICIENT - the job could not run with current memory resources available

• SHIP.ERR.DECODING - the source data could not be decoded (encoding error)
• SHIP.ERR.READING - the source data could not be loaded

• SHIP.ERR.WRITING - the target data could not be loaded