Simple API

Introduktion

QCAD Simple API er et lille sæt globale scriptfunktioner, der forenkler almindelige opgaver som at tilføje enheder til en tegning, forespørge på enheder og ændre dem (flytte, trimme, afrunde, parallelforskyde, …). Det er primært beregnet til brug i Script Shell og til korte proceduremæssige scripts, der køres fra en fil, men det kan bruges fra ethvert script.

Simple API dækker kun en lille del af det komplette QCAD-API. Da det selv er skrevet i ECMAScript (JavaScript), er det også et godt udgangspunkt for at lære, hvordan det underliggende QCAD-API fungerer. Kildekoden findes i filerne scripts/simple.js og scripts/simple_*.js i QCAD-kildekoden.

Brug af Simple API

I Script Shell (Diverse > Udvikling > Script Shell) og i scripts, der startes med Diverse > Udvikling > Kør script, er alle Simple API-funktioner direkte tilgængelige. Indtast for eksempel:

addLine(0,0, 100,100);

I dine egne scriptfiler, for eksempel i interaktive scripthandlinger eller kommandolinjeværktøjer, skal du først inkludere filen simple.js:

include("scripts/simple.js");

addLine(0,0, 100,100);

Alle funktioner arbejder på den tegning, der aktuelt er åben i QCAD-programvinduet, medmindre en transaktion bruges til at omdirigere dem til et andet dokument (se Transaktioner).

Alle eksempler på denne side kan indsættes i Script Shell for en tom tegning. Hvert eksempel opretter de enheder, det har brug for. Brug Visning > Automatisk zoom eller funktionen autoZoom() for at se resultatet.

Konventioner

Koordinater

Positioner kan angives på tre forskellige måder:

• Som to separate tal: addLine(0,0, 100,100)
• Som et array med to tal: addLine([0,0], [100,100])
• Som vektorobjekt: addLine(new RVector(0,0), new RVector(100,100))

Vinkler angives altid i grader, undtagen start- og slutparametrene for ellipser, som angives i radianer.

Enhedsreferencer

Funktioner, der arbejder med en eksisterende enhed, accepterer enheden i forskellige former:

• Et enheds-ID (tal), for eksempel 1234.
• Et enhedsobjekt, som det returneres af oprettelsesfunktionerne, for eksempel returværdien af addLine(...).
• En position i tegningen ([x,y] eller RVector): den enhed, der ligger tættest på den angivne position, bruges.
• En form (for eksempel new RLine(0,0, 100,0)): handlingen anvendes kun på formen, tegningen ændres ikke.

var l = addLine(0,0, 100,0);
move(l, [0,10]);              // via enhedsobjekt
move(l.getId(), [0,10]);      // via enheds-ID
move([50,20], [0,10]);        // via position: enheden tættest på 50,20

Klikpositioner

Nogle handlinger afhænger af, hvor der klikkes på en enhed, når det tilsvarende værktøj bruges interaktivt. Ved trimning bevares den del af enheden, der ligger ved klikpositionen, ved afrunding og affasning bearbejdes de ender af enhederne, der ligger tættest på klikpositionerne, og ved parallelforskydning oprettes paralleller på den side, hvor klikpositionen ligger.

I Simple API kan en klikposition følge efter hver enhedsreference. Hvis en enhed refereres via en position, fungerer denne position også som klikposition. Hvis der ikke angives nogen klikposition, bruges enhedens midtpunkt:

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

// trim line til limit, bevar den del af linjen, der ligger ved 10,0:
trim(line, [10,0], limit);

Returværdier

• Oprettelsesfunktioner returnerer den tilføjede enhed. Enheden kan videregives til andre funktioner eller forespørges om oplysninger (for eksempel getId(), getLength() eller getStartPoint()).
• Transformationer (move, rotate, scale, mirror, lengthen, reverse) returnerer den ændrede enhed.
• Andre ændringsfunktioner (trim, round, bevel, offset, breakOut, autoTrim, divide, explode, stretch) returnerer den transaktion, der blev anvendt på tegningen, eller undefined, hvis handlingen mislykkedes.
• Hvis der videregives former i stedet for enheder, ændrer transformationerne de angivne former, og alle andre funktioner returnerer de resulterende former som et array.

