Simple API

Introduktion

QCAD:s Simple API är en liten uppsättning globala skriptfunktioner som förenklar vanliga uppgifter som att lägga till entiteter i en ritning, fråga efter entiteter och ändra dem (flytta, trimma, avrunda, parallellförskjuta, …). Det är främst avsett för användning i Script Shell och för korta procedurella skript som körs från en fil, men det kan användas från vilket skript som helst.

Simple API täcker bara en liten del av det kompletta QCAD-API:et. Eftersom det självt är skrivet i ECMAScript (JavaScript) är det också en bra utgångspunkt för att lära sig hur det underliggande QCAD-API:et fungerar. Källkoden finns i filerna scripts/simple.js och scripts/simple_*.js i QCAD:s källkod.

Använda Simple API

I Script Shell (Diverse > Utveckling > Script Shell) och i skript som startas med Diverse > Utveckling > Kör skript är alla Simple API-funktioner tillgängliga direkt. Skriv till exempel:

addLine(0,0, 100,100);

I dina egna skriptfiler, till exempel i interaktiva skripthandlingar eller kommandoradsverktyg, inkluderar du först filen simple.js:

include("scripts/simple.js");

addLine(0,0, 100,100);

Alla funktioner arbetar på den ritning som för närvarande är öppen i QCAD:s programfönster, såvida inte en transaktion används för att omdirigera dem till ett annat dokument (se Transaktioner).

Alla exempel på den här sidan kan klistras in i Script Shell för en tom ritning. Varje exempel skapar de entiteter det behöver. Använd Visa > Auto Zoom eller funktionen autoZoom() för att se resultatet.

Konventioner

Koordinater

Positioner kan anges på tre olika sätt:

• Som två separata tal: addLine(0,0, 100,100)
• Som en array med två tal: addLine([0,0], [100,100])
• Som vektorobjekt: addLine(new RVector(0,0), new RVector(100,100))

Vinklar anges alltid i grader, utom start- och slutparametrarna för ellipser som anges i radianer.

Entitetsreferenser

Funktioner som arbetar med en befintlig entitet accepterar entiteten i olika former:

• Ett entitets-ID (tal), till exempel 1234.
• Ett entitetsobjekt som returneras av skapandefunktionerna, till exempel returvärdet från addLine(...).
• En position i ritningen ([x,y] eller RVector): den entitet som ligger närmast den angivna positionen används.
• En form (till exempel new RLine(0,0, 100,0)): åtgärden tillämpas endast på formen, ritningen ändras inte.

var l = addLine(0,0, 100,0);
move(l, [0,10]);              // via entitetsobjekt
move(l.getId(), [0,10]);      // via entitets-ID
move([50,20], [0,10]);        // via position: entiteten närmast 50,20

Klickpositioner

Vissa åtgärder beror på var en entitet klickas när motsvarande verktyg används interaktivt. Vid trimning behålls den del av entiteten som ligger vid klickpositionen, vid avrundning och fasning bearbetas de ändar av entiteterna som ligger närmast klickpositionerna, och parallellförskjutning skapar paralleller på klickpositionens sida.

I Simple API kan en klickposition följa varje entitetsreferens. Om en entitet refereras via en position fungerar den positionen även som klickposition. Om ingen klickposition anges används entitetens mittpunkt:

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

// trimma line mot limit, behåll den del av linjen som ligger vid 10,0:
trim(line, [10,0], limit);

Returvärden

• Skapandefunktioner returnerar den tillagda entiteten. Entiteten kan skickas till andra funktioner eller frågas efter information (till exempel getId(), getLength() eller getStartPoint()).
• Transformationer (move, rotate, scale, mirror, lengthen, reverse) returnerar den ändrade entiteten.
• Övriga ändringsfunktioner (trim, round, bevel, offset, breakOut, autoTrim, divide, explode, stretch) returnerar den transaktion som tillämpades på ritningen eller undefined om åtgärden misslyckades.
• Om former skickas i stället för entiteter ändrar transformationerna de angivna formerna och alla andra funktioner returnerar de resulterande formerna som en array.

