Simple API

Úvod

QCAD Simple API je malá sada globálních skriptových funkcí, které zjednodušují běžné úlohy, jako je přidávání prvků do výkresu, dotazování na prvky a jejich úpravy (přesouvání, oříznutí, zaoblení, vytváření rovnoběžek, …). Je určeno hlavně pro použití ve Script Shell a pro krátké procedurální skripty, které se spouštějí ze souboru, lze jej však použít v jakémkoli skriptu.

Simple API pokrývá jen malou část kompletního API QCAD. Protože je samo napsáno v ECMAScriptu (JavaScriptu), je také dobrým výchozím bodem pro seznámení s tím, jak funguje základní API QCAD. Zdrojový kód najdete v souborech scripts/simple.js a scripts/simple_*.js zdrojového kódu QCAD.

Používání Simple API

Ve Script Shell (Různé > Vývoj > Script Shell) a ve skriptech spuštěných pomocí Různé > Vývoj > Spustit skript jsou všechny funkce Simple API k dispozici přímo. Zadejte například:

addLine(0,0, 100,100);

Ve vlastních souborech skriptů, například v interaktivních skriptových akcích nebo v nástrojích příkazového řádku, nejprve vložte soubor simple.js:

include("scripts/simple.js");

addLine(0,0, 100,100);

Všechny funkce pracují s výkresem, který je právě otevřen v okně aplikace QCAD, pokud nejsou pomocí transakce přesměrovány do jiného dokumentu (viz Transakce).

Všechny příklady na této stránce lze vložit do Script Shell prázdného výkresu. Každý příklad si vytvoří prvky, které potřebuje. Výsledek zobrazíte pomocí Zobrazení > Automatické přiblížení nebo funkce autoZoom().

Konvence

Souřadnice

Polohy lze předávat třemi různými způsoby:

• Jako dvě samostatná čísla: addLine(0,0, 100,100)
• Jako pole dvou čísel: addLine([0,0], [100,100])
• Jako objekt vektoru: addLine(new RVector(0,0), new RVector(100,100))

Úhly se vždy zadávají ve stupních, s výjimkou počátečního a koncového parametru elips, které se zadávají v radiánech.

Odkazy na prvky

Funkce, které pracují s existujícím prvkem, přijímají prvek v různých podobách:

• ID prvku (číslo), například 1234.
• Objekt prvku, jak jej vracejí funkce pro vytváření, například návratová hodnota addLine(...).
• Poloha ve výkresu ([x,y] nebo RVector): použije se prvek nejbližší zadané poloze.
• Tvar (například new RLine(0,0, 100,0)): operace se použije pouze na tvar, výkres se nezmění.

var l = addLine(0,0, 100,0);
move(l, [0,10]);              // pomocí objektu prvku
move(l.getId(), [0,10]);      // pomocí ID prvku
move([50,20], [0,10]);        // pomocí polohy: prvek nejbližší bodu 50,20

Polohy kliknutí

Některé operace závisí na tom, kam se při interaktivním použití odpovídajícího nástroje na prvek klikne. Oříznutí zachová část prvku v místě kliknutí, zaoblení a zkosení se provede na koncích prvků nejbližších polohám kliknutí a vytváření rovnoběžek vytvoří rovnoběžky na straně polohy kliknutí.

V Simple API může za každým odkazem na prvek následovat poloha kliknutí. Pokud je na prvek odkazováno polohou, slouží tato poloha zároveň jako poloha kliknutí. Pokud poloha kliknutí není zadána, použije se střední bod prvku:

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

// oříznout čáru k omezení, zachovat část čáry u bodu 10,0:
trim(line, [10,0], limit);

Návratové hodnoty

• Funkce pro vytváření vracejí přidaný prvek. Prvek lze předat dalším funkcím nebo se na něj dotázat na informace (například getId(), getLength() nebo getStartPoint()).
• Transformace (move, rotate, scale, mirror, lengthen, reverse) vracejí upravený prvek.
• Ostatní funkce pro úpravy (trim, round, bevel, offset, breakOut, autoTrim, divide, explode, stretch) vracejí transakci, která byla na výkres použita, nebo undefined, pokud se operace nezdařila.
• Pokud se místo prvků předávají tvary, transformace upraví zadané tvary a všechny ostatní funkce vrátí výsledné tvary jako pole.

