Difference between revisions of "SHIP:Sail:qr"

From Serious Documentation
Jump to: navigation, search
(→‎Parameters/Return Value)
 
(5 intermediate revisions by 2 users not shown)
Line 1: Line 1:
 
__NOTOC__
 
__NOTOC__
 
{{SailFuncTableStart|}}<onlyinclude>
 
{{SailFuncTableStart|}}<onlyinclude>
−
|{{SailFunc|qr}}||{{DataType|Integer}} err ||style="text-align:center;"|v5.1||Generates a QR code image in a {{Node|canvas}} object.</onlyinclude>
+
|{{SailFunc|qr}}||{{DataType|Integer}}||style="text-align:center;"|v5.1||Generates a QR code image in a {{Node|canvas}} object.</onlyinclude>
 
|}
 
|}
 
== See Also: ==
 
== See Also: ==
Line 25: Line 25:
 
|y||{{DataType|Dimension}}||Vertical offset in canvas for bottom right corner of QR code
 
|y||{{DataType|Dimension}}||Vertical offset in canvas for bottom right corner of QR code
 
|-
 
|-
−
|mode||{{DataType|Byte}}||Type of QR code 0...127
+
|mode||{{DataType|Byte}}||Type of QR code 0...2
 
|-
 
|-
−
|redundancy||{{DataType|Byte}}|| Data redundancy desired in QR image 0..100 as a percentage
+
|redundancy||{{DataType|Byte}}|| Data redundancy level desired in QR image 0..3
 
|-
 
|-
−
|src||{{DataType|String}} or {{DataType|Buffer}}||String or Buffer object for source data
+
|src||{{DataType|String}}/{{DataType|Buffer}}||String or Buffer object for source data
 
|-
 
|-
 
|eventVar||{{DataType|Node}}||Node name of an {{DataType|Integer}} variable for completion event and error code return; the node may also be a variable of type {{DataType|Node}} which must point at an {{DataType|Integer}} variable allowing indirection.  
 
|eventVar||{{DataType|Node}}||Node name of an {{DataType|Integer}} variable for completion event and error code return; the node may also be a variable of type {{DataType|Node}} which must point at an {{DataType|Integer}} variable allowing indirection.  
Line 39: Line 39:
 
! scope="col" style="text-align:left" | Return
 
! scope="col" style="text-align:left" | Return
 
! scope="col" style="text-align:left" | {{DataType|Integer}}
 
! scope="col" style="text-align:left" | {{DataType|Integer}}
−
! scope="col" style="text-align:left" | [[SHIP:Error_Codes|Error Codes]] related to launching the job; {{Const|SHIP.ERR.NONE}} if job successfully launched
+
! scope="col" style="text-align:left" | <!--- Remove link until page exist [[SHIP:Error_Codes|Error Codes]] --->'''Error Codes''' related to launching the job; <!--- Remove link until page exist {{Const|SHIP.ERR.NONE}}--->'''SHIP.ERR.NONE''' if job successfully launched
 
|}
 
|}
  
 
== Detailed Description ==
 
== Detailed Description ==
  
−
The {{SailFunc|qr}} function renders a QR code image into a canvas node based on runtime data held in a binary {{DataType|Buffer}} or {{DataType|String}}.
+
The {{SailFunc|qr}} function renders a QR code image into a canvas node based on run-time data held in a binary {{DataType|Buffer}}/{{DataType|String}}.
  
 
Since QR codes are always square, the <code>size</code> 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 <code>qr</code> functions <code>x</code> and <code>y</code> parameters indicate the bottom-left corner of the QR code's target location.  In the canvas, the QR code will be rendered at <nowiki>[</nowiki>x,y..(x+size-1),(y+size-1)<nowiki>]</nowiki>.
 
Since QR codes are always square, the <code>size</code> 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 <code>qr</code> functions <code>x</code> and <code>y</code> parameters indicate the bottom-left corner of the QR code's target location.  In the canvas, the QR code will be rendered at <nowiki>[</nowiki>x,y..(x+size-1),(y+size-1)<nowiki>]</nowiki>.
Line 56: Line 56:
 
! scope="col" style="text-align:left" | Description
 
! scope="col" style="text-align:left" | Description
 
|-
 
|-
−
|0||{{const|SHIP.QR.TYPE.BINARY}}||<code>src</code> will be processed as a binary object in a binary QR code; {{DataType|String}} types will include the trailing 0, {{DataType|Buffer}} types will include index 0 through occupied-1 inclusive.
+
|0||<!--- Remove link until page exist {{const|SHIP.QR.TYPE.BINARY}}--->'''SHIP.QR.TYPE.BINARY'''||<code>src</code> will be processed as a binary object in a binary QR code; {{DataType|String}} types will include the trailing 0, {{DataType|Buffer}} types will include index 0 through occupied-1 inclusive.
 
|-
 
|-
−
|1||{{const|SHIP.QR.TYPE.ASCII}}||<code>src</code> will be processed as an 8-bit ASCII string object; {{DataType|Buffer}} source objects will be processed from offset 0 up until the first 0 byte is encountered or occupied-1, whichever comes first.
+
|1||<!--- Remove link until page exist {{const|SHIP.QR.TYPE.ASCII}}--->'''SHIP.QR.TYPE.ASCII'''||<code>src</code> will be processed as an 8-bit ASCII string object; {{DataType|Buffer}} source objects will be processed from offset 0 up until the first 0 byte is encountered or occupied-1, whichever comes first.
 