Misslyckade åtgärder genererar inget fel. I stället visas en varning i Script Shell, till exempel ”Enheten kan inte beskäras.”.

Skapa entiteter

addPoint

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

Lägger till en punktentitet vid den angivna positionen.

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

addLine

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

Lägger till en linje från startpunkten till slutpunkten.

// en triangel:
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])

Lägger till en oändlig linje (konstruktionslinje) genom baspunkten x,y med riktningen dx,dy. Riktningen anges relativt baspunkten.

// horisontell konstruktionslinje och konstruktionslinje i 45 grader genom 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)

Lägger till en båge med angiven mittpunkt, radie, startvinkel och slutvinkel. Vinklarna anges i grader. Bågar går moturs från startvinkeln till slutvinkeln, såvida inte reversed är true (valfritt, standard är false).

// kvartsbåge från 0 till 90 grader:
addArc(0,0, 50, 0, 90);

// medurs båge från 0 till 90 grader (de andra tre kvarten):
addArc([0,0], 40, 0, 90, true);

addCircle

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

Lägger till en cirkel med angiven mittpunkt och radie.

// koncentriska cirklar:
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)

Lägger till en ellips eller en ellipsbåge. mx,my är storaxelns ändpunkt, relativt mittpunkten. ratio är förhållandet mellan lillaxeln och storaxeln. startParam och endParam är de ellipsparametrar i radianer där ellipsen börjar och slutar. Använd 0 och 2*Math.PI för en hel ellips.

// hel ellips med storradien 50 och lillradien 25:
addEllipse(0,0, 50,0, 0.5, 0, 2*Math.PI, false);

// övre halvan av en roterad ellips:
addEllipse([0,0], [30,30], 0.3, 0, Math.PI, false);

addPolyline

addPolyline(points, closed, relative)

Lägger till en polylinje genom de angivna hörnpunkterna. points är en array med hörnpunkter, var och en angiven som [x, y], [x, y, bulge] eller [x, y, bulge, relative]. I stället för x, y kan en RVector användas.

• bulge (utbuktning) definierar formen på det segment som börjar vid den här hörnpunkten: 0 (standard) för ett rakt segment, 1 för en halvcirkel moturs, -1 för en halvcirkel medurs. Andra värden skapar bågsegment däremellan (utbuktningen är tangens för en fjärdedel av bågvinkeln).
• relative: true om koordinaterna för den här hörnpunkten är relativa till föregående hörnpunkt.
• closed: true för att stänga polylinjen (standard är false).
• relative: true för att behandla koordinaterna för alla hörnpunkter som relativa till föregående hörnpunkt (standard är false).

// stängd rektangel:
addPolyline([[0,0], [100,0], [100,50], [0,50]], true);

// avlångt spår (slits) med två halvcirklar:
addPolyline([[0,60], [80,60,1], [80,80], [0,80,1]], true);

// sicksacklinje med relativa koordinater:
addPolyline([[0,100], [10,10], [10,-10], [10,10], [10,-10]], false, true);

addSpline

addSpline(fitPoints, closed)

Lägger till en spline genom de angivna anpassningspunkterna. fitPoints är en array med [x, y]-arrayer eller RVector-objekt. Om closed är true stängs splinen (periodisk).

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

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

Handledningen Köra skript från en fil visar ett annat exempel som plottar en Lissajous-kurva som 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)

Lägger till en enradig text vid den angivna positionen. Alla argument efter positionen är valfria:

• height: texthöjd (standard 1)
• angle: textvinkel i grader (standard 0)
• font: teckensnittsnamn (standard "Standard")
• vAlign: vertikal justering: RS.VAlignTop (standard), RS.VAlignMiddle, RS.VAlignBase eller RS.VAlignBottom
• hAlign: horisontell justering: RS.HAlignLeft (standard), RS.HAlignCenter eller RS.HAlignRight
• bold, italic: true för fet eller kursiv text (endast TrueType-teckensnitt)

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

