Jednostavni API

Uvod

QCAD Simple API (jednostavni API) mali je skup globalnih funkcija za skripte koje pojednostavljuju uobičajene zadatke poput dodavanja entiteta u crtež, ispitivanja entiteta i njihova mijenjanja (premještanje, obrezivanje, zaobljavanje, stvaranje paralela, …). Prvenstveno je namijenjen za upotrebu u ljusci za skripte i za kratke proceduralne skripte koje se pokreću iz datoteke, ali se može koristiti iz bilo koje skripte.

Simple API pokriva samo mali dio cjelokupnog QCAD API-ja. Budući da je i sam napisan u ECMAScriptu (JavaScript), dobro je polazište i za učenje načina na koji radi temeljni QCAD API. Izvorni kôd nalazi se u datotekama scripts/simple.js i scripts/simple_*.js izvornog kôda QCAD-a.

Korištenje Simple API-ja

U ljusci za skripte (Razno > Razvoj > Ljuska za skripte) i u skriptama pokrenutima pomoću Razno > Razvoj > Pokreni skriptu sve su funkcije Simple API-ja izravno dostupne. Upišite na primjer:

addLine(0,0, 100,100);

U vlastitim datotekama skripti, na primjer u interaktivnim akcijama skripti ili alatima naredbenog retka, najprije uključite datoteku simple.js:

include("scripts/simple.js");

addLine(0,0, 100,100);

Sve funkcije rade na crtežu koji je trenutno otvoren u prozoru aplikacije QCAD, osim ako se transakcijom ne preusmjere na drugi dokument (vidi Transakcije).

Svi primjeri na ovoj stranici mogu se zalijepiti u ljusku za skripte praznog crteža. Svaki primjer stvara entitete koji su mu potrebni. Koristite Prikaz > Automatski zum ili funkciju autoZoom() kako biste vidjeli rezultat.

Konvencije

Koordinate

Položaji se mogu predati na tri različita načina:

• Kao dva zasebna broja: addLine(0,0, 100,100)
• Kao polje od dva broja: addLine([0,0], [100,100])
• Kao vektorski objekt: addLine(new RVector(0,0), new RVector(100,100))

Kutovi se uvijek zadaju u stupnjevima, osim početnog i završnog parametra elipsa koji se zadaju u radijanima.

Reference na entitete

Funkcije koje rade s postojećim entitetom prihvaćaju entitet u različitim oblicima:

• ID entiteta (broj), na primjer 1234.
• Objekt entiteta kakav vraćaju funkcije za stvaranje, na primjer povratna vrijednost funkcije addLine(...).
• Položaj u crtežu ([x,y] ili RVector): koristi se entitet najbliži zadanom položaju.
• Oblik (na primjer new RLine(0,0, 100,0)): operacija se primjenjuje samo na oblik, crtež se ne mijenja.

var l = addLine(0,0, 100,0);
move(l, [0,10]);              // putem objekta entiteta
move(l.getId(), [0,10]);      // putem ID-a entiteta
move([50,20], [0,10]);        // putem položaja: entitet najbliži točki 50,20

Položaji klika

Neke operacije ovise o tome gdje se klikne na entitet pri interaktivnom korištenju odgovarajućeg alata. Obrezivanje zadržava dio entiteta na položaju klika, zaobljavanje i zakošenje obrađuju krajeve entiteta najbliže položajima klika, a odmak stvara paralele na strani položaja klika.

U Simple API-ju iza svake reference na entitet može slijediti položaj klika. Ako se na entitet referencira položajem, taj položaj služi i kao položaj klika. Ako položaj klika nije zadan, koristi se središnja točka entiteta:

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

// obreži liniju do granice, zadrži dio linije kod 10,0:
trim(line, [10,0], limit);

Povratne vrijednosti

• Funkcije za stvaranje vraćaju dodani entitet. Entitet se može predati drugim funkcijama ili se od njega mogu zatražiti informacije (na primjer getId(), getLength() ili getStartPoint()).
• Transformacije (move, rotate, scale, mirror, lengthen, reverse) vraćaju izmijenjeni entitet.
• Ostale funkcije izmjene (trim, round, bevel, offset, breakOut, autoTrim, divide, explode, stretch) vraćaju transakciju koja je primijenjena na crtež ili undefined ako operacija nije uspjela.
• Ako se umjesto entiteta predaju oblici, transformacije mijenjaju zadane oblike, a sve ostale funkcije vraćaju rezultirajuće oblike kao polje.