Mislykkede handlinger udløser ikke en fejl. I stedet vises en advarsel i Script Shell, for eksempel »Enheden kan ikke beskæres.«.

Oprettelse af enheder

addPoint

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

Tilføjer en punktenhed ved den angivne position.

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

addLine

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

Tilføjer en linje fra startpunktet til slutpunktet.

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

Tilføjer en uendelig linje (konstruktionslinje) gennem basispunktet x,y med retningen dx,dy. Retningen angives relativt til basispunktet.

// vandret konstruktionslinje og konstruktionslinje i 45 grader gennem 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)

Tilføjer en bue med det angivne centrum, radius, startvinkel og slutvinkel. Vinkler angives i grader. Buer løber mod uret fra startvinklen til slutvinklen, medmindre reversed er true (valgfri, standard er false).

// kvartbue fra 0 til 90 grader:
addArc(0,0, 50, 0, 90);

// bue med uret fra 0 til 90 grader (de andre tre kvarte):
addArc([0,0], 40, 0, 90, true);

addCircle

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

Tilføjer en cirkel med det angivne centrum og den angivne radius.

// koncentriske cirkler:
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)

Tilføjer en ellipse eller en elliptisk bue. mx,my er hovedaksens slutpunkt relativt til centrum. ratio er forholdet mellem lilleaksen og hovedaksen. startParam og endParam er de ellipseparametre i radianer, hvor ellipsen starter og slutter. Brug 0 og 2*Math.PI for en fuld ellipse.

// fuld ellipse med en stor radius på 50 og en lille radius på 25:
addEllipse(0,0, 50,0, 0.5, 0, 2*Math.PI, false);

// øverste halvdel af en drejet ellipse:
addEllipse([0,0], [30,30], 0.3, 0, Math.PI, false);

addPolyline

addPolyline(points, closed, relative)

Tilføjer en polylinje gennem de angivne toppunkter. points er et array af toppunkter, der hver angives som [x, y], [x, y, bulge] eller [x, y, bulge, relative]. I stedet for x, y kan en RVector bruges.

• bulge definerer formen af det segment, der starter ved dette toppunkt: 0 (standard) for et lige segment, 1 for en halvcirkel mod uret, -1 for en halvcirkel med uret. Andre værdier giver buesegmenter derimellem (bulge er tangens til en fjerdedel af buevinklen).
• relative: true, hvis koordinaterne for dette toppunkt er relative til det forrige toppunkt.
• closed: true for at lukke polylinjen (standard er false).
• relative: true for at behandle koordinaterne for alle toppunkter som relative til det forrige toppunkt (standard er false).

// lukket rektangel:
addPolyline([[0,0], [100,0], [100,50], [0,50]], true);

// langhulsform med to halvcirkler:
addPolyline([[0,60], [80,60,1], [80,80], [0,80,1]], true);

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

addSpline

addSpline(fitPoints, closed)

Tilføjer en spline gennem de angivne pasningspunkter. fitPoints er et array af [x, y]-arrays eller RVector-objekter. Hvis closed er true, er splinen lukket (periodisk).

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

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

Vejledningen Kørsel af scripts fra en fil viser endnu et eksempel, der tegner en Lissajous-kurve 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)

Tilføjer en tekst på én linje ved den angivne position. Alle argumenter efter positionen er valgfrie:

• height: teksthøjde (standard 1)
• angle: tekstvinkel i grader (standard 0)
• font: skrifttypenavn (standard "Standard")
• vAlign: lodret justering: RS.VAlignTop (standard), RS.VAlignMiddle, RS.VAlignBase eller RS.VAlignBottom
• hAlign: vandret justering: RS.HAlignLeft (standard), RS.HAlignCenter eller RS.HAlignRight
• bold, italic: true for fed eller kursiv tekst (kun TrueType-skrifttyper)

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

