Simple API

Uvod

QCAD Simple API je majhen nabor globalnih skriptnih funkcij, ki poenostavijo pogosta opravila, kot so dodajanje entitet v risbo, poizvedovanje po entitetah in njihovo spreminjanje (premikanje, krajšanje, zaokroževanje, ustvarjanje vzporednic, …). Namenjen je predvsem uporabi v Script Shell in za kratke proceduralne skripte, ki se zaženejo iz datoteke, vendar ga je mogoče uporabiti v katerem koli skriptu.

Simple API pokriva le majhen del celotnega API-ja QCAD. Ker je sam napisan v ECMAScript (JavaScript), je tudi dobro izhodišče za spoznavanje delovanja osnovnega API-ja QCAD. Izvorno kodo najdete v datotekah scripts/simple.js in scripts/simple_*.js izvorne kode QCAD.

Uporaba Simple API

V Script Shell (Razno > Razvoj > Ukazna lupina) in v skriptih, zagnanih z Razno > Razvoj > Zaženi skripto, so vse funkcije Simple API na voljo neposredno. Vnesite na primer:

addLine(0,0, 100,100);

V lastnih skriptnih datotekah, na primer v interaktivnih skriptnih dejanjih ali orodjih ukazne vrstice, najprej vključite datoteko simple.js:

include("scripts/simple.js");

addLine(0,0, 100,100);

Vse funkcije delujejo na risbi, ki je trenutno odprta v oknu aplikacije QCAD, razen če jih transakcija preusmeri na drug dokument (glejte Transakcije).

Vse primere na tej strani lahko prilepite v Script Shell prazne risbe. Vsak primer ustvari entitete, ki jih potrebuje. Za prikaz rezultata uporabite Pogled > Samodejna povečava ali funkcijo autoZoom().

Dogovori

Koordinate

Položaje je mogoče podati na tri različne načine:

• Kot dve ločeni števili: addLine(0,0, 100,100)
• Kot polje dveh števil: addLine([0,0], [100,100])
• Kot vektorski objekt: addLine(new RVector(0,0), new RVector(100,100))

Koti so vedno podani v stopinjah, razen začetnega in končnega parametra elips, ki sta podana v radianih.

Sklicevanje na entitete

Funkcije, ki delajo z obstoječo entiteto, sprejmejo entiteto v različnih oblikah:

• ID entitete (število), na primer 1234.
• Objekt entitete, kot ga vrnejo funkcije za ustvarjanje, na primer vrnjena vrednost addLine(...).
• Položaj v risbi ([x,y] ali RVector): uporabi se entiteta, ki je najbližja podanemu položaju.
• Oblika (na primer new RLine(0,0, 100,0)): operacija se izvede samo na obliki, risba se ne spremeni.

var l = addLine(0,0, 100,0);
move(l, [0,10]);              // z objektom entitete
move(l.getId(), [0,10]);      // z ID-jem entitete
move([50,20], [0,10]);        // s položajem: entiteta, najbližja 50,20

Položaji klikov

Nekatere operacije so odvisne od tega, kje kliknete entiteto, ko enakovredno orodje uporabljate interaktivno. Krajšanje ohrani del entitete na položaju klika, zaokroževanje in posnetje roba obdelata konca entitet, ki sta najbližja položajema klikov, ustvarjanje vzporednic pa ustvari vzporednice na strani položaja klika.

V Simple API lahko vsakemu sklicu na entiteto sledi položaj klika. Če je entiteta podana s položajem, ta položaj služi tudi kot položaj klika. Če položaj klika ni podan, se uporabi srednja točka entitete:

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

// skrajšaj črto do meje, ohrani del črte pri 10,0:
trim(line, [10,0], limit);

Vrnjene vrednosti

• Funkcije za ustvarjanje vrnejo dodano entiteto. Entiteto lahko podate drugim funkcijam ali od nje pridobite podatke (na primer getId(), getLength() ali getStartPoint()).
• Transformacije (move, rotate, scale, mirror, lengthen, reverse) vrnejo spremenjeno entiteto.
• Druge funkcije za spreminjanje (trim, round, bevel, offset, breakOut, autoTrim, divide, explode, stretch) vrnejo transakcijo, ki je bila uporabljena na risbi, ali undefined, če operacija ni uspela.
• Če namesto entitet podate oblike, transformacije spremenijo podane oblike, vse druge funkcije pa vrnejo nastale oblike kot polje.

