A Simple API

Bevezetés

A QCAD Simple API globális szkriptfüggvények kis gyűjteménye, amely leegyszerűsíti a gyakori feladatokat, például elemek hozzáadását a rajzhoz, elemek lekérdezését és módosítását (mozgatás, vágás, lekerekítés, eltolás stb.). Elsősorban a Szkript parancssorban való használatra, valamint rövid, eljárásorientált, fájlból futtatott szkriptekhez készült, de bármely szkriptből használható.

A Simple API a teljes QCAD API-nak csak egy kis részét fedi le. Mivel maga is ECMAScript (JavaScript) nyelven íródott, jó kiindulópont ahhoz is, hogy megismerje, hogyan működik a mögötte álló QCAD API. A forráskód a QCAD forráskódjának scripts/simple.js és scripts/simple_*.js fájljaiban található.

A Simple API használata

A Szkript parancssorban (Egyéb > Fejlesztés > Szkript parancssor) és az Egyéb > Fejlesztés > Szkript futtatása menüvel indított szkriptekben az összes Simple API függvény közvetlenül elérhető. Írja be például:

addLine(0,0, 100,100);

Saját szkriptfájljaiban, például interaktív szkriptműveletekben vagy parancssori eszközökben, először illessze be a simple.js fájlt:

include("scripts/simple.js");

addLine(0,0, 100,100);

Minden függvény a QCAD alkalmazásablakban éppen megnyitott rajzon dolgozik, kivéve, ha egy tranzakció egy másik dokumentumra irányítja át őket (lásd Tranzakciók).

Az oldalon található összes példa beilleszthető egy üres rajz Szkript parancssorába. Minden példa létrehozza a szükséges elemeket. Az eredmény megtekintéséhez használja a Nézet > Automatikus nagyítás menüt vagy az autoZoom() függvényt.

Konvenciók

Koordináták

A pozíciók háromféleképpen adhatók meg:

• Két különálló számként: addLine(0,0, 100,100)
• Két számból álló tömbként: addLine([0,0], [100,100])
• Vektorobjektumként: addLine(new RVector(0,0), new RVector(100,100))

A szögeket mindig fokban kell megadni, kivéve az ellipszisek kezdő- és végparaméterét, amelyeket radiánban kell megadni.

Hivatkozás elemekre

A meglévő elemmel dolgozó függvények többféle formában fogadják el az elemet:

• Elemazonosító (szám), például 1234.
• Elemobjektum, ahogyan a létrehozó függvények visszaadják, például az addLine(...) visszatérési értéke.
• Egy pozíció a rajzban ([x,y] vagy RVector): a megadott pozícióhoz legközelebbi elem kerül felhasználásra.
• Egy alakzat (például new RLine(0,0, 100,0)): a művelet csak az alakzatra vonatkozik, a rajz nem változik.

var l = addLine(0,0, 100,0);
move(l, [0,10]);              // elemobjektummal
move(l.getId(), [0,10]);      // elemazonosítóval
move([50,20], [0,10]);        // pozícióval: az 50,20-hoz legközelebbi elem

Kattintási pozíciók

Egyes műveletek attól függnek, hogy a megfelelő eszköz interaktív használatakor hol kattintanak az elemre. A vágás az elemnek a kattintási pozíciónál lévő részét tartja meg, a lekerekítés és a letörés az elemeknek a kattintási pozíciókhoz legközelebbi végeit kerekíti le, illetve töri le, az eltolás pedig a kattintási pozíció felőli oldalon hoz létre párhuzamosokat.

A Simple API-ban minden elemhivatkozást követhet egy kattintási pozíció. Ha egy elemre pozícióval hivatkozik, ez a pozíció egyben kattintási pozícióként is szolgál. Ha nincs megadva kattintási pozíció, az elem középpontja kerül felhasználásra:

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

// a vonal levágása a határoló elemig, a vonal 10,0-nál lévő része megmarad:
trim(line, [10,0], limit);

Visszatérési értékek

