Drawing API

The functions JavaScript is given to read and make a drawing: the same for JavaScript functions in a drawing and for extensions (post-processors, design rules, templates, reports and save extensions). Design rules, reports, post-processors and save extensions can read the drawing, but not change it.

Values

Numbers, strings and true/false are as they are. A position is {x, y}; a list is an array and a dictionary a Map. Values given back come the same way: an object with numbers x and y is a position, any other object a dictionary of its properties.

Points

A point the functions give back is {x, y, id}: its position, and its name in the drawing ("P4"). The points are those of the page worked on (each page has its own); the variables are the whole drawing's. Where a function takes a point, it can be given:

a point ({x, y, id}), its name ("P4") or its number (4): that point, so what is made follows it when it moves;
a position ({x: 10, y: 20} or [10, 20]): a new point there, fixed.

Reading the drawing

Function	Meaning
`vars.NAME`	A variable: `vars.L` is `L`, `vars.GAP` is `GAP`.
`variable("NAME")`	The same, by name: `variable("W")`. A system variable is named with or without its `#`: `variable("#DFS")`, `vars.DFS`.
`getPoint(p)`	A point that exists: `getPoint(4)`, `getPoint("P4")`.
`evaluate("…")`	An expression of the drawing language: `evaluate("DISTANCE(P0,P2)")`.

Variables and points

Function	Meaning
`setVariable("NAME", value)`	Sets a variable: to a number, or to an expression (`setVariable("H", "L/2")`).
`newPoint("expression")`	A new point defined by an expression: `newPoint("[L,0]")`, `newPoint("P3+[0,GAP]")`.
`newPoint(position)`	A new point at a position, fixed.
`offset(p, dx, dy)`	A new point that far from another.
`polar(p, angle, distance)`	A new point at an angle (in degrees, anticlockwise from the x axis) and distance from another.
`between(p, q, t)`	A new point part of the way from one point to another (0 at the first, 1 at the second).

