Simple API

Innledning

QCAD Simple API er et lite sett med globale skriptfunksjoner som forenkler vanlige oppgaver som å legge til enheter i en tegning, spørre etter enheter og endre dem (flytte, trimme, avrunde, lage offset, …). Det er hovedsakelig laget for bruk i Script Shell og for korte prosedyreskript som kjøres fra en fil, men det kan brukes fra et hvilket som helst skript.

Simple API dekker bare en liten del av det komplette QCAD-API-et. Siden det selv er skrevet i ECMAScript (JavaScript), er det også et godt utgangspunkt for å lære hvordan det underliggende QCAD-API-et fungerer. Kildekoden finnes i filene scripts/simple.js og scripts/simple_*.js i QCAD-kildekoden.

Bruke Simple API

I Script Shell (Diverse > Utvikling > Skript Shell) og i skript som startes med Diverse > Utvikling > Kjør skript, er alle Simple API-funksjoner direkte tilgjengelige. Skriv for eksempel:

addLine(0,0, 100,100);

I dine egne skriptfiler, for eksempel i interaktive skripthandlinger eller kommandolinjeverktøy, må du først inkludere filen simple.js:

include("scripts/simple.js");

addLine(0,0, 100,100);

Alle funksjoner virker på tegningen som for øyeblikket er åpen i QCAD-programvinduet, med mindre en transaksjon brukes til å omdirigere dem til et annet dokument (se Transaksjoner).

Alle eksemplene på denne siden kan limes inn i Script Shell for en tom tegning. Hvert eksempel oppretter enhetene det trenger. Bruk Vis > Automatisk zoom eller funksjonen autoZoom() for å se resultatet.

Konvensjoner

Koordinater

Posisjoner kan angis på tre forskjellige måter:

• Som to separate tall: addLine(0,0, 100,100)
• Som en matrise med to tall: addLine([0,0], [100,100])
• Som vektorobjekt: addLine(new RVector(0,0), new RVector(100,100))

Vinkler angis alltid i grader, unntatt start- og sluttparameterne for ellipser, som angis i radianer.

Enhetsreferanser

Funksjoner som arbeider med en eksisterende enhet, godtar enheten i ulike former:

• En enhets-ID (tall), for eksempel 1234.
• Et enhetsobjekt slik det returneres av opprettelsesfunksjonene, for eksempel returverdien fra addLine(...).
• En posisjon i tegningen ([x,y] eller RVector): enheten som ligger nærmest den angitte posisjonen, brukes.
• En form (for eksempel new RLine(0,0, 100,0)): operasjonen brukes bare på formen, tegningen endres ikke.

var l = addLine(0,0, 100,0);
move(l, [0,10]);              // via enhetsobjekt
move(l.getId(), [0,10]);      // via enhets-ID
move([50,20], [0,10]);        // via posisjon: enheten nærmest 50,20

Klikkposisjoner

Noen operasjoner avhenger av hvor det klikkes på en enhet når det tilsvarende verktøyet brukes interaktivt. Ved trimming beholdes den delen av enheten som ligger ved klikkposisjonen, ved avrunding og avfasing bearbeides de endene av enhetene som ligger nærmest klikkposisjonene, og ved offset opprettes paralleller på den siden der klikkposisjonen ligger.

I Simple API kan en klikkposisjon følge etter hver enhetsreferanse. Hvis en enhet refereres via en posisjon, fungerer denne posisjonen også som klikkposisjon. Hvis ingen klikkposisjon er angitt, brukes enhetens midtpunkt:

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

// trim line mot limit, behold den delen av linjen som ligger ved 10,0:
trim(line, [10,0], limit);

Returverdier

• Opprettelsesfunksjoner returnerer den tillagte enheten. Enheten kan sendes til andre funksjoner eller spørres om informasjon (for eksempel getId(), getLength() eller getStartPoint()).
• Transformasjoner (move, rotate, scale, mirror, lengthen, reverse) returnerer den endrede enheten.
• Andre endringsfunksjoner (trim, round, bevel, offset, breakOut, autoTrim, divide, explode, stretch) returnerer transaksjonen som ble brukt på tegningen, eller undefined hvis operasjonen mislyktes.
• Hvis det sendes former i stedet for enheter, endrer transformasjonene de angitte formene, og alle andre funksjoner returnerer de resulterende formene som en matrise.