Neuspele operacije ne sprožijo napake. Namesto tega se v Script Shell prikaže opozorilo, na primer „Entitete ni mogoče krajšat.“.

Ustvarjanje entitet

addPoint

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

Doda entiteto točke na podanem položaju.

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

addLine

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

Doda črto od začetne do končne točke.

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

Doda neskončno črto (pomožno črto) skozi osnovno točko x,y s smerjo dx,dy. Smer je podana relativno glede na osnovno točko.

// vodoravna pomožna črta in pomožna črta pod 45 stopinjami skozi 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)

Doda lok s podanim središčem, polmerom, začetnim in končnim kotom. Koti so v stopinjah. Loki potekajo v nasprotni smeri urinega kazalca od začetnega do končnega kota, razen če je reversed true (neobvezno, privzeto je false).

// četrtinski lok od 0 do 90 stopinj:
addArc(0,0, 50, 0, 90);

// lok v smeri urinega kazalca od 0 do 90 stopinj (ostale tri četrtine):
addArc([0,0], 40, 0, 90, true);

addCircle

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

Doda krog s podanim središčem in polmerom.

// koncentrični krogi:
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)

Doda elipso ali eliptični lok. mx,my je končna točka glavne osi, relativno glede na središče. ratio je razmerje med stransko in glavno osjo. startParam in endParam sta parametra elipse v radianih, kjer se elipsa začne in konča. Za celotno elipso uporabite 0 in 2*Math.PI.

// celotna elipsa z velikim polmerom 50 in malim polmerom 25:
addEllipse(0,0, 50,0, 0.5, 0, 2*Math.PI, false);

// zgornja polovica zasukane elipse:
addEllipse([0,0], [30,30], 0.3, 0, Math.PI, false);

addPolyline

addPolyline(points, closed, relative)

Doda lomljenko skozi podana oglišča. points je polje oglišč, od katerih je vsako podano kot [x, y], [x, y, bulge] ali [x, y, bulge, relative]. Namesto x, y lahko uporabite RVector.

• bulge (izboklina) določa obliko segmenta, ki se začne v tem oglišču: 0 (privzeto) za raven segment, 1 za polkrog v nasprotni smeri urinega kazalca, -1 za polkrog v smeri urinega kazalca. Druge vrednosti ustvarijo vmesne ločne segmente (izboklina je tangens četrtine središčnega kota loka).
• relative: true, če so koordinate tega oglišča relativne glede na prejšnje oglišče.
• closed: true za zaključeno lomljenko (privzeto je false).
• relative: true, če naj se koordinate vseh oglišč obravnavajo kot relativne glede na prejšnje oglišče (privzeto je false).

// zaključen pravokotnik:
addPolyline([[0,0], [100,0], [100,50], [0,50]], true);

// oblika utora z dvema polkrogoma:
addPolyline([[0,60], [80,60,1], [80,80], [0,80,1]], true);

// cikcak črta z relativnimi koordinatami:
addPolyline([[0,100], [10,10], [10,-10], [10,10], [10,-10]], false, true);

addSpline

addSpline(fitPoints, closed)

Doda krivuljo (spline) skozi podane točke prileganja. fitPoints je polje polj [x, y] ali objektov RVector. Če je closed true, je krivulja zaključena (periodična).

// odprta krivulja:
addSpline([[0,0], [30,40], [60,0], [90,40]], false);

// zaključena krivulja:
addSpline([[0,60], [40,80], [80,60], [40,100]], true);

Vadnica Zaganjanje skriptov iz datoteke prikazuje še en primer, ki izriše Lissajousovo krivuljo kot krivuljo 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)

Doda enovrstično besedilo na podanem položaju. Vsi argumenti za položajem so neobvezni:

• height: višina besedila (privzeto 1)
• angle: kot besedila v stopinjah (privzeto 0)
• font: ime pisave (privzeto "Standard")
• vAlign: navpična poravnava: RS.VAlignTop (privzeto), RS.VAlignMiddle, RS.VAlignBase ali RS.VAlignBottom
• hAlign: vodoravna poravnava: RS.HAlignLeft (privzeto), RS.HAlignCenter ali RS.HAlignRight
• bold, italic: true za krepko ali ležeče besedilo (samo pisave TrueType)

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

