API de dibujo

Las funciones que recibe JavaScript para leer y crear un dibujo: las mismas para las funciones JavaScript de un dibujo y para las extensiones (posprocesadores, reglas de diseño, plantillas, informes y extensiones de guardado). Las reglas de diseño, los informes, los posprocesadores y las extensiones de guardado pueden leer el dibujo, pero no modificarlo.

Valores

Los números, las cadenas y true/false son tal cual. Una posición es {x, y}; una lista es un array y un diccionario un Map. Los valores devueltos llegan de la misma forma: un objeto con los números x e y es una posición; cualquier otro objeto, un diccionario de sus propiedades.

Puntos

Un punto que devuelven las funciones es {x, y, id}: su posición y su nombre en el dibujo ("P4"). Los puntos son los de la página con la que se trabaja (cada página tiene los suyos); las variables son las de todo el dibujo. Cuando una función recibe un punto, se le puede dar:

un punto ({x, y, id}), su nombre ("P4") o su número (4): ese punto, de modo que lo creado lo sigue cuando se mueve;
una posición ({x: 10, y: 20} o [10, 20]): un punto nuevo allí, fijo.

Leer el dibujo

Función	Significado
`vars.NAME`	Una variable: `vars.L` es `L`, `vars.GAP` es `GAP`.
`variable("NAME")`	Lo mismo, por nombre: `variable("W")`. Una variable de sistema se nombra con o sin su `#`: `variable("#DFS")`, `vars.DFS`.
`getPoint(p)`	Un punto existente: `getPoint(4)`, `getPoint("P4")`.
`evaluate("…")`	Una expresión del lenguaje de dibujo: `evaluate("DISTANCE(P0,P2)")`.

Variables y puntos

Función	Significado
`setVariable("NAME", value)`	Asigna una variable: un número o una expresión (`setVariable("H", "L/2")`).
`newPoint("expression")`	Un punto nuevo definido por una expresión: `newPoint("[L,0]")`, `newPoint("P3+[0,GAP]")`.
`newPoint(position)`	Un punto nuevo en una posición, fijo.
`offset(p, dx, dy)`	Un punto nuevo a esa distancia de otro.
`polar(p, angle, distance)`	Un punto nuevo a un ángulo (en grados, en sentido antihorario desde el eje x) y una distancia de otro.
`between(p, q, t)`	Un punto nuevo en una fracción del recorrido de un punto a otro (0 en el primero, 1 en el segundo).

Los tamaños (dx, dy, angle, distance, t y el radio de un círculo) pueden ser números o expresiones como cadenas ("W/2"): una expresión mantiene el punto nuevo definido a partir de sus variables, de modo que se mueve cuando cambian.

Elementos

Función	Significado
`line(p, q)`	Una línea.
`arc(start, centre, end, anticlockwise)`	Un arco (en sentido antihorario si se omite).
`circle(centre, radius)`	Un círculo; el radio, un número o una expresión.
`bezier(p0, c1, c2, p3)`	Una curva de Bézier cúbica.
`polyline([p, …], closed)`	Una polilínea que pasa por los puntos (no cerrada si se omite).
`point(p)`	Un elemento punto.
`text(p, "text", height, rotation)`	Texto (altura 10, sin rotación, si se omiten).
`layer(n)`	La capa en la que se crean los elementos que siguen (`null`: la capa actual).
`command("…")`	Cualquier instrucción del lenguaje de dibujo: `command("FILLET(@1,@2,5)")`.

Qué es el dibujo