Mislykkede operasjoner utløser ingen feil. I stedet vises en advarsel i Script Shell, for eksempel «Enheten kan ikke trimmes.».

Opprette enheter

addPoint

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

Legger til en punktenhet ved den angitte posisjonen.

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

addLine

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

Legger til en linje fra startpunktet til sluttpunktet.

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

Legger til en uendelig linje (konstruksjonslinje) gjennom basispunktet x,y med retningen dx,dy. Retningen angis relativt til basispunktet.

// horisontal konstruksjonslinje og konstruksjonslinje på 45 grader gjennom 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)

Legger til en bue med angitt senter, radius, startvinkel og sluttvinkel. Vinkler angis i grader. Buer går mot klokken fra startvinkelen til sluttvinkelen, med mindre reversed er true (valgfritt, standard er false).

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

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

addCircle

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

Legger til en sirkel med angitt senter og radius.

// konsentriske sirkler:
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)

Legger til en ellipse eller en elliptisk bue. mx,my er hovedaksens endepunkt, relativt til senteret. ratio er forholdet mellom lilleaksen og hovedaksen. startParam og endParam er ellipseparameterne i radianer der ellipsen starter og slutter. Bruk 0 og 2*Math.PI for en hel ellipse.

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

// øvre halvdel av en rotert ellipse:
addEllipse([0,0], [30,30], 0.3, 0, Math.PI, false);

addPolyline

addPolyline(points, closed, relative)

Legger til en polylinje gjennom de angitte toppunktene. points er en matrise med toppunkter, der hvert er angitt som [x, y], [x, y, bulge] eller [x, y, bulge, relative]. I stedet for x, y kan en RVector brukes.

• bulge definerer formen på segmentet som starter ved dette toppunktet: 0 (standard) for et rett segment, 1 for en halvsirkel mot klokken, -1 for en halvsirkel med klokken. Andre verdier gir buesegmenter imellom (bulge er tangens til en fjerdedel av buevinkelen).
• relative: true hvis koordinatene til dette toppunktet er relative til forrige toppunkt.
• closed: true for å lukke polylinjen (standard er false).
• relative: true for å behandle koordinatene til alle toppunkter som relative til forrige toppunkt (standard er false).

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

// avlang hullform med to halvsirkler:
addPolyline([[0,60], [80,60,1], [80,80], [0,80,1]], true);

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

addSpline

addSpline(fitPoints, closed)

Legger til en spline gjennom de angitte tilpasningspunktene. fitPoints er en matrise med [x, y]-matriser eller RVector-objekter. Hvis closed er true, er splinen lukket (periodisk).

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

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

Veiledningen Kjøre skript fra en fil viser et annet eksempel som 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)

Legger til en tekst på én linje ved den angitte posisjonen. Alle argumenter etter posisjonen er valgfrie:

• height: teksthøyde (standard 1)
• angle: tekstvinkel i grader (standard 0)
• font: navn på skrifttype (standard "Standard")
• vAlign: vertikal justering: RS.VAlignTop (standard), RS.VAlignMiddle, RS.VAlignBase eller RS.VAlignBottom
• hAlign: horisontal justering: RS.HAlignLeft (standard), RS.HAlignCenter eller RS.HAlignRight
• bold, italic: true for fet 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])

Legger til en heldekkende flate (solid) med tre eller fire hjørner. Merk at hjørnene i en firesidet solid angis i sikksakkrekkefølge: første hjørne, andre hjørne, deretter hjørnet overfor det andre hjørnet og hjørnet overfor det første hjørnet. For å lage en trekant angir du det tredje hjørnet to ganger.

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

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

Legge til former, enheter og objekter

Følgende funksjoner legger til objekter som er opprettet med det komplette QCAD-API-et, i tegningen. De er nyttige når de spesialiserte opprettelsesfunksjonene ovenfor ikke dekker et bestemt tilfelle.

addShape

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