addSolid

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

Doda zapolnjeno območje (polnilo) s tremi ali štirimi oglišči. Upoštevajte, da so oglišča štiristranega polnila podana v cikcak vrstnem redu: prvo oglišče, drugo oglišče, nato oglišče nasproti drugega oglišča in oglišče nasproti prvega oglišča. Za trikotnik podajte tretje oglišče dvakrat.

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

// zapolnjen trikotnik:
addSolid([60,0], [110,0], [85,50], [85,50]);

Dodajanje oblik, entitet in objektov

Naslednje funkcije v risbo dodajo objekte, ki so bili ustvarjeni s celotnim API-jem QCAD. Uporabne so, kadar zgoraj opisane specializirane funkcije za ustvarjanje ne pokrivajo določenega primera.

addShape

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

Doda podano obliko (RLine, RArc, RCircle, REllipse, RPolyline, RSpline, RPoint, …) kot novo entiteto na trenutno plast. Po želji lahko podate barvo (RColor), tip črte (ime ali ID) in debelino črte (na primer RLineweight.Weight050). Privzeto se uporabijo trenutna barva, tip črte ByLayer in debelina črte 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)

Doda vse oblike v podanem polju kot nove entitete.

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)

Doda podano entiteto (REntity) v risbo. Če barva ni podana, se uporabi trenutna barva.

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)

Doda poljuben objekt (entiteto, plast, blok, …) v risbo in vrne dodani objekt.

// dodaj blok z imenom "Marker", ki vsebuje križec:
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);

// vstavi blok dvakrat:
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)

Izbriše podani objekt iz risbe. Za brisanje entitet je običajno priročnejša funkcija deleteEntity.

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

Plasti in atributi

addLayer

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

Doda novo plast s podanim imenom. Po želji lahko podate ime barve (privzeto "white", ki je na belem ozadju prikazana črno), ime tipa črte (privzeto "CONTINUOUS") in debelino črte (privzeto RLineweight.Weight000). Vrne novo plast ali undefined, če plast s podanim imenom že obstaja.

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

hasLayer

hasLayer(name)

Vrne true, če v risbi obstaja plast s podanim imenom.

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

setCurrentLayer

setCurrentLayer(name)

Nastavi trenutno plast. Vse pozneje dodane entitete so postavljene na to plast.

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

setCurrentColor

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

Nastavi barvo za entitete, ki so dodane pozneje. Barvo lahko podate kot objekt RColor ali kot vrednosti rdeče, zelene in modre (0–255). Z new RColor(RColor.ByLayer) ponastavite barvo na „Po plasti“.

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

Poizvedovanje po entitetah

getEntity

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

Vrne entiteto za podani sklic na entiteto, tj. entiteto s podanim ID-jem, trenutno stanje podane entitete ali entiteto, ki je najbližja podanemu položaju. Vrne undefined, če entiteta ni najdena.

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

// circle še vedno vsebuje staro središče, getEntity vrne trenutno stanje:
getEntity(circle).getCenter();     // vrne 10,0

// entiteta, najbližja 30,0:
getEntity(30,0).getRadius();       // vrne 20

getShape

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

Vrne geometrijo podane entitete kot obliko (RLine za črto, RArc za lok, RPolyline za lomljenko, …). Oblike lahko uporabite za geometrijske izračune, ne da bi spremenili risbo.

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

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

getClosestEntity

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

Vrne entiteto, ki je najbližja podanemu položaju. Če je podan range, se upoštevajo samo entitete znotraj te razdalje od položaja. Vrne undefined, če entiteta ni najdena.

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

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

getEntityShape

getEntityShape(entity, position)

Vrne obliko podanega objekta entitete. Pri sestavljenih entitetah, ki so sestavljene iz več oblik (blokovne reference, šrafure, kote, besedila), se vrne oblika, ki je najbližja podanemu položaju. Položaj je neobvezen.

// blokovna referenca bloka s pravokotnikom:
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)));