Lägger till en helfylld yta (solid) med tre eller fyra hörn. Observera att hörnen på en fyrsidig solid anges i sicksackordning: första hörnet, andra hörnet, sedan hörnet mitt emot det andra hörnet och hörnet mitt emot det första hörnet. För att skapa en triangel anger du det tredje hörnet två gånger.

// fylld kvadrat:
addSolid(0,0, 50,0, 0,50, 50,50);

// fylld triangel:
addSolid([60,0], [110,0], [85,50], [85,50]);

Lägga till former, entiteter och objekt

Följande funktioner lägger till objekt som har skapats med det kompletta QCAD-API:et i ritningen. De är användbara när de specialiserade skapandefunktionerna ovan inte täcker ett visst fall.

addShape

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

Lägger till den angivna formen (RLine, RArc, RCircle, REllipse, RPolyline, RSpline, RPoint, …) som ny entitet på det aktuella lagret. Valfritt kan en färg (RColor), en linjetyp (namn eller ID) och en linjetjocklek (till exempel RLineweight.Weight050) anges. Som standard används den aktuella färgen, linjetypen ByLayer och linjetjockleken 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)

Lägger till alla former i den angivna arrayen som nya entiteter.

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)

Lägger till den angivna entiteten (REntity) i ritningen. Om ingen färg anges används den aktuella färgen.

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)

Lägger till ett valfritt objekt (entitet, lager, block, …) i ritningen och returnerar det tillagda objektet.

// lägg till ett block med namnet "Marker" som innehåller ett kryss:
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);

// infoga blocket två gånger:
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)

Tar bort det angivna objektet från ritningen. För att ta bort entiteter är funktionen deleteEntity oftast smidigare.

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

Lager och attribut

addLayer

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

Lägger till ett nytt lager med det angivna namnet. Valfritt kan färgnamnet (standard "white", som visas svart på vit bakgrund), linjetypsnamnet (standard "CONTINUOUS") och linjetjockleken (standard RLineweight.Weight000) anges. Returnerar det nya lagret eller undefined om ett lager med det angivna namnet redan finns.

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

hasLayer

hasLayer(name)

Returnerar true om ett lager med det angivna namnet finns i ritningen.

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

setCurrentLayer

setCurrentLayer(name)

Anger det aktuella lagret. Alla entiteter som läggs till därefter placeras på det här lagret.

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

setCurrentColor

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

Anger färgen för entiteter som läggs till därefter. Färgen kan anges som RColor-objekt eller som röd-, grön- och blåvärden (0-255). Använd new RColor(RColor.ByLayer) för att återställa färgen till ”Från lager”.

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

Fråga efter entiteter

getEntity

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

Returnerar entiteten för den angivna entitetsreferensen, dvs. entiteten med det angivna ID:t, det aktuella tillståndet för den angivna entiteten eller den entitet som ligger närmast den angivna positionen. Returnerar undefined om ingen entitet hittas.

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

// circle innehåller fortfarande den gamla mittpunkten, getEntity returnerar det aktuella tillståndet:
getEntity(circle).getCenter();     // returnerar 10,0

// entiteten närmast 30,0:
getEntity(30,0).getRadius();       // returnerar 20

getShape

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

Returnerar geometrin för den angivna entiteten som form (RLine för en linje, RArc för en båge, RPolyline för en polylinje, …). Former kan användas för geometriska beräkningar utan att ritningen ändras.

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

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

getClosestEntity

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

Returnerar den entitet som ligger närmast den angivna positionen. Om range anges beaktas endast entiteter inom det avståndet från positionen. Returnerar undefined om ingen entitet hittas.

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

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

getEntityShape

getEntityShape(entity, position)

Returnerar formen för det angivna entitetsobjektet. För sammansatta entiteter som består av flera former (blockreferenser, skrafferingar, måttsättningar, texter) returneras den form som ligger närmast den angivna positionen. Positionen är valfri.

// en blockreferens till ett block med en rektangel:
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)));

// blockreferensens form nära 40,10 (rektangeln):
var s = getEntityShape(getEntity(ref), new RVector(41,10));
s.getLength();                     // returnerar 120

