Simple API

Wprowadzenie

QCAD Simple API to niewielki zestaw globalnych funkcji skryptowych, które upraszczają typowe zadania, takie jak dodawanie obiektów do rysunku, odpytywanie obiektów i ich modyfikowanie (przenoszenie, przycinanie, zaokrąglanie, odsuwanie, …). Jest przeznaczone głównie do użytku w Script Shell oraz w krótkich skryptach proceduralnych, które są uruchamiane z pliku, ale można go używać w dowolnym skrypcie.

Simple API obejmuje jedynie niewielką część kompletnego API QCAD. Ponieważ samo jest napisane w ECMAScript (JavaScript), stanowi również dobry punkt wyjścia do nauki działania bazowego API QCAD. Kod źródłowy znajduje się w plikach scripts/simple.js i scripts/simple_*.js kodu źródłowego QCAD.

Korzystanie z Simple API

W Script Shell (Różne > Rozwój > Script Shell) oraz w skryptach uruchamianych za pomocą Różne > Rozwój > Uruchom skrypt wszystkie funkcje Simple API są dostępne bezpośrednio. Wpisz na przykład:

addLine(0,0, 100,100);

We własnych plikach skryptów, na przykład w interaktywnych akcjach skryptowych lub narzędziach wiersza poleceń, najpierw dołącz plik simple.js:

include("scripts/simple.js");

addLine(0,0, 100,100);

Wszystkie funkcje działają na rysunku, który jest aktualnie otwarty w oknie aplikacji QCAD, chyba że zostanie użyta transakcja, aby przekierować je do innego dokumentu (zobacz Transakcje).

Wszystkie przykłady na tej stronie można wkleić do Script Shell pustego rysunku. Każdy przykład tworzy potrzebne mu obiekty. Aby zobaczyć wynik, użyj Widok > Przybliż automatycznie lub funkcji autoZoom().

Konwencje

Współrzędne

Pozycje można przekazywać na trzy różne sposoby:

• Jako dwie oddzielne liczby: addLine(0,0, 100,100)
• Jako tablicę dwóch liczb: addLine([0,0], [100,100])
• Jako obiekt wektora: addLine(new RVector(0,0), new RVector(100,100))

Kąty są zawsze podawane w stopniach, z wyjątkiem parametrów początkowego i końcowego elips, które są podawane w radianach.

Odwołania do obiektów

Funkcje, które działają na istniejącym obiekcie, akceptują ten obiekt w różnych postaciach:

• Identyfikator obiektu (liczba), na przykład 1234.
• Obiekt zwrócony przez funkcje tworzące, na przykład wartość zwracana przez addLine(...).
• Pozycja na rysunku ([x,y] lub RVector): używany jest obiekt położony najbliżej podanej pozycji.
• Kształt (na przykład new RLine(0,0, 100,0)): operacja jest stosowana tylko do kształtu, rysunek nie jest zmieniany.

var l = addLine(0,0, 100,0);
move(l, [0,10]);              // przez obiekt
move(l.getId(), [0,10]);      // przez identyfikator obiektu
move([50,20], [0,10]);        // przez pozycję: obiekt najbliższy punktowi 50,20

Pozycje kliknięcia

Niektóre operacje zależą od tego, w którym miejscu obiekt zostaje kliknięty podczas interaktywnego używania odpowiedniego narzędzia. Przycinanie zachowuje część obiektu w miejscu kliknięcia, zaokrąglanie i fazowanie obejmuje końce obiektów najbliższe pozycjom kliknięcia, a odsuwanie tworzy linie równoległe po stronie pozycji kliknięcia.

W Simple API po każdym odwołaniu do obiektu może następować pozycja kliknięcia. Jeśli do obiektu odwołuje się pozycja, służy ona jednocześnie jako pozycja kliknięcia. Jeśli pozycja kliknięcia nie zostanie podana, używany jest punkt środkowy obiektu:

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

// przytnij linię do ograniczenia, zachowaj część linii w punkcie 10,0:
trim(line, [10,0], limit);

