SHIP:Node:canvas

Node Home

Node Type	Description
canvas	A RAM-based read-write image area capable of receiving run-time drawing commands.

canvas nodes are targeted for SHIP v5.1 production availability and have limited support in SHIP v5.0. The goal for the canvas system is to support run-time graphing, dynamic loading of images from files into the system, as well as dynamic generation and display of QR codes.

canvas nodes can exist only in the resources area, and can be attached (similar to image nodes) to one or more box nodes in the object property.

The size of the canvas can be larger or smaller than the viewport created by any given box that exposes the canvas, similar to an image in that it is clipped to fit the box inner area, and can be panned/shifted using the offset properties.

Therefore, for example, you can create a canvas many times wider than the box you use to view it and then just manipulate the xoffset property to move the visible portion of the canvas area back and forth inside the box viewable inner area.

Ancestors

The following nodes are permitted to have canvas nodes as descendants:

Node Type	Description
group†	Lightweight node that encloses other nodes for pure organizational benefit, or to create an array of nodes.
resources	All reusable items, such as images, are held in the SHIP top-level node defined as the resources node

^†only a pure series of group node ancestors under the resources node.

Descendants

The following nodes are permitted within canvases:

Node Type	Description
constant	Defines a constant value for use in SHIPTide properties or SAIL scripts.
group	Lightweight node that encloses other nodes for pure organizational benefit, or to create an array of nodes.

Properties

The following properties are available for the canvas node:

Canvas Properties

Property	Data Type	Description
name**	String	The name used to identify this node in SHIPTide.
oh	Dimension	Height of a box model node.
ow	Dimension	Width of a box model node.
valign	VALIGN	Vertical alignment of a box model node within its parent container's inner dimensions.
halign	HALIGN	Horizontal alignment a box model node within its parent container's inner dimensions.
scalex
scaley
visible	Boolean	If true (default) this node will be visible iff all direct line parent nodes up to and including the display node are also visible.
opacity	Byte	Opacity of the displayable node and all its children, grandchildren, etc.

*available at SHIPEngine run time only and cannot be set in SHIPTide. Use a Sail script at shiplaunch time if this property needs to be set when the GUI starts to run.

**available only in SHIPTide; cannot be accessed from Sail scripts at run-time.

Drawing in a Canvas

In a Sail script, the draw built in function causes run-time drawing in a canvas.

The format of the draw built-in function is:

draw(canvas object, draw-command [,arg, arg, ...], draw-command [,arg, arg, ...], ....);

The following are the draw commands available in v5.0.200+:

Commands used in draw function in SHIP.

Command	Arguments	Description
RESET		resets the canvas, does not clear, but puts the pen up and at 0,0 in the 0 degree orientation;
CLEAR	Color clrColor	clears the canvas to a given color
PENRESET		pen up, back to 0,0 and a 0 degree orientation
PENSTYLE	WIP	Currently not implemented
PENWIDTH	WIP	Currently not implemented
PENDOWN	Boolean penDown	puts the pen down (if true) or up (if false)
PENCOLOR	Color penColor	sets the pen color
SHIFTX	Dimension horDirection	shifts the contents of the canvas in the horizontal direction
SHIFTXY	Dimension x, Dimension y	shifts the contents of the canvas
SHIFTY	Dimension verDirection	shifts the contents of the canvas in the vertical direction
MOVE	Float nPixles	move the pen forward from the current location in the current direction by the specified number of pixels
MOVEX	Float nPixels	move the pen from the current location in the x direction by the specified number of pixels
MOVEXY	Float xPixels, Float yPixels	move the pen from the current location in the x and y direction by the specified number of pixels
MOVEY	Float nPixels	move the pen from the current location in the y direction by the specified number of pixels
MOVEABSX	Float xCoord	move the pen's x coordinate to the absolute location indicated
MOVEABSXY	Float xCoord, Float yCoord	move the pen's x and y coordinates to the absolute location indicated
MOVEABSY	Float yCoord	move the pen's y coordinate to the absolute location indicated
ROTATE	Float orientation	rotate the pen orientation from the current orientation by the indicated amount
ROTATEABS	Float orientation	rotate the pen orientation to the absolute orientation indicated
POLYFILL	WIP	Currently not implemented
POLYLINE	WIP	Currently not implemented
TEXT	WIP	Currently not implemented
TEXTSIZE	WIP	Currently not implemented
RECTFILL	WIP	Currently not implemented

Although you would expect many of these commands to use Dimension for their arguments, note how many use Float. The pen position and orientation is maintained by the system in a floating point coordinate in order to retain drawing precision across numerous relative movements, for example drawing a star or box using a series of MOVE and ROTATE commands, such that the ending spot joins well with the starting spot.

Rendering an image from a file onto a canvas

In a Sail script, the image built in function causes run-time rendering of a file containing an image onto a canvas.

The format of the image built-in function is:

Integer err = image(Node canvas, Node file, Integer result[, Integer posX, Integer posY, Integer offsetX, Integer offsetY, Integer clipW, Integer clipH]);

In order to draw images to the canvas from a file, the correct image file format must be used. Currently, the only image file format supported for this is Joint Photographic Experts Group (JPEG). Please see the image built in function for the specific file features supported. JPEG is a commonly used method for lossy compression of digital images. Common extensions for this file format are .jpeg or .jpg.