Tilføjer en udfyldt flade (solid) med tre eller fire hjørner. Bemærk, at hjørnerne på en firesidet solid angives i zigzag-rækkefølge: første hjørne, andet hjørne, derefter hjørnet over for det andet hjørne og hjørnet over for det første hjørne. For at oprette en trekant skal du angive det tredje hjørne to gange.

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

// udfyldt trekant:
addSolid([60,0], [110,0], [85,50], [85,50]);

Tilføjelse af former, enheder og objekter

Følgende funktioner tilføjer objekter, der er oprettet med det komplette QCAD-API, til tegningen. De er nyttige, når de specialiserede oprettelsesfunktioner ovenfor ikke dækker et bestemt tilfælde.

addShape

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

Tilføjer den angivne form (RLine, RArc, RCircle, REllipse, RPolyline, RSpline, RPoint, …) som ny enhed på det aktuelle lag. Der kan valgfrit angives en farve (RColor), en linjetype (navn eller ID) og en linjevægt (for eksempel RLineweight.Weight050). Som standard bruges den aktuelle farve, linjetypen ByLayer og linjevægten 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)

Tilføjer alle former i det angivne array som nye enheder.

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)

Tilføjer den angivne enhed (REntity) til tegningen. Hvis der ikke angives nogen farve, bruges den aktuelle farve.

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)

Tilføjer et vilkårligt objekt (enhed, lag, blok, …) til tegningen og returnerer det tilføjede objekt.

// tilføj en blok med navnet "Marker" med et kryds i:
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);

// indsæt blokken to gange:
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)

Sletter det angivne objekt fra tegningen. Til sletning af enheder er funktionen deleteEntity som regel mere praktisk.

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

Lag og attributter

addLayer

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

Tilføjer et nyt lag med det angivne navn. Der kan valgfrit angives farvenavnet (standard "white", som vises sort på hvid baggrund), linjetypenavnet (standard "CONTINUOUS") og linjevægten (standard RLineweight.Weight000). Returnerer det nye lag eller undefined, hvis der allerede findes et lag med det angivne navn.

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

hasLayer

hasLayer(name)

Returnerer true, hvis der findes et lag med det angivne navn i tegningen.

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

setCurrentLayer

setCurrentLayer(name)

Indstiller det aktuelle lag. Alle enheder, der tilføjes derefter, placeres på dette lag.

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

setCurrentColor

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

Indstiller farven for enheder, der tilføjes derefter. Farven kan angives som RColor-objekt eller som værdier for rød, grøn og blå (0-255). Brug new RColor(RColor.ByLayer) for at nulstille farven til »Af lag«.

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

Forespørgsel på enheder

getEntity

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

Returnerer enheden for den angivne enhedsreference, dvs. enheden med det angivne ID, den aktuelle tilstand af den angivne enhed eller den enhed, der ligger tættest på den angivne position. Returnerer undefined, hvis der ikke findes nogen enhed.

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

// circle indeholder stadig det gamle centrum, getEntity returnerer den aktuelle tilstand:
getEntity(circle).getCenter();     // returnerer 10,0

// enheden tættest på 30,0:
getEntity(30,0).getRadius();       // returnerer 20

getShape

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

Returnerer geometrien for den angivne enhed som form (RLine for en linje, RArc for en bue, RPolyline for en polylinje, …). Former kan bruges til geometriske beregninger uden at ændre tegningen.

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

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

getClosestEntity

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

Returnerer den enhed, der ligger tættest på den angivne position. Hvis range er angivet, tages der kun hensyn til enheder inden for denne afstand fra positionen. Returnerer undefined, hvis der ikke findes nogen enhed.

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

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

getEntityShape

getEntityShape(entity, position)

Returnerer formen for det angivne enhedsobjekt. For sammensatte enheder, der består af flere former (blokreferencer, skraveringer, mål, tekster), returneres den form, der ligger tættest på den angivne position. Positionen er valgfri.