Wartości zwracane

• Funkcje tworzące zwracają dodany obiekt. Obiekt można przekazać do innych funkcji lub odpytać o informacje (na przykład getId(), getLength() lub getStartPoint()).
• Przekształcenia (move, rotate, scale, mirror, lengthen, reverse) zwracają zmodyfikowany obiekt.
• Pozostałe funkcje modyfikujące (trim, round, bevel, offset, breakOut, autoTrim, divide, explode, stretch) zwracają transakcję, która została zastosowana do rysunku, lub undefined, jeśli operacja się nie powiodła.
• Jeśli zamiast obiektów przekazywane są kształty, przekształcenia modyfikują podane kształty, a wszystkie pozostałe funkcje zwracają kształty wynikowe w postaci tablicy.

Nieudane operacje nie zgłaszają błędu. Zamiast tego w Script Shell wyświetlane jest ostrzeżenie, na przykład „Nie można przyciąć obiektu.”.

Tworzenie obiektów

addPoint

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

Dodaje obiekt punktu w podanej pozycji.

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

addLine

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

Dodaje linię od punktu początkowego do punktu końcowego.

// trójkąt:
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 prostą (linię konstrukcyjną) przechodzącą przez punkt bazowy x,y w kierunku dx,dy. Kierunek jest podawany względem punktu bazowego.

// pozioma linia konstrukcyjna i linia konstrukcyjna pod kątem 45 stopni przez 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 łuk o podanym środku, promieniu, kącie początkowym i kącie końcowym. Kąty są podawane w stopniach. Łuki biegną przeciwnie do ruchu wskazówek zegara od kąta początkowego do kąta końcowego, chyba że reversed ma wartość true (opcjonalnie, domyślnie false).

// ćwiartka łuku od 0 do 90 stopni:
addArc(0,0, 50, 0, 90);

// łuk zgodnie z ruchem wskazówek zegara od 0 do 90 stopni (pozostałe trzy ćwiartki):
addArc([0,0], 40, 0, 90, true);

addCircle

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

Dodaje okrąg o podanym środku i promieniu.

// okręgi współśrodkowe:
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 elipsę lub łuk elipsy. mx,my to punkt końcowy osi wielkiej względem środka. ratio to stosunek osi małej do osi wielkiej. startParam i endParam to parametry elipsy w radianach, w których elipsa się zaczyna i kończy. Dla pełnej elipsy użyj 0 i 2*Math.PI.

// pełna elipsa o dużym promieniu 50 i małym promieniu 25:
addEllipse(0,0, 50,0, 0.5, 0, 2*Math.PI, false);

// górna połowa obróconej elipsy:
addEllipse([0,0], [30,30], 0.3, 0, Math.PI, false);

addPolyline

addPolyline(points, closed, relative)

Dodaje polilinię przechodzącą przez podane wierzchołki. points to tablica wierzchołków, z których każdy jest podany jako [x, y], [x, y, bulge] lub [x, y, bulge, relative]. Zamiast x, y można użyć RVector.

• bulge (wybrzuszenie) określa kształt segmentu, który zaczyna się w tym wierzchołku: 0 (domyślnie) dla segmentu prostego, 1 dla półokręgu przeciwnie do ruchu wskazówek zegara, -1 dla półokręgu zgodnie z ruchem wskazówek zegara. Inne wartości tworzą pośrednie segmenty łukowe (wybrzuszenie to tangens jednej czwartej kąta łuku).
• relative: true, jeśli współrzędne tego wierzchołka są względne w stosunku do poprzedniego wierzchołka.
• closed: true, aby zamknąć polilinię (domyślnie false).
• relative: true, aby traktować współrzędne wszystkich wierzchołków jako względne w stosunku do poprzedniego wierzchołka (domyślnie false).

// zamknięty prostokąt:
addPolyline([[0,0], [100,0], [100,50], [0,50]], true);

// kształt podłużnego otworu z dwoma półokręgami:
addPolyline([[0,60], [80,60,1], [80,80], [0,80,1]], true);