Legger til den angitte formen (RLine, RArc, RCircle, REllipse, RPolyline, RSpline, RPoint, …) som ny enhet på gjeldende lag. Valgfritt kan en farge (RColor), en linjetype (navn eller ID) og en linjevekt (for eksempel RLineweight.Weight050) angis. Som standard brukes gjeldende farge, linjetypen ByLayer og linjevekten 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)

Legger til alle formene i den angitte matrisen som nye enheter.

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)

Legger til den angitte enheten (REntity) i tegningen. Hvis ingen farge er angitt, brukes gjeldende farge.

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)

Legger til et hvilket som helst objekt (enhet, lag, blokk, …) i tegningen og returnerer det tillagte objektet.

// legg til en blokk med navnet "Marker" med et kryss 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);

// sett inn blokken to ganger:
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 angitte objektet fra tegningen. For å slette enheter er funksjonen deleteEntity vanligvis mer praktisk.

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

Lag og attributter

addLayer

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

Legger til et nytt lag med det angitte navnet. Valgfritt kan fargenavnet (standard "white", som vises svart på hvit bakgrunn), linjetypenavnet (standard "CONTINUOUS") og linjevekten (standard RLineweight.Weight000) angis. Returnerer det nye laget eller undefined hvis det allerede finnes et lag med det angitte navnet.

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

hasLayer

hasLayer(name)

Returnerer true hvis det finnes et lag med det angitte navnet i tegningen.

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

setCurrentLayer

setCurrentLayer(name)

Angir gjeldende lag. Alle enheter som legges til etterpå, plasseres på dette laget.

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

setCurrentColor

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

Angir fargen for enheter som legges til etterpå. Fargen kan angis som RColor-objekt eller som verdier for rød, grønn og blå (0-255). Bruk new RColor(RColor.ByLayer) for å tilbakestille fargen til «Etter 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);

Spørre etter enheter

getEntity

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

Returnerer enheten for den angitte enhetsreferansen, dvs. enheten med den angitte ID-en, gjeldende tilstand for den angitte enheten eller enheten som ligger nærmest den angitte posisjonen. Returnerer undefined hvis ingen enhet blir funnet.

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

// circle inneholder fortsatt det gamle senteret, getEntity returnerer gjeldende tilstand:
getEntity(circle).getCenter();     // returnerer 10,0

// enheten nærmest 30,0:
getEntity(30,0).getRadius();       // returnerer 20

getShape

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

Returnerer geometrien til den angitte enheten som form (RLine for en linje, RArc for en bue, RPolyline for en polylinje, …). Former kan brukes til geometriske beregninger uten å endre 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 enheten som ligger nærmest den angitte posisjonen. Hvis range er angitt, tas bare enheter innenfor denne avstanden fra posisjonen i betraktning. Returnerer undefined hvis ingen enhet blir funnet.

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 til det angitte enhetsobjektet. For sammensatte enheter som består av flere former (blokkreferanser, skraveringer, dimensjoner, tekster), returneres formen som ligger nærmest den angitte posisjonen. Posisjonen er valgfri.

// en blokkreferanse til en blokk 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 blokkreferansen nær 40,10 (rektangelet):
var s = getEntityShape(getEntity(ref), new RVector(41,10));
s.getLength();                     // returnerer 120

getIntersectionPoints

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

Returnerer en matrise med skjæringspunktene mellom de to angitte enhetene eller formene. Enheter kan angis som enhetsobjekter, enhets-ID-er eller former. Hvis limited er false, behandles enhetene som om de var uendelige (linjer forlenget, buer som hele sirkler). Standard er true.

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

// merk skjæringspunktene med små sirkler:
for (var i=0; i<ips.length; i++) {
    addCircle(ips[i], 2);
}

isPosition og toVector

isPosition(value)
toVector(value)

isPosition returnerer true hvis den angitte verdien er en posisjon (RVector eller en matrise med to eller tre tall). toVector konverterer en posisjon som er angitt som matrise, til en RVector. Disse funksjonene er nyttige når du skriver egne funksjoner som godtar posisjoner på samme måte 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

Endre enheter

Transformasjoner

move

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

Flytter den angitte enheten med den angitte forskyvningen.

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

