Canvas API exposes an imperative view of CDL (CadWorX Declarative Language), format used through all our software stack. It is designed to serve both simple (replacing a figure in a template) and complex manipulation of CDL document and templates.

The API follows JavaScipt semantics and naming conventions as much as possible, and fills the gaps borrowing the style of other popular frameworks like JQuery and Lo-dash, libraries that are used internally and encourage to interact with the API.

CDL tag names are CamelCase. For the most part, they are translated to Canvas using the same CamelCase tag name for type names and backCase for properties.

// <Contour OffsetX="10"></Contour>
var c = Cx.Contour({ offsetX: 10 });

Creation of elements

CDL elements are translated to typed objects in Canvas:

Objects are initialized using JSON notation:

var contour = Cx.Contour({ offset: 10
                         , brush: { color: { rgb: 'FF0000', alpha: 0.5 } } });

You can mix JSON and Canvas objects if you already have the objects available:

var contour = Cx.Contour({ offset: 10
                         , brush: figure.brush() });

Properties

Following JQuery properties semantics, CIL properties exposes both get and set functionality directly using the property name to define a public function (with or with out parameters).

// Getter
var ox = shadow.offsetX();
// Setter
shadow.offsetX( ox+10 );

Setters return the modified object and can be chained to update several properties in a single line:

// Setters chaining
shadow.offsetX(10)
      .offsetY(10)
      .gap(3);

The values returned from properties are typed. You will get a number, a string or a brush when you query the for them. Property setters expect the same courtesy from the user, and passing a string when a number is required is undefined behavior.

Array properties

Working with lists of items is very common when dealing with CDL documents. A document is a list of figures, a figure has a list of processes, a linear gradient brush has a list of colors, Canvas has a list of selected figures. These lists are also exposed as normal properties:

// Getter
var figures = layer.figures();
// Setter
layer.figures( [text, shape, raster] );

The setter in this case will directly replace all figures in the document by the new given figure list.

Array properties can also be accessed using indexing:

// Get one figure
var figure = layer.figures(2);
// Replace one figure
layer.figures( 2, raster );

Array properties getters returns an extended version of a JavaScript Array. These arrays tries to mimic as much as possible the standard Array interface. All the functions in the standard are available. They work in the same way as normal arrays:

var figures = layer.figures();
for(var k=0, size=figures.length; k<size; ++k){
  var figure = figures[k];
  figure.translate(offset);
}

The new JavaScript standard iteration functions (and the extensions provided by lo-dash) are great tools for list handling, reading Underscore.js documentation is heavily recommended before using Canvas. The algorithm above can be writen as:

_.invoke( layer.figures(), 'translate', offset );

Cx Arrays extends the standard set of mutation functions to help in our domain. For example, following the example above, the user can remove the small figures using:

figures.remove(smallFigures);

The new mutation functions are:

For all functions, the parameters specs are:

• a value or array of values to be added
• e value or array of values to be removed
• v value or array of values to be relocated
• i array index
• n count

Functions that remove values return these values so the user can use them or dispose them if needed.