Neuspjele operacije ne izazivaju pogrešku. Umjesto toga u ljusci za skripte prikazuje se upozorenje, na primjer „Entitet ne može biti obrezan.”.

Stvaranje entiteta

addPoint

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

Dodaje entitet točke na zadani položaj.

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

addLine

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

Dodaje liniju od početne do krajnje točke.

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

Dodaje beskonačnu liniju (konstrukcijsku liniju) kroz osnovnu točku x,y sa smjerom dx,dy. Smjer se zadaje relativno u odnosu na osnovnu točku.

// vodoravna konstrukcijska linija i konstrukcijska linija pod 45 stupnjeva kroz 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)

Dodaje luk sa zadanim središtem, polumjerom, početnim i završnim kutom. Kutovi su u stupnjevima. Lukovi idu suprotno od smjera kazaljke na satu od početnog do završnog kuta, osim ako je reversed true (neobavezno, zadano je false).

// četvrtina luka od 0 do 90 stupnjeva:
addArc(0,0, 50, 0, 90);

// luk u smjeru kazaljke na satu od 0 do 90 stupnjeva (preostale tri četvrtine):
addArc([0,0], 40, 0, 90, true);

addCircle

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

Dodaje kružnicu sa zadanim središtem i polumjerom.

// koncentrične kružnice:
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)

Dodaje elipsu ili eliptični luk. mx,my je krajnja točka glavne osi, relativno u odnosu na središte. ratio je omjer između sporedne i glavne osi. startParam i endParam su parametri elipse u radijanima na kojima elipsa počinje i završava. Za punu elipsu koristite 0 i 2*Math.PI.

// puna elipsa s glavnim polumjerom 50 i sporednim polumjerom 25:
addEllipse(0,0, 50,0, 0.5, 0, 2*Math.PI, false);

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

addPolyline

addPolyline(points, closed, relative)

Dodaje poliliniju kroz zadane vrhove. points je polje vrhova, od kojih je svaki zadan kao [x, y], [x, y, bulge] ili [x, y, bulge, relative]. Umjesto x, y može se koristiti RVector.

• bulge (izbočina) određuje oblik segmenta koji počinje u ovom vrhu: 0 (zadano) za ravni segment, 1 za polukružnicu suprotno od smjera kazaljke na satu, -1 za polukružnicu u smjeru kazaljke na satu. Ostale vrijednosti stvaraju lučne segmente između toga (izbočina je tangens četvrtine kuta luka).
• relative: true ako su koordinate ovog vrha relativne u odnosu na prethodni vrh.
• closed: true za zatvaranje polilinije (zadano je false).
• relative: true ako se koordinate svih vrhova tretiraju kao relativne u odnosu na prethodni vrh (zadano je false).

// zatvoreni pravokutnik:
addPolyline([[0,0], [100,0], [100,50], [0,50]], true);

// oblik utora s dvije polukružnice:
addPolyline([[0,60], [80,60,1], [80,80], [0,80,1]], true);

// cik-cak linija s relativnim koordinatama:
addPolyline([[0,100], [10,10], [10,-10], [10,10], [10,-10]], false, true);

addSpline

addSpline(fitPoints, closed)

Dodaje splajn kroz zadane točke prilagodbe. fitPoints je polje polja [x, y] ili objekata RVector. Ako je closed true, splajn je zatvoren (periodičan).

// otvoreni splajn:
addSpline([[0,0], [30,40], [60,0], [90,40]], false);

// zatvoreni splajn:
addSpline([[0,60], [40,80], [80,60], [40,100]], true);

Vodič Pokretanje skripti iz datoteke prikazuje još jedan primjer koji iscrtava Lissajousovu krivulju kao splajn.

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)

Dodaje jednoredni tekst na zadani položaj. Svi argumenti nakon položaja su neobavezni:

• height: visina teksta (zadano 1)
• angle: kut teksta u stupnjevima (zadano 0)
• font: naziv fonta (zadano "Standard")
• vAlign: okomito poravnanje: RS.VAlignTop (zadano), RS.VAlignMiddle, RS.VAlignBase ili RS.VAlignBottom
• hAlign: vodoravno poravnanje: RS.HAlignLeft (zadano), RS.HAlignCenter ili RS.HAlignRight
• bold, italic: true za podebljani ili kurzivni tekst (samo TrueType fontovi)

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

Dodaje područje čvrste ispune s tri ili četiri kuta. Imajte na umu da se kutovi četverostrane čvrste ispune zadaju cik-cak redoslijedom: prvi kut, drugi kut, zatim kut nasuprot drugom kutu i kut nasuprot prvom kutu. Za stvaranje trokuta treći kut predajte dvaput.

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

// ispunjeni trokut:
addSolid([60,0], [110,0], [85,50], [85,50]);

Dodavanje oblika, entiteta i objekata

Sljedeće funkcije dodaju u crtež objekte stvorene pomoću cjelokupnog QCAD API-ja. Korisne su kada gore navedene specijalizirane funkcije za stvaranje ne pokrivaju određeni slučaj.

addShape

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

Dodaje zadani oblik (RLine, RArc, RCircle, REllipse, RPolyline, RSpline, RPoint, …) kao novi entitet na trenutni sloj. Neobavezno se mogu zadati boja (RColor), vrsta crte (naziv ili ID) i debljina crte (na primjer RLineweight.Weight050). Prema zadanim postavkama koriste se trenutna boja, vrsta crte ByLayer i debljina crte 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)

Dodaje sve oblike iz zadanog polja kao 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)

Dodaje zadani entitet (REntity) u crtež. Ako boja nije zadana, koristi se trenutna boja.

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)

Dodaje bilo koji objekt (entitet, sloj, blok, …) u crtež i vraća dodani objekt.

// dodaj blok naziva "Marker" s križićem u njemu:
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);

// umetni blok dvaput:
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)

Briše zadani objekt iz crteža. Za brisanje entiteta obično je praktičnija funkcija deleteEntity.

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

Slojevi i atributi

addLayer

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

Dodaje novi sloj sa zadanim nazivom. Neobavezno se mogu zadati naziv boje (zadano "white", koja se na bijeloj pozadini prikazuje crno), naziv vrste crte (zadano "CONTINUOUS") i debljina crte (zadano RLineweight.Weight000). Vraća novi sloj ili undefined ako sloj sa zadanim nazivom već postoji.

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

hasLayer

hasLayer(name)

Vraća true ako u crtežu postoji sloj sa zadanim nazivom.

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

setCurrentLayer

setCurrentLayer(name)

Postavlja trenutni sloj. Svi entiteti dodani nakon toga smještaju se na taj sloj.

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

setCurrentColor

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

Postavlja boju za entitete koji se dodaju nakon toga. Boja se može zadati kao objekt RColor ili kao vrijednosti crvene, zelene i plave (0-255). Koristite new RColor(RColor.ByLayer) za vraćanje boje na „Po sloju”.

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

Ispitivanje entiteta

getEntity

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

Vraća entitet za zadanu referencu na entitet, tj. entitet sa zadanim ID-om, trenutno stanje zadanog entiteta ili entitet najbliži zadanom položaju. Vraća undefined ako entitet nije pronađen.

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

// circle još sadrži staro središte, getEntity vraća trenutno stanje:
getEntity(circle).getCenter();     // vraća 10,0

// entitet najbliži točki 30,0:
getEntity(30,0).getRadius();       // vraća 20

getShape

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

Vraća geometriju zadanog entiteta kao oblik (RLine za liniju, RArc za luk, RPolyline za poliliniju, …). Oblici se mogu koristiti za geometrijske izračune bez mijenjanja crteža.

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

var pl = getShape(50,0);
pl.getLength();                    // vraća 150

getClosestEntity

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

Vraća entitet najbliži zadanom položaju. Ako je zadan range, uzimaju se u obzir samo entiteti unutar te udaljenosti od položaja. Vraća undefined ako entitet nije pronađen.

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

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

getEntityShape

getEntityShape(entity, position)