getIntersectionPoints

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

Returnerar en array med skärningspunkterna mellan de två angivna entiteterna eller formerna. Entiteter kan anges som entitetsobjekt, entitets-ID:n eller former. Om limited är false behandlas entiteterna som om de vore oändliga (linjer förlängda, bågar som hela cirklar). Standard är true.

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

// markera skärningspunkterna med små cirklar:
for (var i=0; i<ips.length; i++) {
    addCircle(ips[i], 2);
}

isPosition och toVector

isPosition(value)
toVector(value)

isPosition returnerar true om det angivna värdet är en position (RVector eller en array med två eller tre tal). toVector konverterar en position som anges som array till en RVector. Dessa funktioner är användbara när du skriver egna funktioner som accepterar positioner på samma sätt som 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]);                 // returnerar true
isPosition("abc");                 // returnerar false

Ändra entiteter

Transformationer

move

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

Flyttar den angivna entiteten med den angivna förskjutningen.

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

rotate

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

Roterar den angivna entiteten med den angivna vinkeln i grader runt den angivna mittpunkten. Om ingen mittpunkt anges roteras entiteten runt origo 0,0.

// en solfjäder av linjer, roterade runt 0,0:
for (var a=0; a<360; a+=30) {
    var l = addLine(10,0, 50,0);
    rotate(l, a);
}

// rotera en kvadrat runt dess mittpunkt:
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])

Skalar den angivna entiteten med den angivna faktorn. Fokuspunkten (den punkt som förblir på plats) är som standard origo 0,0. Olika faktorer för X och Y kan anges som arrayen [sx, sy]. Observera att vissa entiteter, till exempel cirklar och bågar, inte kan skalas med olika faktorer i X och 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(...))

Speglar den angivna entiteten i den axel som definieras av två punkter.

var pl = addPolyline([[10,0], [40,0], [40,30]], false);
// spegla i Y-axeln:
mirror(pl, 0,0, 0,100);

För att behålla originalet och skapa en speglad kopia lägger du först till en kopia av entiteten:

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

Trimma och förlänga

trim

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

Trimmar entiteten trimEntity mot den begränsande entiteten limitingEntity. Den del av den trimmade entiteten som ligger vid klickpositionen trimPos behålls. Om de två entiteterna inte skär varandra förlängs entiteten till den begränsande entiteten. Om det finns flera skärningspunkter används den som ligger närmast klickpositionen limitingPos. Om trimBoth är true trimmas båda entiteterna mot varandra.

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

// behåll den vänstra delen, linjen slutar nu vid 70,0:
trim(line, [10,0], limit);

// förläng en linje till en cirkel:
var line = addLine(0,0, 50,0);
var circle = addCircle(100,0, 20);

// förläng till den skärningspunkt med cirkeln som ligger närmast 80,0:
trim(line, [25,0], circle, [80,0]);      // linjen slutar nu vid 80,0

trimBoth

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

Trimmar eller förlänger båda entiteterna till deras skärningspunkt. Detta är en genväg för trim med trimBoth satt till true.

// två linjer som inte möts förlängs så att de bildar ett hörn vid 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)

Förlänger den angivna entiteten med det angivna beloppet. Negativa belopp förkortar entiteten. Som standard förlängs entiteten vid sin slutpunkt. Ange true för start för att i stället förlänga den vid startpunkten, eller ange en position nära den ände som ska förlängas.

var line = addLine(0,0, 100,0);
lengthen(line, 20);              // linjen slutar nu vid 120,0
lengthen(line, true, -10);       // linjen börjar nu vid 10,0

var arc = addArc(0,50, 30, 0, 90);
lengthen(arc, [30,50], 10);      // förläng bågen vid dess startpunkt

breakOut

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

Bryter ut segmentet av den angivna entiteten vid den angivna positionen. Segmentet slutar vid de närmaste skärningspunkterna med andra entiteter på båda sidor om positionen. Om det inte finns någon skärningspunkt på ena sidan sträcker sig segmentet till entitetens ände. Om removeSegment är true (standard) tas segmentet bort. Annars behålls det som en separat entitet.

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