Neúspěšné operace nevyvolávají chybu. Místo toho se ve Script Shell zobrazí varování, například „Prvek nemůže být oříznut.“.

Vytváření prvků

addPoint

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

Přidá bodový prvek na zadanou polohu.

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

addLine

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

Přidá čáru z počátečního bodu do koncového bodu.

// trojúhelník:
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])

Přidá nekonečnou přímku (konstrukční přímku) procházející základním bodem x,y se směrem dx,dy. Směr se zadává relativně k základnímu bodu.

// vodorovná konstrukční přímka a konstrukční přímka pod úhlem 45 stupňů procházející bodem 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)

Přidá oblouk se zadaným středem, poloměrem, počátečním úhlem a koncovým úhlem. Úhly jsou ve stupních. Oblouky vedou proti směru hodinových ručiček od počátečního úhlu ke koncovému úhlu, pokud reversed není true (volitelné, výchozí hodnota je false).

// čtvrtinový oblouk od 0 do 90 stupňů:
addArc(0,0, 50, 0, 90);

// oblouk po směru hodinových ručiček od 0 do 90 stupňů (zbývající tři čtvrtiny):
addArc([0,0], 40, 0, 90, true);

addCircle

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

Přidá kružnici se zadaným středem a poloměrem.

// soustředné 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)

Přidá elipsu nebo eliptický oblouk. mx,my je koncový bod hlavní osy relativně ke středu. ratio je poměr mezi vedlejší a hlavní osou. startParam a endParam jsou parametry elipsy v radiánech, kde elipsa začíná a končí. Pro celou elipsu použijte 0 a 2*Math.PI.

// celá elipsa s hlavní poloosou 50 a vedlejší poloosou 25:
addEllipse(0,0, 50,0, 0.5, 0, 2*Math.PI, false);

// horní polovina natočené elipsy:
addEllipse([0,0], [30,30], 0.3, 0, Math.PI, false);

addPolyline

addPolyline(points, closed, relative)

Přidá lomenou čáru procházející zadanými vrcholy. points je pole vrcholů, z nichž každý je zadán jako [x, y], [x, y, bulge] nebo [x, y, bulge, relative]. Místo x, y lze použít RVector.

• bulge (vypouklina) určuje tvar segmentu, který začíná v tomto vrcholu: 0 (výchozí) pro přímý segment, 1 pro půlkružnici proti směru hodinových ručiček, -1 pro půlkružnici po směru hodinových ručiček. Jiné hodnoty vytvářejí obloukové segmenty mezi těmito krajními případy (vypouklina je tangens čtvrtiny středového úhlu oblouku).
• relative: true, pokud jsou souřadnice tohoto vrcholu relativní k předchozímu vrcholu.
• closed: true pro uzavření lomené čáry (výchozí hodnota je false).
• relative: true, pokud se mají souřadnice všech vrcholů považovat za relativní k předchozímu vrcholu (výchozí hodnota je false).

// uzavřený obdélník:
addPolyline([[0,0], [100,0], [100,50], [0,50]], true);

// tvar drážky se dvěma půlkružnicemi:
addPolyline([[0,60], [80,60,1], [80,80], [0,80,1]], true);

// klikatá čára s relativními souřadnicemi:
addPolyline([[0,100], [10,10], [10,-10], [10,10], [10,-10]], false, true);

addSpline

addSpline(fitPoints, closed)

Přidá křivku (spline) procházející zadanými upevňujícími body. fitPoints je pole polí [x, y] nebo objektů RVector. Pokud je closed true, křivka je uzavřená (periodická).

// otevřená křivka:
addSpline([[0,0], [30,40], [60,0], [90,40]], false);

// uzavřená křivka:
addSpline([[0,60], [40,80], [80,60], [40,100]], true);

Návod Spouštění skriptů ze souboru ukazuje další příklad, který vykreslí Lissajousovu křivku jako 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)

Přidá jednořádkový text na zadanou polohu. Všechny argumenty za polohou jsou volitelné:

• height: výška textu (výchozí 1)
• angle: úhel textu ve stupních (výchozí 0)
• font: název písma (výchozí "Standard")
• vAlign: svislé zarovnání: RS.VAlignTop (výchozí), RS.VAlignMiddle, RS.VAlignBase nebo RS.VAlignBottom
• hAlign: vodorovné zarovnání: RS.HAlignLeft (výchozí), RS.HAlignCenter nebo RS.HAlignRight
• bold, italic: true pro tučný text nebo kurzívu (pouze písma 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])