• A létrehozó függvények a hozzáadott elemet adják vissza. Az elem átadható más függvényeknek, vagy lekérdezhetők az adatai (például getId(), getLength() vagy getStartPoint()).
• A transzformációk (move, rotate, scale, mirror, lengthen, reverse) a módosított elemet adják vissza.
• Az egyéb módosító függvények (trim, round, bevel, offset, breakOut, autoTrim, divide, explode, stretch) a rajzon végrehajtott tranzakciót adják vissza, vagy undefined értéket, ha a művelet sikertelen volt.
• Ha elemek helyett alakzatokat ad át, a transzformációk a megadott alakzatokat módosítják, az összes többi függvény pedig tömbként adja vissza az eredményül kapott alakzatokat.

A sikertelen műveletek nem váltanak ki hibát. Ehelyett a Szkript parancssorban figyelmeztetés jelenik meg, például „Az elem nem vágható le.”.

Elemek létrehozása

addPoint

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

Pont elemet ad hozzá a megadott pozícióban.

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

addLine

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

Vonalat ad hozzá a kezdőponttól a végpontig.

// egy háromszög:
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])

Végtelen egyenest (szerkesztővonalat) ad hozzá, amely az x,y bázisponton halad át dx,dy irányban. Az irányt a bázisponthoz képest relatívan kell megadni.

// vízszintes és 45 fokos szerkesztővonalak a 0,0 ponton át:
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)

Ívet ad hozzá a megadott középponttal, sugárral, kezdőszöggel és végszöggel. A szögek fokban értendők. Az ívek a kezdőszögtől a végszögig az óramutató járásával ellentétes irányban haladnak, kivéve, ha a reversed értéke true (opcionális, alapértelmezett: false).

// negyedív 0 és 90 fok között:
addArc(0,0, 50, 0, 90);

// az óramutató járásával megegyező ív 0-tól 90 fokig (a másik három negyed):
addArc([0,0], 40, 0, 90, true);

addCircle

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

Kört ad hozzá a megadott középponttal és sugárral.

// koncentrikus körök:
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)

Ellipszist vagy ellipszisívet ad hozzá. Az mx,my a főtengely végpontja a középponthoz képest. A ratio a kistengely és a főtengely aránya. A startParam és az endParam az ellipszis kezdetének és végének paramétere radiánban. Teljes ellipszishez használja a 0 és a 2*Math.PI értéket.

// teljes ellipszis 50-es nagy és 25-ös kis sugárral:
addEllipse(0,0, 50,0, 0.5, 0, 2*Math.PI, false);

// egy elforgatott ellipszis felső fele:
addEllipse([0,0], [30,30], 0.3, 0, Math.PI, false);

addPolyline

addPolyline(points, closed, relative)

Vonalláncot ad hozzá a megadott csúcsokon keresztül. A points a csúcsok tömbje, amelyek mindegyike [x, y], [x, y, bulge] vagy [x, y, bulge, relative] formában adható meg. Az x, y helyett RVector is használható.

• bulge (ívhajlat) az ennél a csúcsnál kezdődő szakasz alakját határozza meg: 0 (alapértelmezett) egyenes szakaszt, 1 az óramutató járásával ellentétes félkört, -1 az óramutató járásával megegyező félkört jelent. Más értékek a kettő közötti ívszakaszokat hoznak létre (az ívhajlat az ív középponti szöge negyedének tangense).
• relative: true, ha a csúcs koordinátái az előző csúcshoz képest relatívak.
• closed: true a vonallánc bezárásához (alapértelmezett: false).
• relative: true, ha az összes csúcs koordinátáit az előző csúcshoz képest relatívként kell kezelni (alapértelmezett: false).

// zárt téglalap:
addPolyline([[0,0], [100,0], [100,50], [0,50]], true);

// hosszlyuk alakzat két félkörrel:
addPolyline([[0,60], [80,60,1], [80,80], [0,80,1]], true);

// cikkcakkos vonal relatív koordinátákkal:
addPolyline([[0,100], [10,10], [10,-10], [10,10], [10,-10]], false, true);

addSpline

addSpline(fitPoints, closed)

