La Simple API

Introducción

La QCAD Simple API es un pequeño conjunto de funciones de script globales que simplifican tareas comunes como añadir entidades a un dibujo, consultar entidades y modificarlas (mover, recortar, redondear, desfasar, …). Está pensada principalmente para usarse en la consola de scripts y para scripts procedimentales breves que se ejecutan desde un archivo, pero se puede usar desde cualquier script.

La Simple API solo abarca una pequeña parte de la API completa de QCAD. Como está escrita a su vez en ECMAScript (JavaScript), también es un buen punto de partida para aprender cómo funciona la API de QCAD subyacente. El código fuente se encuentra en los archivos scripts/simple.js y scripts/simple_*.js del código fuente de QCAD.

Usar la Simple API

En la consola de scripts (Misceláneo > Desarrollo > Consola de scripts) y en los scripts iniciados con Misceláneo > Desarrollo > Ejecutar script, todas las funciones de la Simple API están disponibles directamente. Escriba por ejemplo:

addLine(0,0, 100,100);

En sus propios archivos de script, por ejemplo en acciones de script interactivas o en herramientas de línea de comandos, incluya primero el archivo simple.js:

include("scripts/simple.js");

addLine(0,0, 100,100);

Todas las funciones actúan sobre el dibujo que está abierto en ese momento en la ventana de la aplicación QCAD, a menos que se use una transacción para redirigirlas a otro documento (véase Transacciones).

Todos los ejemplos de esta página se pueden pegar en la consola de scripts de un dibujo vacío. Cada ejemplo crea las entidades que necesita. Use Ver > Zoom automático o la función autoZoom() para ver el resultado.

Convenciones

Coordenadas

Las posiciones se pueden pasar de tres maneras diferentes:

• Como dos números separados: addLine(0,0, 100,100)
• Como array de dos números: addLine([0,0], [100,100])
• Como objeto vector: addLine(new RVector(0,0), new RVector(100,100))

Los ángulos se indican siempre en grados, excepto los parámetros inicial y final de las elipses, que se indican en radianes.

Referencias a entidades

Las funciones que trabajan con una entidad existente aceptan la entidad de varias formas:

• Un ID de entidad (número), por ejemplo 1234.
• Un objeto de entidad tal como lo devuelven las funciones de creación, por ejemplo el valor devuelto por addLine(...).
• Una posición en el dibujo ([x,y] o RVector): se usa la entidad más cercana a la posición indicada.
• Una forma (por ejemplo new RLine(0,0, 100,0)): la operación se aplica solo a la forma, el dibujo no se modifica.

var l = addLine(0,0, 100,0);
move(l, [0,10]);              // por objeto de entidad
move(l.getId(), [0,10]);      // por ID de entidad
move([50,20], [0,10]);        // por posición: la entidad más cercana a 50,20

Posiciones de clic

Algunas operaciones dependen del lugar en el que se hace clic en una entidad al usar la herramienta equivalente de forma interactiva. El recorte conserva la parte de la entidad situada en la posición de clic, el redondeo y el biselado actúan sobre los extremos de las entidades más cercanos a las posiciones de clic y el desfase crea paralelas en el lado de la posición de clic.

En la Simple API, cada referencia a una entidad puede ir seguida de una posición de clic. Si una entidad se referencia mediante una posición, esa posición sirve también como posición de clic. Si no se indica ninguna posición de clic, se usa el punto medio de la entidad:

var line = addLine(0,0, 100,0);
var limit = addLine(70,-20, 70,20);

// recortar line con limit, conservar la parte de line en 10,0:
trim(line, [10,0], limit);

Valores devueltos

• Las funciones de creación devuelven la entidad añadida. La entidad se puede pasar a otras funciones o consultar para obtener información (por ejemplo getId(), getLength() o getStartPoint()).
• Las transformaciones (move, rotate, scale, mirror, lengthen, reverse) devuelven la entidad modificada.
• Las demás funciones de modificación (trim, round, bevel, offset, breakOut, autoTrim, divide, explode, stretch) devuelven la transacción que se aplicó al dibujo o undefined si la operación falló.
• Si se pasan formas en lugar de entidades, las transformaciones modifican las formas indicadas y todas las demás funciones devuelven las formas resultantes como array.

Las operaciones fallidas no generan un error. En su lugar, se muestra una advertencia en la consola de scripts, por ejemplo «Entidad no se pueden recortar.».

Crear entidades

addPoint

addPoint(x, y)
addPoint([x, y])

Añade una entidad de punto en la posición indicada.

for (var i=0; i<10; i++) {
    addPoint(i*10, 0);
}

addLine

addLine(x1, y1, x2, y2)
addLine([x1, y1], [x2, y2])

Añade una línea desde el punto inicial hasta el punto final.

// un triángulo:
addLine(0,0, 100,0);
addLine(100,0, 50,80);
addLine(50,80, 0,0);

addXLine

addXLine(x, y, dx, dy)
addXLine([x, y], [dx, dy])

Añade una línea infinita (línea de construcción) que pasa por el punto base x,y con la dirección dx,dy. La dirección se indica de forma relativa al punto base.

// líneas de construcción horizontal y a 45 grados que pasan por 0,0:
addXLine(0,0, 1,0);
addXLine([0,0], [1,1]);