Přidá plochu s plnou výplní (solid) se třemi nebo čtyřmi rohy. Upozorňujeme, že rohy čtyřúhelníkové výplně se zadávají v pořadí do cik-cak: první roh, druhý roh, potom roh protilehlý ke druhému rohu a roh protilehlý k prvnímu rohu. Chcete-li vytvořit trojúhelník, zadejte třetí roh dvakrát.

// vyplněný čtverec:
addSolid(0,0, 50,0, 0,50, 50,50);

// vyplněný trojúhelník:
addSolid([60,0], [110,0], [85,50], [85,50]);

Přidávání tvarů, prvků a objektů

Následující funkce přidávají do výkresu objekty, které byly vytvořeny pomocí kompletního API QCAD. Jsou užitečné tehdy, když specializované funkce pro vytváření uvedené výše určitý případ nepokrývají.

addShape

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

Přidá zadaný tvar (RLine, RArc, RCircle, REllipse, RPolyline, RSpline, RPoint, …) jako nový prvek do aktuální vrstvy. Volitelně lze zadat barvu (RColor), typ čáry (název nebo ID) a tloušťku čáry (například RLineweight.Weight050). Ve výchozím nastavení se použije aktuální barva, typ čáry ByLayer a tloušťka čáry 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)

Přidá všechny tvary v zadaném poli jako nové prvky.

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)

Přidá zadaný prvek (REntity) do výkresu. Pokud není zadána barva, použije se aktuální 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)

Přidá do výkresu libovolný objekt (prvek, vrstvu, blok, …) a vrátí přidaný objekt.

// přidat blok s názvem "Marker" obsahující křížek:
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);

// vložit blok dvakrát:
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)

Odstraní zadaný objekt z výkresu. K odstraňování prvků je obvykle pohodlnější funkce deleteEntity.

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

Vrstvy a vlastnosti

addLayer

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

Přidá novou vrstvu se zadaným názvem. Volitelně lze zadat název barvy (výchozí "white", která se na bílém pozadí zobrazuje černě), název typu čáry (výchozí "CONTINUOUS") a tloušťku čáry (výchozí RLineweight.Weight000). Vrátí novou vrstvu nebo undefined, pokud vrstva se zadaným názvem již existuje.

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

hasLayer

hasLayer(name)

Vrátí true, pokud ve výkresu existuje vrstva se zadaným názvem.

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

setCurrentLayer

setCurrentLayer(name)

Nastaví aktuální vrstvu. Všechny poté přidané prvky se umístí do této vrstvy.

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

setCurrentColor

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

Nastaví barvu pro prvky přidané poté. Barvu lze zadat jako objekt RColor nebo jako hodnoty červené, zelené a modré složky (0-255). Pomocí new RColor(RColor.ByLayer) barvu vrátíte na „Podle vrstvy“.

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

Dotazování na prvky

getEntity

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

Vrátí prvek pro zadaný odkaz na prvek, tj. prvek se zadaným ID, aktuální stav zadaného prvku nebo prvek nejbližší zadané poloze. Vrátí undefined, pokud žádný prvek není nalezen.

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

// circle stále obsahuje starý střed, getEntity vrací aktuální stav:
getEntity(circle).getCenter();     // vrátí 10,0

// prvek nejbližší bodu 30,0:
getEntity(30,0).getRadius();       // vrátí 20

getShape

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

Vrátí geometrii zadaného prvku jako tvar (RLine pro čáru, RArc pro oblouk, RPolyline pro lomenou čáru, …). Tvary lze použít pro geometrické výpočty bez změny výkresu.

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

var pl = getShape(50,0);
pl.getLength();                    // vrátí 150

getClosestEntity

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

Vrátí prvek nejbližší zadané poloze. Pokud je zadán range, berou se v úvahu pouze prvky v této vzdálenosti od polohy. Vrátí undefined, pokud žádný prvek není nalezen.

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

getClosestEntity(50,10).getStartPoint();     // vrátí 0,0
getClosestEntity([50,25], 5);               // vrátí undefined

getEntityShape

getEntityShape(entity, position)

Vrátí tvar zadaného objektu prvku. U složených prvků, které se skládají z více tvarů (reference bloků, šrafování, kóty, texty), se vrátí tvar nejbližší zadané poloze. Poloha je volitelná.