// oblika blokovne reference blizu 40,10 (pravokotnik):
var s = getEntityShape(getEntity(ref), new RVector(41,10));
s.getLength();                     // vrne 120

getIntersectionPoints

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

Vrne polje s presečišči dveh podanih entitet ali oblik. Entitete lahko podate kot objekte entitet, ID-je entitet ali oblike. Če je limited false, se entitete obravnavajo, kot da bi bile neskončne (podaljšane črte, loki kot celotni krogi). Privzeto je true.

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

// označi presečišča z majhnimi krogi:
for (var i=0; i<ips.length; i++) {
    addCircle(ips[i], 2);
}

isPosition in toVector

isPosition(value)
toVector(value)

isPosition vrne true, če je podana vrednost položaj (RVector ali polje dveh ali treh števil). toVector pretvori položaj, podan kot polje, v RVector. Ti funkciji sta uporabni pri pisanju lastnih funkcij, ki sprejemajo položaje na enak način kot 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]);                 // vrne true
isPosition("abc");                 // vrne false

Spreminjanje entitet

Transformacije

move

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

Premakne podano entiteto za podani odmik.

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

rotate

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

Zavrti podano entiteto za podani kot v stopinjah okoli podanega središča. Če središče ni podano, se entiteta zavrti okoli izhodišča 0,0.

// pahljača črt, zavrtenih okoli 0,0:
for (var a=0; a<360; a+=30) {
    var l = addLine(10,0, 50,0);
    rotate(l, a);
}

// zavrti kvadrat okoli njegovega središča:
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])

Spremeni merilo podane entitete za podani faktor. Žariščna točka (točka, ki ostane na mestu) je privzeto izhodišče 0,0. Različne faktorje za X in Y lahko podate kot polje [sx, sy]. Upoštevajte, da nekaterih entitet, kot so krogi in loki, ni mogoče povečati z različnimi faktorji v X in 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(...))

Zrcali podano entiteto prek osi, določene z dvema točkama.

var pl = addPolyline([[10,0], [40,0], [40,30]], false);
// zrcali prek osi Y:
mirror(pl, 0,0, 0,100);

Če želite ohraniti izvirnik in ustvariti zrcaljeno kopijo, najprej dodajte kopijo entitete:

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

Krajšanje in podaljševanje

trim

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

Skrajša entiteto trimEntity do mejitvene entitete limitingEntity. Ohrani se del skrajšane entitete na položaju klika trimPos. Če se entiteti ne sekata, se entiteta podaljša do mejitvene entitete. Če obstaja več presečišč, se uporabi tisto, ki je najbližje položaju klika limitingPos. Če je trimBoth true, se obe entiteti skrajšata druga do druge.

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

// ohrani levi del, črta se zdaj konča pri 70,0:
trim(line, [10,0], limit);

// podaljšaj črto do kroga:
var line = addLine(0,0, 50,0);
var circle = addCircle(100,0, 20);

// podaljšaj do presečišča s krogom, ki je najbližje 80,0:
trim(line, [25,0], circle, [80,0]);      // črta se zdaj konča pri 80,0

trimBoth

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

Skrajša ali podaljša obe entiteti do njunega presečišča. To je bližnjica za trim z trimBoth, nastavljenim na true.

// dve črti, ki se ne dotikata, se podaljšata, da tvorita vogal pri 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)

Podaljša podano entiteto za podano vrednost. Negativne vrednosti entiteto skrajšajo. Privzeto se entiteta podaljša na končni točki. Za start podajte true, če jo želite namesto tega podaljšati na začetni točki, ali podajte položaj blizu konca, ki naj se podaljša.

var line = addLine(0,0, 100,0);
lengthen(line, 20);              // črta se zdaj konča pri 120,0
lengthen(line, true, -10);       // črta se zdaj začne pri 10,0

var arc = addArc(0,50, 30, 0, 90);
lengthen(arc, [30,50], 10);      // podaljšaj lok na njegovi začetni točki

breakOut

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

Odlomi segment podane entitete na podanem položaju. Segment se konča pri najbližjih presečiščih z drugimi entitetami na obeh straneh položaja. Če na eni strani ni presečišča, segment sega do konca entitete. Če je removeSegment true (privzeto), se segment izbriše. V nasprotnem primeru se ohrani kot ločena entiteta.

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

