La Simple API

Introduzione

La QCAD Simple API è un piccolo insieme di funzioni di script globali che semplificano attività comuni come l’aggiunta di entità a un disegno, l’interrogazione delle entità e la loro modifica (spostare, tagliare, raccordare, creare offset, …). È pensata principalmente per l’uso nella Script Shell e per brevi script procedurali eseguiti da un file, ma può essere utilizzata da qualsiasi script.

La Simple API copre solo una piccola parte dell’API completa di QCAD. Poiché è scritta a sua volta in ECMAScript (JavaScript), è anche un buon punto di partenza per imparare come funziona l’API di QCAD sottostante. Il codice sorgente si trova nei file scripts/simple.js e scripts/simple_*.js del codice sorgente di QCAD.

Utilizzare la Simple API

Nella Script Shell (Varie > Sviluppo > Script Shell) e negli script avviati con Varie > Sviluppo > Esegui script, tutte le funzioni della Simple API sono disponibili direttamente. Digitare ad esempio:

addLine(0,0, 100,100);

Nei propri file di script, ad esempio nelle azioni di script interattive o negli strumenti da riga di comando, includere prima il file simple.js:

include("scripts/simple.js");

addLine(0,0, 100,100);

Tutte le funzioni agiscono sul disegno attualmente aperto nella finestra dell’applicazione QCAD, a meno che non si utilizzi una transazione per reindirizzarle a un altro documento (vedere Transazioni).

Tutti gli esempi di questa pagina possono essere incollati nella Script Shell di un disegno vuoto. Ogni esempio crea le entità di cui ha bisogno. Utilizzare Vista > Zoom automatico o la funzione autoZoom() per vedere il risultato.

Convenzioni

Coordinate

Le posizioni possono essere passate in tre modi diversi:

• Come due numeri separati: addLine(0,0, 100,100)
• Come array di due numeri: addLine([0,0], [100,100])
• Come oggetto vettore: addLine(new RVector(0,0), new RVector(100,100))

Gli angoli sono sempre indicati in gradi, ad eccezione dei parametri iniziale e finale delle ellissi, che sono indicati in radianti.

Riferimenti alle entità

Le funzioni che operano su un’entità esistente accettano l’entità in varie forme:

• Un ID di entità (numero), ad esempio 1234.
• Un oggetto entità come restituito dalle funzioni di creazione, ad esempio il valore restituito da addLine(...).
• Una posizione nel disegno ([x,y] o RVector): viene utilizzata l’entità più vicina alla posizione indicata.
• Una forma (ad esempio new RLine(0,0, 100,0)): l’operazione viene applicata solo alla forma, il disegno non viene modificato.

var l = addLine(0,0, 100,0);
move(l, [0,10]);              // tramite oggetto entità
move(l.getId(), [0,10]);      // tramite ID di entità
move([50,20], [0,10]);        // tramite posizione: l'entità più vicina a 50,20

Posizioni di clic

Alcune operazioni dipendono dal punto in cui si fa clic su un’entità quando si utilizza lo strumento equivalente in modo interattivo. Il taglio mantiene la parte dell’entità nella posizione di clic, il raccordo e lo smusso agiscono sulle estremità delle entità più vicine alle posizioni di clic e l’offset crea parallele sul lato della posizione di clic.

Nella Simple API, una posizione di clic può seguire ogni riferimento a un’entità. Se un’entità è referenziata tramite una posizione, tale posizione funge anche da posizione di clic. Se non viene indicata alcuna posizione di clic, viene utilizzato il punto medio dell’entità:

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

// tagliare line su limit, mantenere la parte di line in 10,0:
trim(line, [10,0], limit);

Valori restituiti

• Le funzioni di creazione restituiscono l’entità aggiunta. L’entità può essere passata ad altre funzioni o interrogata per ottenere informazioni (ad esempio getId(), getLength() o getStartPoint()).
• Le trasformazioni (move, rotate, scale, mirror, lengthen, reverse) restituiscono l’entità modificata.
• Le altre funzioni di modifica (trim, round, bevel, offset, breakOut, autoTrim, divide, explode, stretch) restituiscono la transazione applicata al disegno oppure undefined se l’operazione non è riuscita.
• Se vengono passate forme invece di entità, le trasformazioni modificano le forme indicate e tutte le altre funzioni restituiscono le forme risultanti come array.