// linia zygzakowata ze współrzędnymi względnymi:
addPolyline([[0,100], [10,10], [10,-10], [10,10], [10,-10]], false, true);

addSpline

addSpline(fitPoints, closed)

Dodaje splajn przechodzący przez podane punkty dopasowania. fitPoints to tablica tablic [x, y] lub obiektów RVector. Jeśli closed ma wartość true, splajn jest zamknięty (okresowy).

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

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

Samouczek Uruchamianie skryptów z pliku pokazuje inny przykład, który wykreśla krzywą Lissajous jako 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 tekst jednowierszowy w podanej pozycji. Wszystkie argumenty po pozycji są opcjonalne:

• height: wysokość tekstu (domyślnie 1)
• angle: kąt tekstu w stopniach (domyślnie 0)
• font: nazwa czcionki (domyślnie "Standard")
• vAlign: wyrównanie w pionie: RS.VAlignTop (domyślnie), RS.VAlignMiddle, RS.VAlignBase lub RS.VAlignBottom
• hAlign: wyrównanie w poziomie: RS.HAlignLeft (domyślnie), RS.HAlignCenter lub RS.HAlignRight
• bold, italic: true dla tekstu pogrubionego lub kursywy (tylko czcionki 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])

Dodaje obszar z jednolitym wypełnieniem (solid) o trzech lub czterech narożnikach. Należy pamiętać, że narożniki czworokątnego wypełnienia podaje się w kolejności zygzakowatej: pierwszy narożnik, drugi narożnik, następnie narożnik naprzeciwko drugiego narożnika i narożnik naprzeciwko pierwszego narożnika. Aby utworzyć trójkąt, przekaż trzeci narożnik dwukrotnie.

// wypełniony kwadrat:
addSolid(0,0, 50,0, 0,50, 50,50);

// wypełniony trójkąt:
addSolid([60,0], [110,0], [85,50], [85,50]);

Dodawanie kształtów, obiektów i obiektów API

Poniższe funkcje dodają do rysunku obiekty, które zostały utworzone za pomocą pełnego API QCAD. Są przydatne, gdy wyspecjalizowane funkcje tworzące opisane powyżej nie obejmują określonego przypadku.

addShape

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

Dodaje podany kształt (RLine, RArc, RCircle, REllipse, RPolyline, RSpline, RPoint, …) jako nowy obiekt na bieżącej warstwie. Opcjonalnie można podać kolor (RColor), rodzaj linii (nazwa lub identyfikator) i szerokość linii (na przykład RLineweight.Weight050). Domyślnie używany jest bieżący kolor, rodzaj linii ByLayer i szerokość linii 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 wszystkie kształty z podanej tablicy jako nowe obiekty.

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 podany obiekt (REntity) do rysunku. Jeśli kolor nie zostanie podany, używany jest bieżący kolor.

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 dowolny obiekt API (obiekt rysunku, warstwę, blok, …) do rysunku i zwraca dodany obiekt.

// dodaj blok o nazwie "Marker" z krzyżykiem:
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);

// wstaw blok dwukrotnie:
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)

Usuwa podany obiekt API z rysunku. Do usuwania obiektów rysunku zwykle wygodniejsza jest funkcja deleteEntity.

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

Warstwy i atrybuty

addLayer

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

Dodaje nową warstwę o podanej nazwie. Opcjonalnie można podać nazwę koloru (domyślnie "white", który na białym tle jest wyświetlany jako czarny), nazwę rodzaju linii (domyślnie "CONTINUOUS") i szerokość linii (domyślnie RLineweight.Weight000). Zwraca nową warstwę lub undefined, jeśli warstwa o podanej nazwie już istnieje.

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

hasLayer

hasLayer(name)

Zwraca true, jeśli na rysunku istnieje warstwa o podanej nazwie.

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

setCurrentLayer

setCurrentLayer(name)

Ustawia bieżącą warstwę. Wszystkie obiekty dodane później są umieszczane na tej warstwie.

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