rotate

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

Roterer den angitte enheten med den angitte vinkelen i grader rundt det angitte senteret. Hvis ikke noe senter er angitt, roteres enheten rundt origo 0,0.

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

// roter et kvadrat rundt senteret:
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 angitte enheten med den angitte faktoren. Fokuspunktet (punktet som blir liggende på plass) er som standard origo 0,0. Ulike faktorer for X og Y kan angis som matrise [sx, sy]. Merk at enkelte enheter, som sirkler og buer, ikke kan skaleres med ulike 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(...))

Speiler den angitte enheten om aksen som er definert av to punkter.

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

For å beholde originalen og lage en speilet kopi legger du først til en kopi av enheten:

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

Trimming og forlengelse

trim

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

Trimmer enheten trimEntity mot den begrensende enheten limitingEntity. Den delen av den trimmede enheten som ligger ved klikkposisjonen trimPos, beholdes. Hvis de to enhetene ikke skjærer hverandre, forlenges enheten til den begrensende enheten. Hvis det finnes flere skjæringspunkter, brukes det som ligger nærmest klikkposisjonen limitingPos. Hvis trimBoth er true, trimmes begge enhetene mot hverandre.

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

// behold den venstre delen, linjen slutter nå ved 70,0:
trim(line, [10,0], limit);

// forleng en linje til en sirkel:
var line = addLine(0,0, 50,0);
var circle = addCircle(100,0, 20);

// forleng til skjæringspunktet med sirkelen nærmest 80,0:
trim(line, [25,0], circle, [80,0]);      // linjen slutter nå ved 80,0

trimBoth

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

Trimmer eller forlenger begge enhetene til skjæringspunktet deres. Dette er en snarvei for trim med trimBoth satt til true.

// to linjer som ikke berører hverandre, forlenges slik at 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)

Forlenger den angitte enheten med den angitte lengden. Negative verdier forkorter enheten. Som standard forlenges enheten ved sluttpunktet. Angi true for start for å forlenge den ved startpunktet i stedet, eller angi en posisjon nær den enden som skal forlenges.

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

var arc = addArc(0,50, 30, 0, 90);
lengthen(arc, [30,50], 10);      // forleng buen ved startpunktet

breakOut

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

Bryter ut segmentet av den angitte enheten ved den angitte posisjonen. Segmentet slutter ved de nærmeste skjæringspunktene med andre enheter på hver side av posisjonen. Hvis det ikke finnes noe skjæringspunkt på den ene siden, strekker segmentet seg til enden av enheten. Hvis removeSegment er true (standard), slettes segmentet. Ellers beholdes det som en separat enhet.

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

// fjern delen av linjen mellom 30,0 og 70,0:
breakOut(line, [50,0]);

autoTrim

autoTrim(entity, pos)
autoTrim(pos)

Det motsatte av breakOut: beholder bare segmentet av den angitte enheten ved den angitte posisjonen og fjerner resten. Segmentet slutter ved de nærmeste skjæringspunktene med andre enheter på hver side av posisjonen.

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

// behold bare delen mellom 30,0 og 70,0:
autoTrim(line, [50,0]);

divide

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

Deler den angitte enheten ved den angitte posisjonen. En åpen enhet (linje, bue, åpen polylinje, …) deles i to deler ved én posisjon eller i tre deler ved to posisjoner. Lukkede enheter (sirkler, hele ellipser, lukkede polylinjer) krever to posisjoner og deles i to deler.

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 halvsirkler

Hjørner

round

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

Avrunder hjørnet mellom to enheter med en bue med den angitte radiusen (avrundingsbue). Klikkposisjonene angir hvilke ender av enhetene som avrundes. Hvis trim er true (standard), trimmes begge enhetene mot avrundingsbuen.

// et rektangel med avrundede 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ørnene i en polylinje kan også avrundes ved å angi den samme polylinjen to ganger med en klikkposisjon på hvert av de to segmentene:

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)

Avfaser hjørnet mellom to enheter med en rett linje (fase). distance1 er avstanden fra hjørnet til faselinjen langs den første enheten, distance2 langs den andre enheten (standard er distance1). Hvis trim er true (standard), trimmes begge enhetene mot faselinjen. 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)