// en blokreference til en blok med et 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)));

// formen i blokreferencen nær 40,10 (rektanglet):
var s = getEntityShape(getEntity(ref), new RVector(41,10));
s.getLength();                     // returnerer 120

getIntersectionPoints

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

Returnerer et array med skæringspunkterne mellem de to angivne enheder eller former. Enheder kan angives som enhedsobjekter, enheds-ID’er eller former. Hvis limited er false, behandles enhederne, som om de var uendelige (linjer forlænget, buer som hele cirkler). Standard er true.

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

// markér skæringspunkterne med små cirkler:
for (var i=0; i<ips.length; i++) {
    addCircle(ips[i], 2);
}

isPosition og toVector

isPosition(value)
toVector(value)

isPosition returnerer true, hvis den angivne værdi er en position (RVector eller et array med to eller tre tal). toVector konverterer en position, der er angivet som array, til en RVector. Disse funktioner er nyttige, når du skriver dine egne funktioner, der accepterer positioner på samme måde 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]);                 // returnerer true
isPosition("abc");                 // returnerer false

Ændring af enheder

Transformationer

move

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

Flytter den angivne enhed med den angivne forskydning.

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

rotate

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

Drejer den angivne enhed med den angivne vinkel i grader omkring det angivne centrum. Hvis der ikke angives noget centrum, drejes enheden omkring origo 0,0.

// en vifte af linjer, drejet omkring 0,0:
for (var a=0; a<360; a+=30) {
    var l = addLine(10,0, 50,0);
    rotate(l, a);
}

// drej et kvadrat omkring dets centrum:
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])

Skalerer den angivne enhed med den angivne faktor. Fokuspunktet (det punkt, der forbliver på sin plads) er som standard origo 0,0. Forskellige faktorer for X og Y kan angives som array [sx, sy]. Bemærk, at nogle enheder som cirkler og buer ikke kan skaleres med forskellige faktorer i X og 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(...))

Spejler den angivne enhed om den akse, der er defineret af to punkter.

var pl = addPolyline([[10,0], [40,0], [40,30]], false);
// spejl om Y-aksen:
mirror(pl, 0,0, 0,100);

For at bevare originalen og oprette en spejlet kopi skal du først tilføje en kopi af enheden:

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

Trimning og forlængelse

trim

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

Trimmer enheden trimEntity til den begrænsende enhed limitingEntity. Den del af den trimmede enhed, der ligger ved klikpositionen trimPos, bevares. Hvis de to enheder ikke skærer hinanden, forlænges enheden til den begrænsende enhed. Hvis der er flere skæringspunkter, bruges det, der ligger tættest på klikpositionen limitingPos. Hvis trimBoth er true, trimmes begge enheder til hinanden.

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

// bevar den venstre del, linjen slutter nu ved 70,0:
trim(line, [10,0], limit);

// forlæng en linje til en cirkel:
var line = addLine(0,0, 50,0);
var circle = addCircle(100,0, 20);

// forlæng til skæringspunktet med cirklen tættest på 80,0:
trim(line, [25,0], circle, [80,0]);      // linjen slutter nu ved 80,0

trimBoth

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

Trimmer eller forlænger begge enheder til deres skæringspunkt. Dette er en genvej til trim med trimBoth sat til true.

// to linjer, der ikke rører hinanden, forlænges, så de danner et hjørne ved 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)

Forlænger den angivne enhed med den angivne længde. Negative værdier forkorter enheden. Som standard forlænges enheden ved sit slutpunkt. Angiv true for start for i stedet at forlænge den ved sit startpunkt, eller angiv en position tæt på den ende, der skal forlænges.

var line = addLine(0,0, 100,0);
lengthen(line, 20);              // linjen slutter nu ved 120,0
lengthen(line, true, -10);       // linjen starter nu ved 10,0

var arc = addArc(0,50, 30, 0, 90);
lengthen(arc, [30,50], 10);      // forlæng buen ved dens startpunkt