setCurrentColor

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

Ustawia kolor dla obiektów dodawanych później. Kolor można podać jako obiekt RColor lub jako wartości czerwonej, zielonej i niebieskiej składowej (0-255). Użyj new RColor(RColor.ByLayer), aby przywrócić kolor „Według warstwy”.

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

Odpytywanie obiektów

getEntity

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

Zwraca obiekt dla podanego odwołania do obiektu, tzn. obiekt o podanym identyfikatorze, bieżący stan podanego obiektu lub obiekt położony najbliżej podanej pozycji. Zwraca undefined, jeśli nie znaleziono żadnego obiektu.

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

// circle nadal przechowuje stary środek, getEntity zwraca bieżący stan:
getEntity(circle).getCenter();     // zwraca 10,0

// obiekt najbliższy punktowi 30,0:
getEntity(30,0).getRadius();       // zwraca 20

getShape

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

Zwraca geometrię podanego obiektu jako kształt (RLine dla linii, RArc dla łuku, RPolyline dla polilinii, …). Kształtów można używać do obliczeń geometrycznych bez zmieniania rysunku.

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

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

getClosestEntity

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

Zwraca obiekt położony najbliżej podanej pozycji. Jeśli podano range, uwzględniane są tylko obiekty znajdujące się w tej odległości od pozycji. Zwraca undefined, jeśli nie znaleziono żadnego obiektu.

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

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

getEntityShape

getEntityShape(entity, position)

Zwraca kształt podanego obiektu. W przypadku obiektów złożonych, które składają się z wielu kształtów (odniesienia do bloków, kreskowania, wymiary, teksty), zwracany jest kształt położony najbliżej podanej pozycji. Pozycja jest opcjonalna.

// odniesienie do bloku zawierającego prostokąt:
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)));

// kształt odniesienia do bloku w pobliżu 40,10 (prostokąt):
var s = getEntityShape(getEntity(ref), new RVector(41,10));
s.getLength();                     // zwraca 120

getIntersectionPoints

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

Zwraca tablicę z punktami przecięcia dwóch podanych obiektów lub kształtów. Obiekty można podać jako obiekty, identyfikatory obiektów lub kształty. Jeśli limited ma wartość false, obiekty są traktowane tak, jakby były nieskończone (linie przedłużone, łuki jako pełne okręgi). Domyślnie true.

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

// zaznacz przecięcia małymi okręgami:
for (var i=0; i<ips.length; i++) {
    addCircle(ips[i], 2);
}

isPosition i toVector

isPosition(value)
toVector(value)

isPosition zwraca true, jeśli podana wartość jest pozycją (RVector lub tablica dwóch albo trzech liczb). toVector konwertuje pozycję podaną jako tablica na RVector. Funkcje te są przydatne przy pisaniu własnych funkcji, które akceptują pozycje w taki sam sposób jak 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]);                 // zwraca true
isPosition("abc");                 // zwraca false

Modyfikowanie obiektów

Przekształcenia

move

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

Przenosi podany obiekt o podane przesunięcie.

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

rotate

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

Obraca podany obiekt o podany kąt w stopniach wokół podanego środka. Jeśli środek nie zostanie podany, obiekt jest obracany wokół początku układu współrzędnych 0,0.

// wachlarz linii obróconych wokół 0,0:
for (var a=0; a<360; a+=30) {
    var l = addLine(10,0, 50,0);
    rotate(l, a);
}

// obróć kwadrat wokół jego środka:
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])

Skaluje podany obiekt o podany współczynnik. Punkt ostrości (punkt, który pozostaje w miejscu) to domyślnie początek układu współrzędnych 0,0. Różne współczynniki dla X i Y można podać jako tablicę [sx, sy]. Należy pamiętać, że niektórych obiektów, takich jak okręgi i łuki, nie można skalować z różnymi współczynnikami w 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(...))

Tworzy lustrzane odbicie podanego obiektu względem osi zdefiniowanej przez dwa punkty.