Spline-t ad hozzá a megadott illesztési pontokon keresztül. A fitPoints [x, y] tömbök vagy RVector objektumok tömbje. Ha a closed értéke true, a spline zárt (periodikus).

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

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

A Szkriptek futtatása fájlból oktatóanyag egy másik példát mutat be, amely egy Lissajous-görbét rajzol spline-ként.

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)

Egysoros szöveget ad hozzá a megadott pozícióban. A pozíció utáni összes argumentum opcionális:

• height: szövegmagasság (alapértelmezett: 1)
• angle: a szöveg szöge fokban (alapértelmezett: 0)
• font: a betűkészlet neve (alapértelmezett: "Standard")
• vAlign: függőleges igazítás: RS.VAlignTop (alapértelmezett), RS.VAlignMiddle, RS.VAlignBase vagy RS.VAlignBottom
• hAlign: vízszintes igazítás: RS.HAlignLeft (alapértelmezett), RS.HAlignCenter vagy RS.HAlignRight
• bold, italic: true félkövér vagy dőlt szöveghez (csak TrueType betűkészleteknél)

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

Három vagy négy csúcsú teljes kitöltésű területet ad hozzá. Vegye figyelembe, hogy a négyoldalú kitöltés csúcsait cikkcakkos sorrendben kell megadni: első csúcs, második csúcs, majd a második csúccsal szemközti csúcs, végül az első csúccsal szemközti csúcs. Háromszög létrehozásához adja meg kétszer a harmadik csúcsot.

// kitöltött négyzet:
addSolid(0,0, 50,0, 0,50, 50,50);

// kitöltött háromszög:
addSolid([60,0], [110,0], [85,50], [85,50]);

Alakzatok, elemek és objektumok hozzáadása

A következő függvények a teljes QCAD API-val létrehozott objektumokat adnak hozzá a rajzhoz. Akkor hasznosak, ha a fenti speciális létrehozó függvények egy adott esetet nem fednek le.

addShape

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

A megadott alakzatot (RLine, RArc, RCircle, REllipse, RPolyline, RSpline, RPoint, …) új elemként adja hozzá az aktuális réteghez. Opcionálisan megadható szín (RColor), vonaltípus (név vagy azonosító) és vonalvastagság (például RLineweight.Weight050). Alapértelmezés szerint az aktuális szín, a ByLayer vonaltípus és a ByLayer vonalvastagság kerül felhasználásra.

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)

A megadott tömb összes alakzatát új elemként adja hozzá.

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)

A megadott elemet (REntity) adja hozzá a rajzhoz. Ha nincs megadva szín, az aktuális szín kerül felhasználásra.

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)

Bármilyen objektumot (elemet, réteget, blokkot, …) hozzáad a rajzhoz, és visszaadja a hozzáadott objektumot.

// „Marker” nevű blokk hozzáadása egy kereszttel:
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);

// a blokk kétszeri beszúrása:
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)

Törli a megadott objektumot a rajzból. Elemek törléséhez általában a deleteEntity függvény kényelmesebb.

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

Rétegek és tulajdonságok

addLayer

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

Új réteget ad hozzá a megadott névvel. Opcionálisan megadható a szín neve (alapértelmezett: "white", amely fehér háttéren feketén jelenik meg), a vonaltípus neve (alapértelmezett: "CONTINUOUS") és a vonalvastagság (alapértelmezett: RLineweight.Weight000). Az új réteget adja vissza, vagy undefined értéket, ha már létezik ilyen nevű réteg.

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

hasLayer

hasLayer(name)

true értéket ad vissza, ha a rajzban létezik a megadott nevű réteg.

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

setCurrentLayer

setCurrentLayer(name)

Beállítja az aktuális réteget. Minden ezután hozzáadott elem erre a rétegre kerül.

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

setCurrentColor

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

Beállítja az ezután hozzáadott elemek színét. A szín megadható RColor objektumként vagy vörös, zöld, kék értékekként (0-255). A szín „Réteg szerint” értékre való visszaállításához használja a new RColor(RColor.ByLayer) kifejezést.

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

Elemek lekérdezése

getEntity

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