// reference bloku, který obsahuje obdélník:
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)));

// tvar reference bloku poblíž bodu 40,10 (obdélník):
var s = getEntityShape(getEntity(ref), new RVector(41,10));
s.getLength();                     // vrátí 120

getIntersectionPoints

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

Vrátí pole s průsečíky dvou zadaných prvků nebo tvarů. Prvky lze zadat jako objekty prvků, ID prvků nebo tvary. Pokud je limited false, s prvky se zachází, jako by byly nekonečné (čáry prodloužené, oblouky jako celé kružnice). Výchozí hodnota je true.

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

// označit průsečíky malými kružnicemi:
for (var i=0; i<ips.length; i++) {
    addCircle(ips[i], 2);
}

isPosition a toVector

isPosition(value)
toVector(value)

isPosition vrátí true, pokud je zadaná hodnota poloha (RVector nebo pole dvou nebo tří čísel). toVector převede polohu zadanou jako pole na RVector. Tyto funkce jsou užitečné při psaní vlastních funkcí, které přijímají polohy stejným způsobem jako 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]);                 // vrátí true
isPosition("abc");                 // vrátí false

Úpravy prvků

Transformace

move

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

Přesune zadaný prvek o zadaný posun.

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

rotate

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

Natočí zadaný prvek o zadaný úhel ve stupních kolem zadaného středu. Pokud střed není zadán, prvek se natočí kolem počátku 0,0.

// vějíř čar natočených kolem bodu 0,0:
for (var a=0; a<360; a+=30) {
    var l = addLine(10,0, 50,0);
    rotate(l, a);
}

// natočit čtverec kolem jeho středu:
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])

Změní měřítko zadaného prvku o zadaný faktor. Ohnisko (bod, který zůstává na místě) je ve výchozím nastavení počátek 0,0. Různé faktory pro X a Y lze zadat jako pole [sx, sy]. Upozorňujeme, že u některých prvků, jako jsou kružnice a oblouky, nelze měřítko měnit různými faktory v X a 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(...))

Zrcadlí zadaný prvek podle osy definované dvěma body.

var pl = addPolyline([[10,0], [40,0], [40,30]], false);
// zrcadlit podle osy Y:
mirror(pl, 0,0, 0,100);

Chcete-li zachovat originál a vytvořit zrcadlenou kopii, nejprve přidejte kopii prvku:

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

Oříznutí a prodloužení

trim

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

Ořízne prvek trimEntity k omezujícímu prvku limitingEntity. Část ořezávaného prvku v poloze kliknutí trimPos se zachová. Pokud se oba prvky neprotínají, prvek se prodlouží k omezujícímu prvku. Pokud existuje více průsečíků, použije se ten, který je nejblíže poloze kliknutí limitingPos. Pokud je trimBoth true, oba prvky se oříznou navzájem.

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

// zachovat levou část, čára nyní končí v bodě 70,0:
trim(line, [10,0], limit);

// prodloužit čáru ke kružnici:
var line = addLine(0,0, 50,0);
var circle = addCircle(100,0, 20);

// prodloužit k průsečíku s kružnicí, který je nejblíže bodu 80,0:
trim(line, [25,0], circle, [80,0]);      // čára nyní končí v bodě 80,0

trimBoth

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

Ořízne nebo prodlouží oba prvky k jejich průsečíku. Jedná se o zkratku pro trim s trimBoth nastaveným na true.

// dvě čáry, které se nedotýkají, se prodlouží a vytvoří roh v bodě 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)

Prodlouží zadaný prvek o zadanou hodnotu. Záporné hodnoty prvek zkrátí. Ve výchozím nastavení se prvek prodlouží na svém koncovém bodě. Chcete-li jej místo toho prodloužit na počátečním bodě, předejte pro start hodnotu true, nebo předejte polohu blízko konce, který se má prodloužit.

var line = addLine(0,0, 100,0);
lengthen(line, 20);              // čára nyní končí v bodě 120,0
lengthen(line, true, -10);       // čára nyní začíná v bodě 10,0

var arc = addArc(0,50, 30, 0, 90);
lengthen(arc, [30,50], 10);      // prodloužit oblouk na jeho počátečním bodě

breakOut

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