var pl = addPolyline([[10,0], [40,0], [40,30]], false);
// odbicie lustrzane względem osi Y:
mirror(pl, 0,0, 0,100);

Aby zachować oryginał i utworzyć kopię lustrzaną, najpierw dodaj kopię obiektu:

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

Przycinanie i wydłużanie

trim

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

Przycina obiekt trimEntity do obiektu ograniczającego limitingEntity. Część przycinanego obiektu w pozycji kliknięcia trimPos zostaje zachowana. Jeśli oba obiekty się nie przecinają, obiekt jest przedłużany do obiektu ograniczającego. Jeśli istnieje wiele przecięć, używane jest to, które leży najbliżej pozycji kliknięcia limitingPos. Jeśli trimBoth ma wartość true, oba obiekty są przycinane do siebie nawzajem.

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

// zachowaj lewą część, linia kończy się teraz w punkcie 70,0:
trim(line, [10,0], limit);

// przedłuż linię do okręgu:
var line = addLine(0,0, 50,0);
var circle = addCircle(100,0, 20);

// przedłuż do przecięcia z okręgiem najbliższego punktowi 80,0:
trim(line, [25,0], circle, [80,0]);      // linia kończy się teraz w punkcie 80,0

trimBoth

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

Przycina lub przedłuża oba obiekty do ich punktu przecięcia. Jest to skrót dla trim z trimBoth ustawionym na true.

// dwie niestykające się linie zostają przedłużone, tworząc narożnik w punkcie 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)

Wydłuża podany obiekt o podaną wartość. Wartości ujemne skracają obiekt. Domyślnie obiekt jest wydłużany w punkcie końcowym. Przekaż true dla start, aby zamiast tego wydłużyć go w punkcie początkowym, lub przekaż pozycję w pobliżu końca, który ma zostać wydłużony.

var line = addLine(0,0, 100,0);
lengthen(line, 20);              // linia kończy się teraz w punkcie 120,0
lengthen(line, true, -10);       // linia zaczyna się teraz w punkcie 10,0

var arc = addArc(0,50, 30, 0, 90);
lengthen(arc, [30,50], 10);      // wydłuż łuk w jego punkcie początkowym

breakOut

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

Wycina segment podanego obiektu w podanej pozycji. Segment kończy się na najbliższych przecięciach z innymi obiektami po obu stronach pozycji. Jeśli po jednej stronie nie ma przecięcia, segment sięga do końca obiektu. Jeśli removeSegment ma wartość true (domyślnie), segment jest usuwany. W przeciwnym razie zostaje zachowany jako oddzielny obiekt.

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

// usuń część linii między 30,0 a 70,0:
breakOut(line, [50,0]);

autoTrim

autoTrim(entity, pos)
autoTrim(pos)

Przeciwieństwo breakOut: zachowuje tylko segment podanego obiektu w podanej pozycji i usuwa resztę. Segment kończy się na najbliższych przecięciach z innymi obiektami po obu stronach pozycji.

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

// zachowaj tylko część między 30,0 a 70,0:
autoTrim(line, [50,0]);

divide

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

Dzieli podany obiekt w podanej pozycji. Obiekt otwarty (linia, łuk, otwarta polilinia, …) jest dzielony na dwie części w jednej pozycji lub na trzy części w dwóch pozycjach. Obiekty zamknięte (okręgi, pełne elipsy, zamknięte polilinie) wymagają dwóch pozycji i są dzielone na dwie części.

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

var circle = addCircle(0,50, 20);
divide(circle, [20,50], [-20,50]);   // dwa półokręgi

Narożniki

round

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

Zaokrągla narożnik między dwoma obiektami łukiem o podanym promieniu (zaokrąglenie). Pozycje kliknięcia wskazują, które końce obiektów zostaną zaokrąglone. Jeśli trim ma wartość true (domyślnie), oba obiekty są przycinane do łuku zaokrąglenia.

// prostokąt z zaokrąglonymi narożnikami:
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);