addArc

addArc(cx, cy, radius, startAngle, endAngle)
addArc(cx, cy, radius, startAngle, endAngle, reversed)
addArc([cx, cy], radius, startAngle, endAngle, reversed)

Añade un arco con el centro, el radio, el ángulo inicial y el ángulo final indicados. Los ángulos se expresan en grados. Los arcos van en sentido antihorario desde el ángulo inicial hasta el ángulo final, a menos que reversed sea true (opcional, el valor predeterminado es false).

// cuarto de arco de 0 a 90 grados:
addArc(0,0, 50, 0, 90);

// arco en sentido horario de 0 a 90 grados (los otros tres cuartos):
addArc([0,0], 40, 0, 90, true);

addCircle

addCircle(cx, cy, radius)
addCircle([cx, cy], radius)

Añade un círculo con el centro y el radio indicados.

// círculos concéntricos:
for (var r=10; r<=50; r+=10) {
    addCircle(0,0, r);
}

addEllipse

addEllipse(cx, cy, mx, my, ratio, startParam, endParam, reversed)
addEllipse([cx, cy], [mx, my], ratio, startParam, endParam, reversed)

Añade una elipse o un arco elíptico. mx,my es el punto final del eje mayor, relativo al centro. ratio es la proporción entre el eje menor y el eje mayor. startParam y endParam son los parámetros de la elipse en radianes en los que la elipse empieza y termina. Use 0 y 2*Math.PI para una elipse completa.

// elipse completa con un radio mayor de 50 y un radio menor de 25:
addEllipse(0,0, 50,0, 0.5, 0, 2*Math.PI, false);

// mitad superior de una elipse girada:
addEllipse([0,0], [30,30], 0.3, 0, Math.PI, false);

addPolyline

addPolyline(points, closed, relative)

Añade una polilínea que pasa por los vértices indicados. points es un array de vértices, cada uno indicado como [x, y], [x, y, bulge] o [x, y, bulge, relative]. En lugar de x, y, se puede usar un RVector.

• bulge define la forma del segmento que empieza en este vértice: 0 (predeterminado) para un segmento recto, 1 para un semicírculo en sentido antihorario, -1 para un semicírculo en sentido horario. Otros valores crean segmentos de arco intermedios (la curvatura es la tangente de una cuarta parte del ángulo del arco).
• relative: true si las coordenadas de este vértice son relativas al vértice anterior.
• closed: true para cerrar la polilínea (el valor predeterminado es false).
• relative: true para tratar las coordenadas de todos los vértices como relativas al vértice anterior (el valor predeterminado es false).

// rectángulo cerrado:
addPolyline([[0,0], [100,0], [100,50], [0,50]], true);

// forma de ranura con dos semicírculos:
addPolyline([[0,60], [80,60,1], [80,80], [0,80,1]], true);

// línea en zigzag con coordenadas relativas:
addPolyline([[0,100], [10,10], [10,-10], [10,10], [10,-10]], false, true);

addSpline

addSpline(fitPoints, closed)

Añade una spline que pasa por los puntos de ajuste indicados. fitPoints es un array de arrays [x, y] o de objetos RVector. Si closed es true, la spline es cerrada (periódica).

// spline abierta:
addSpline([[0,0], [30,40], [60,0], [90,40]], false);

// spline cerrada:
addSpline([[0,60], [40,80], [80,60], [40,100]], true);

El tutorial Ejecutar scripts desde un archivo muestra otro ejemplo que traza una curva de Lissajous como spline.

addSimpleText

addSimpleText(text, x, y)
addSimpleText(text, x, y, height, angle, font, vAlign, hAlign, bold, italic)
addSimpleText(text, [x, y], height, angle, font, vAlign, hAlign, bold, italic)

Añade un texto de una sola línea en la posición indicada. Todos los argumentos que siguen a la posición son opcionales:

• height: altura del texto (predeterminado 1)
• angle: ángulo del texto en grados (predeterminado 0)
• font: nombre de la fuente (predeterminado "Standard")
• vAlign: alineación vertical: RS.VAlignTop (predeterminado), RS.VAlignMiddle, RS.VAlignBase o RS.VAlignBottom
• hAlign: alineación horizontal: RS.HAlignLeft (predeterminado), RS.HAlignCenter o RS.HAlignRight
• bold, italic: true para texto en negrita o en cursiva (solo fuentes TrueType)

addSimpleText("Hello World", 0,0);
addSimpleText("Title", [0,20], 10);
addSimpleText("Centered", [50,-20], 5, 0, "Standard", RS.VAlignMiddle, RS.HAlignCenter);
addSimpleText("Rotated", 100,0, 5, 45);

addSolid

addSolid(x1, y1, x2, y2, x3, y3, x4, y4)
addSolid([x1, y1], [x2, y2], [x3, y3], [x4, y4])

Añade un área de relleno sólido con tres o cuatro esquinas. Tenga en cuenta que las esquinas de un sólido de cuatro lados se indican en orden de zigzag: primera esquina, segunda esquina, después la esquina opuesta a la segunda y la esquina opuesta a la primera. Para crear un triángulo, indique dos veces la tercera esquina.

// cuadrado relleno:
addSolid(0,0, 50,0, 0,50, 50,50);