// ta bort den del av linjen som ligger mellan 30,0 och 70,0:
breakOut(line, [50,0]);

autoTrim

autoTrim(entity, pos)
autoTrim(pos)

Motsatsen till breakOut: behåller endast segmentet av den angivna entiteten vid den angivna positionen och tar bort resten. Segmentet slutar vid de närmaste skärningspunkterna med andra entiteter på båda sidor om positionen.

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

// behåll endast delen mellan 30,0 och 70,0:
autoTrim(line, [50,0]);

divide

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

Delar upp den angivna entiteten vid den angivna positionen. En öppen entitet (linje, båge, öppen polylinje, …) delas upp i två delar vid en position eller i tre delar vid två positioner. Stängda entiteter (cirklar, hela ellipser, stängda polylinjer) kräver två positioner och delas upp i två delar.

var line = addLine(0,0, 100,0);
divide(line, [40,0]);            // två linjer: 0..40 och 40..100

var circle = addCircle(0,50, 20);
divide(circle, [20,50], [-20,50]);   // två halvcirklar

Hörn

round

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

Avrundar hörnet mellan två entiteter med en båge med den angivna radien (hörnavrundning). Klickpositionerna anger vilka ändar av entiteterna som avrundas. Om trim är true (standard) trimmas båda entiteterna mot avrundningsbågen.

// en rektangel med avrundade hörn:
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);

Även hörnen på en polylinje kan avrundas, genom att samma polylinje anges två gånger med en klickposition på vart och ett av de två segmenten:

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

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

Fasar hörnet mellan två entiteter med en rak linje (fas). distance1 är faslinjens avstånd från hörnet längs den första entiteten, distance2 längs den andra entiteten (standard är distance1). Om trim är true (standard) trimmas båda entiteterna mot faslinjen. chamfer är ett alias för 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)

Skapar paralleller till linjer, koncentriska bågar och cirklar eller parallellkurvor (offsetkurvor) till ellipser och andra entiteter. number är antalet paralleller som ska skapas (standard 1). Parallellerna skapas på båda sidor om entiteten, såvida inte en sida anges, antingen som positionen sidePos intill entiteten eller som side (RS.LeftHand, RS.RightHand eller RS.BothSides). Parallellförskjutning av polylinjer och splines är endast tillgänglig i QCAD Professional.

var line = addLine(0,0, 100,0);
offset(line, 5);                 // en parallell på varje sida

var line2 = addLine(0,30, 100,30);
offset(line2, 5, 2, RS.LeftHand);    // två paralleller på vänster sida (ovanför)

var circle = addCircle(50,80, 10);
offset(circle, [50,95], 3, 4);   // fyra koncentriska cirklar utanför

reverse

reverse(entity)
reverse(x, y)

Vänder riktningen på den angivna entiteten, dvs. byter plats på dess start- och slutpunkt.

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

explode

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

Exploderar den angivna entiteten till enklare entiteter: polylinjer till linjer och bågar, blockreferenser till deras innehåll, texter till linjer och splines, måttsättningar och skrafferingar till linjer, bågar osv. Den ursprungliga entiteten tas bort.

options är ett valfritt objekt med inställningar som annars hämtas från programinställningarna, till exempel { splineSegments: 64, textToPolylines: true }. Alternativ som stöds är: splineTolerance, splineSegments, ellipseSegments, splinesToLineSegments, textToPolylines, textSplineToLineOrArc, multilineTextToSimpleText och circlesToPolylines.

var pl = addPolyline([[0,0], [100,0,1], [100,50], [0,50]], true);
explode(pl);                     // tre linjer och en båge

stretch

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

Sträcker alla entiteter i det rektangulära område som definieras av två hörn med den angivna förskjutningen. Entiteter som ligger helt inom området flyttas, entiteter som korsar områdets gräns sträcks (endast ändpunkterna inom området flyttas). Området kan även anges som RBox eller som en stängd RPolyline-form. Om entiteter är markerade i ritningen sträcks endast de markerade entiteterna.