Narożniki polilinii również można zaokrąglać, przekazując tę samą polilinię dwukrotnie z pozycją kliknięcia na każdym z dwóch segmentów:

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)

Fazuje narożnik między dwoma obiektami linią prostą (faza). distance1 to odległość linii fazy od narożnika wzdłuż pierwszego obiektu, distance2 wzdłuż drugiego obiektu (domyślnie distance1). Jeśli trim ma wartość true (domyślnie), oba obiekty są przycinane do linii fazy. chamfer jest aliasem dla 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)

Tworzy linie równoległe do linii, łuki i okręgi współśrodkowe lub krzywe równoległe do elips i innych obiektów. number to liczba tworzonych krzywych równoległych (domyślnie 1). Krzywe równoległe są tworzone po obu stronach obiektu, chyba że podano stronę, albo jako pozycję sidePos obok obiektu, albo jako side (RS.LeftHand, RS.RightHand lub RS.BothSides). Odsuwanie polilinii i splajnów jest dostępne tylko w QCAD Professional.

var line = addLine(0,0, 100,0);
offset(line, 5);                 // jedna linia równoległa po każdej stronie

var line2 = addLine(0,30, 100,30);
offset(line2, 5, 2, RS.LeftHand);    // dwie linie równoległe po lewej stronie (powyżej)

var circle = addCircle(50,80, 10);
offset(circle, [50,95], 3, 4);   // cztery okręgi współśrodkowe na zewnątrz

reverse

reverse(entity)
reverse(x, y)

Odwraca kierunek podanego obiektu, tzn. zamienia jego punkt początkowy z punktem końcowym.

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

explode

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

Rozbija podany obiekt na prostsze obiekty: polilinie na linie i łuki, odniesienia do bloków na ich zawartość, teksty na linie i splajny, wymiary i kreskowania na linie, łuki itd. Oryginalny obiekt zostaje usunięty.

options to opcjonalny obiekt z ustawieniami, które w przeciwnym razie są pobierane z preferencji aplikacji, na przykład { splineSegments: 64, textToPolylines: true }. Obsługiwane opcje to: splineTolerance, splineSegments, ellipseSegments, splinesToLineSegments, textToPolylines, textSplineToLineOrArc, multilineTextToSimpleText i circlesToPolylines.

var pl = addPolyline([[0,0], [100,0,1], [100,50], [0,50]], true);
explode(pl);                     // trzy linie i jeden łuk

stretch

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

Rozciąga wszystkie obiekty w prostokątnym obszarze zdefiniowanym przez dwa narożniki o podane przesunięcie. Obiekty, które leżą całkowicie wewnątrz obszaru, są przenoszone, a obiekty przecinające granicę obszaru są rozciągane (przenoszone są tylko punkty końcowe znajdujące się wewnątrz obszaru). Obszar można również podać jako RBox lub jako kształt zamkniętej RPolyline. Jeśli na rysunku są zaznaczone obiekty, rozciągane są tylko zaznaczone obiekty.

// prostokąt złożony z linii:
addLine(0,0, 100,0);
addLine(100,0, 100,50);
addLine(100,50, 0,50);
addLine(0,50, 0,0);

// poszerz prostokąt o 50 jednostek, rozciągając jego prawą stronę:
stretch([80,-10], [120,60], [50,0]);

deleteEntity

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

Usuwa podany obiekt z rysunku.

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

deleteEntity(l1);                // przez obiekt
deleteEntity(l2.getId());        // przez identyfikator obiektu
deleteEntity(50,20);             // przez pozycję

paste

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

Wkleja zawartość dokumentu sourceDocument do interfejsu dokumentu destination lub do bieżącego rysunku, jeśli destination ma wartość undefined. Wklejona zawartość jest przesuwana o offset, skalowana o scale i obracana o rotation stopni. Wszystkie argumenty są wymagane:

• flipHorizontal, flipVertical: true, aby odwrócić zawartość
• toCurrentLayer: true, aby wkleić wszystkie obiekty na bieżącą warstwę
• overwriteLayers, overwriteBlocks: true, aby nadpisać istniejące warstwy lub bloki o tej samej nazwie