Sizes (dx, dy, angle, distance, t and a circle's radius) can be numbers, or expressions as strings ("W/2"): an expression keeps the new point defined on its variables, so it moves when they change.

Elements

Function	Meaning
`line(p, q)`	A line.
`arc(start, centre, end, anticlockwise)`	An arc (anticlockwise if left out).
`circle(centre, radius)`	A circle; the radius a number or an expression.
`bezier(p0, c1, c2, p3)`	A cubic Bézier curve.
`polyline([p, …], closed)`	A polyline through the points (not closed if left out).
`point(p)`	A point element.
`text(p, "text", height, rotation)`	Text (height 10, no rotation, if left out).
`layer(n)`	The layer the elements after it are made on (`null`: the current layer).
`command("…")`	Any statement of the drawing language: `command("FILLET(@1,@2,5)")`.

What the drawing is

Function	Meaning
`drawingInfo()`	Everything known about the drawing, worked out now (below).
`classification()`	What it is: `{category, style, product, tags, description, …}`. A field not set is `""`; `tags` is an array.
`classify("field", value)`	Sets a field of it (`""` or `null` removes it): `classify("style", "FEFCO 0201")`. An array is kept as a list: `classify("tags", ["rsc", "shipping"])`.
`classify({…})`	Sets several at once: `classify({ category: "Corrugated box", tags: ["rsc"] })`.
`classificationStyles()`	The reference list's styles, each `{code, name, category, series}`: `{code: "FEFCO 0201", name: "Regular slotted container", category: "Corrugated box", series: false}`.
`classificationCategories()`	The reference list's categories, by name: `["Folding carton", "Corrugated box", …]`.
`notes()`	Its notes, by name: `notes().Customer`.
`note("name")`	A note's value, or `null` if there is none.
`setNote("name", value)`	Sets a note (`""` or `null` removes it).

drawingInfo() gives an object of:

Property	Meaning
`name`, `path`, `units`	The drawing's name and file (`""` if not saved), and `"mm"` or `"in"`.
`classification`, `notes`	As above.
`variables`	Its variables (not the hidden ones), by name, worked out: `variables.L`.
`bounds`	Its extent: `{minX, minY, maxX, maxY, width, height}` (`null` if nothing is drawn).
`elements`	Each element of the page worked on: its `id`, `kind`, `layer`, `layerName`, `length`, `area`, `closed`, `start`, `end`, `bounds`, `radius`, `rule`, `minRadius`, `minRadiusAt`, `corners`, `bridges` and `tool` (see Design rules).
`layers`	Each layer: its number, `name`, whether it is `cutting`, and the `count`, `length` and `area` of its elements.
`totals`	`elements`, `length`, `width` and `height`; `lengthByLayer` and `countByLayer` by layer name (`totals.lengthByLayer.Cut`); `byKind` (`totals.byKind.LINE`).
`page`, `pages`	The page worked on, and every page: its `name`, whether it is `current`, and how many `elements` and `points` it has.
`nests`	The nests on every page, with their sheets, copies and wastage.
`frames`	Frames of mitred moulding on the page worked on (the Mitre Frame tool's pieces round a picture, or pieces laid out as a cut list): each `{joined, whole, width, rebate, rebateFrom, outsideWidth, outsideHeight, pieces}`, its `rebate` `null` if the drawing doesn't say it (`rebateFrom`: `"line"`, or the variable, `"FRRB1"`), and each piece `{side, longPoint, shortPoint}` (`side`: `"bottom"`, `"right"`, `"top"`, `"left"`; `"width"` or `"height"` laid out).
`stone`	Stone pieces on the page worked on (closed outlines on cutting layers; one inside a piece is its cut-out): `{pieces, slabs, edges, cutOuts, area, netArea}`. Each piece `{number, label, area, netArea, width, height, perimeter, slab, cutOuts, edges}`: its `label` a text inside it that names no cut-out, `slab` the number of the slab it is on (or `null`), each cut-out `{kind, width, height, area, round, from}` (`kind`: `"Sink"`, `"Hob"`, `"Tap hole"`, `"Socket"`, `"Cut-out"`, `"Round cut-out"`; `from`: `"label"`, `"layer"` or `"shape"`), `edges` the length of its edges marked with each profile (lines on the layers named Edge and the profile). Each slab (outlines on the Slab layer) `{number, width, height, area, usedArea}`; `edges` and `cutOuts` the totals by profile and by kind. See Stone and Tile.
`accessories`	The accessories placed on the page worked on, priced from the shared price list (or each part's own `APRICE`): `{list, items, cost, unpriced}`. Each in `list` `{item, kind, quantity, unit, price, cost, priced, x, y, id}` (`unit`: `"each"`, `"m"` or `"m²"`; `price` `null` if it has none); `items` the same added up by item and price `{item, unit, quantity, price, cost, priced, count}`; `cost` all of them; `unpriced` the items with no price.
`library`, `functions`	The names of the parts in its library and of its functions.

Design rules, reports and save extensions are given the same object as their drawing. A JavaScript function in a drawing can read the notes and classification, but not call drawingInfo() (it is worked out as part of the drawing) or change them; nor can design rules, reports, post-processors and save extensions change them.

Showing values

print(…) and console.log(…) show values in the Interactive window, as PRINT does, with the function's or extension's name.

Extensions only

Function	Meaning
`postProcessor({…})`	Declares a post-processor.
`designRule({…})`	Declares a design rule.
`template({…})`	Declares a template.
`drawingReport({…})`	Declares a report.
`onSave({…})`	Declares a save extension.
`command({…})`	In a package: declares a command, run from menus, toolbar buttons, a shortcut or Run Command…; what it changes is undone as one step.
`uiExtension({…})`	In a package: menu items, toolbar buttons and groups it adds, and the app's own it hides or moves.
`t("key", …)`	In a package: its string for the key, in the language the app is shown in (English if that has none).
`cameraRegistration({…})`	Declares a camera registration: where a camera finds a job's registration marks.
`httpRequest(url, {…})`	In a camera registration, while it measures: a request to one of the services it declares.
`report(message, elements, at)`	In a design rule: a problem found.
`distanceBetween(a, b)`, `crossings(a, b)`	In a design rule or a report: how near two elements come, and where they cross.

Dialogs and picks

While a command runs, ui asks the user things; each function gives back a promise for an async run() to await, and the app goes on working while the user answers.

Function	Meaning
`await ui.form({ title, fields, validate })`	A form: its values by field id (`number`, `integer`, `length`, `angle`, `text`, `choice`, `check`, `point` fields), checked before it closes; `null` if cancelled.
`await ui.pick({ kind, prompt, filter })`	A pick in the drawing: a place (`{x, y}`, with the `id` of a point clicked on), an element or elements as `drawingInfo()` describes them; `null` on Esc.
`await ui.message(text, { title, kind })`	A message (`kind`: `"information"`, `"warning"`, `"error"`).
`await ui.confirm(text, { title })`	A question: `true` for Yes.
`ui.progress({ title, cancellable })`	A progress window: `await p.update(fraction, text)` (`false` once cancelled), `p.cancelled()`, `p.close()`.
`await ui.runDesign(name, values)`	A library design opened as a new drawing with the values given.

Each needs a permission in the package's manifest.

Automation scripts only

Automation scripts have the functions above on their current drawing, and their own to open, make, export and save drawings (openDrawing, newDrawing, runDesign, a drawing's export and save …) and to read and write files in their folders (readCsv, writeText …).