Vraća oblik zadanog objekta entiteta. Za složene entitete koji se sastoje od više oblika (reference bloka, šrafure, kote, tekstovi) vraća se oblik najbliži zadanom položaju. Položaj je neobavezan.

// referenca bloka koji sadrži pravokutnik:
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)));

// oblik reference bloka blizu točke 40,10 (pravokutnik):
var s = getEntityShape(getEntity(ref), new RVector(41,10));
s.getLength();                     // vraća 120

getIntersectionPoints

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

Vraća polje s točkama presjeka dvaju zadanih entiteta ili oblika. Entiteti se mogu zadati kao objekti entiteta, ID-ovi entiteta ili oblici. Ako je limited false, entiteti se tretiraju kao da su beskonačni (linije produžene, lukovi kao pune kružnice). Zadano je true.

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

// označi presjeke malim kružnicama:
for (var i=0; i<ips.length; i++) {
    addCircle(ips[i], 2);
}

isPosition i toVector

isPosition(value)
toVector(value)

isPosition vraća true ako je zadana vrijednost položaj (RVector ili polje od dva ili tri broja). toVector pretvara položaj zadan kao polje u RVector. Ove su funkcije korisne pri pisanju vlastitih funkcija koje prihvaćaju položaje na isti način kao 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]);                 // vraća true
isPosition("abc");                 // vraća false

Mijenjanje entiteta

Transformacije

move

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

Premješta zadani entitet za zadani pomak.

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

rotate

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

Rotira zadani entitet za zadani kut u stupnjevima oko zadanog središta. Ako središte nije zadano, entitet se rotira oko ishodišta 0,0.

// lepeza linija, rotiranih oko 0,0:
for (var a=0; a<360; a+=30) {
    var l = addLine(10,0, 50,0);
    rotate(l, a);
}

// rotiraj kvadrat oko njegova središta:
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])

Skalira zadani entitet zadanim faktorom. Točka fokusa (točka koja ostaje na mjestu) prema zadanim postavkama je ishodište 0,0. Različiti faktori za X i Y mogu se zadati kao polje [sx, sy]. Imajte na umu da se neki entiteti poput kružnica i lukova ne mogu skalirati različitim faktorima u X i 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 zadani entitet oko osi definirane dvjema točkama.

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

Da biste zadržali izvornik i stvorili zrcalnu kopiju, najprije dodajte kopiju entiteta:

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

Obrezivanje i produljivanje

trim

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

Obrezuje entitet trimEntity do graničnog entiteta limitingEntity. Dio obrezanog entiteta na položaju klika trimPos se zadržava. Ako se dva entiteta ne sijeku, entitet se produljuje do graničnog entiteta. Ako postoji više presjeka, koristi se onaj najbliži položaju klika limitingPos. Ako je trimBoth true, oba se entiteta obrezuju jedan do drugoga.

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

// zadrži lijevi dio, linija sada završava kod 70,0:
trim(line, [10,0], limit);

// produlji liniju do kružnice:
var line = addLine(0,0, 50,0);
var circle = addCircle(100,0, 20);

// produlji do presjeka s kružnicom najbližeg točki 80,0:
trim(line, [25,0], circle, [80,0]);      // linija sada završava kod 80,0

trimBoth

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

Obrezuje ili produljuje oba entiteta do njihove točke presjeka. Ovo je prečac za trim s trimBoth postavljenim na true.

// dvije linije koje se ne dodiruju produljuju se tako da tvore kut kod 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)

Produljuje zadani entitet za zadani iznos. Negativni iznosi skraćuju entitet. Prema zadanim postavkama entitet se produljuje na svojoj krajnjoj točki. Predajte true za start kako biste ga umjesto toga produljili na početnoj točki ili predajte položaj blizu kraja koji treba produljiti.

var line = addLine(0,0, 100,0);
lengthen(line, 20);              // linija sada završava kod 120,0
lengthen(line, true, -10);       // linija sada počinje kod 10,0

var arc = addArc(0,50, 30, 0, 90);
lengthen(arc, [30,50], 10);      // produlji luk na njegovoj početnoj točki

breakOut

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

Izdvaja segment zadanog entiteta na zadanom položaju. Segment završava na najbližim presjecima s drugim entitetima s obje strane položaja. Ako s jedne strane nema presjeka, segment se proteže do kraja entiteta. Ako je removeSegment true (zadano), segment se briše. U suprotnom se zadržava kao zaseban entitet.

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