A megadott elemhivatkozáshoz tartozó elemet adja vissza, azaz a megadott azonosítójú elemet, a megadott elem aktuális állapotát vagy a megadott pozícióhoz legközelebbi elemet. undefined értéket ad vissza, ha nem található elem.

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

// a circle még a régi középpontot tárolja, a getEntity az aktuális állapotot adja vissza:
getEntity(circle).getCenter();     // visszaadja: 10,0

// a 30,0-hoz legközelebbi elem:
getEntity(30,0).getRadius();       // visszaadja: 20

getShape

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

A megadott elem geometriáját adja vissza alakzatként (vonal esetén RLine, ív esetén RArc, vonallánc esetén RPolyline, …). Az alakzatok geometriai számításokhoz használhatók a rajz megváltoztatása nélkül.

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

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

getClosestEntity

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

A megadott pozícióhoz legközelebbi elemet adja vissza. Ha a range meg van adva, csak a pozíciótól ezen a távolságon belül lévő elemek jönnek számításba. undefined értéket ad vissza, ha nem található elem.

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

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

getEntityShape

getEntityShape(entity, position)

A megadott elemobjektum alakzatát adja vissza. Több alakzatból álló összetett elemek (blokkreferenciák, sraffozások, méretvonalak, szövegek) esetén a megadott pozícióhoz legközelebbi alakzatot adja vissza. A pozíció opcionális.

// egy téglalapot tartalmazó blokk blokkreferenciája:
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)));

// a blokkreferencia 40,10 közelében lévő alakzata (a téglalap):
var s = getEntityShape(getEntity(ref), new RVector(41,10));
s.getLength();                     // visszaadja: 120

getIntersectionPoints

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

A két megadott elem vagy alakzat metszéspontjait tartalmazó tömböt adja vissza. Az elemek megadhatók elemobjektumként, elemazonosítóként vagy alakzatként. Ha a limited értéke false, az elemeket úgy kezeli, mintha végtelenek lennének (a vonalak meghosszabbítva, az ívek teljes körként). Az alapértelmezett érték true.

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

// a metszéspontok megjelölése kis körökkel:
for (var i=0; i<ips.length; i++) {
    addCircle(ips[i], 2);
}

isPosition és toVector

isPosition(value)
toVector(value)

Az isPosition true értéket ad vissza, ha a megadott érték pozíció (RVector vagy két-három számból álló tömb). A toVector a tömbként megadott pozíciót RVector objektummá alakítja. Ezek a függvények akkor hasznosak, ha olyan saját függvényeket ír, amelyek a Simple API-hoz hasonló módon fogadnak el pozíciókat.

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]);                 // visszaadja: true
isPosition("abc");                 // visszaadja: false

Elemek módosítása

Transzformációk

move

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

A megadott elemet a megadott eltolással mozgatja.

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

rotate

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

A megadott elemet a megadott, fokban kifejezett szöggel elforgatja a megadott középpont körül. Ha nincs megadva középpont, az elem a 0,0 origó körül forog.

// vonalak legyezője, a 0,0 körül elforgatva:
for (var a=0; a<360; a+=30) {
    var l = addLine(10,0, 50,0);
    rotate(l, a);
}

// négyzet elforgatása a középpontja körül:
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])

A megadott elemet a megadott tényezővel átméretezi. A fókuszpont (a helyben maradó pont) alapértelmezés szerint a 0,0 origó. Az X és Y irányú eltérő tényezők [sx, sy] tömbként adhatók meg. Vegye figyelembe, hogy egyes elemek, például a körök és az ívek, nem méretezhetők át eltérő X és Y tényezővel.

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

A megadott elemet a két ponttal meghatározott tengelyre tükrözi.

var pl = addPolyline([[10,0], [40,0], [40,30]], false);
// tükrözés az Y tengelyre:
mirror(pl, 0,0, 0,100);

Ha meg szeretné tartani az eredetit, és tükrözött másolatot szeretne létrehozni, először adja hozzá az elem egy másolatát:

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

Vágás és hosszabbítás

trim

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