Oppretter paralleller til linjer, konsentriske buer og sirkler eller parallelle kurver (offset-kurver) til ellipser og andre enheter. number er antall paralleller som skal opprettes (standard 1). Parallellene opprettes på begge sider av enheten, med mindre en side er angitt, enten som posisjon sidePos ved siden av enheten eller som side (RS.LeftHand, RS.RightHand eller RS.BothSides). Offset av polylinjer og splines er bare tilgjengelig i QCAD Professional.

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

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

var circle = addCircle(50,80, 10);
offset(circle, [50,95], 3, 4);   // fire konsentriske sirkler utenfor

reverse

reverse(entity)
reverse(x, y)

Snur retningen på den angitte enheten, dvs. bytter om start- og sluttpunktet.

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 angitte enheten til enklere enheter: polylinjer til linjer og buer, blokkreferanser til innholdet sitt, tekster til linjer og splines, dimensjoner og skraveringer til linjer, buer osv. Den opprinnelige enheten slettes.

options er et valgfritt objekt med innstillinger som ellers hentes fra programinnstillingene, for eksempel { splineSegments: 64, textToPolylines: true }. Støttede alternativer 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 én bue

stretch

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

Strekker alle enheter i det rektangulære området som er definert av to hjørner, med den angitte forskyvningen. Enheter som ligger helt innenfor området, flyttes, mens enheter som krysser områdets grense, strekkes (bare endepunktene innenfor området flyttes). Området kan også angis som RBox eller som lukket RPolyline-form. Hvis det er valgt enheter i tegningen, strekkes bare de valgte enhetene.

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

// gjør rektangelet 50 tegningsenheter bredere ved å strekke høyre side:
stretch([80,-10], [120,60], [50,0]);

deleteEntity

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

Sletter den angitte enheten fra tegningen.

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

deleteEntity(l1);                // via enhet
deleteEntity(l2.getId());        // via enhets-ID
deleteEntity(50,20);             // via posisjon

paste

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

Limer inn innholdet i dokumentet sourceDocument i dokumentgrensesnittet destination, eller i gjeldende tegning hvis destination er undefined. Det innlimte innholdet flyttes med offset, skaleres med scale og roteres med rotation grader. Alle argumenter er obligatoriske:

• flipHorizontal, flipVertical: true for å vende innholdet
• toCurrentLayer: true for å lime inn alle enheter på gjeldende lag
• overwriteLayers, overwriteBlocks: true for å overskrive eksisterende lag eller blokker med samme navn

// lag et symbol i et dokument som ikke vises på skjermen:
var symbol = createDocument();
startTransaction(symbol);
addCircle(0,0, 10);
addLine(-10,0, 10,0);
addLine(0,-10, 0,10);
endTransaction();

// lim det inn tre ganger i gjeldende 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);
}

Transaksjoner

startTransaction og endTransaction

startTransaction()
startTransaction(document)
endTransaction()

Som standard brukes hvert Simple API-kall umiddelbart på tegningen og kan angres enkeltvis. Mellom startTransaction() og endTransaction() samles alle endringer og brukes samlet når endTransaction kalles. Dette har to fordeler:

• Det er mye raskere når mange enheter legges til.
• Alle endringer kan angres i ett enkelt trinn.

Hvis et dokument (RDocument) eller et dokumentgrensesnitt (RDocumentInterface) sendes til startTransaction, brukes alle endringer på dette dokumentet i stedet for på gjeldende tegning. Dette er nyttig for å lage tegninger i bakgrunnen, for eksempel for å 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();

Vær oppmerksom på følgende når du arbeider med transaksjoner:

• Innenfor en transaksjon er endringene ennå ikke en del av tegningen. Endringsfunksjoner som trim eller round kan ikke referere til enheter som er lagt til i samme transaksjon.
• Enheter som returneres av opprettelsesfunksjoner innenfor en transaksjon, har ikke en gyldig ID, heller ikke etter endTransaction. For å endre slike enheter senere refererer du til dem via posisjon.
• Alle enheter som legges til innenfor en transaksjon, plasseres på laget som er gjeldende når endTransaction kalles. Angi gjeldende lag før transaksjonen startes, og bruk separate transaksjoner for ulike lag.

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