Vyřízne segment zadaného prvku v zadané poloze. Segment končí na nejbližších průsečících s jinými prvky na obou stranách polohy. Pokud na jedné straně žádný průsečík není, segment sahá až ke konci prvku. Pokud je removeSegment true (výchozí), segment se odstraní. Jinak se zachová jako samostatný prvek.

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

// odstranit část čáry mezi body 30,0 a 70,0:
breakOut(line, [50,0]);

autoTrim

autoTrim(entity, pos)
autoTrim(pos)

Opak breakOut: zachová pouze segment zadaného prvku v zadané poloze a zbytek odstraní. Segment končí na nejbližších průsečících s jinými prvky na obou stranách polohy.

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

// zachovat pouze část mezi body 30,0 a 70,0:
autoTrim(line, [50,0]);

divide

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

Rozdělí zadaný prvek v zadané poloze. Otevřený prvek (čára, oblouk, otevřená lomená čára, …) se rozdělí na dvě části v jedné poloze nebo na tři části ve dvou polohách. Uzavřené prvky (kružnice, celé elipsy, uzavřené lomené čáry) vyžadují dvě polohy a rozdělí se na dvě části.

var line = addLine(0,0, 100,0);
divide(line, [40,0]);            // dvě čáry: 0..40 a 40..100

var circle = addCircle(0,50, 20);
divide(circle, [20,50], [-20,50]);   // dvě půlkružnice

Rohy

round

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

Zaoblí roh mezi dvěma prvky obloukem o zadaném poloměru (zaoblení). Polohy kliknutí určují, které konce prvků se zaoblí. Pokud je trim true (výchozí), oba prvky se oříznou k zaoblovacímu oblouku.

// obdélník se zaoblenými rohy:
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);

Zaoblit lze i rohy lomené čáry, a to tak, že se dvakrát předá stejná lomená čára s polohou kliknutí na každém ze dvou segmentů:

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

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

Zkosí roh mezi dvěma prvky přímou čarou (zkosení). distance1 je vzdálenost čáry zkosení od rohu podél prvního prvku, distance2 podél druhého prvku (výchozí hodnota je distance1). Pokud je trim true (výchozí), oba prvky se oříznou k čáře zkosení. chamfer je alias pro 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)

Vytvoří rovnoběžky k čarám, soustředné oblouky a kružnice nebo ekvidistantní křivky k elipsám a dalším prvkům. number je počet vytvářených rovnoběžek (výchozí 1). Rovnoběžky se vytvoří na obou stranách prvku, pokud není zadána strana, buď jako poloha sidePos vedle prvku, nebo jako side (RS.LeftHand, RS.RightHand nebo RS.BothSides). Vytváření ekvidistant k lomeným čarám a křivkám spline je k dispozici pouze v QCAD Professional.

var line = addLine(0,0, 100,0);
offset(line, 5);                 // jedna rovnoběžka na každé straně

var line2 = addLine(0,30, 100,30);
offset(line2, 5, 2, RS.LeftHand);    // dvě rovnoběžky na levé straně (nahoře)

var circle = addCircle(50,80, 10);
offset(circle, [50,95], 3, 4);   // čtyři soustředné kružnice vně

reverse

reverse(entity)
reverse(x, y)

Obrátí směr zadaného prvku, tj. prohodí jeho počáteční a koncový bod.

var line = addLine(0,0, 100,0);
line = reverse(line);
line.getStartPoint();            // vrátí 100,0

explode

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

Rozloží zadaný prvek na jednodušší prvky: lomené čáry na čáry a oblouky, reference bloků na jejich obsah, texty na čáry a křivky spline, kóty a šrafování na čáry, oblouky atd. Původní prvek se odstraní.

options je volitelný objekt s nastaveními, která se jinak přebírají z předvoleb aplikace, například { splineSegments: 64, textToPolylines: true }. Podporované možnosti jsou: splineTolerance, splineSegments, ellipseSegments, splinesToLineSegments, textToPolylines, textSplineToLineOrArc, multilineTextToSimpleText a circlesToPolylines.

var pl = addPolyline([[0,0], [100,0,1], [100,50], [0,50]], true);
explode(pl);                     // tři čáry a jeden oblouk

stretch

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

Roztáhne všechny prvky v obdélníkové oblasti definované dvěma rohy o zadaný posun. Prvky, které leží zcela uvnitř oblasti, se přesunou, prvky, které protínají hranici oblasti, se roztáhnou (přesunou se pouze koncové body uvnitř oblasti). Oblast lze zadat také jako RBox nebo jako tvar uzavřené RPolyline. Pokud jsou ve výkresu vybrány prvky, roztáhnou se pouze vybrané prvky.