A trimEntity elemet a limitingEntity határoló elemig vágja le. A levágott elemnek a trimPos kattintási pozíciónál lévő része megmarad. Ha a két elem nem metszi egymást, az elem a határoló elemig meghosszabbodik. Ha több metszéspont van, a limitingPos kattintási pozícióhoz legközelebbi kerül felhasználásra. Ha a trimBoth értéke true, mindkét elem a másikig vágódik le.

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

// a bal oldali rész megmarad, a vonal most 70,0-nál végződik:
trim(line, [10,0], limit);

// vonal meghosszabbítása egy körig:
var line = addLine(0,0, 50,0);
var circle = addCircle(100,0, 20);

// meghosszabbítás a körrel alkotott, 80,0-hoz legközelebbi metszéspontig:
trim(line, [25,0], circle, [80,0]);      // a vonal most 80,0-nál végződik

trimBoth

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

Mindkét elemet levágja vagy meghosszabbítja a metszéspontjukig. Ez a trim rövidítése, ahol a trimBoth értéke true.

// két nem érintkező vonal meghosszabbodik, és sarkot alkot 100,0-nál:
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)

A megadott elemet a megadott mértékkel meghosszabbítja. Negatív érték esetén az elem rövidül. Alapértelmezés szerint az elem a végpontjánál hosszabbodik meg. Adjon meg true értéket a start paraméternek, ha inkább a kezdőpontjánál szeretné meghosszabbítani, vagy adjon meg egy pozíciót a meghosszabbítandó vég közelében.

var line = addLine(0,0, 100,0);
lengthen(line, 20);              // a vonal most 120,0-nál végződik
lengthen(line, true, -10);       // a vonal most 10,0-nál kezdődik

var arc = addArc(0,50, 30, 0, 90);
lengthen(arc, [30,50], 10);      // az ív meghosszabbítása a kezdőpontjánál

breakOut

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

Kitöri a megadott elem szakaszát a megadott pozícióban. A szakasz a pozíció két oldalán a más elemekkel alkotott legközelebbi metszéspontokig tart. Ha az egyik oldalon nincs metszéspont, a szakasz az elem végéig tart. Ha a removeSegment értéke true (alapértelmezett), a szakasz törlődik. Ellenkező esetben különálló elemként megmarad.

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

// a vonal 30,0 és 70,0 közötti részének eltávolítása:
breakOut(line, [50,0]);

autoTrim

autoTrim(entity, pos)
autoTrim(pos)

A breakOut ellentéte: csak a megadott elem megadott pozíciónál lévő szakaszát tartja meg, a többit eltávolítja. A szakasz a pozíció két oldalán a más elemekkel alkotott legközelebbi metszéspontokig tart.

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

// csak a 30,0 és 70,0 közötti rész marad meg:
autoTrim(line, [50,0]);

divide

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

Felosztja a megadott elemet a megadott pozícióban. Egy nyitott elem (vonal, ív, nyitott vonallánc, …) egy pozícióban két részre, két pozícióban három részre oszlik. A zárt elemekhez (körök, teljes ellipszisek, zárt vonalláncok) két pozíció szükséges, és két részre oszlanak.

var line = addLine(0,0, 100,0);
divide(line, [40,0]);            // két vonal: 0..40 és 40..100

var circle = addCircle(0,50, 20);
divide(circle, [20,50], [-20,50]);   // két félkör

Sarkok

round

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

Két elem közötti sarkot lekerekíti a megadott sugarú ívvel. A kattintási pozíciók jelzik, hogy az elemek melyik vége kerül lekerekítésre. Ha a trim értéke true (alapértelmezett), mindkét elem a lekerekítő ívig vágódik le.

// téglalap lekerekített sarkokkal:
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);

Egy vonallánc csúcsai is lekerekíthetők, ha ugyanazt a vonalláncot kétszer adja át, mindkét szakaszon egy-egy kattintási pozícióval:

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

bevel és 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)

Két elem közötti sarkot egyenes vonallal letöri. A distance1 a letörési vonal távolsága a saroktól az első elem mentén, a distance2 a második elem mentén (alapértelmezés szerint megegyezik a distance1 értékével). Ha a trim értéke true (alapértelmezett), mindkét elem a letörési vonalig vágódik le. A chamfer a bevel másik neve.

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)