// triángulo relleno:
addSolid([60,0], [110,0], [85,50], [85,50]);

Añadir formas, entidades y objetos

Las siguientes funciones añaden al dibujo objetos creados con la API completa de QCAD. Son útiles cuando las funciones de creación especializadas anteriores no cubren un caso determinado.

addShape

addShape(shape)
addShape(shape, color, linetype, lineweight)

Añade la forma indicada (RLine, RArc, RCircle, REllipse, RPolyline, RSpline, RPoint, …) como nueva entidad en la capa actual. Opcionalmente, se pueden indicar un color (RColor), un tipo de línea (nombre o ID) y un grosor de línea (por ejemplo RLineweight.Weight050). De forma predeterminada se usan el color actual, el tipo de línea ByLayer y el grosor de línea ByLayer.

addShape(new RLine(new RVector(0,0), new RVector(100,0)));
addShape(new RCircle(new RVector(50,0), 20), new RColor("red"));
addShape(new RLine(new RVector(0,-20), new RVector(100,-20)), new RColor("blue"), "DASHED", RLineweight.Weight050);

addShapes

addShapes(shapes)

Añade todas las formas del array indicado como nuevas entidades.

var shapes = [];
for (var i=0; i<5; i++) {
    shapes.push(new RCircle(new RVector(i*20, 0), 8));
}
addShapes(shapes);

addEntity

addEntity(entity)
addEntity(entity, color, linetype, lineweight)

Añade la entidad indicada (REntity) al dibujo. Si no se indica ningún color, se usa el color actual.

var doc = getDocument();
var data = new RLineData(new RVector(0,0), new RVector(100,50));
var entity = new RLineEntity(doc, data);
addEntity(entity);

addObject

addObject(object)

Añade cualquier objeto (entidad, capa, bloque, …) al dibujo y devuelve el objeto añadido.

// añadir un bloque llamado "Marker" con una cruz:
var doc = getDocument();
var block = addObject(new RBlock(doc, "Marker", new RVector(0,0)));

var l1 = new RLineEntity(doc, new RLineData(new RVector(-5,0), new RVector(5,0)));
l1.setBlockId(block.getId());
addEntity(l1);
var l2 = new RLineEntity(doc, new RLineData(new RVector(0,-5), new RVector(0,5)));
l2.setBlockId(block.getId());
addEntity(l2);

// insertar el bloque dos veces:
addEntity(new RBlockReferenceEntity(doc, new RBlockReferenceData(block.getId(), new RVector(0,0), new RVector(1,1), 0.0)));
addEntity(new RBlockReferenceEntity(doc, new RBlockReferenceData(block.getId(), new RVector(50,0), new RVector(2,2), 0.0)));

deleteObject

deleteObject(object)

Elimina el objeto indicado del dibujo. Para eliminar entidades, la función deleteEntity suele ser más práctica.

var line = addLine(0,0, 100,0);
deleteObject(line);

Capas y atributos

addLayer

addLayer(name)
addLayer(name, color, linetype, lineweight)

Añade una nueva capa con el nombre indicado. Opcionalmente, se pueden indicar el nombre del color (predeterminado "white", que se muestra en negro sobre un fondo blanco), el nombre del tipo de línea (predeterminado "CONTINUOUS") y el grosor de línea (predeterminado RLineweight.Weight000). Devuelve la nueva capa o undefined si ya existe una capa con el nombre indicado.

addLayer("Construction", "gray", "DASHED");
addLayer("Contour", "blue", "CONTINUOUS", RLineweight.Weight050);

hasLayer

hasLayer(name)

Devuelve true si en el dibujo existe una capa con el nombre indicado.

if (!hasLayer("Holes")) {
    addLayer("Holes", "red");
}

setCurrentLayer

setCurrentLayer(name)

Establece la capa actual. Todas las entidades que se añadan a continuación se colocan en esta capa.

addLayer("Holes", "red");
setCurrentLayer("Holes");
addCircle(0,0, 5);
addCircle(50,0, 5);
setCurrentLayer("0");

setCurrentColor

setCurrentColor(color)
setCurrentColor(r, g, b)

Establece el color de las entidades que se añadan a continuación. El color se puede indicar como objeto RColor o como valores de rojo, verde y azul (0-255). Use new RColor(RColor.ByLayer) para restablecer el color a «Por Capa».

setCurrentColor(255, 0, 0);
addCircle(0,0, 10);
setCurrentColor(new RColor("blue"));
addCircle(30,0, 10);
setCurrentColor(new RColor(RColor.ByLayer));
addCircle(60,0, 10);

Consultar entidades

getEntity

getEntity(id)
getEntity(entity)
getEntity(x, y)
getEntity([x, y])

Devuelve la entidad correspondiente a la referencia indicada, es decir, la entidad con el ID indicado, el estado actual de la entidad indicada o la entidad más cercana a la posición indicada. Devuelve undefined si no se encuentra ninguna entidad.

var circle = addCircle(0,0, 20);
move(circle, [10,0]);

// circle todavía contiene el centro antiguo, getEntity devuelve el estado actual:
getEntity(circle).getCenter();     // devuelve 10,0

// entidad más cercana a 30,0:
getEntity(30,0).getRadius();       // devuelve 20

getShape

getShape(id)
getShape(entity)
getShape(x, y)
getShape([x, y])