// obdélník složený z čar:
addLine(0,0, 100,0);
addLine(100,0, 100,50);
addLine(100,50, 0,50);
addLine(0,50, 0,0);

// rozšířit obdélník o 50 jednotek roztažením jeho pravé strany:
stretch([80,-10], [120,60], [50,0]);

deleteEntity

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

Odstraní zadaný prvek z výkresu.

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

deleteEntity(l1);                // pomocí prvku
deleteEntity(l2.getId());        // pomocí ID prvku
deleteEntity(50,20);             // pomocí polohy

paste

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

Vloží obsah dokumentu sourceDocument do rozhraní dokumentu destination nebo do aktuálního výkresu, pokud je destination undefined. Vložený obsah se posune o offset, změní se jeho měřítko o scale a natočí se o rotation stupňů. Všechny argumenty jsou povinné:

• flipHorizontal, flipVertical: true pro převrácení obsahu
• toCurrentLayer: true pro vložení všech prvků do aktuální vrstvy
• overwriteLayers, overwriteBlocks: true pro přepsání existujících vrstev nebo bloků se stejným názvem

// vytvořit symbol v neviditelném dokumentu:
var symbol = createDocument();
startTransaction(symbol);
addCircle(0,0, 10);
addLine(-10,0, 10,0);
addLine(0,-10, 0,10);
endTransaction();

// vložit jej třikrát do aktuálního výkresu:
for (var i=0; i<3; i++) {
    paste(symbol, undefined, [i*50, 0], 1+i*0.5, i*15, false, false, false, false, false);
}

Transakce

startTransaction a endTransaction

startTransaction()
startTransaction(document)
endTransaction()

Ve výchozím nastavení se každé volání Simple API okamžitě použije na výkres a lze je jednotlivě vrátit zpět. Mezi startTransaction() a endTransaction() se všechny změny shromažďují a použijí se společně při zavolání endTransaction. To má dvě výhody:

• Při přidávání mnoha prvků je to mnohem rychlejší.
• Všechny změny lze vrátit zpět v jediném kroku.

Pokud se do startTransaction předá dokument (RDocument) nebo rozhraní dokumentu (RDocumentInterface), všechny změny se místo do aktuálního výkresu použijí do tohoto dokumentu. To je užitečné pro vytváření výkresů na pozadí, například pro jejich export do souboru (viz createDocumentInterface).

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

Při práci s transakcemi mějte na paměti následující:

• V rámci transakce nejsou změny ještě součástí výkresu. Funkce pro úpravy jako trim nebo round nemohou odkazovat na prvky přidané ve stejné transakci.
• Prvky vrácené funkcemi pro vytváření v rámci transakce nemají platné ID, a to ani po endTransaction. Chcete-li takové prvky později upravit, odkazujte na ně pomocí polohy.
• Všechny prvky přidané v rámci transakce se umístí do vrstvy, která je aktuální při zavolání endTransaction. Nastavte aktuální vrstvu před zahájením transakce a pro různé vrstvy používejte samostatné transakce.

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

// odkázat na nové čáry pomocí polohy a zaoblit roh:
round([50,0], [100,25], 10);

getTransactionDocument a getTransactionDocumentInterface

getTransactionDocument()
getTransactionDocumentInterface()

Vrátí dokument nebo rozhraní dokumentu, na které se aktuální transakce vztahuje. Mimo transakce se vrátí aktuální dokument a rozhraní dokumentu.

var doc = createDocument();
startTransaction(doc);
addLine(0,0, 10,0);
getTransactionDocument() === doc;    // vrátí true
endTransaction();

getOperation

getOperation()

Vrátí operaci (RAddObjectsOperation) aktuální transakce. Mimo transakci se vrátí nová operace, kterou je nutné použít explicitně. Je to určeno pro pokročilé použití, například pro kombinování volání Simple API s kompletním API 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();

Pohled

autoZoom

autoZoom()

Přiblíží aktuální pohled tak, aby byl vidět celý výkres.

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)

Přiblíží na zadaný prvek, tvar nebo obdélníkovou oblast. margin je okraj kolem oblasti v pixelech (výchozí 10).

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

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

Dokumenty a aplikace