Párhuzamosokat hoz létre vonalakhoz, koncentrikus íveket és köröket, illetve ellipszisek és más elemek párhuzamos görbéit. A number a létrehozandó párhuzamosok száma (alapértelmezett: 1). A párhuzamosok az elem mindkét oldalán jönnek létre, kivéve, ha meg van adva egy oldal, akár az elem melletti sidePos pozícióként, akár side értékként (RS.LeftHand, RS.RightHand vagy RS.BothSides). Vonalláncok és spline-ok eltolása csak a QCAD Professional változatban érhető el.

var line = addLine(0,0, 100,0);
offset(line, 5);                 // egy-egy párhuzamos mindkét oldalon

var line2 = addLine(0,30, 100,30);
offset(line2, 5, 2, RS.LeftHand);    // két párhuzamos a bal oldalon (felül)

var circle = addCircle(50,80, 10);
offset(circle, [50,95], 3, 4);   // négy koncentrikus kör kívül

reverse

reverse(entity)
reverse(x, y)

Megfordítja a megadott elem irányát, azaz felcseréli a kezdő- és végpontját.

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

explode

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

A megadott elemet egyszerűbb elemekre veti szét: a vonalláncokat vonalakra és ívekre, a blokkreferenciákat a tartalmukra, a szövegeket vonalakra és spline-okra, a méretvonalakat és sraffozásokat vonalakra, ívekre stb. Az eredeti elem törlődik.

Az options egy opcionális objektum olyan beállításokkal, amelyek egyébként az alkalmazás beállításaiból származnak, például { splineSegments: 64, textToPolylines: true }. A támogatott beállítások: splineTolerance, splineSegments, ellipseSegments, splinesToLineSegments, textToPolylines, textSplineToLineOrArc, multilineTextToSimpleText és circlesToPolylines.

var pl = addPolyline([[0,0], [100,0,1], [100,50], [0,50]], true);
explode(pl);                     // három vonal és egy ív

stretch

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

A két sarokponttal meghatározott téglalap alakú területen lévő összes elemet a megadott eltolással nyújtja. A teljesen a területen belül lévő elemek elmozdulnak, a terület határát keresztező elemek nyúlnak (csak a területen belüli végpontok mozdulnak el). A terület RBox vagy zárt RPolyline alakzatként is megadható. Ha a rajzban elemek vannak kijelölve, csak a kijelölt elemek nyúlnak.

// vonalakból álló téglalap:
addLine(0,0, 100,0);
addLine(100,0, 100,50);
addLine(100,50, 0,50);
addLine(0,50, 0,0);

// a téglalap 50 egységgel szélesebbé tétele a jobb oldalának nyújtásával:
stretch([80,-10], [120,60], [50,0]);

deleteEntity

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

Törli a megadott elemet a rajzból.

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

deleteEntity(l1);                // elemmel
deleteEntity(l2.getId());        // elemazonosítóval
deleteEntity(50,20);             // pozícióval

paste

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

A sourceDocument dokumentum tartalmát beilleszti a destination dokumentum-interfészbe, vagy az aktuális rajzba, ha a destination értéke undefined. A beillesztett tartalom offset értékkel eltolódik, scale tényezővel átméreteződik és rotation fokkal elfordul. Minden argumentum kötelező:

• flipHorizontal, flipVertical: true a tartalom tükrözéséhez
• toCurrentLayer: true az összes elem aktuális rétegre történő beillesztéséhez
• overwriteLayers, overwriteBlocks: true az azonos nevű meglévő rétegek vagy blokkok felülírásához

// szimbólum létrehozása egy képernyőn kívüli dokumentumban:
var symbol = createDocument();
startTransaction(symbol);
addCircle(0,0, 10);
addLine(-10,0, 10,0);
addLine(0,-10, 0,10);
endTransaction();

// háromszori beillesztés az aktuális rajzba:
for (var i=0; i<3; i++) {
    paste(symbol, undefined, [i*50, 0], 1+i*0.5, i*15, false, false, false, false, false);
}