// referer til de nye linjene via posisjon for å avrunde hjørnet:
round([50,0], [100,25], 10);

getTransactionDocument og getTransactionDocumentInterface

getTransactionDocument()
getTransactionDocumentInterface()

Returnerer dokumentet eller dokumentgrensesnittet som gjeldende transaksjon gjelder for. Utenfor transaksjoner returneres gjeldende dokument og gjeldende dokumentgrensesnitt.

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

getOperation

getOperation()

Returnerer operasjonen (RAddObjectsOperation) for gjeldende transaksjon. Utenfor en transaksjon returneres en ny operasjon som må brukes eksplisitt. Dette er ment for avansert bruk, for eksempel for å kombinere Simple API-kall med det komplette 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();

Visning

autoZoom

autoZoom()

Zoomer gjeldende visning slik at 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 angitte enheten, formen eller det rektangulære området. margin er margen rundt området i piksler (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 dokumentgrensesnittet (RDocumentInterface) for gjeldende tegning. Dokumentgrensesnittet kobler et dokument til visningene sine og har funksjoner for å importere og eksportere filer, utføre operasjoner, angre og gjøre om.

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

getDocument

getDocument()

Returnerer gjeldende dokument (RDocument). Dokumentet inneholder alle enheter, lag, blokker osv. i en tegning og har funksjoner for å spørre etter dem.

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

getGraphicsView

getGraphicsView()

Returnerer gjeldende eller sist aktive visning (RGraphicsView) av gjeldende tegning.

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

createDocument

createDocument()

Oppretter et nytt, tomt dokument i minnet som ikke vises i et vindu. Et slikt dokument uten skjermvisning kan fylles ved hjelp av en transaksjon og deretter limes inn 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()

Oppretter et nytt, tomt dokument i minnet sammen med et dokumentgrensesnitt. Dokumentgrensesnittet kan brukes til å 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 å hindre brukerinndata, for eksempel under lange operasjoner eller animasjoner. enableInput aktiverer programvinduet igjen, og isInputEnabled returnerer true hvis brukerinndata for øyeblikket er aktivert. Sørg alltid for å aktivere inndata igjen på slutten av skriptet ditt.

update

update()

Behandler ventende hendelser slik at brukergrensesnittet oppdateres under lange operasjoner. Brukerinndata må være deaktivert med disableInput før update kalles.

sleep

sleep(milliseconds)

Setter skriptet på pause i den angitte tiden i millisekunder, samtidig som brukergrensesnittet holdes oppdatert. Brukerinndata må være deaktivert med disableInput før sleep kalles.

Følgende eksempel bruker disableInput, sleep og enableInput til å vise en enkel animasjon:

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 skrives advarsler ut til konsollen.

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

Brukerinndata

Følgende funksjoner viser en enkel dialog som ber brukeren om en verdi. Hvis brukeren avbryter dialogen, returneres undefined.

getInt

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

Ber brukeren om et heltall. value er startverdien (standard 0), step er trinnet for tallboksen (standard 1), min og max er det tillatte området.

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 brukeren om et tall. value er startverdien (standard 0), decimals er antall viste desimaler (standard 1), min og max er det tillatte området.

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

getText

getText(title, prompt, text)

Ber brukeren 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)

Lar brukeren velge et element fra en nedtrekksliste. items er en streng med alle elementene atskilt med separator (standard ","). index er indeksen til elementet som er valgt i utgangspunktet (standard 0). Returnerer det valgte elementet eller undefined hvis dialogen ble avbrutt.

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 flens

Dette eksemplet kombinerer flere funksjoner i Simple API for å tegne en flens med en boltsirkel, bolthull på et eget lag og en rektangulær utsparing med avrundede hjørner:

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

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

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

// bolthull, lagt til i én transaksjon:
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 utsparing med avrundede 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();

Linjene i utsparingen legges til uten transaksjon, slik at de kan sendes direkte til round. Bolthullene legges til i en transaksjon, noe som er raskere og gjør at de kan angres i ett trinn.