// utwórz symbol w niewidocznym dokumencie:
var symbol = createDocument();
startTransaction(symbol);
addCircle(0,0, 10);
addLine(-10,0, 10,0);
addLine(0,-10, 0,10);
endTransaction();

// wklej go trzy razy do bieżącego rysunku:
for (var i=0; i<3; i++) {
    paste(symbol, undefined, [i*50, 0], 1+i*0.5, i*15, false, false, false, false, false);
}

Transakcje

startTransaction i endTransaction

startTransaction()
startTransaction(document)
endTransaction()

Domyślnie każde wywołanie Simple API jest natychmiast stosowane do rysunku i może zostać cofnięte osobno. Między startTransaction() a endTransaction() wszystkie zmiany są zbierane i stosowane razem w chwili wywołania endTransaction. Ma to dwie zalety:

• Jest to znacznie szybsze przy dodawaniu wielu obiektów.
• Wszystkie zmiany można cofnąć w jednym kroku.

Jeśli do startTransaction zostanie przekazany dokument (RDocument) lub interfejs dokumentu (RDocumentInterface), wszystkie zmiany są stosowane do tego dokumentu zamiast do bieżącego rysunku. Jest to przydatne do tworzenia rysunków w tle, na przykład w celu wyeksportowania ich do pliku (zobacz createDocumentInterface).

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

Podczas pracy z transakcjami należy pamiętać o następujących kwestiach:

• W obrębie transakcji zmiany nie są jeszcze częścią rysunku. Funkcje modyfikujące, takie jak trim lub round, nie mogą odwoływać się do obiektów dodanych w tej samej transakcji.
• Obiekty zwrócone przez funkcje tworzące w obrębie transakcji nie mają prawidłowego identyfikatora, nawet po endTransaction. Aby później zmodyfikować takie obiekty, odwołuj się do nich przez pozycję.
• Wszystkie obiekty dodane w obrębie transakcji są umieszczane na warstwie, która jest bieżąca w chwili wywołania endTransaction. Ustaw bieżącą warstwę przed rozpoczęciem transakcji i używaj oddzielnych transakcji dla różnych warstw.

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

// odwołaj się do nowych linii przez pozycję, aby zaokrąglić narożnik:
round([50,0], [100,25], 10);

getTransactionDocument i getTransactionDocumentInterface

getTransactionDocument()
getTransactionDocumentInterface()

Zwracają dokument lub interfejs dokumentu, którego dotyczy bieżąca transakcja. Poza transakcjami zwracany jest bieżący dokument i interfejs dokumentu.

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

getOperation

getOperation()

Zwraca operację (RAddObjectsOperation) bieżącej transakcji. Poza transakcją zwracana jest nowa operacja, którą trzeba zastosować jawnie. Jest to przeznaczone do zaawansowanych zastosowań, na przykład do łączenia wywołań Simple API z pełnym 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();

Widok

autoZoom

autoZoom()

Przybliża bieżący widok tak, aby widoczny był cały rysunek.

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)

Przybliża do podanego obiektu, kształtu lub prostokątnego obszaru. margin to margines wokół obszaru w pikselach (domyślnie 10).

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

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

Dokumenty i aplikacja

getMainWindow

getMainWindow()

Zwraca okno aplikacji QCAD (RMainWindowQt).

getMainWindow().windowTitle;

getDocumentInterface

getDocumentInterface()

Zwraca interfejs dokumentu (RDocumentInterface) bieżącego rysunku. Interfejs dokumentu łączy dokument z jego widokami i udostępnia funkcje do importowania i eksportowania plików, stosowania operacji, cofania i ponawiania.

addLine(0,0, 100,0);
getDocumentInterface().undo();       // ponownie usuwa linię

getDocument

getDocument()

Zwraca bieżący dokument (RDocument). Dokument przechowuje wszystkie obiekty, warstwy, bloki itd. rysunku i udostępnia funkcje do ich odpytywania.