breakOut

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

Bryder segmentet af den angivne enhed ud ved den angivne position. Segmentet ender ved de nærmeste skæringspunkter med andre enheder på hver side af positionen. Hvis der ikke er noget skæringspunkt på den ene side, strækker segmentet sig til enhedens ende. Hvis removeSegment er true (standard), slettes segmentet. Ellers bevares det som en separat enhed.

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

// fjern den del af linjen, der ligger mellem 30,0 og 70,0:
breakOut(line, [50,0]);

autoTrim

autoTrim(entity, pos)
autoTrim(pos)

Det modsatte af breakOut: bevarer kun segmentet af den angivne enhed ved den angivne position og fjerner resten. Segmentet ender ved de nærmeste skæringspunkter med andre enheder på hver side af positionen.

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

// bevar kun delen mellem 30,0 og 70,0:
autoTrim(line, [50,0]);

divide

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

Opdeler den angivne enhed ved den angivne position. En åben enhed (linje, bue, åben polylinje, …) opdeles i to dele ved én position eller i tre dele ved to positioner. Lukkede enheder (cirkler, hele ellipser, lukkede polylinjer) kræver to positioner og opdeles i to dele.

var line = addLine(0,0, 100,0);
divide(line, [40,0]);            // to linjer: 0..40 og 40..100

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

Hjørner

round

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

Afrunder hjørnet mellem to enheder med en bue med den angivne radius (afrunding). Klikpositionerne angiver, hvilke ender af enhederne der afrundes. Hvis trim er true (standard), trimmes begge enheder til afrundingsbuen.

// et rektangel med afrundede hjørner:
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);

Hjørnerne i en polylinje kan også afrundes ved at angive den samme polylinje to gange med en klikposition på hvert af de to segmenter:

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

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

Affaser hjørnet mellem to enheder med en ret linje (skråkant). distance1 er afstanden fra hjørnet til affasningslinjen langs den første enhed, distance2 langs den anden enhed (standard er distance1). Hvis trim er true (standard), trimmes begge enheder til affasningslinjen. chamfer er et alias for 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)

Opretter paralleller til linjer, koncentriske buer og cirkler eller parallelkurver til ellipser og andre enheder. number er antallet af paralleller, der skal oprettes (standard 1). Parallellerne oprettes på begge sider af enheden, medmindre der angives en side, enten som position sidePos ved siden af enheden eller som side (RS.LeftHand, RS.RightHand eller RS.BothSides). Parallelforskydning af polylinjer og splines er kun tilgængelig i QCAD Professional.

var line = addLine(0,0, 100,0);
offset(line, 5);                 // én parallel på hver side

var line2 = addLine(0,30, 100,30);
offset(line2, 5, 2, RS.LeftHand);    // to paralleller på venstre side (ovenover)

var circle = addCircle(50,80, 10);
offset(circle, [50,95], 3, 4);   // fire koncentriske cirkler udenfor

reverse

reverse(entity)
reverse(x, y)

Vender retningen af den angivne enhed, dvs. bytter om på dens start- og slutpunkt.

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

explode

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

Eksploderer den angivne enhed til enklere enheder: polylinjer til linjer og buer, blokreferencer til deres indhold, tekster til linjer og splines, mål og skraveringer til linjer, buer osv. Den oprindelige enhed slettes.

options er et valgfrit objekt med indstillinger, der ellers hentes fra programmets præferencer, for eksempel { splineSegments: 64, textToPolylines: true }. Understøttede indstillinger er: splineTolerance, splineSegments, ellipseSegments, splinesToLineSegments, textToPolylines, textSplineToLineOrArc, multilineTextToSimpleText og circlesToPolylines.

var pl = addPolyline([[0,0], [100,0,1], [100,50], [0,50]], true);
explode(pl);                     // tre linjer og en bue

stretch

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