// odstrani del črte med 30,0 in 70,0:
breakOut(line, [50,0]);

autoTrim

autoTrim(entity, pos)
autoTrim(pos)

Nasprotje breakOut: ohrani samo segment podane entitete na podanem položaju in odstrani preostanek. Segment se konča pri najbližjih presečiščih z drugimi entitetami na obeh straneh položaja.

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

// ohrani samo del med 30,0 in 70,0:
autoTrim(line, [50,0]);

divide

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

Razdeli podano entiteto na podanem položaju. Odprta entiteta (črta, lok, odprta lomljenka, …) se razdeli na dva dela pri enem položaju ali na tri dele pri dveh položajih. Zaključene entitete (krogi, celotne elipse, zaključene lomljenke) zahtevajo dva položaja in se razdelijo na dva dela.

var line = addLine(0,0, 100,0);
divide(line, [40,0]);            // dve črti: 0..40 in 40..100

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

Vogali

round

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

Zaokroži vogal med dvema entitetama z lokom s podanim polmerom (zaokrožitev). Položaja klikov določata, kateri konci entitet se zaokrožijo. Če je trim true (privzeto), se obe entiteti skrajšata do loka zaokrožitve.

// pravokotnik z zaobljenimi vogali:
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);

Zaokrožiti je mogoče tudi vogale lomljenke, tako da isto lomljenko podate dvakrat s položajem klika na vsakem od obeh segmentov:

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

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

Odreže vogal med dvema entitetama z ravno črto (posneti rob). distance1 je razdalja črte odreza od vogala vzdolž prve entitete, distance2 vzdolž druge entitete (privzeto distance1). Če je trim true (privzeto), se obe entiteti skrajšata do črte odreza. chamfer je drugo ime za 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)

Ustvari vzporednice črtam, koncentrične loke in kroge ali vzporedne krivulje elips in drugih entitet. number je število vzporednic, ki naj se ustvarijo (privzeto 1). Vzporednice se ustvarijo na obeh straneh entitete, razen če je podana stran, bodisi kot položaj sidePos ob entiteti bodisi kot side (RS.LeftHand, RS.RightHand ali RS.BothSides). Odmik lomljenk in krivulj spline je na voljo samo v QCAD Professional.

var line = addLine(0,0, 100,0);
offset(line, 5);                 // ena vzporednica na vsaki strani

var line2 = addLine(0,30, 100,30);
offset(line2, 5, 2, RS.LeftHand);    // dve vzporednici na levi strani (zgoraj)

var circle = addCircle(50,80, 10);
offset(circle, [50,95], 3, 4);   // štirje koncentrični krogi zunaj

reverse

reverse(entity)
reverse(x, y)

Obrne smer podane entitete, tj. zamenja njeno začetno in končno točko.

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

explode

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

Razbije podano entiteto na preprostejše entitete: lomljenke na črte in loke, blokovne reference na njihovo vsebino, besedila na črte in krivulje spline, kote in šrafure na črte, loke itd. Izvirna entiteta se izbriše.

options je neobvezen objekt z nastavitvami, ki se sicer prevzamejo iz nastavitev aplikacije, na primer { splineSegments: 64, textToPolylines: true }. Podprte možnosti so: splineTolerance, splineSegments, ellipseSegments, splinesToLineSegments, textToPolylines, textSplineToLineOrArc, multilineTextToSimpleText in circlesToPolylines.

var pl = addPolyline([[0,0], [100,0,1], [100,50], [0,50]], true);
explode(pl);                     // tri črte in en lok

stretch

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

Raztegne (orodje Razširi) vse entitete v pravokotnem območju, določenem z dvema ogliščema, za podani odmik. Entitete, ki ležijo v celoti znotraj območja, se premaknejo, entitete, ki prečkajo mejo območja, se raztegnejo (premaknejo se samo končne točke znotraj območja). Območje lahko podate tudi kot RBox ali kot obliko zaključene RPolyline. Če so v risbi izbrane entitete, se raztegnejo samo izbrane entitete.

// pravokotnik iz črt:
addLine(0,0, 100,0);
addLine(100,0, 100,50);
addLine(100,50, 0,50);
addLine(0,50, 0,0);