Le operazioni non riuscite non generano un errore. Viene invece mostrato un avviso nella Script Shell, ad esempio «Entità non può essere tagliato.».

Creare entità

addPoint

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

Aggiunge un’entità punto nella posizione indicata.

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

addLine

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

Aggiunge una linea dal punto iniziale al punto finale.

// un triangolo:
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])

Aggiunge una linea infinita (linea di costruzione) passante per il punto base x,y con la direzione dx,dy. La direzione è indicata relativamente al punto base.

// linee di costruzione orizzontale e a 45 gradi passanti per 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)

Aggiunge un arco con il centro, il raggio, l’angolo iniziale e l’angolo finale indicati. Gli angoli sono in gradi. Gli archi vanno in senso antiorario dall’angolo iniziale all’angolo finale, a meno che reversed non sia true (facoltativo, il valore predefinito è false).

// quarto d'arco da 0 a 90 gradi:
addArc(0,0, 50, 0, 90);

// arco in senso orario da 0 a 90 gradi (gli altri tre quarti):
addArc([0,0], 40, 0, 90, true);

addCircle

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

Aggiunge un cerchio con il centro e il raggio indicati.

// cerchi concentrici:
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)

Aggiunge un’ellisse o un arco d’ellisse. mx,my è il punto finale dell’asse maggiore, relativo al centro. ratio è il rapporto tra l’asse minore e l’asse maggiore. startParam e endParam sono i parametri dell’ellisse in radianti in cui l’ellisse inizia e termina. Utilizzare 0 e 2*Math.PI per un’ellisse completa.

// ellisse completa con raggio maggiore di 50 e raggio minore di 25:
addEllipse(0,0, 50,0, 0.5, 0, 2*Math.PI, false);

// metà superiore di un'ellisse ruotata:
addEllipse([0,0], [30,30], 0.3, 0, Math.PI, false);

addPolyline

addPolyline(points, closed, relative)

Aggiunge una polilinea passante per i vertici indicati. points è un array di vertici, ciascuno indicato come [x, y], [x, y, bulge] o [x, y, bulge, relative]. Al posto di x, y è possibile utilizzare un RVector.

• bulge definisce la forma del segmento che inizia in questo vertice: 0 (predefinito) per un segmento rettilineo, 1 per un semicerchio in senso antiorario, -1 per un semicerchio in senso orario. Altri valori creano segmenti d’arco intermedi (la bombatura è la tangente di un quarto dell’angolo dell’arco).
• relative: true se le coordinate di questo vertice sono relative al vertice precedente.
• closed: true per chiudere la polilinea (il valore predefinito è false).
• relative: true per considerare le coordinate di tutti i vertici come relative al vertice precedente (il valore predefinito è false).

// rettangolo chiuso:
addPolyline([[0,0], [100,0], [100,50], [0,50]], true);

// forma ad asola con due semicerchi:
addPolyline([[0,60], [80,60,1], [80,80], [0,80,1]], true);

// linea a zigzag con coordinate relative:
addPolyline([[0,100], [10,10], [10,-10], [10,10], [10,-10]], false, true);

addSpline

addSpline(fitPoints, closed)

Aggiunge una spline passante per i punti di adattamento indicati. fitPoints è un array di array [x, y] o di oggetti RVector. Se closed è true, la spline è chiusa (periodica).

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

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

Il tutorial Eseguire script da un file mostra un altro esempio che traccia una curva di Lissajous come 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)

Aggiunge un testo su una sola riga nella posizione indicata. Tutti gli argomenti dopo la posizione sono facoltativi:

• height: altezza del testo (predefinito 1)
• angle: angolo del testo in gradi (predefinito 0)
• font: nome del font (predefinito "Standard")
• vAlign: allineamento verticale: RS.VAlignTop (predefinito), RS.VAlignMiddle, RS.VAlignBase o RS.VAlignBottom
• hAlign: allineamento orizzontale: RS.HAlignLeft (predefinito), RS.HAlignCenter o RS.HAlignRight
• bold, italic: true per testo in grassetto o in corsivo (solo font 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])