Strækker alle enheder i det rektangulære område, der er defineret af to hjørner, med den angivne forskydning. Enheder, der ligger helt inden for området, flyttes, mens enheder, der krydser områdets grænse, strækkes (kun de slutpunkter, der ligger inden for området, flyttes). Området kan også angives som RBox eller som lukket RPolyline-form. Hvis der er valgt enheder i tegningen, strækkes kun de valgte enheder.

// et rektangel af linjer:
addLine(0,0, 100,0);
addLine(100,0, 100,50);
addLine(100,50, 0,50);
addLine(0,50, 0,0);

// gør rektanglet 50 tegningsenheder bredere ved at strække dets højre side:
stretch([80,-10], [120,60], [50,0]);

deleteEntity

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

Sletter den angivne enhed fra tegningen.

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

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

paste

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

Indsætter indholdet af dokumentet sourceDocument i dokumentgrænsefladen destination eller i den aktuelle tegning, hvis destination er undefined. Det indsatte indhold flyttes med offset, skaleres med scale og drejes med rotation grader. Alle argumenter er påkrævede:

• flipHorizontal, flipVertical: true for at vende indholdet
• toCurrentLayer: true for at indsætte alle enheder på det aktuelle lag
• overwriteLayers, overwriteBlocks: true for at overskrive eksisterende lag eller blokke med samme navn

// opret et symbol i et dokument, der ikke vises på skærmen:
var symbol = createDocument();
startTransaction(symbol);
addCircle(0,0, 10);
addLine(-10,0, 10,0);
addLine(0,-10, 0,10);
endTransaction();

// indsæt det tre gange i den aktuelle tegning:
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 og endTransaction

startTransaction()
startTransaction(document)
endTransaction()

Som standard anvendes hvert Simple API-kald straks på tegningen og kan fortrydes enkeltvis. Mellem startTransaction() og endTransaction() samles alle ændringer og anvendes samlet, når endTransaction kaldes. Dette har to fordele:

• Det er meget hurtigere, når der tilføjes mange enheder.
• Alle ændringer kan fortrydes i ét enkelt trin.

Hvis et dokument (RDocument) eller en dokumentgrænseflade (RDocumentInterface) videregives til startTransaction, anvendes alle ændringer på dette dokument i stedet for på den aktuelle tegning. Dette er nyttigt til at oprette tegninger i baggrunden, for eksempel for at eksportere dem til 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();

Bemærk følgende, når du arbejder med transaktioner:

• Inden for en transaktion er ændringerne endnu ikke en del af tegningen. Ændringsfunktioner som trim eller round kan ikke referere til enheder, der er tilføjet i den samme transaktion.
• Enheder, der returneres af oprettelsesfunktioner inden for en transaktion, har ikke et gyldigt ID, heller ikke efter endTransaction. For senere at ændre sådanne enheder skal du referere til dem via position.
• Alle enheder, der tilføjes inden for en transaktion, placeres på det lag, der er aktuelt, når endTransaction kaldes. Indstil det aktuelle lag, før transaktionen startes, og brug separate transaktioner til forskellige lag.

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

// referér til de nye linjer via position for at afrunde hjørnet:
round([50,0], [100,25], 10);

getTransactionDocument og getTransactionDocumentInterface

getTransactionDocument()
getTransactionDocumentInterface()

Returnerer det dokument eller den dokumentgrænseflade, som den aktuelle transaktion gælder for. Uden for transaktioner returneres det aktuelle dokument og den aktuelle dokumentgrænseflade.

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

getOperation

getOperation()

Returnerer operationen (RAddObjectsOperation) for den aktuelle transaktion. Uden for en transaktion returneres en ny operation, som skal anvendes eksplicit. Dette er beregnet til avanceret brug, for eksempel til at kombinere Simple API-kald med det komplette QCAD-API.

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

Visning

autoZoom

autoZoom()

Zoomer den aktuelle visning, så hele tegningen er synlig.

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)

Zoomer til den angivne enhed, form eller det angivne rektangulære område. margin er margenen omkring området i pixels (standard 10).

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

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