Devuelve la geometría de la entidad indicada como forma (RLine para una línea, RArc para un arco, RPolyline para una polilínea, …). Las formas se pueden usar para cálculos geométricos sin modificar el dibujo.

addPolyline([[0,0], [100,0], [100,50]], false);

var pl = getShape(50,0);
pl.getLength();                    // devuelve 150

getClosestEntity

getClosestEntity(x, y)
getClosestEntity([x, y], range)

Devuelve la entidad más cercana a la posición indicada. Si se indica range, solo se tienen en cuenta las entidades que se encuentran dentro de esa distancia de la posición. Devuelve undefined si no se encuentra ninguna entidad.

addLine(0,0, 100,0);
addLine(0,50, 100,50);

getClosestEntity(50,10).getStartPoint();     // devuelve 0,0
getClosestEntity([50,25], 5);               // devuelve undefined

getEntityShape

getEntityShape(entity, position)

Devuelve la forma del objeto de entidad indicado. Para entidades complejas compuestas por varias formas (referencias de bloque, rayados, acotaciones, textos), se devuelve la forma más cercana a la posición indicada. La posición es opcional.

// una referencia de bloque de un bloque con un rectángulo:
var doc = getDocument();
var block = addObject(new RBlock(doc, "Box", new RVector(0,0)));
var pl = new RPolylineEntity(doc, new RPolylineData());
pl.setShape(new RPolyline([new RVector(0,0), new RVector(40,0), new RVector(40,20), new RVector(0,20)], true));
pl.setBlockId(block.getId());
addEntity(pl);
var ref = addEntity(new RBlockReferenceEntity(doc, new RBlockReferenceData(block.getId(), new RVector(0,0), new RVector(1,1), 0.0)));

// forma de la referencia de bloque cerca de 40,10 (el rectángulo):
var s = getEntityShape(getEntity(ref), new RVector(41,10));
s.getLength();                     // devuelve 120

getIntersectionPoints

getIntersectionPoints(entity1, entity2)
getIntersectionPoints(entity1, entity2, limited)

Devuelve un array con los puntos de intersección de las dos entidades o formas indicadas. Las entidades se pueden indicar como objetos de entidad, ID de entidad o formas. Si limited es false, las entidades se tratan como si fueran infinitas (líneas prolongadas, arcos como círculos completos). El valor predeterminado es true.

var line = addLine(-50,0, 50,0);
var circle = addCircle(0,0, 30);
var ips = getIntersectionPoints(line, circle);

// marcar las intersecciones con círculos pequeños:
for (var i=0; i<ips.length; i++) {
    addCircle(ips[i], 2);
}

isPosition y toVector

isPosition(value)
toVector(value)

isPosition devuelve true si el valor indicado es una posición (RVector o array de dos o tres números). toVector convierte una posición indicada como array en un RVector. Estas funciones son útiles al escribir sus propias funciones que acepten posiciones de la misma manera que la Simple API.

function addCross(pos, size) {
    var p = toVector(pos);
    addLine(p.x-size, p.y, p.x+size, p.y);
    addLine(p.x, p.y-size, p.x, p.y+size);
}

addCross([0,0], 5);
addCross(new RVector(20,0), 5);
isPosition([1,2]);                 // devuelve true
isPosition("abc");                 // devuelve false

Modificar entidades

Transformaciones

move

move(entity, dx, dy)
move(entity, [dx, dy])

Mueve la entidad indicada según el desplazamiento indicado.

var c = addCircle(0,0, 10);
move(c, 50,0);

rotate

rotate(entity, angle)
rotate(entity, angle, cx, cy)
rotate(entity, angle, [cx, cy])

Gira la entidad indicada el ángulo indicado en grados alrededor del centro indicado. Si no se indica ningún centro, la entidad se gira alrededor del origen 0,0.

// un abanico de líneas, giradas alrededor de 0,0:
for (var a=0; a<360; a+=30) {
    var l = addLine(10,0, 50,0);
    rotate(l, a);
}

// girar un cuadrado alrededor de su centro:
var sq = addPolyline([[100,0], [120,0], [120,20], [100,20]], true);
rotate(sq, 45, [110,10]);

scale

scale(entity, factor)
scale(entity, factor, cx, cy)
scale(entity, factor, [cx, cy])
scale(entity, [sx, sy], [cx, cy])

Escala la entidad indicada según el factor indicado. El punto de enfoque (el punto que permanece en su sitio) es de forma predeterminada el origen 0,0. Se pueden indicar factores diferentes para X e Y como array [sx, sy]. Tenga en cuenta que algunas entidades, como los círculos y los arcos, no se pueden escalar con factores diferentes en X e Y.

var sq = addPolyline([[0,0], [10,0], [10,10], [0,10]], true);
scale(sq, 3);

var pl = addPolyline([[50,0], [60,0], [60,10], [50,10]], true);
scale(pl, [2,1], [50,0]);

mirror

mirror(entity, x1, y1, x2, y2)
mirror(entity, [x1, y1], [x2, y2])
mirror(entity, new RLine(...))

Refleja en espejo la entidad indicada respecto al eje definido por dos puntos.

var pl = addPolyline([[10,0], [40,0], [40,30]], false);
// reflejar en espejo respecto al eje Y:
mirror(pl, 0,0, 0,100);