|-
 
|-
−
|2||{{const|SHIP.QR.TYPE.UTF8}}||<code>src</code> will be processed as an UTF-8 string object; {{DataType|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.
+
|2||<!--- Remove link until page exist {{const|SHIP.QR.TYPE.UTF8}}--->'''SHIP.QR.TYPE.UTF8'''||<code>src</code> will be processed as an UTF-8 string object; {{DataType|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 ===
 
=== Launching, Completion and Error Codes ===
−
The {{SailFunc|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.
+
The {{SailFunc|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 enqueuing 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 {{Const|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.
+
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 <!--- Remove link until page exist {{Const|SHIP.ERR.NONE}}--->'''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:
 +
* <!--- Remove link until page exist {{Const|SHIP.ERR.NONE}}--->'''SHIP.ERR.NONE''' - no error, job is enqueued for background processing
 +
* <!--- Remove link until page exist {{Const|SHIP.ERR.QUEUEPUT}}--->'''SHIP.ERR.QUEUEPUT''' - the job queue is full and the new job cannot be enqueued
 +
* <!--- Remove link until page exist {{Const|SHIP.ERR.PARAM}}--->'''SHIP.ERR.PARAM''' - a function parameter was invalid
 +
* <!--- Remove link until page exist {{Const|SHIP.ERR.EVENT_NO_HANDLER}}--->'''SHIP.ERR.EVENT_NO_HANDLER''' - no valid event handler <code>eventVar</code> was specified
  
−
When the function execution is complete, the <code>eventVar</code> specified in the function call will experience a change event, irrespective of whether its value changed from one function invocation to the next.  A {{Node|listener}} on this <code>eventVar</code> will always wake up and run its attached {{Node|script}} when the function completes. Function return codes include:
+
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 <code>eventVar</code> parameter must be specified and ultimately reference a {{Node|variable}} node of type {{DataType|Integer}}.  When the function execution is complete, the {{DataType|Integer}} {{Node|variable}} will experience a change event, irrespective of whether its value changed from one function invocation to the next.  A {{Node|listener}} on this {{Node|variable}} will always wake up and run its attached {{Node|script}} when the function completes.  
−
* {{Const|SHIP.ERR.NONE}} - no error, job is enqueued for background processing
 
−
* {{Const|SHIP.ERR.QUEUEPUT}} - the job queue is full and the new job cannot be enqueued
 
−
* {{Const|SHIP.ERR.PARAM}} - a function parameter was invalid
 
−
* {{Const|SHIP.ERR.EVENT_NO_HANDLER}} - no valid event handler <code>eventVar</code> was specified
 
  
−
The <code>eventVar</code> on this event, will contain a value corresponding to the completion status of the function as one of the standard [[SHIP:Runtime_Error|SHIP Runtime Error Codes]].  0, or SHIP.ERR.NONE, for the whole value always indicates error-free completion. Error values include:
+
The <code>eventVar</code> parameter can be the name of an {{DataType|Integer}} {{Node|variable}}, or it can reference a {{Node|variable}} of type {{DataType|Node}} (or a consecutive series of those references) that eventually end up pointing at an {{DataType|Integer}} {{Node|variable}}. 
−
* {{Const|SHIP.ERR.NONE}} - no error, job completed successfully
 
  
−
* {{Const|SHIP.ERR.MEM_INSUFFICIENT}} - the job could not run with current memory resources available
 
  
−
* {{Const|SHIP.ERR.DECODING}} - the source data could not be decoded (encoding error)
+
The <code>eventVar</code> on this event, will contain a value corresponding to the completion status of the function as one of the standard <!--- Remove link until page exist [[SHIP:Runtime_Error|SHIP Runtime Error Codes]]--->'''SHIP Runtime Error Codes.  0, or SHIP.ERR.NONE, for the whole value always indicates error-free completion. Error values include:
−
* {{Const|SHIP.ERR.READING}} - the source data could not be loaded
+
* <!--- Remove link until page exist {{Const|SHIP.ERR.NONE}}--->''' SHIP.ERR.NONE - no error, job completed successfully
  
−
* {{Const|SHIP.ERR.WRITING}} - the target data could not be loaded
+
* <!--- Remove link until page exist {{Const|SHIP.ERR.MEM_INSUFFICIENT}}--->'''SHIP.ERR.INSUFFICIENT''' - the job could not run with current memory resources available
 +
 
 +
* <!--- Remove link until page exist {{Const|SHIP.ERR.DECODING}}--->'''SHIP.ERR.DECODING''' - the source data could not be decoded (encoding error)
 +
* <!--- Remove link until page exist {{Const|SHIP.ERR.READING}}--->'''SHIP.ERR.READING''' - the source data could not be loaded
 +
 
 +
* <!--- Remove link until page exist {{Const|SHIP.ERR.WRITING}}--->'''SHIP.ERR.WRITING''' - the target data could not be loaded
  
 
== Examples ==
 
== Examples ==
 +
 +
[[Category:Canvas Functions]]

Latest revision as of 15:41, 26 October 2016

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

See Also:

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

Examples

Retrieved from "https://techref.myserious.com/index.php?title=SHIP:Sail:qr&oldid=6332"