// razširi pravokotnik za 50 enot z raztegom njegove desne strani:
stretch([80,-10], [120,60], [50,0]);

deleteEntity

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

Izbriše podano entiteto iz risbe.

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

deleteEntity(l1);                // z entiteto
deleteEntity(l2.getId());        // z ID-jem entitete
deleteEntity(50,20);             // s položajem

paste

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

Prilepi vsebino dokumenta sourceDocument v vmesnik dokumenta destination ali v trenutno risbo, če je destination undefined. Prilepljena vsebina se premakne za offset, spremeni merilo za scale in zavrti za rotation stopinj. Vsi argumenti so obvezni:

• flipHorizontal, flipVertical: true za obračanje vsebine
• toCurrentLayer: true za lepljenje vseh entitet na trenutno plast
• overwriteLayers, overwriteBlocks: true za prepis obstoječih plasti ali blokov z enakim imenom

// ustvari simbol v dokumentu, ki ni prikazan na zaslonu:
var symbol = createDocument();
startTransaction(symbol);
addCircle(0,0, 10);
addLine(-10,0, 10,0);
addLine(0,-10, 0,10);
endTransaction();

// prilepi ga trikrat v trenutno risbo:
for (var i=0; i<3; i++) {
    paste(symbol, undefined, [i*50, 0], 1+i*0.5, i*15, false, false, false, false, false);
}

Transakcije

startTransaction in endTransaction

startTransaction()
startTransaction(document)
endTransaction()

Privzeto se vsak klic Simple API takoj uporabi na risbi in ga je mogoče razveljaviti posamično. Med startTransaction() in endTransaction() se vse spremembe zberejo in uporabijo skupaj, ko se pokliče endTransaction. To ima dve prednosti:

• Pri dodajanju številnih entitet je veliko hitreje.
• Vse spremembe je mogoče razveljaviti v enem samem koraku.

Če funkciji startTransaction podate dokument (RDocument) ali vmesnik dokumenta (RDocumentInterface), se vse spremembe namesto na trenutni risbi uporabijo na tem dokumentu. To je uporabno za ustvarjanje risb v ozadju, na primer za njihov izvoz v datoteko (glejte createDocumentInterface).

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

Pri delu s transakcijami upoštevajte naslednje:

• Znotraj transakcije spremembe še niso del risbe. Funkcije za spreminjanje, kot sta trim ali round, se ne morejo sklicevati na entitete, dodane v isti transakciji.
• Entitete, ki jih funkcije za ustvarjanje vrnejo znotraj transakcije, nimajo veljavnega ID-ja, niti po endTransaction. Če želite takšne entitete pozneje spremeniti, se nanje sklicujte s položajem.
• Vse entitete, dodane znotraj transakcije, so postavljene na plast, ki je trenutna ob klicu endTransaction. Trenutno plast nastavite pred začetkom transakcije in za različne plasti uporabite ločene transakcije.

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

// za zaokrožitev vogala se na novi črti sklicuj s položajem:
round([50,0], [100,25], 10);

getTransactionDocument in getTransactionDocumentInterface

getTransactionDocument()
getTransactionDocumentInterface()

Vrneta dokument ali vmesnik dokumenta, na katerega se nanaša trenutna transakcija. Zunaj transakcij se vrneta trenutni dokument in vmesnik dokumenta.

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

getOperation

getOperation()

Vrne operacijo (RAddObjectsOperation) trenutne transakcije. Zunaj transakcije se vrne nova operacija, ki jo je treba uporabiti izrecno. To je namenjeno napredni uporabi, na primer za kombiniranje klicev Simple API s celotnim API-jem QCAD.

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

Pogled

autoZoom

autoZoom()

Poveča ali pomanjša trenutni pogled tako, da je vidna celotna risba.

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)

Poveča pogled na podano entiteto, obliko ali pravokotno območje. margin je rob okoli območja v slikovnih pikah (privzeto 10).

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

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

Dokumenti in aplikacija

getMainWindow

getMainWindow()

Vrne okno aplikacije QCAD (RMainWindowQt).

getMainWindow().windowTitle;

getDocumentInterface

getDocumentInterface()