Para conservar el original y crear una copia reflejada, añada primero una copia de la entidad:

var arc = addArc(20,0, 10, 0, 180);
var copy = addShape(getShape(arc));
mirror(copy, [0,-10], [0,10]);

Recortar y alargar

trim

trim(trimEntity, limitingEntity)
trim(trimEntity, trimPos, limitingEntity, limitingPos)
trim(trimEntity, trimPos, limitingEntity, limitingPos, trimBoth)
trim(trimPos, limitingPos)

Recorta la entidad trimEntity con la entidad limitante limitingEntity. Se conserva la parte de la entidad recortada situada en la posición de clic trimPos. Si las dos entidades no se cortan, la entidad se alarga hasta la entidad limitante. Si hay varias intersecciones, se usa la más cercana a la posición de clic limitingPos. Si trimBoth es true, ambas entidades se recortan entre sí.

var line = addLine(0,0, 100,0);
var limit = addLine(70,-20, 70,20);

// conservar la parte izquierda, ahora line termina en 70,0:
trim(line, [10,0], limit);

// alargar una línea hasta un círculo:
var line = addLine(0,0, 50,0);
var circle = addCircle(100,0, 20);

// alargar hasta la intersección con el círculo más cercana a 80,0:
trim(line, [25,0], circle, [80,0]);      // ahora line termina en 80,0

trimBoth

trimBoth(entity1, entity2)
trimBoth(entity1, pos1, entity2, pos2)
trimBoth(pos1, pos2)

Recorta o alarga ambas entidades hasta su punto de intersección. Es un atajo para trim con trimBoth establecido en true.

// dos líneas que no se tocan se alargan para formar una esquina en 100,0:
var a = addLine(0,0, 80,0);
var b = addLine(100,20, 100,100);
trimBoth(a, b);

lengthen

lengthen(entity, amount)
lengthen(entity, start, amount)
lengthen(entity, pos, amount)
lengthen(pos, amount)

Alarga la entidad indicada en la cantidad indicada. Las cantidades negativas acortan la entidad. De forma predeterminada, la entidad se alarga por su punto final. Pase true para start si desea alargarla por su punto inicial, o pase una posición cercana al extremo que se debe alargar.

var line = addLine(0,0, 100,0);
lengthen(line, 20);              // ahora line termina en 120,0
lengthen(line, true, -10);       // ahora line empieza en 10,0

var arc = addArc(0,50, 30, 0, 90);
lengthen(arc, [30,50], 10);      // alargar el arco por su punto inicial

breakOut

breakOut(entity, pos)
breakOut(entity, pos, removeSegment)
breakOut(pos)

Rompe el segmento de la entidad indicada situado en la posición indicada. El segmento termina en las intersecciones más cercanas con otras entidades a ambos lados de la posición. Si en un lado no hay ninguna intersección, el segmento se extiende hasta el extremo de la entidad. Si removeSegment es true (predeterminado), el segmento se elimina. De lo contrario, se conserva como una entidad independiente.

var line = addLine(0,0, 100,0);
addLine(30,-10, 30,10);
addLine(70,-10, 70,10);

// eliminar la parte de la línea entre 30,0 y 70,0:
breakOut(line, [50,0]);

autoTrim

autoTrim(entity, pos)
autoTrim(pos)

Lo contrario de breakOut: conserva solo el segmento de la entidad indicada situado en la posición indicada y elimina el resto. El segmento termina en las intersecciones más cercanas con otras entidades a ambos lados de la posición.

var line = addLine(0,0, 100,0);
addLine(30,-10, 30,10);
addLine(70,-10, 70,10);

// conservar solo la parte entre 30,0 y 70,0:
autoTrim(line, [50,0]);

divide

divide(entity, pos)
divide(entity, pos1, pos2)
divide(pos)

Divide la entidad indicada en la posición indicada. Una entidad abierta (línea, arco, polilínea abierta, …) se divide en dos partes en una posición o en tres partes en dos posiciones. Las entidades cerradas (círculos, elipses completas, polilíneas cerradas) requieren dos posiciones y se dividen en dos partes.

var line = addLine(0,0, 100,0);
divide(line, [40,0]);            // dos líneas: 0..40 y 40..100

var circle = addCircle(0,50, 20);
divide(circle, [20,50], [-20,50]);   // dos semicírculos

Esquinas

round

round(entity1, entity2, radius)
round(entity1, pos1, entity2, pos2, radius)
round(entity1, pos1, entity2, pos2, radius, trim)
round(pos1, pos2, radius)

Redondea la esquina entre dos entidades con un arco del radio indicado (empalme). Las posiciones de clic indican qué extremos de las entidades se redondean. Si trim es true (predeterminado), ambas entidades se recortan con el arco de redondeo.

// un rectángulo con esquinas redondeadas:
var l1 = addLine(0,0, 100,0);
var l2 = addLine(100,0, 100,50);
var l3 = addLine(100,50, 0,50);
var l4 = addLine(0,50, 0,0);

round(l1, l2, 10);
round(l2, l3, 10);
round(l3, l4, 10);
round(l4, l1, 10);

Las esquinas de una polilínea también se pueden redondear, pasando dos veces la misma polilínea con una posición de clic en cada uno de los dos segmentos:

var pl = addPolyline([[0,0], [100,0], [100,50]], false);
round(pl, [50,0], pl, [100,25], 10);

bevel y chamfer

bevel(entity1, entity2, distance)
bevel(entity1, entity2, distance1, distance2)
bevel(entity1, pos1, entity2, pos2, distance1, distance2)
bevel(entity1, pos1, entity2, pos2, distance1, distance2, trim)
bevel(pos1, pos2, distance)

Bisela la esquina entre dos entidades con una línea recta (chaflán). distance1 es la distancia de la línea de chaflán a la esquina a lo largo de la primera entidad, distance2 a lo largo de la segunda entidad (predeterminado distance1). Si trim es true (predeterminado), ambas entidades se recortan con la línea de chaflán. chamfer es un alias de bevel.

var a = addLine(0,0, 100,0);
var b = addLine(100,0, 100,50);
bevel(a, b, 10);

var c = addLine(0,100, 100,100);
var d = addLine(100,100, 100,150);
chamfer(c, d, 20, 10);

offset

offset(entity, distance)
offset(entity, distance, number)
offset(entity, distance, number, side)
offset(entity, sidePos, distance)
offset(entity, sidePos, distance, number)

Crea paralelas a líneas, arcos y círculos concéntricos o curvas desfasadas de elipses y otras entidades. number es el número de paralelas que se deben crear (predeterminado 1). Las paralelas se crean a ambos lados de la entidad, a menos que se indique un lado, ya sea como posición sidePos junto a la entidad o como side (RS.LeftHand, RS.RightHand o RS.BothSides). El desfase de polilíneas y splines solo está disponible en QCAD Professional.

var line = addLine(0,0, 100,0);
offset(line, 5);                 // una paralela a cada lado

var line2 = addLine(0,30, 100,30);
offset(line2, 5, 2, RS.LeftHand);    // dos paralelas en el lado izquierdo (encima)

var circle = addCircle(50,80, 10);
offset(circle, [50,95], 3, 4);   // cuatro círculos concéntricos por fuera

reverse

reverse(entity)
reverse(x, y)

Invierte la dirección de la entidad indicada, es decir, intercambia su punto inicial y su punto final.

var line = addLine(0,0, 100,0);
line = reverse(line);
line.getStartPoint();            // devuelve 100,0

explode

explode(entity)
explode(entity, options)
explode(x, y)

Explota la entidad indicada en entidades más simples: las polilíneas en líneas y arcos, las referencias de bloque en su contenido, los textos en líneas y splines, las acotaciones y los rayados en líneas, arcos, etc. La entidad original se elimina.

options es un objeto opcional con ajustes que, de lo contrario, se toman de las preferencias de la aplicación, por ejemplo { splineSegments: 64, textToPolylines: true }. Las opciones admitidas son: splineTolerance, splineSegments, ellipseSegments, splinesToLineSegments, textToPolylines, textSplineToLineOrArc, multilineTextToSimpleText y circlesToPolylines.

var pl = addPolyline([[0,0], [100,0,1], [100,50], [0,50]], true);
explode(pl);                     // tres líneas y un arco

stretch

stretch(x1, y1, x2, y2, dx, dy)
stretch([x1, y1], [x2, y2], [dx, dy])
stretch(area, offset)

Estira todas las entidades del área rectangular definida por dos esquinas según el desplazamiento indicado. Las entidades que se encuentran completamente dentro del área se mueven, y las entidades que cruzan el borde del área se estiran (solo se mueven los puntos finales situados dentro del área). El área también se puede indicar como RBox o como forma RPolyline cerrada. Si hay entidades seleccionadas en el dibujo, solo se estiran las entidades seleccionadas.

// un rectángulo formado por líneas:
addLine(0,0, 100,0);
addLine(100,0, 100,50);
addLine(100,50, 0,50);
addLine(0,50, 0,0);

// hacer el rectángulo 50 unidades más ancho estirando su lado derecho:
stretch([80,-10], [120,60], [50,0]);

deleteEntity

deleteEntity(entity)
deleteEntity(id)
deleteEntity(x, y)

Elimina la entidad indicada del dibujo.

var l1 = addLine(0,0, 100,0);
var l2 = addLine(0,10, 100,10);
addLine(0,20, 100,20);

deleteEntity(l1);                // por entidad
deleteEntity(l2.getId());        // por ID de entidad
deleteEntity(50,20);             // por posición

paste

paste(sourceDocument, destination, offset, scale, rotation,
      flipHorizontal, flipVertical, toCurrentLayer, overwriteLayers, overwriteBlocks)

Pega el contenido del documento sourceDocument en la interfaz de documento destination o en el dibujo actual si destination es undefined. El contenido pegado se mueve según offset, se escala según scale y se gira rotation grados. Todos los argumentos son obligatorios:

• flipHorizontal, flipVertical: true para voltear el contenido
• toCurrentLayer: true para pegar todas las entidades en la capa actual
• overwriteLayers, overwriteBlocks: true para sobrescribir las capas o bloques existentes con el mismo nombre

// crear un símbolo en un documento fuera de pantalla:
var symbol = createDocument();
startTransaction(symbol);
addCircle(0,0, 10);
addLine(-10,0, 10,0);
addLine(0,-10, 0,10);
endTransaction();