Tranzakciók

startTransaction és endTransaction

startTransaction()
startTransaction(document)
endTransaction()

Alapértelmezés szerint minden Simple API hívás azonnal végrehajtódik a rajzon, és egyenként visszavonható. A startTransaction() és az endTransaction() között az összes módosítás összegyűlik, és az endTransaction meghívásakor együtt hajtódik végre. Ennek két előnye van:

• Sok elem hozzáadásakor sokkal gyorsabb.
• Az összes módosítás egyetlen lépésben visszavonható.

Ha a startTransaction függvénynek egy dokumentumot (RDocument) vagy dokumentum-interfészt (RDocumentInterface) ad át, az összes módosítás az aktuális rajz helyett abban a dokumentumban hajtódik végre. Ez hasznos rajzok háttérben történő létrehozásához, például fájlba exportáláshoz (lásd createDocumentInterface).

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

Tranzakciók használatakor vegye figyelembe a következőket:

• Egy tranzakción belül a módosítások még nem részei a rajznak. Az olyan módosító függvények, mint a trim vagy a round, nem hivatkozhatnak ugyanabban a tranzakcióban hozzáadott elemekre.
• A létrehozó függvények által egy tranzakción belül visszaadott elemeknek nincs érvényes azonosítójuk, még az endTransaction után sem. Ha később módosítani szeretné ezeket az elemeket, pozícióval hivatkozzon rájuk.
• A tranzakción belül hozzáadott összes elem arra a rétegre kerül, amely az endTransaction meghívásakor aktuális. Állítsa be az aktuális réteget a tranzakció indítása előtt, és különböző rétegekhez használjon külön tranzakciókat.

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

// hivatkozás az új vonalakra pozícióval a sarok lekerekítéséhez:
round([50,0], [100,25], 10);

getTransactionDocument és getTransactionDocumentInterface

getTransactionDocument()
getTransactionDocumentInterface()

Azt a dokumentumot vagy dokumentum-interfészt adják vissza, amelyre az aktuális tranzakció vonatkozik. Tranzakciókon kívül az aktuális dokumentumot és dokumentum-interfészt adják vissza.

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

getOperation

getOperation()

Az aktuális tranzakció műveletét (RAddObjectsOperation) adja vissza. Tranzakción kívül egy új műveletet ad vissza, amelyet kifejezetten végre kell hajtani. Haladó felhasználásra szolgál, például a Simple API hívások és a teljes QCAD API kombinálására.

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

Nézet

autoZoom

autoZoom()

Úgy nagyítja az aktuális nézetet, hogy a teljes rajz látható legyen.

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)

A megadott elemre, alakzatra vagy téglalap alakú területre nagyít. A margin a terület körüli margó képpontban (alapértelmezett: 10).

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

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

Dokumentumok és alkalmazás

getMainWindow

getMainWindow()

A QCAD alkalmazásablakot (RMainWindowQt) adja vissza.

getMainWindow().windowTitle;

getDocumentInterface

getDocumentInterface()

Az aktuális rajz dokumentum-interfészét (RDocumentInterface) adja vissza. A dokumentum-interfész összeköti a dokumentumot a nézeteivel, és függvényeket biztosít fájlok importálásához és exportálásához, műveletek végrehajtásához, visszavonáshoz és ismétléshez.

addLine(0,0, 100,0);
getDocumentInterface().undo();       // ismét eltávolítja a vonalat

getDocument

getDocument()

Az aktuális dokumentumot (RDocument) adja vissza. A dokumentum tartalmazza egy rajz összes elemét, rétegét, blokkját stb., és függvényeket biztosít ezek lekérdezéséhez.

addLine(0,0, 100,0);
addCircle(0,0, 10);
getDocument().queryAllEntities().length;     // a rajzban lévő elemek száma

getGraphicsView

getGraphicsView()

Az aktuális rajz aktuális vagy utoljára aktív nézetét (RGraphicsView) adja vissza.

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

createDocument

createDocument()