// en rektangel av linjer:
addLine(0,0, 100,0);
addLine(100,0, 100,50);
addLine(100,50, 0,50);
addLine(0,50, 0,0);

// gör rektangeln 50 enheter bredare genom att sträcka dess högra sida:
stretch([80,-10], [120,60], [50,0]);

deleteEntity

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

Tar bort den angivna entiteten från ritningen.

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

deleteEntity(l1);                // via entitet
deleteEntity(l2.getId());        // via entitets-ID
deleteEntity(50,20);             // via position

paste

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

Klistrar in innehållet i dokumentet sourceDocument i dokumentgränssnittet destination eller i den aktuella ritningen om destination är undefined. Det inklistrade innehållet flyttas med offset, skalas med scale och roteras med rotation grader. Alla argument är obligatoriska:

• flipHorizontal, flipVertical: true för att vända innehållet
• toCurrentLayer: true för att klistra in alla entiteter på det aktuella lagret
• overwriteLayers, overwriteBlocks: true för att skriva över befintliga lager eller block med samma namn

// skapa en symbol i ett dokument utanför skärmen:
var symbol = createDocument();
startTransaction(symbol);
addCircle(0,0, 10);
addLine(-10,0, 10,0);
addLine(0,-10, 0,10);
endTransaction();

// klistra in den tre gånger i den aktuella ritningen:
for (var i=0; i<3; i++) {
    paste(symbol, undefined, [i*50, 0], 1+i*0.5, i*15, false, false, false, false, false);
}

Transaktioner

startTransaction och endTransaction

startTransaction()
startTransaction(document)
endTransaction()

Som standard tillämpas varje anrop till Simple API omedelbart på ritningen och kan ångras individuellt. Mellan startTransaction() och endTransaction() samlas alla ändringar in och tillämpas tillsammans när endTransaction anropas. Detta har två fördelar:

• Det går mycket snabbare när många entiteter läggs till.
• Alla ändringar kan ångras i ett enda steg.

Om ett dokument (RDocument) eller ett dokumentgränssnitt (RDocumentInterface) skickas till startTransaction tillämpas alla ändringar på det dokumentet i stället för på den aktuella ritningen. Detta är användbart för att skapa ritningar i bakgrunden, till exempel för att exportera dem till en fil (se createDocumentInterface).

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

Tänk på följande när du arbetar med transaktioner:

• Inom en transaktion är ändringarna ännu inte en del av ritningen. Ändringsfunktioner som trim eller round kan inte referera till entiteter som lagts till i samma transaktion.
• Entiteter som returneras av skapandefunktioner inom en transaktion har inget giltigt ID, inte ens efter endTransaction. För att ändra sådana entiteter senare refererar du till dem via position.
• Alla entiteter som läggs till inom en transaktion placeras på det lager som är aktuellt när endTransaction anropas. Ange det aktuella lagret innan transaktionen startas och använd separata transaktioner för olika lager.

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

// referera till de nya linjerna via position för att avrunda hörnet:
round([50,0], [100,25], 10);

getTransactionDocument och getTransactionDocumentInterface

getTransactionDocument()
getTransactionDocumentInterface()

Returnerar det dokument eller dokumentgränssnitt som den aktuella transaktionen gäller. Utanför transaktioner returneras det aktuella dokumentet och dokumentgränssnittet.

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

getOperation

getOperation()

Returnerar operationen (RAddObjectsOperation) för den aktuella transaktionen. Utanför en transaktion returneras en ny operation som måste tillämpas explicit. Detta är avsett för avancerad användning, till exempel för att kombinera anrop till Simple API med det kompletta QCAD-API:et.

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

Vy

autoZoom

autoZoom()

Zoomar den aktuella vyn så att hela ritningen syns.

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)

Zoomar till den angivna entiteten, formen eller det rektangulära området. margin är marginalen runt området i pixlar (standard 10).

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

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

Dokument och program

getMainWindow

getMainWindow()