// pegarlo tres veces en el dibujo actual:
for (var i=0; i<3; i++) {
    paste(symbol, undefined, [i*50, 0], 1+i*0.5, i*15, false, false, false, false, false);
}

Transacciones

startTransaction y endTransaction

startTransaction()
startTransaction(document)
endTransaction()

De forma predeterminada, cada llamada a la Simple API se aplica inmediatamente al dibujo y se puede deshacer individualmente. Entre startTransaction() y endTransaction(), todos los cambios se recopilan y se aplican juntos cuando se llama a endTransaction. Esto tiene dos ventajas:

• Es mucho más rápido al añadir muchas entidades.
• Todos los cambios se pueden deshacer en un solo paso.

Si se pasa un documento (RDocument) o una interfaz de documento (RDocumentInterface) a startTransaction, todos los cambios se aplican a ese documento en lugar de al dibujo actual. Esto es útil para crear dibujos en segundo plano, por ejemplo para exportarlos a un archivo (véase createDocumentInterface).

startTransaction();
for (var x=0; x<=200; x+=10) {
    for (var y=0; y<=200; y+=10) {
        addPoint(x, y);
    }
}
endTransaction();

Tenga en cuenta lo siguiente al trabajar con transacciones:

• Dentro de una transacción, los cambios todavía no forman parte del dibujo. Las funciones de modificación como trim o round no pueden hacer referencia a entidades añadidas en la misma transacción.
• Las entidades devueltas por las funciones de creación dentro de una transacción no tienen un ID válido, ni siquiera después de endTransaction. Para modificar estas entidades más adelante, haga referencia a ellas mediante su posición.
• Todas las entidades añadidas dentro de una transacción se colocan en la capa que es la actual cuando se llama a endTransaction. Establezca la capa actual antes de iniciar la transacción y use transacciones separadas para capas diferentes.

startTransaction();
addLine(0,0, 100,0);
addLine(100,0, 100,50);
endTransaction();

// hacer referencia a las nuevas líneas mediante su posición para redondear la esquina:
round([50,0], [100,25], 10);

getTransactionDocument y getTransactionDocumentInterface

getTransactionDocument()
getTransactionDocumentInterface()

Devuelven el documento o la interfaz de documento al que se aplica la transacción actual. Fuera de las transacciones, se devuelven el documento y la interfaz de documento actuales.

var doc = createDocument();
startTransaction(doc);
addLine(0,0, 10,0);
getTransactionDocument() === doc;    // devuelve true
endTransaction();

getOperation

getOperation()

Devuelve la operación (RAddObjectsOperation) de la transacción actual. Fuera de una transacción, se devuelve una nueva operación que se debe aplicar explícitamente. Está pensada para un uso avanzado, por ejemplo para combinar llamadas a la Simple API con la API completa de QCAD.

startTransaction();
addCircle(0,0, 10);
var doc = getTransactionDocument();
var e = new RLineEntity(doc, new RLineData(new RVector(-10,0), new RVector(10,0)));
getOperation().addObject(e);
endTransaction();

Vista

autoZoom

autoZoom()

Hace zoom en la vista actual de modo que todo el dibujo sea visible.

addCircle(1000,1000, 500);
autoZoom();

zoomTo

zoomTo(entity)
zoomTo(entity, margin)
zoomTo([x1, y1], [x2, y2])
zoomTo([x1, y1], [x2, y2], margin)
zoomTo(box, margin)

Hace zoom a la entidad, la forma o el área rectangular indicada. margin es el margen alrededor del área en píxeles (predeterminado 10).

addCircle(0,0, 100);
var small = addCircle(80,0, 2);
zoomTo(small, 50);

zoomTo([0,0], [100,100]);

Documentos y aplicación

getMainWindow

getMainWindow()

Devuelve la ventana de la aplicación QCAD (RMainWindowQt).

getMainWindow().windowTitle;

getDocumentInterface

getDocumentInterface()

Devuelve la interfaz de documento (RDocumentInterface) del dibujo actual. La interfaz de documento conecta un documento con sus vistas y proporciona funciones para importar y exportar archivos, aplicar operaciones, deshacer y rehacer.

addLine(0,0, 100,0);
getDocumentInterface().undo();       // vuelve a eliminar la línea

getDocument

getDocument()

Devuelve el documento actual (RDocument). El documento contiene todas las entidades, capas, bloques, etc. de un dibujo y proporciona funciones para consultarlos.

addLine(0,0, 100,0);
addCircle(0,0, 10);
getDocument().queryAllEntities().length;     // número de entidades en el dibujo

getGraphicsView

getGraphicsView()

Devuelve la vista actual o la última vista activa (RGraphicsView) del dibujo actual.

addCircle(0,0, 50);
getGraphicsView().autoZoom();

createDocument

createDocument()

Crea un nuevo documento vacío en memoria que no se muestra en ninguna ventana. Un documento fuera de pantalla de este tipo se puede rellenar mediante una transacción y después pegar en un dibujo (véase paste).

var doc = createDocument();
startTransaction(doc);
addLine(0,0, 100,0);
addLine(100,0, 100,100);
endTransaction();

doc.queryAllEntities().length;       // devuelve 2

createDocumentInterface

createDocumentInterface()