Új, üres dokumentumot hoz létre a memóriában, amely nem jelenik meg ablakban. Egy ilyen képernyőn kívüli dokumentum tranzakcióval feltölthető, majd beilleszthető egy rajzba (lásd paste).

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

doc.queryAllEntities().length;       // visszaadja: 2

createDocumentInterface

createDocumentInterface()

Új, üres dokumentumot hoz létre a memóriában egy dokumentum-interfésszel együtt. A dokumentum-interfész fájlok importálására vagy exportálására használható.

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 és isInputEnabled

disableInput()
enableInput()
isInputEnabled()

A disableInput letiltja a QCAD alkalmazásablakot a felhasználói bevitel megakadályozása érdekében, például hosszú műveletek vagy animációk közben. Az enableInput újra engedélyezi az alkalmazásablakot, az isInputEnabled pedig true értéket ad vissza, ha a felhasználói bevitel éppen engedélyezve van. Mindig gondoskodjon arról, hogy a szkript végén újra engedélyezze a bevitelt.

update

update()

Feldolgozza a függőben lévő eseményeket, hogy a felhasználói felület hosszú műveletek közben is frissüljön. Az update meghívása előtt a felhasználói bevitelt le kell tiltani a disableInput függvénnyel.

sleep

sleep(milliseconds)

A megadott, ezredmásodpercben kifejezett időre szünetelteti a szkriptet, miközben a felhasználói felületet naprakészen tartja. A sleep meghívása előtt a felhasználói bevitelt le kell tiltani a disableInput függvénnyel.

A következő példa a disableInput, a sleep és az enableInput segítségével egy egyszerű animációt mutat be:

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)

Figyelmeztető üzenetet jelenít meg. A Szkript parancssorban a figyelmeztetések a parancssori előzményben jelennek meg. Egyébként a figyelmeztetések a konzolra íródnak ki.

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

Felhasználói bevitel

A következő függvények egyszerű párbeszédablakot jelenítenek meg, amelyben a felhasználótól egy értéket kérnek be. Ha a felhasználó megszakítja a párbeszédablakot, undefined értéket adnak vissza.

getInt

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

Egész számot kér be a felhasználótól. A value a kezdeti érték (alapértelmezett: 0), a step a léptetőmező lépésköze (alapértelmezett: 1), a min és a max a megengedett tartomány.

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)

Számot kér be a felhasználótól. A value a kezdeti érték (alapértelmezett: 0), a decimals a megjelenített tizedesjegyek száma (alapértelmezett: 1), a min és a max a megengedett tartomány.

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

getText

getText(title, prompt, text)

Szöveget kér be a felhasználótól. A text a kezdeti szöveg (alapértelmezés szerint üres).

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

getItem

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

Lehetővé teszi, hogy a felhasználó kiválasszon egy listaelemet egy legördülő listából. Az items egy karakterlánc, amely az összes listaelemet tartalmazza separator karakterrel elválasztva (alapértelmezett: ","). Az index a kezdetben kiválasztott listaelem indexe (alapértelmezett: 0). A kiválasztott listaelemet adja vissza, vagy undefined értéket, ha a párbeszédablakot megszakították.

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

Példa: Egy karima

Ez a példa a Simple API több függvényét kombinálja egy karima megrajzolásához, amely osztókörrel, külön rétegen lévő csavarfuratokkal és lekerekített téglalap alakú kivágással rendelkezik:

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

// körvonal:
setCurrentLayer("0");
addCircle(0,0, 100);

// osztókör és középvonalak:
setCurrentLayer("Center Lines");
addCircle(0,0, 75);
addLine(-110,0, 110,0);
addLine(0,-110, 0,110);

// csavarfuratok, egyetlen tranzakcióban hozzáadva:
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();

// lekerekített négyzet alakú kivágás a közepén:
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();

A kivágás vonalai tranzakció nélkül kerülnek hozzáadásra, így közvetlenül átadhatók a round függvénynek. A csavarfuratok egy tranzakcióban kerülnek hozzáadásra, ami gyorsabb, és lehetővé teszi, hogy egyetlen lépésben visszavonhatók legyenek.