addLine(0,0, 100,0);
addCircle(0,0, 10);
getDocument().queryAllEntities().length;     // liczba obiektów na rysunku

getGraphicsView

getGraphicsView()

Zwraca bieżący lub ostatnio aktywny widok (RGraphicsView) bieżącego rysunku.

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

createDocument

createDocument()

Tworzy w pamięci nowy, pusty dokument, który nie jest wyświetlany w oknie. Taki niewidoczny dokument można wypełnić za pomocą transakcji, a następnie wkleić do rysunku (zobacz paste).

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

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

createDocumentInterface

createDocumentInterface()

Tworzy w pamięci nowy, pusty dokument wraz z interfejsem dokumentu. Interfejsu dokumentu można używać do importowania lub eksportowania plików.

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 wyłącza okno aplikacji QCAD, aby uniemożliwić wprowadzanie danych przez użytkownika, na przykład podczas długich operacji lub animacji. enableInput ponownie włącza okno aplikacji, a isInputEnabled zwraca true, jeśli wprowadzanie danych przez użytkownika jest aktualnie włączone. Zawsze pamiętaj, aby na końcu skryptu ponownie włączyć wprowadzanie danych.

update

update()

Przetwarza oczekujące zdarzenia, tak aby interfejs użytkownika był aktualizowany podczas długich operacji. Przed wywołaniem update należy wyłączyć wprowadzanie danych przez użytkownika za pomocą disableInput.

sleep

sleep(milliseconds)

Wstrzymuje skrypt na podany czas w milisekundach, utrzymując przy tym aktualność interfejsu użytkownika. Przed wywołaniem sleep należy wyłączyć wprowadzanie danych przez użytkownika za pomocą disableInput.

Poniższy przykład używa disableInput, sleep i enableInput do wyświetlenia prostej animacji:

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)

Wyświetla komunikat ostrzegawczy. W Script Shell ostrzeżenia są wyświetlane w historii wiersza poleceń. W przeciwnym razie ostrzeżenia są wypisywane na konsoli.

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

Dane wprowadzane przez użytkownika

Poniższe funkcje wyświetlają proste okno dialogowe z prośbą o podanie wartości przez użytkownika. Jeśli użytkownik anuluje okno dialogowe, zwracana jest wartość undefined.

getInt

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

Prosi użytkownika o podanie liczby całkowitej. value to wartość początkowa (domyślnie 0), step to krok pola numerycznego (domyślnie 1), min i max to dozwolony zakres.

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)

Prosi użytkownika o podanie liczby. value to wartość początkowa (domyślnie 0), decimals to liczba wyświetlanych miejsc po przecinku (domyślnie 1), min i max to dozwolony zakres.

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

getText

getText(title, prompt, text)

Prosi użytkownika o podanie tekstu. text to tekst początkowy (domyślnie pusty).

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

getItem

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

Pozwala użytkownikowi wybrać element z listy rozwijanej. items to ciąg znaków zawierający wszystkie elementy oddzielone znakiem separator (domyślnie ","). index to indeks początkowo wybranego elementu (domyślnie 0). Zwraca wybrany element lub undefined, jeśli okno dialogowe zostało anulowane.

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

Przykład: kołnierz

Ten przykład łączy kilka funkcji Simple API, aby narysować kołnierz z okręgiem podziałowym, otworami na śruby na oddzielnej warstwie i prostokątnym wycięciem o zaokrąglonych narożnikach:

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

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

// okrąg podziałowy i linie środkowe:
setCurrentLayer("Center Lines");
addCircle(0,0, 75);
addLine(-110,0, 110,0);
addLine(0,-110, 0,110);

// otwory na śruby, dodane w jednej transakcji:
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();

// kwadratowe wycięcie o zaokrąglonych narożnikach w środku:
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();

Linie wycięcia są dodawane bez transakcji, dzięki czemu można je przekazać bezpośrednio do round. Otwory na śruby są dodawane w transakcji, co jest szybsze i pozwala cofnąć ich dodanie w jednym kroku.