Función	Significado
`drawingInfo()`	Todo lo que se sabe del dibujo, calculado en ese momento (abajo).
`classification()`	Qué es: `{category, style, product, tags, description, …}`. Un campo sin definir es `""`; `tags` es una matriz.
`classify("field", value)`	Define uno de sus campos (`""` o `null` lo quita): `classify("style", "FEFCO 0201")`. Una matriz se guarda como lista: `classify("tags", ["rsc", "shipping"])`.
`classify({…})`	Define varios a la vez: `classify({ category: "Corrugated box", tags: ["rsc"] })`.
`classificationStyles()`	Los estilos de la lista de referencia, cada uno `{code, name, category, series}`: `{code: "FEFCO 0201", name: "Regular slotted container", category: "Corrugated box", series: false}`.
`classificationCategories()`	Las categorías de la lista de referencia, por nombre: `["Folding carton", "Corrugated box", …]`.
`notes()`	Sus notas, por nombre: `notes().Customer`.
`note("name")`	El valor de una nota, o `null` si no la hay.
`setNote("name", value)`	Define una nota (`""` o `null` la quita).

drawingInfo() da un objeto con:

Propiedad	Significado
`name`, `path`, `units`	El nombre y el archivo del dibujo (`""` si no se ha guardado), y `"mm"` o `"in"`.
`classification`, `notes`	Como arriba.
`variables`	Sus variables (no las ocultas), por nombre, calculadas: `variables.L`.
`bounds`	Su extensión: `{minX, minY, maxX, maxY, width, height}` (`null` si no hay nada dibujado).
`elements`	Cada elemento de la página en la que se trabaja: su `id`, `kind`, `layer`, `layerName`, `length`, `area`, `closed`, `start`, `end`, `bounds`, `radius`, `rule`, `minRadius`, `minRadiusAt`, `corners`, `bridges` y `tool` (véase Reglas de diseño).
`layers`	Cada capa: su número, `name`, si es de corte (`cutting`), y el número (`count`), la longitud (`length`) y el área (`area`) de sus elementos.
`totals`	`elements`, `length`, `width` y `height`; `lengthByLayer` y `countByLayer` por nombre de capa (`totals.lengthByLayer.Cut`); `byKind` (`totals.byKind.LINE`).
`page`, `pages`	La página en la que se trabaja y todas las páginas: su `name`, si es la actual (`current`) y cuántos elementos (`elements`) y puntos (`points`) tiene.
`nests`	Los anidados de todas las páginas, con sus hojas, copias y desperdicio.
`frames`	Los marcos de moldura a inglete de la página en la que se trabaja (las piezas de la herramienta Marco a inglete alrededor de una imagen, o piezas dispuestas como lista de corte): cada uno `{joined, whole, width, rebate, rebateFrom, outsideWidth, outsideHeight, pieces}`, con su `rebate` (galce) `null` si el dibujo no lo indica (`rebateFrom`: `"line"`, o la variable, `"FRRB1"`), y cada pieza `{side, longPoint, shortPoint}` (`side`: `"bottom"`, `"right"`, `"top"`, `"left"`; `"width"` o `"height"` si están dispuestas en lista).
`stone`	Las piezas de piedra de la página en la que se trabaja (contornos cerrados en capas de corte; uno dentro de una pieza es su hueco): `{pieces, slabs, edges, cutOuts, area, netArea}`. Cada pieza `{number, label, area, netArea, width, height, perimeter, slab, cutOuts, edges}`: su `label`, un texto dentro de ella que no nombra ningún hueco; `slab`, el número de la tabla en la que está (o `null`); cada hueco `{kind, width, height, area, round, from}` (`kind`: `"Sink"`, `"Hob"`, `"Tap hole"`, `"Socket"`, `"Cut-out"`, `"Round cut-out"`; `from`: `"label"`, `"layer"` o `"shape"`); `edges`, la longitud de sus cantos marcados con cada perfil (líneas en las capas cuyo nombre es Edge y el perfil). Cada tabla (contornos en la capa Slab) `{number, width, height, area, usedArea}`; `edges` y `cutOuts`, los totales por perfil y por tipo. Consulte Piedra y baldosas.
`accessories`	Los accesorios colocados en la página en la que se trabaja, con precios de la lista compartida (o el `APRICE` propio de cada pieza): `{list, items, cost, unpriced}`. Cada uno de `list` `{item, kind, quantity, unit, price, cost, priced, x, y, id}` (`unit`: `"each"`, `"m"` o `"m²"`; `price` es `null` si no tiene); `items` los mismos sumados por artículo y precio `{item, unit, quantity, price, cost, priced, count}`; `cost` el de todos; `unpriced` los artículos sin precio.
`library`, `functions`	Los nombres de las piezas de su biblioteca y de sus funciones.