// ukloni dio linije između 30,0 i 70,0:
breakOut(line, [50,0]);

autoTrim

autoTrim(entity, pos)
autoTrim(pos)

Suprotno od breakOut: zadržava samo segment zadanog entiteta na zadanom položaju i uklanja ostatak. Segment završava na najbližim presjecima s drugim entitetima s obje strane položaja.

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

// zadrži samo dio između 30,0 i 70,0:
autoTrim(line, [50,0]);

divide

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

Dijeli zadani entitet na zadanom položaju. Otvoreni entitet (linija, luk, otvorena polilinija, …) dijeli se na dva dijela na jednom položaju ili na tri dijela na dva položaja. Zatvoreni entiteti (kružnice, pune elipse, zatvorene polilinije) zahtijevaju dva položaja i dijele se na dva dijela.

var line = addLine(0,0, 100,0);
divide(line, [40,0]);            // dvije linije: 0..40 i 40..100

var circle = addCircle(0,50, 20);
divide(circle, [20,50], [-20,50]);   // dvije polukružnice

Kutovi

round

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

Zaobljuje kut između dvaju entiteta lukom zadanog polumjera (zaobljenje). Položaji klika označavaju koji se krajevi entiteta zaobljuju. Ako je trim true (zadano), oba se entiteta obrezuju do luka zaobljenja.

// pravokutnik sa zaobljenim kutovima:
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);

I kutovi polilinije mogu se zaobliti, tako da se ista polilinija preda dvaput s po jednim položajem klika na svakom od dvaju segmenata:

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

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

Zakošuje kut između dvaju entiteta ravnom linijom (faseta). distance1 je udaljenost linije zakošenja od kuta duž prvog entiteta, distance2 duž drugog entiteta (zadano je distance1). Ako je trim true (zadano), oba se entiteta obrezuju do linije zakošenja. chamfer je zamjensko 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)

Stvara paralele linijama, koncentrične lukove i kružnice ili paralelne krivulje elipsa i drugih entiteta. number je broj paralela koje treba stvoriti (zadano 1). Paralele se stvaraju s obje strane entiteta, osim ako je strana zadana, bilo kao položaj sidePos pokraj entiteta ili kao side (RS.LeftHand, RS.RightHand ili RS.BothSides). Odmak polilinija i splajnova dostupan je samo u QCAD Professional.

var line = addLine(0,0, 100,0);
offset(line, 5);                 // jedna paralela sa svake strane

var line2 = addLine(0,30, 100,30);
offset(line2, 5, 2, RS.LeftHand);    // dvije paralele na lijevoj strani (iznad)

var circle = addCircle(50,80, 10);
offset(circle, [50,95], 3, 4);   // četiri koncentrične kružnice izvana

reverse

reverse(entity)
reverse(x, y)

Obrće smjer zadanog entiteta, tj. zamjenjuje njegovu početnu i krajnju točku.

var line = addLine(0,0, 100,0);
line = reverse(line);
line.getStartPoint();            // vraća 100,0

explode

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

Razgrađuje zadani entitet na jednostavnije entitete: polilinije na linije i lukove, reference bloka na njihov sadržaj, tekstove na linije i splajnove, kote i šrafure na linije, lukove itd. Izvorni entitet se briše.

options je neobavezni objekt s postavkama koje se inače preuzimaju iz postavki aplikacije, na primjer { splineSegments: 64, textToPolylines: true }. Podržane opcije su: splineTolerance, splineSegments, ellipseSegments, splinesToLineSegments, textToPolylines, textSplineToLineOrArc, multilineTextToSimpleText i circlesToPolylines.

var pl = addPolyline([[0,0], [100,0,1], [100,50], [0,50]], true);
explode(pl);                     // tri linije i jedan luk

stretch

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

Rasteže sve entitete u pravokutnom području definiranom dvama kutovima za zadani pomak. Entiteti koji leže potpuno unutar područja premještaju se, a entiteti koji prelaze granicu područja rastežu se (premještaju se samo krajnje točke unutar područja). Područje se može zadati i kao RBox ili kao zatvoreni oblik RPolyline. Ako su u crtežu odabrani entiteti, rastežu se samo odabrani entiteti.