Crea un nuevo documento vacío en memoria junto con una interfaz de documento. La interfaz de documento se puede usar para importar o exportar archivos.

var di = createDocumentInterface();
startTransaction(di);
addCircle(0,0, 50);
addSimpleText("Created by script", [-40,-60], 5);
endTransaction();

di.exportFile(QDir.homePath() + "/simple_api_example.dxf", "R27 (2013) DXF");

disableInput, enableInput y isInputEnabled

disableInput()
enableInput()
isInputEnabled()

disableInput desactiva la ventana de la aplicación QCAD para impedir la entrada del usuario, por ejemplo durante operaciones largas o animaciones. enableInput vuelve a activar la ventana de la aplicación e isInputEnabled devuelve true si la entrada del usuario está activada en ese momento. Asegúrese siempre de volver a activar la entrada al final de su script.

update

update()

Procesa los eventos pendientes para que la interfaz de usuario se actualice durante las operaciones largas. La entrada del usuario debe desactivarse con disableInput antes de llamar a update.

sleep

sleep(milliseconds)

Pausa el script durante el tiempo indicado en milisegundos, manteniendo actualizada la interfaz de usuario. La entrada del usuario debe desactivarse con disableInput antes de llamar a sleep.

El siguiente ejemplo usa disableInput, sleep y enableInput para mostrar una animación sencilla:

disableInput();
var c = addCircle(0,0, 10);
autoZoom();
for (var i=0; i<20; i++) {
    c = move(c, 5,0);
    sleep(50);
}
enableInput();

warning

warning(message)

Muestra un mensaje de advertencia. En la consola de scripts, las advertencias se muestran en el historial de comandos. En caso contrario, las advertencias se imprimen en la consola del sistema.

if (getDocument().queryAllEntities().length===0) {
    warning("The drawing is empty.");
}

Entrada del usuario

Las siguientes funciones muestran un cuadro de diálogo sencillo para pedir un valor al usuario. Si el usuario cancela el cuadro de diálogo, se devuelve undefined.

getInt

getInt(title, prompt, value, step, min, max)

Pide al usuario un número entero. value es el valor inicial (predeterminado 0), step el incremento del campo numérico (predeterminado 1), min y max el rango permitido.

var n = getInt("Circles", "Number of circles:", 5, 1, 1, 100);
if (isNull(n)) {
    warning("Canceled.");
}
else {
    for (var i=1; i<=n; i++) {
        addCircle(0,0, i*10);
    }
}

getDouble

getDouble(title, prompt, value, decimals, min, max)

Pide al usuario un número. value es el valor inicial (predeterminado 0), decimals el número de decimales mostrados (predeterminado 1), min y max el rango permitido.

var r = getDouble("Circle", "Radius:", 25.0, 2, 0.01, 1000);
if (!isNull(r)) {
    addCircle(0,0, r);
}

getText

getText(title, prompt, text)

Pide al usuario un texto. text es el texto inicial (predeterminado vacío).

var t = getText("Label", "Text:", "Hello");
if (!isNull(t)) {
    addSimpleText(t, 0,0, 10);
}

getItem

getItem(title, prompt, items, index, separator)

Permite al usuario elegir un elemento de una lista desplegable. items es una cadena con todos los elementos separados por separator (predeterminado ","). index es el índice del elemento seleccionado inicialmente (predeterminado 0). Devuelve el elemento elegido o undefined si se canceló el cuadro de diálogo.

var shape = getItem("Shape", "Shape to add:", "Circle,Square,Triangle", 0);
if (shape==="Circle") {
    addCircle(0,0, 50);
}
else if (shape==="Square") {
    addPolyline([[-50,-50], [50,-50], [50,50], [-50,50]], true);
}
else if (shape==="Triangle") {
    addPolyline([[-50,-50], [50,-50], [0,50]], true);
}

Ejemplo: una brida

Este ejemplo combina varias funciones de la Simple API para dibujar una brida con un círculo de taladros, agujeros para pernos en una capa separada y una abertura rectangular con esquinas redondeadas:

addLayer("Center Lines", "gray", "CENTER");
addLayer("Holes", "red");

// contorno:
setCurrentLayer("0");
addCircle(0,0, 100);

// círculo de taladros y líneas de centro:
setCurrentLayer("Center Lines");
addCircle(0,0, 75);
addLine(-110,0, 110,0);
addLine(0,-110, 0,110);

// agujeros para pernos, añadidos en una sola transacción:
setCurrentLayer("Holes");
startTransaction();
for (var a=0; a<360; a+=45) {
    var angle = a * Math.PI / 180;
    addCircle(75*Math.cos(angle), 75*Math.sin(angle), 8);
}
endTransaction();

// abertura cuadrada redondeada en el centro:
setCurrentLayer("0");
var l1 = addLine(-30,-30, 30,-30);
var l2 = addLine(30,-30, 30,30);
var l3 = addLine(30,30, -30,30);
var l4 = addLine(-30,30, -30,-30);
round(l1, l2, 8);
round(l2, l3, 8);
round(l3, l4, 8);
round(l4, l1, 8);

autoZoom();

Las líneas de la abertura se añaden sin transacción, de modo que se pueden pasar directamente a round. Los agujeros para pernos se añaden en una transacción, lo que es más rápido y permite deshacerlos en un solo paso.