Aggiunge un’area a riempimento pieno (solido) con tre o quattro vertici. Si noti che i vertici di un solido a quattro lati sono indicati in ordine a zigzag: primo vertice, secondo vertice, poi il vertice opposto al secondo e il vertice opposto al primo. Per creare un triangolo, indicare due volte il terzo vertice.

// quadrato pieno:
addSolid(0,0, 50,0, 0,50, 50,50);

// triangolo pieno:
addSolid([60,0], [110,0], [85,50], [85,50]);

Aggiungere forme, entità e oggetti

Le funzioni seguenti aggiungono al disegno oggetti creati con l’API completa di QCAD. Sono utili quando le funzioni di creazione specializzate descritte sopra non coprono un determinato caso.

addShape

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

Aggiunge la forma indicata (RLine, RArc, RCircle, REllipse, RPolyline, RSpline, RPoint, …) come nuova entità sul livello corrente. Facoltativamente è possibile indicare un colore (RColor), un tipo di linea (nome o ID) e uno spessore di linea (ad esempio RLineweight.Weight050). Per impostazione predefinita vengono utilizzati il colore corrente, il tipo di linea ByLayer e lo spessore di linea 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)

Aggiunge tutte le forme dell’array indicato come nuove entità.

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)

Aggiunge l’entità indicata (REntity) al disegno. Se non viene indicato alcun colore, viene utilizzato il colore corrente.

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)

Aggiunge un oggetto qualsiasi (entità, livello, blocco, …) al disegno e restituisce l’oggetto aggiunto.

// aggiungere un blocco chiamato "Marker" contenente una croce:
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);

// inserire il blocco due volte:
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 l’oggetto indicato dal disegno. Per eliminare entità, la funzione deleteEntity è di solito più comoda.

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

Livelli e attributi

addLayer

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

Aggiunge un nuovo livello con il nome indicato. Facoltativamente è possibile indicare il nome del colore (predefinito "white", che viene visualizzato nero su sfondo bianco), il nome del tipo di linea (predefinito "CONTINUOUS") e lo spessore di linea (predefinito RLineweight.Weight000). Restituisce il nuovo livello oppure undefined se esiste già un livello con il nome indicato.

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

hasLayer

hasLayer(name)

Restituisce true se nel disegno esiste un livello con il nome indicato.

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

setCurrentLayer

setCurrentLayer(name)

Imposta il livello corrente. Tutte le entità aggiunte successivamente vengono posizionate su questo livello.

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

setCurrentColor

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

Imposta il colore per le entità aggiunte successivamente. Il colore può essere indicato come oggetto RColor o come valori di rosso, verde e blu (0-255). Utilizzare new RColor(RColor.ByLayer) per reimpostare il colore su «Da livello».

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);

Interrogare le entità

getEntity

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

Restituisce l’entità per il riferimento indicato, ovvero l’entità con l’ID indicato, lo stato attuale dell’entità indicata o l’entità più vicina alla posizione indicata. Restituisce undefined se non viene trovata alcuna entità.

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

// circle contiene ancora il vecchio centro, getEntity restituisce lo stato attuale:
getEntity(circle).getCenter();     // restituisce 10,0

// entità più vicina a 30,0:
getEntity(30,0).getRadius();       // restituisce 20

getShape

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

Restituisce la geometria dell’entità indicata come forma (RLine per una linea, RArc per un arco, RPolyline per una polilinea, …). Le forme possono essere utilizzate per calcoli geometrici senza modificare il disegno.

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

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

getClosestEntity

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

Restituisce l’entità più vicina alla posizione indicata. Se viene indicato range, vengono considerate solo le entità entro tale distanza dalla posizione. Restituisce undefined se non viene trovata alcuna entità.

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

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

getEntityShape

getEntityShape(entity, position)

Restituisce la forma dell’oggetto entità indicato. Per le entità complesse composte da più forme (riferimenti di blocco, tratteggi, quote, testi), viene restituita la forma più vicina alla posizione indicata. La posizione è facoltativa.