// pravokutnik od linija:
addLine(0,0, 100,0);
addLine(100,0, 100,50);
addLine(100,50, 0,50);
addLine(0,50, 0,0);

// proširi pravokutnik za 50 jedinica rastezanjem njegove desne strane:
stretch([80,-10], [120,60], [50,0]);

deleteEntity

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

Briše zadani entitet iz crteža.

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

deleteEntity(l1);                // putem entiteta
deleteEntity(l2.getId());        // putem ID-a entiteta
deleteEntity(50,20);             // putem položaja

paste

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

Lijepi sadržaj dokumenta sourceDocument u sučelje dokumenta destination ili u trenutni crtež ako je destination undefined. Zalijepljeni sadržaj premješta se za offset, skalira faktorom scale i rotira za rotation stupnjeva. Svi su argumenti obavezni:

• flipHorizontal, flipVertical: true za okretanje sadržaja
• toCurrentLayer: true za lijepljenje svih entiteta na trenutni sloj
• overwriteLayers, overwriteBlocks: true za prepisivanje postojećih slojeva ili blokova s istim nazivom

// stvori simbol u dokumentu izvan zaslona:
var symbol = createDocument();
startTransaction(symbol);
addCircle(0,0, 10);
addLine(-10,0, 10,0);
addLine(0,-10, 0,10);
endTransaction();

// zalijepi ga triput u trenutni crtež:
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 i endTransaction

startTransaction()
startTransaction(document)
endTransaction()

Prema zadanim postavkama svaki se poziv Simple API-ja odmah primjenjuje na crtež i može se zasebno poništiti. Između startTransaction() i endTransaction() sve se promjene prikupljaju i primjenjuju zajedno kada se pozove endTransaction. To ima dvije prednosti:

• Mnogo je brže pri dodavanju velikog broja entiteta.
• Sve se promjene mogu poništiti u jednom koraku.

Ako se funkciji startTransaction preda dokument (RDocument) ili sučelje dokumenta (RDocumentInterface), sve se promjene primjenjuju na taj dokument umjesto na trenutni crtež. To je korisno za stvaranje crteža u pozadini, na primjer radi njihova izvoza u datoteku (vidi createDocumentInterface).

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

Pri radu s transakcijama imajte na umu sljedeće:

• Unutar transakcije promjene još nisu dio crteža. Funkcije izmjene poput trim ili round ne mogu se odnositi na entitete dodane u istoj transakciji.
• Entiteti koje funkcije za stvaranje vrate unutar transakcije nemaju valjani ID, čak ni nakon endTransaction. Da biste takve entitete kasnije mijenjali, referencirajte ih putem položaja.
• Svi entiteti dodani unutar transakcije smještaju se na sloj koji je trenutni u trenutku poziva endTransaction. Postavite trenutni sloj prije početka transakcije i koristite zasebne transakcije za različite slojeve.

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

// referenciraj nove linije putem položaja kako bi se zaoblio kut:
round([50,0], [100,25], 10);

getTransactionDocument i getTransactionDocumentInterface

getTransactionDocument()
getTransactionDocumentInterface()

Vraćaju dokument ili sučelje dokumenta na koje se odnosi trenutna transakcija. Izvan transakcija vraćaju se trenutni dokument i sučelje dokumenta.

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

getOperation

getOperation()

Vraća operaciju (RAddObjectsOperation) trenutne transakcije. Izvan transakcije vraća se nova operacija koju treba izričito primijeniti. Namijenjeno je naprednoj upotrebi, na primjer za kombiniranje poziva Simple API-ja s cjelokupnim QCAD API-jem.

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

Prikaz

autoZoom

autoZoom()

Zumira trenutni prikaz tako da je vidljiv cijeli crtež.

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)

Zumira na zadani entitet, oblik ili pravokutno područje. margin je rub oko područja u pikselima (zadano 10).

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

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

Dokumenti i aplikacija

getMainWindow

getMainWindow()

Vraća prozor aplikacije QCAD (RMainWindowQt).

getMainWindow().windowTitle;

getDocumentInterface

getDocumentInterface()