Dokumenter og program

getMainWindow

getMainWindow()

Returnerer QCAD-programvinduet (RMainWindowQt).

getMainWindow().windowTitle;

getDocumentInterface

getDocumentInterface()

Returnerer dokumentgrænsefladen (RDocumentInterface) for den aktuelle tegning. Dokumentgrænsefladen forbinder et dokument med dets visninger og stiller funktioner til rådighed til import og eksport af filer, anvendelse af operationer, fortrydelse og gendannelse.

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

getDocument

getDocument()

Returnerer det aktuelle dokument (RDocument). Dokumentet indeholder alle enheder, lag, blokke osv. i en tegning og stiller funktioner til rådighed til at forespørge på dem.

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

getGraphicsView

getGraphicsView()

Returnerer den aktuelle eller senest aktive visning (RGraphicsView) af den aktuelle tegning.

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

createDocument

createDocument()

Opretter et nyt, tomt dokument i hukommelsen, som ikke vises i et vindue. Et sådant dokument uden skærmvisning kan fyldes ved hjælp af en transaktion og derefter indsættes i en tegning (se paste).

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

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

createDocumentInterface

createDocumentInterface()

Opretter et nyt, tomt dokument i hukommelsen sammen med en dokumentgrænseflade. Dokumentgrænsefladen kan bruges til at importere eller eksportere 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 og isInputEnabled

disableInput()
enableInput()
isInputEnabled()

disableInput deaktiverer QCAD-programvinduet for at forhindre brugerinput, for eksempel under lange operationer eller animationer. enableInput aktiverer programvinduet igen, og isInputEnabled returnerer true, hvis brugerinput aktuelt er aktiveret. Sørg altid for at aktivere input igen i slutningen af dit script.

update

update()

Behandler ventende hændelser, så brugergrænsefladen opdateres under lange operationer. Brugerinput skal være deaktiveret med disableInput, før update kaldes.

sleep

sleep(milliseconds)

Sætter scriptet på pause i den angivne tid i millisekunder, mens brugergrænsefladen holdes opdateret. Brugerinput skal være deaktiveret med disableInput, før sleep kaldes.

Følgende eksempel bruger disableInput, sleep og enableInput til at vise 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)

Viser en advarsel. I Script Shell vises advarsler i kommandolinjehistorikken. Ellers udskrives advarsler til konsollen.

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

Brugerinput

Følgende funktioner viser en enkel dialogboks, der beder brugeren om en værdi. Hvis brugeren annullerer dialogboksen, returneres undefined.

getInt

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

Beder brugeren om et heltal. value er startværdien (standard 0), step er trinstørrelsen for spinboksen (standard 1), min og max er det tilladte interval.

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)

Beder brugeren om et tal. value er startværdien (standard 0), decimals er antallet af viste decimaler (standard 1), min og max er det tilladte interval.

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

getText

getText(title, prompt, text)

Beder brugeren om en tekst. text er starteksten (standard tom).

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

getItem

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

Lader brugeren vælge et element fra en rulleliste. items er en streng med alle elementer adskilt af separator (standard ","). index er indekset for det oprindeligt valgte element (standard 0). Returnerer det valgte element eller undefined, hvis dialogboksen blev annulleret.

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

Eksempel: En flange

Dette eksempel kombinerer flere funktioner i Simple API for at tegne en flange med en boltcirkel, boltehuller på et separat lag og en rektangulær udskæring med afrundede hjørner:

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

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

// boltcirkel og centerlinjer:
setCurrentLayer("Center Lines");
addCircle(0,0, 75);
addLine(-110,0, 110,0);
addLine(0,-110, 0,110);

// boltehuller, tilføjet i én 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();

// kvadratisk udskæring med afrundede hjørner i midten:
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();

Udskæringens linjer tilføjes uden transaktion, så de kan videregives direkte til round. Boltehullerne tilføjes i en transaktion, hvilket er hurtigere og gør, at de kan fortrydes i ét trin.