// un riferimento di blocco di un blocco con un rettangolo:
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 del riferimento di blocco vicino a 40,10 (il rettangolo):
var s = getEntityShape(getEntity(ref), new RVector(41,10));
s.getLength();                     // restituisce 120

getIntersectionPoints

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

Restituisce un array con i punti di intersezione delle due entità o forme indicate. Le entità possono essere indicate come oggetti entità, ID di entità o forme. Se limited è false, le entità vengono trattate come se fossero infinite (linee prolungate, archi come cerchi completi). Il valore predefinito è true.

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

// contrassegnare le intersezioni con piccoli cerchi:
for (var i=0; i<ips.length; i++) {
    addCircle(ips[i], 2);
}

isPosition e toVector

isPosition(value)
toVector(value)

isPosition restituisce true se il valore indicato è una posizione (RVector o array di due o tre numeri). toVector converte una posizione indicata come array in un RVector. Queste funzioni sono utili quando si scrivono funzioni proprie che accettano posizioni nello stesso modo della 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]);                 // restituisce true
isPosition("abc");                 // restituisce false

Modificare le entità

Trasformazioni

move

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

Sposta l’entità indicata dello spostamento indicato.

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

rotate

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

Ruota l’entità indicata dell’angolo indicato in gradi attorno al centro indicato. Se non viene indicato alcun centro, l’entità viene ruotata attorno all’origine 0,0.

// un ventaglio di linee, ruotate attorno a 0,0:
for (var a=0; a<360; a+=30) {
    var l = addLine(10,0, 50,0);
    rotate(l, a);
}

// ruotare un quadrato attorno al suo 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])

Scala l’entità indicata del fattore indicato. Il punto focale (il punto che rimane fermo) è per impostazione predefinita l’origine 0,0. Fattori diversi per X e Y possono essere indicati come array [sx, sy]. Si noti che alcune entità, come cerchi e archi, non possono essere scalate con fattori diversi in 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(...))

Specchia l’entità indicata rispetto all’asse definito da due punti.

var pl = addPolyline([[10,0], [40,0], [40,30]], false);
// specchiare rispetto all'asse Y:
mirror(pl, 0,0, 0,100);

Per mantenere l’originale e creare una copia speculare, aggiungere prima una copia dell’entità:

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

Tagliare e allungare

trim

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

Taglia l’entità trimEntity sull’entità limitante limitingEntity. Viene mantenuta la parte dell’entità tagliata che si trova nella posizione di clic trimPos. Se le due entità non si intersecano, l’entità viene estesa fino all’entità limitante. Se sono presenti più intersezioni, viene utilizzata quella più vicina alla posizione di clic limitingPos. Se trimBoth è true, entrambe le entità vengono tagliate l’una sull’altra.

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

// mantenere la parte sinistra, ora line termina in 70,0:
trim(line, [10,0], limit);

// estendere una linea fino a un cerchio:
var line = addLine(0,0, 50,0);
var circle = addCircle(100,0, 20);

// estendere fino all'intersezione con il cerchio più vicina a 80,0:
trim(line, [25,0], circle, [80,0]);      // ora line termina in 80,0

trimBoth

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

Taglia o estende entrambe le entità fino al loro punto di intersezione. È una scorciatoia per trim con trimBoth impostato su true.

// due linee che non si toccano vengono estese fino a formare un angolo in 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)

Allunga l’entità indicata della quantità indicata. Valori negativi accorciano l’entità. Per impostazione predefinita, l’entità viene allungata nel suo punto finale. Passare true per start per allungarla invece nel suo punto iniziale, oppure passare una posizione vicina all’estremità da allungare.

var line = addLine(0,0, 100,0);
lengthen(line, 20);              // ora line termina in 120,0
lengthen(line, true, -10);       // ora line inizia in 10,0

var arc = addArc(0,50, 30, 0, 90);
lengthen(arc, [30,50], 10);      // allungare l'arco nel suo punto iniziale

breakOut

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

Rompe il segmento dell’entità indicata che si trova nella posizione indicata. Il segmento termina nelle intersezioni più vicine con altre entità su entrambi i lati della posizione. Se su un lato non c’è alcuna intersezione, il segmento si estende fino all’estremità dell’entità. Se removeSegment è true (predefinito), il segmento viene eliminato. Altrimenti viene mantenuto come entità separata.

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