getMainWindow

getMainWindow()

Vrátí okno aplikace QCAD (RMainWindowQt).

getMainWindow().windowTitle;

getDocumentInterface

getDocumentInterface()

Vrátí rozhraní dokumentu (RDocumentInterface) aktuálního výkresu. Rozhraní dokumentu propojuje dokument s jeho pohledy a poskytuje funkce pro import a export souborů, použití operací a pro akce Zpět a Znovu.

addLine(0,0, 100,0);
getDocumentInterface().undo();       // čáru opět odstraní

getDocument

getDocument()

Vrátí aktuální dokument (RDocument). Dokument obsahuje všechny prvky, vrstvy, bloky atd. výkresu a poskytuje funkce pro dotazování na ně.

addLine(0,0, 100,0);
addCircle(0,0, 10);
getDocument().queryAllEntities().length;     // počet prvků ve výkresu

getGraphicsView

getGraphicsView()

Vrátí aktuální nebo naposledy aktivní pohled (RGraphicsView) aktuálního výkresu.

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

createDocument

createDocument()

Vytvoří v paměti nový prázdný dokument, který se nezobrazuje v žádném okně. Takový neviditelný dokument lze naplnit pomocí transakce a poté vložit do výkresu (viz paste).

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

doc.queryAllEntities().length;       // vrátí 2

createDocumentInterface

createDocumentInterface()

Vytvoří v paměti nový prázdný dokument společně s rozhraním dokumentu. Rozhraní dokumentu lze použít k importu nebo exportu souborů.

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

disableInput()
enableInput()
isInputEnabled()

disableInput deaktivuje okno aplikace QCAD, aby zabránila vstupu uživatele, například během dlouhých operací nebo animací. enableInput okno aplikace znovu aktivuje a isInputEnabled vrátí true, pokud je vstup uživatele právě povolen. Vždy nezapomeňte na konci skriptu vstup opět povolit.

update

update()

Zpracuje čekající události, aby se uživatelské rozhraní během dlouhých operací aktualizovalo. Před voláním update musí být vstup uživatele zakázán pomocí disableInput.

sleep

sleep(milliseconds)

Pozastaví skript na zadanou dobu v milisekundách a přitom udržuje uživatelské rozhraní aktuální. Před voláním sleep musí být vstup uživatele zakázán pomocí disableInput.

Následující příklad používá disableInput, sleep a enableInput k zobrazení jednoduché animace:

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)

Zobrazí varovnou zprávu. Ve Script Shell se varování zobrazují v historii příkazového řádku. Jinak se varování vypisují do konzole.

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

Vstup uživatele

Následující funkce zobrazí jednoduchý dialog, ve kterém uživatele požádají o zadání hodnoty. Pokud uživatel dialog zruší, vrátí se undefined.

getInt

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

Požádá uživatele o zadání celého čísla. value je počáteční hodnota (výchozí 0), step krok číselníku (výchozí 1), min a max povolený rozsah.

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)

Požádá uživatele o zadání čísla. value je počáteční hodnota (výchozí 0), decimals počet zobrazených desetinných míst (výchozí 1), min a max povolený rozsah.

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

getText

getText(title, prompt, text)

Požádá uživatele o zadání textu. text je počáteční text (ve výchozím nastavení prázdný).

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

getItem

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

Umožní uživateli vybrat položku z rozbalovacího seznamu. items je řetězec se všemi položkami oddělenými pomocí separator (výchozí ","). index je index původně vybrané položky (výchozí 0). Vrátí vybranou položku nebo undefined, pokud byl dialog zrušen.

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říklad: příruba

Tento příklad kombinuje několik funkcí Simple API a nakreslí přírubu s roztečnou kružnicí, otvory pro šrouby v samostatné vrstvě a obdélníkovým výřezem se zaoblenými rohy:

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

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

// roztečná kružnice a osy:
setCurrentLayer("Center Lines");
addCircle(0,0, 75);
addLine(-110,0, 110,0);
addLine(0,-110, 0,110);

// otvory pro šrouby, přidané v jedné transakci:
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();

// čtvercový výřez se zaoblenými rohy uprostřed:
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();

Čáry výřezu se přidávají bez transakce, aby je bylo možné předat přímo funkci round. Otvory pro šrouby se přidávají v transakci, což je rychlejší a umožňuje jejich přidání vrátit zpět v jednom kroku.