Returnerar QCAD:s programfönster (RMainWindowQt).

getMainWindow().windowTitle;

getDocumentInterface

getDocumentInterface()

Returnerar dokumentgränssnittet (RDocumentInterface) för den aktuella ritningen. Dokumentgränssnittet kopplar ett dokument till dess vyer och tillhandahåller funktioner för att importera och exportera filer, tillämpa operationer, ångra och göra om.

addLine(0,0, 100,0);
getDocumentInterface().undo();       // tar bort linjen igen

getDocument

getDocument()

Returnerar det aktuella dokumentet (RDocument). Dokumentet innehåller alla entiteter, lager, block osv. i en ritning och tillhandahåller funktioner för att fråga efter dem.

addLine(0,0, 100,0);
addCircle(0,0, 10);
getDocument().queryAllEntities().length;     // antal entiteter i ritningen

getGraphicsView

getGraphicsView()

Returnerar den aktuella eller senast aktiva vyn (RGraphicsView) för den aktuella ritningen.

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

createDocument

createDocument()

Skapar ett nytt, tomt dokument i minnet som inte visas i något fönster. Ett sådant dokument utanför skärmen kan fyllas med hjälp av en transaktion och sedan klistras in i en ritning (se paste).

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

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

createDocumentInterface

createDocumentInterface()

Skapar ett nytt, tomt dokument i minnet tillsammans med ett dokumentgränssnitt. Dokumentgränssnittet kan användas för att importera eller exportera filer.

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

disableInput()
enableInput()
isInputEnabled()

disableInput inaktiverar QCAD:s programfönster för att förhindra användarinmatning, till exempel under långa åtgärder eller animationer. enableInput aktiverar programfönstret igen och isInputEnabled returnerar true om användarinmatning för närvarande är aktiverad. Se alltid till att aktivera inmatningen igen i slutet av ditt skript.

update

update()

Bearbetar väntande händelser så att användargränssnittet uppdateras under långa åtgärder. Användarinmatning måste inaktiveras med disableInput innan update anropas.

sleep

sleep(milliseconds)

Pausar skriptet under den angivna tiden i millisekunder samtidigt som användargränssnittet hålls uppdaterat. Användarinmatning måste inaktiveras med disableInput innan sleep anropas.

Följande exempel använder disableInput, sleep och enableInput för att visa en enkel animation:

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)

Visar ett varningsmeddelande. I Script Shell visas varningar i kommandohistoriken. Annars skrivs varningar ut till konsolen.

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

Användarinmatning

Följande funktioner visar en enkel dialogruta för att be användaren om ett värde. Om användaren avbryter dialogrutan returneras undefined.

getInt

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

Ber användaren om ett heltal. value är startvärdet (standard 0), step stegstorleken för rotationsrutan (standard 1), min och max det tillåtna intervallet.

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)

Ber användaren om ett tal. value är startvärdet (standard 0), decimals antalet decimaler som visas (standard 1), min och max det tillåtna intervallet.

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

getText

getText(title, prompt, text)

Ber användaren om en text. text är starttexten (standard tom).

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

getItem

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

Låter användaren välja ett objekt i en listruta. items är en sträng med alla objekt åtskilda av separator (standard ","). index är indexet för det objekt som är valt från början (standard 0). Returnerar det valda objektet eller undefined om dialogrutan avbröts.

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

Exempel: En fläns

Detta exempel kombinerar flera funktioner i Simple API för att rita en fläns med en hålcirkel, bulthål på ett separat lager och ett rektangulärt urtag med avrundade hörn:

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

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

// hålcirkel och centrumlinjer:
setCurrentLayer("Center Lines");
addCircle(0,0, 75);
addLine(-110,0, 110,0);
addLine(0,-110, 0,110);

// bulthål, tillagda i en enda transaktion:
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();

// kvadratiskt urtag med avrundade hörn i mitten:
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();

Urtagets linjer läggs till utan transaktion så att de kan skickas direkt till round. Bulthålen läggs till i en transaktion, vilket går snabbare och gör att de kan ångras i ett enda steg.