// rimuovere la parte della linea tra 30,0 e 70,0:
breakOut(line, [50,0]);

autoTrim

autoTrim(entity, pos)
autoTrim(pos)

L’opposto di breakOut: mantiene solo il segmento dell’entità indicata che si trova nella posizione indicata e rimuove il resto. Il segmento termina nelle intersezioni più vicine con altre entità su entrambi i lati della posizione.

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

// mantenere solo la parte tra 30,0 e 70,0:
autoTrim(line, [50,0]);

divide

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

Divide l’entità indicata nella posizione indicata. Un’entità aperta (linea, arco, polilinea aperta, …) viene divisa in due parti in una posizione o in tre parti in due posizioni. Le entità chiuse (cerchi, ellissi complete, polilinee chiuse) richiedono due posizioni e vengono divise in due parti.

var line = addLine(0,0, 100,0);
divide(line, [40,0]);            // due linee: 0..40 e 40..100

var circle = addCircle(0,50, 20);
divide(circle, [20,50], [-20,50]);   // due semicerchi

Angoli

round

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

Raccorda l’angolo tra due entità con un arco del raggio indicato (raccordo). Le posizioni di clic indicano quali estremità delle entità vengono raccordate. Se trim è true (predefinito), entrambe le entità vengono tagliate sull’arco di raccordo.

// un rettangolo con angoli arrotondati:
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);

Anche gli angoli di una polilinea possono essere raccordati, passando due volte la stessa polilinea con una posizione di clic su ciascuno dei due segmenti:

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

bevel e 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)

Smussa l’angolo tra due entità con una linea retta (smusso). distance1 è la distanza della linea di smusso dall’angolo lungo la prima entità, distance2 lungo la seconda entità (predefinito distance1). Se trim è true (predefinito), entrambe le entità vengono tagliate sulla linea di smusso. chamfer è un alias di 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 parallele a linee, archi e cerchi concentrici o curve di offset di ellissi e di altre entità. number è il numero di parallele da creare (predefinito 1). Le parallele vengono create su entrambi i lati dell’entità, a meno che non venga indicato un lato, come posizione sidePos accanto all’entità oppure come side (RS.LeftHand, RS.RightHand o RS.BothSides). L’offset di polilinee e spline è disponibile solo in QCAD Professional.

var line = addLine(0,0, 100,0);
offset(line, 5);                 // una parallela su ciascun lato

var line2 = addLine(0,30, 100,30);
offset(line2, 5, 2, RS.LeftHand);    // due parallele sul lato sinistro (sopra)

var circle = addCircle(50,80, 10);
offset(circle, [50,95], 3, 4);   // quattro cerchi concentrici all'esterno

reverse

reverse(entity)
reverse(x, y)

Inverte la direzione dell’entità indicata, ovvero scambia il suo punto iniziale e il suo punto finale.

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

explode

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

Esplode l’entità indicata in entità più semplici: le polilinee in linee e archi, i riferimenti di blocco nel loro contenuto, i testi in linee e spline, le quote e i tratteggi in linee, archi, ecc. L’entità originale viene eliminata.

options è un oggetto facoltativo con impostazioni che altrimenti vengono prese dalle preferenze dell’applicazione, ad esempio { splineSegments: 64, textToPolylines: true }. Le opzioni supportate sono: splineTolerance, splineSegments, ellipseSegments, splinesToLineSegments, textToPolylines, textSplineToLineOrArc, multilineTextToSimpleText e circlesToPolylines.

var pl = addPolyline([[0,0], [100,0,1], [100,50], [0,50]], true);
explode(pl);                     // tre linee e un arco

stretch

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

Stira tutte le entità nell’area rettangolare definita da due vertici dello spostamento indicato. Le entità che si trovano completamente all’interno dell’area vengono spostate, le entità che attraversano il bordo dell’area vengono stirate (vengono spostati solo i punti finali all’interno dell’area). L’area può essere indicata anche come RBox o come forma RPolyline chiusa. Se nel disegno sono selezionate delle entità, vengono stirate solo le entità selezionate.