Vrne vmesnik dokumenta (RDocumentInterface) trenutne risbe. Vmesnik dokumenta povezuje dokument z njegovimi pogledi in ponuja funkcije za uvoz in izvoz datotek, uporabo operacij, razveljavitev in uveljavitev.

addLine(0,0, 100,0);
getDocumentInterface().undo();       // znova odstrani črto

getDocument

getDocument()

Vrne trenutni dokument (RDocument). Dokument vsebuje vse entitete, plasti, bloke itd. risbe in ponuja funkcije za poizvedovanje po njih.

addLine(0,0, 100,0);
addCircle(0,0, 10);
getDocument().queryAllEntities().length;     // število entitet v risbi

getGraphicsView

getGraphicsView()

Vrne trenutni ali nazadnje aktivni pogled (RGraphicsView) trenutne risbe.

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

createDocument

createDocument()

Ustvari nov, prazen dokument v pomnilniku, ki ni prikazan v oknu. Takšen dokument, ki ni prikazan na zaslonu, je mogoče napolniti s transakcijo in ga nato prilepiti v risbo (glejte paste).

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

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

createDocumentInterface

createDocumentInterface()

Ustvari nov, prazen dokument v pomnilniku skupaj z vmesnikom dokumenta. Vmesnik dokumenta je mogoče uporabiti za uvoz ali izvoz datotek.

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

disableInput()
enableInput()
isInputEnabled()

disableInput onemogoči okno aplikacije QCAD, da prepreči uporabniški vnos, na primer med dolgimi operacijami ali animacijami. enableInput znova omogoči okno aplikacije, isInputEnabled pa vrne true, če je uporabniški vnos trenutno omogočen. Vedno poskrbite, da na koncu skripta znova omogočite vnos.

update

update()

Obdela čakajoče dogodke, tako da se uporabniški vmesnik med dolgimi operacijami posodablja. Pred klicem update morate uporabniški vnos onemogočiti z disableInput.

sleep

sleep(milliseconds)

Zaustavi skript za podani čas v milisekundah, pri čemer se uporabniški vmesnik še naprej posodablja. Pred klicem sleep morate uporabniški vnos onemogočiti z disableInput.

Naslednji primer uporablja disableInput, sleep in enableInput za prikaz preproste animacije:

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)

Prikaže opozorilno sporočilo. V Script Shell so opozorila prikazana v zgodovini ukazne vrstice. Sicer se opozorila izpišejo v konzolo.

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

Uporabniški vnos

Naslednje funkcije prikažejo preprosto pogovorno okno, v katerem uporabnika vprašajo za vrednost. Če uporabnik pogovorno okno prekliče, se vrne undefined.

getInt

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

Uporabnika vpraša za celo število. value je začetna vrednost (privzeto 0), step korak številskega polja s puščicama (privzeto 1), min in max pa dovoljeni obseg.

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)

Uporabnika vpraša za število. value je začetna vrednost (privzeto 0), decimals število prikazanih decimalnih mest (privzeto 1), min in max pa dovoljeni obseg.

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

getText

getText(title, prompt, text)

Uporabnika vpraša za besedilo. text je začetno besedilo (privzeto prazno).

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

getItem

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

Uporabniku omogoči izbiro elementa s spustnega seznama. items je niz z vsemi elementi, ločenimi z separator (privzeto ","). index je indeks na začetku izbranega elementa (privzeto 0). Vrne izbrani element ali undefined, če je bilo pogovorno okno preklicano.

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

Primer: prirobnica

Ta primer združuje več funkcij Simple API za risanje prirobnice z delilnim krogom, luknjami za vijake na ločeni plasti in zaobljenim pravokotnim izrezom:

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

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

// delilni krog in sredinske črte:
setCurrentLayer("Center Lines");
addCircle(0,0, 75);
addLine(-110,0, 110,0);
addLine(0,-110, 0,110);

// luknje za vijake, dodane v eni transakciji:
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();

// kvadratni izrez z zaobljenimi vogali v središču:
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();

Črte izreza so dodane brez transakcije, tako da jih je mogoče neposredno podati funkciji round. Luknje za vijake so dodane v transakciji, kar je hitrejše in omogoča, da jih razveljavite v enem koraku.