Vraća sučelje dokumenta (RDocumentInterface) trenutnog crteža. Sučelje dokumenta povezuje dokument s njegovim prikazima i pruža funkcije za uvoz i izvoz datoteka, primjenu operacija, poništavanje i ponavljanje.

addLine(0,0, 100,0);
getDocumentInterface().undo();       // ponovno uklanja liniju

getDocument

getDocument()

Vraća trenutni dokument (RDocument). Dokument sadrži sve entitete, slojeve, blokove itd. crteža i pruža funkcije za njihovo ispitivanje.

addLine(0,0, 100,0);
addCircle(0,0, 10);
getDocument().queryAllEntities().length;     // broj entiteta u crtežu

getGraphicsView

getGraphicsView()

Vraća trenutni ili posljednji aktivni prikaz (RGraphicsView) trenutnog crteža.

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

createDocument

createDocument()

Stvara novi, prazni dokument u memoriji koji se ne prikazuje u prozoru. Takav dokument izvan zaslona može se popuniti pomoću transakcije, a zatim zalijepiti u crtež (vidi paste).

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

doc.queryAllEntities().length;       // vraća 2

createDocumentInterface

createDocumentInterface()

Stvara novi, prazni dokument u memoriji zajedno sa sučeljem dokumenta. Sučelje dokumenta može se koristiti za uvoz ili izvoz datoteka.

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

disableInput()
enableInput()
isInputEnabled()

disableInput onemogućuje prozor aplikacije QCAD kako bi se spriječio korisnički unos, na primjer tijekom dugih operacija ili animacija. enableInput ponovno omogućuje prozor aplikacije, a isInputEnabled vraća true ako je korisnički unos trenutno omogućen. Uvijek se pobrinite da na kraju skripte ponovno omogućite unos.

update

update()

Obrađuje događaje na čekanju kako bi se korisničko sučelje ažuriralo tijekom dugih operacija. Prije poziva funkcije update korisnički unos mora biti onemogućen pomoću disableInput.

sleep

sleep(milliseconds)

Pauzira skriptu na zadano vrijeme u milisekundama, a korisničko sučelje pritom ostaje ažurno. Prije poziva funkcije sleep korisnički unos mora biti onemogućen pomoću disableInput.

Sljedeći primjer koristi disableInput, sleep i enableInput za prikaz jednostavne 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)

Prikazuje poruku upozorenja. U ljusci za skripte upozorenja se prikazuju u povijesti naredbenog retka. Inače se upozorenja ispisuju u konzolu.

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

Korisnički unos

Sljedeće funkcije prikazuju jednostavan dijalog kojim se od korisnika traži vrijednost. Ako korisnik otkaže dijalog, vraća se undefined.

getInt

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

Traži od korisnika cijeli broj. value je početna vrijednost (zadano 0), step korak brojčanog polja (zadano 1), a min i max dopušteni raspon.

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)

Traži od korisnika broj. value je početna vrijednost (zadano 0), decimals broj prikazanih decimala (zadano 1), a min i max dopušteni raspon.

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

getText

getText(title, prompt, text)

Traži od korisnika tekst. text je početni tekst (zadano prazno).

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

getItem

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

Omogućuje korisniku odabir stavke s padajućeg popisa. items je niz znakova sa svim stavkama odvojenima znakom separator (zadano ","). index je indeks početno odabrane stavke (zadano 0). Vraća odabranu stavku ili undefined ako je dijalog otkazan.

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

Primjer: prirubnica

Ovaj primjer kombinira nekoliko funkcija Simple API-ja za crtanje prirubnice s diobenim krugom, provrtima za vijke na zasebnom sloju i pravokutnim izrezom sa zaobljenim kutovima:

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

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

// diobeni krug i središnje linije:
setCurrentLayer("Center Lines");
addCircle(0,0, 75);
addLine(-110,0, 110,0);
addLine(0,-110, 0,110);

// provrti za vijke, dodani u jednoj 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 sa zaobljenim kutovima u sredini:
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();

Linije izreza dodaju se bez transakcije kako bi se mogle izravno predati funkciji round. Provrti za vijke dodaju se u transakciji, što je brže i omogućuje njihovo poništavanje u jednom koraku.