// un rettangolo composto da linee:
addLine(0,0, 100,0);
addLine(100,0, 100,50);
addLine(100,50, 0,50);
addLine(0,50, 0,0);

// rendere il rettangolo più largo di 50 unità stirando il suo lato destro:
stretch([80,-10], [120,60], [50,0]);

deleteEntity

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

Elimina l’entità indicata dal disegno.

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

deleteEntity(l1);                // tramite entità
deleteEntity(l2.getId());        // tramite ID di entità
deleteEntity(50,20);             // tramite posizione

paste

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

Incolla il contenuto del documento sourceDocument nell’interfaccia documento destination oppure nel disegno corrente se destination è undefined. Il contenuto incollato viene spostato di offset, scalato di scale e ruotato di rotation gradi. Tutti gli argomenti sono obbligatori:

• flipHorizontal, flipVertical: true per capovolgere il contenuto
• toCurrentLayer: true per incollare tutte le entità sul livello corrente
• overwriteLayers, overwriteBlocks: true per sovrascrivere livelli o blocchi esistenti con lo stesso nome

// creare un simbolo in un documento fuori schermo:
var symbol = createDocument();
startTransaction(symbol);
addCircle(0,0, 10);
addLine(-10,0, 10,0);
addLine(0,-10, 0,10);
endTransaction();

// incollarlo tre volte nel disegno corrente:
for (var i=0; i<3; i++) {
    paste(symbol, undefined, [i*50, 0], 1+i*0.5, i*15, false, false, false, false, false);
}

Transazioni

startTransaction e endTransaction

startTransaction()
startTransaction(document)
endTransaction()

Per impostazione predefinita, ogni chiamata della Simple API viene applicata immediatamente al disegno e può essere annullata singolarmente. Tra startTransaction() e endTransaction(), tutte le modifiche vengono raccolte e applicate insieme quando viene chiamato endTransaction. Ciò offre due vantaggi:

• È molto più veloce quando si aggiungono molte entità.
• Tutte le modifiche possono essere annullate in un unico passaggio.

Se a startTransaction viene passato un documento (RDocument) o un’interfaccia documento (RDocumentInterface), tutte le modifiche vengono applicate a tale documento invece che al disegno corrente. Ciò è utile per creare disegni in background, ad esempio per esportarli in un file (vedere createDocumentInterface).

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

Quando si lavora con le transazioni, tenere presente quanto segue:

• All’interno di una transazione, le modifiche non fanno ancora parte del disegno. Le funzioni di modifica come trim o round non possono fare riferimento a entità aggiunte nella stessa transazione.
• Le entità restituite dalle funzioni di creazione all’interno di una transazione non hanno un ID valido, nemmeno dopo endTransaction. Per modificare tali entità in seguito, farvi riferimento tramite la posizione.
• Tutte le entità aggiunte all’interno di una transazione vengono posizionate sul livello che è corrente quando viene chiamato endTransaction. Impostare il livello corrente prima di avviare la transazione e utilizzare transazioni separate per livelli diversi.

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

// fare riferimento alle nuove linee tramite la posizione per raccordare l'angolo:
round([50,0], [100,25], 10);

getTransactionDocument e getTransactionDocumentInterface

getTransactionDocument()
getTransactionDocumentInterface()

Restituiscono il documento o l’interfaccia documento a cui si applica la transazione corrente. Al di fuori delle transazioni, vengono restituiti il documento e l’interfaccia documento correnti.

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

getOperation

getOperation()

Restituisce l’operazione (RAddObjectsOperation) della transazione corrente. Al di fuori di una transazione, viene restituita una nuova operazione che deve essere applicata esplicitamente. È pensata per un uso avanzato, ad esempio per combinare chiamate della Simple API con l’API completa di 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()

Esegue lo zoom della vista corrente in modo che l’intero disegno sia visibile.

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)

Esegue lo zoom sull’entità, sulla forma o sull’area rettangolare indicata. margin è il margine attorno all’area in pixel (predefinito 10).

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

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

Documenti e applicazione

getMainWindow

getMainWindow()

Restituisce la finestra dell’applicazione QCAD (RMainWindowQt).

getMainWindow().windowTitle;

getDocumentInterface