Las reglas de diseño, los informes y las extensiones de guardado reciben el mismo objeto como su drawing. Una función JavaScript de un dibujo puede leer las notas y la clasificación, pero no llamar a drawingInfo() (se calcula como parte del dibujo) ni cambiarlas; tampoco pueden cambiarlas las reglas de diseño, los informes, los posprocesadores ni las extensiones de guardado.

Mostrar valores

print(…) y console.log(…) muestran valores en la ventana Interactiva, como hace PRINT, con el nombre de la función o de la extensión.

Solo para extensiones

Función	Significado
`postProcessor({…})`	Declara un posprocesador.
`designRule({…})`	Declara una regla de diseño.
`template({…})`	Declara una plantilla.
`drawingReport({…})`	Declara un informe.
`onSave({…})`	Declara una extensión de guardado.
`command({…})`	En un paquete: declara un comando, que se ejecuta desde menús, botones de la barra de herramientas, un atajo de teclado o Ejecutar comando…; lo que modifica se deshace en un solo paso.
`uiExtension({…})`	En un paquete: los elementos de menú, botones y grupos de la barra de herramientas que añade, y los propios de la aplicación que oculta o mueve.
`t("key", …)`	En un paquete: su texto para la clave, en el idioma en que se muestra la aplicación (en inglés si no lo tiene en ese idioma).
`cameraRegistration({…})`	Declara un registro con cámara: dónde encuentra una cámara las marcas de registro de un trabajo.
`httpRequest(url, {…})`	En un registro con cámara, mientras mide: una solicitud a uno de los servicios que declara.
`report(message, elements, at)`	En una regla de diseño: un problema encontrado.
`distanceBetween(a, b)`, `crossings(a, b)`	En una regla de diseño o un informe: cuánto se acercan dos elementos y dónde se cruzan.

Cuadros de diálogo y selecciones

Mientras se ejecuta un comando, ui hace preguntas al usuario; cada función devuelve una promesa que un async run() espera con await, y la aplicación sigue funcionando mientras el usuario responde.

Función	Significado
`await ui.form({ title, fields, validate })`	Un formulario: sus valores por id de campo (campos `number`, `integer`, `length`, `angle`, `text`, `choice`, `check`, `point`), comprobados antes de cerrarse; `null` si se cancela.
`await ui.pick({ kind, prompt, filter })`	Una selección en el dibujo: un lugar (`{x, y}`, con el `id` del punto en el que se hace clic), un elemento o varios tal como los describe `drawingInfo()`; `null` con Esc.
`await ui.message(text, { title, kind })`	Un mensaje (`kind`: `"information"`, `"warning"`, `"error"`).
`await ui.confirm(text, { title })`	Una pregunta: `true` para Sí.
`ui.progress({ title, cancellable })`	Una ventana de progreso: `await p.update(fraction, text)` (`false` una vez cancelada), `p.cancelled()`, `p.close()`.
`await ui.runDesign(name, values)`	Un diseño de la biblioteca abierto como dibujo nuevo con los valores indicados.

Cada una necesita un permiso en el manifiesto del paquete.

Solo para scripts de automatización

Los scripts de automatización tienen las funciones anteriores sobre su dibujo actual, y otras propias para abrir, crear, exportar y guardar dibujos (openDrawing, newDrawing, runDesign, export y save de un dibujo …) y para leer y escribir archivos en sus carpetas (readCsv, writeText …).

Véase también: Funciones JavaScript, Extensiones, Scripts de automatización.