getDocumentInterface()

Restituisce l’interfaccia documento (RDocumentInterface) del disegno corrente. L’interfaccia documento collega un documento alle sue viste e fornisce funzioni per importare ed esportare file, applicare operazioni, annullare e ripetere.

addLine(0,0, 100,0);
getDocumentInterface().undo();       // rimuove di nuovo la linea

getDocument

getDocument()

Restituisce il documento corrente (RDocument). Il documento contiene tutte le entità, i livelli, i blocchi, ecc. di un disegno e fornisce funzioni per interrogarli.

addLine(0,0, 100,0);
addCircle(0,0, 10);
getDocument().queryAllEntities().length;     // numero di entità nel disegno

getGraphicsView

getGraphicsView()

Restituisce la vista corrente o l’ultima vista attiva (RGraphicsView) del disegno corrente.

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

createDocument

createDocument()

Crea un nuovo documento vuoto in memoria che non viene mostrato in una finestra. Un documento fuori schermo di questo tipo può essere riempito tramite una transazione e poi incollato in un disegno (vedere paste).

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

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

createDocumentInterface

createDocumentInterface()

Crea un nuovo documento vuoto in memoria insieme a un’interfaccia documento. L’interfaccia documento può essere utilizzata per importare o esportare file.

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 e isInputEnabled

disableInput()
enableInput()
isInputEnabled()

disableInput disattiva la finestra dell’applicazione QCAD per impedire l’input dell’utente, ad esempio durante operazioni lunghe o animazioni. enableInput riattiva la finestra dell’applicazione e isInputEnabled restituisce true se l’input dell’utente è attualmente abilitato. Assicurarsi sempre di riattivare l’input alla fine dello script.

update

update()

Elabora gli eventi in sospeso in modo che l’interfaccia utente venga aggiornata durante le operazioni lunghe. L’input dell’utente deve essere disattivato con disableInput prima di chiamare update.

sleep

sleep(milliseconds)

Mette in pausa lo script per il tempo indicato in millisecondi, mantenendo aggiornata l’interfaccia utente. L’input dell’utente deve essere disattivato con disableInput prima di chiamare sleep.

L’esempio seguente utilizza disableInput, sleep e enableInput per mostrare una semplice animazione:

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)

Mostra un messaggio di avviso. Nella Script Shell, gli avvisi vengono mostrati nella cronologia dei comandi. Altrimenti, gli avvisi vengono stampati sulla console.

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

Input dell’utente

Le funzioni seguenti mostrano una semplice finestra di dialogo per chiedere un valore all’utente. Se l’utente annulla la finestra di dialogo, viene restituito undefined.

getInt

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

Chiede all’utente un numero intero. value è il valore iniziale (predefinito 0), step il passo del campo numerico (predefinito 1), min e max l’intervallo consentito.

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)

Chiede all’utente un numero. value è il valore iniziale (predefinito 0), decimals il numero di decimali mostrati (predefinito 1), min e max l’intervallo consentito.

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

getText

getText(title, prompt, text)

Chiede all’utente un testo. text è il testo iniziale (predefinito vuoto).

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

getItem

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

Consente all’utente di scegliere un elemento da un elenco a discesa. items è una stringa con tutti gli elementi separati da separator (predefinito ","). index è l’indice dell’elemento selezionato inizialmente (predefinito 0). Restituisce l’elemento scelto oppure undefined se la finestra di dialogo è stata annullata.

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);
}

Esempio: una flangia

Questo esempio combina diverse funzioni della Simple API per disegnare una flangia con un cerchio di foratura, fori per bulloni su un livello separato e un’apertura rettangolare con angoli raccordati:

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

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

// cerchio di foratura e linee d'asse:
setCurrentLayer("Center Lines");
addCircle(0,0, 75);
addLine(-110,0, 110,0);
addLine(0,-110, 0,110);

// fori per bulloni, aggiunti in un'unica transazione:
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();

// apertura quadrata raccordata al 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();

Le linee dell’apertura vengono aggiunte senza transazione, in modo da poterle passare direttamente a round. I fori per bulloni vengono aggiunti in una transazione, il che è più veloce e permette di annullarli in un unico passaggio.