Simple API

Въведение

Simple API на QCAD е малък набор от глобални скриптови функции, които опростяват често срещани задачи, като добавяне на обекти към чертеж, извличане на информация за обекти и тяхната промяна (преместване, подрязване, закръгляване, отместване, …). Той е предназначен главно за използване в Скрипт Shell и за кратки процедурни скриптове, които се изпълняват от файл, но може да се използва от всеки скрипт.

Simple API обхваща само малка част от пълния API на QCAD. Тъй като самият той е написан на ECMAScript (JavaScript), той е и добра отправна точка, за да научите как работи основният API на QCAD. Изходният код се намира във файловете scripts/simple.js и scripts/simple_*.js на изходния код на QCAD.

Използване на Simple API

В Скрипт Shell (Разни > Развитие > Скрипт Shell) и в скриптовете, стартирани с Разни > Развитие > Изпълнение на скрипт, всички функции на Simple API са достъпни директно. Въведете например:

addLine(0,0, 100,100);

Във вашите собствени скриптови файлове, например в интерактивни скриптови действия или инструменти от командния ред, първо включете файла simple.js:

include("scripts/simple.js");

addLine(0,0, 100,100);

Всички функции работят върху чертежа, който в момента е отворен в прозореца на приложението QCAD, освен ако не се използва транзакция, която ги пренасочва към друг документ (вижте Транзакции).

Всички примери на тази страница могат да бъдат поставени в Скрипт Shell на празен чертеж. Всеки пример създава обектите, от които се нуждае. Използвайте Вижте > Автоматично увеличение или функцията autoZoom(), за да видите резултата.

Конвенции

Координати

Позициите могат да се подават по три различни начина:

• Като две отделни числа: addLine(0,0, 100,100)
• Като масив от две числа: addLine([0,0], [100,100])
• Като векторен обект: addLine(new RVector(0,0), new RVector(100,100))

Ъглите винаги се задават в градуси, с изключение на началния и крайния параметър на елипсите, които се задават в радиани.

Препратки към обекти

Функциите, които работят със съществуващ обект, приемат обекта в различни форми:

• ID на обект (число), например 1234.
• Самият обект, както е върнат от функциите за създаване, например върнатата стойност на addLine(...).
• Позиция в чертежа ([x,y] или RVector): използва се обектът, който е най-близо до дадената позиция.
• Форма (например new RLine(0,0, 100,0)): операцията се прилага само върху формата, чертежът не се променя.

var l = addLine(0,0, 100,0);
move(l, [0,10]);              // чрез обекта
move(l.getId(), [0,10]);      // чрез ID на обекта
move([50,20], [0,10]);        // чрез позиция: обектът, най-близо до 50,20

Позиции на щракване

Някои операции зависят от това къде се щраква върху обекта, когато съответният инструмент се използва интерактивно. При подрязване се запазва частта от обекта в позицията на щракване, при закръгляване и скосяване се закръглят краищата на обектите, които са най-близо до позициите на щракване, а при отместване се създават успоредни линии от страната на позицията на щракване.

В Simple API след всяка препратка към обект може да следва позиция на щракване. Ако обектът е посочен чрез позиция, тази позиция служи и като позиция на щракване. Ако не е зададена позиция на щракване, се използва средната точка на обекта:

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

// подрязване на line до limit, запазва се частта от line при 10,0:
trim(line, [10,0], limit);

Върнати стойности

• Функциите за създаване връщат добавения обект. Обектът може да бъде подаден на други функции или от него да се извлече информация (например getId(), getLength() или getStartPoint()).
• Трансформациите (move, rotate, scale, mirror, lengthen, reverse) връщат променения обект.
• Другите функции за промяна (trim, round, bevel, offset, breakOut, autoTrim, divide, explode, stretch) връщат транзакцията, която е приложена към чертежа, или undefined, ако операцията е неуспешна.
• Ако вместо обекти се подават форми, трансформациите променят дадените форми, а всички останали функции връщат получените форми като масив.

Неуспешните операции не предизвикват грешка. Вместо това в Скрипт Shell се показва предупреждение, например „Субектът не може да бъде подрязан.“.

Създаване на обекти

addPoint

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

Добавя обект точка в дадената позиция.

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

addLine

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

Добавя линия от началната до крайната точка.

// триъгълник:
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])

Добавя безкрайна линия (спомагателна линия) през базовата точка x,y с посока dx,dy. Посоката се задава спрямо базовата точка.

// хоризонтална и наклонена под 45 градуса спомагателна линия през 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)

Добавя дъга с дадения център, радиус, начален ъгъл и краен ъгъл. Ъглите са в градуси. Дъгите вървят обратно на часовниковата стрелка от началния към крайния ъгъл, освен ако reversed не е true (незадължително, по подразбиране е false).

// четвърт дъга от 0 до 90 градуса:
addArc(0,0, 50, 0, 90);

// дъга по часовниковата стрелка от 0 до 90 градуса (другите три четвърти):
addArc([0,0], 40, 0, 90, true);

addCircle

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

Добавя окръжност с дадения център и радиус.

// концентрични окръжности:
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)

Добавя елипса или елиптична дъга. mx,my е крайната точка на голямата ос спрямо центъра. ratio е отношението между малката и голямата ос. startParam и endParam са параметрите на елипсата в радиани, при които елипсата започва и завършва. Използвайте 0 и 2*Math.PI за пълна елипса.

// пълна елипса с голям радиус 50 и малък радиус 25:
addEllipse(0,0, 50,0, 0.5, 0, 2*Math.PI, false);

// горната половина на завъртяна елипса:
addEllipse([0,0], [30,30], 0.3, 0, Math.PI, false);

addPolyline

addPolyline(points, closed, relative)

Добавя полилиния през дадените върхове. points е масив от върхове, всеки зададен като [x, y], [x, y, bulge] или [x, y, bulge, relative]. Вместо x, y може да се използва RVector.

• bulge (издутина) определя формата на сегмента, който започва в този връх: 0 (по подразбиране) за прав сегмент, 1 за полуокръжност обратно на часовниковата стрелка, -1 за полуокръжност по часовниковата стрелка. Други стойности създават дъгови сегменти между тях (издутината е тангенсът на една четвърт от централния ъгъл на дъгата).
• relative: true, ако координатите на този връх са относителни спрямо предишния връх.
• closed: true, за да се затвори полилинията (по подразбиране е false).
• relative: true, за да се третират координатите на всички върхове като относителни спрямо предишния връх (по подразбиране е false).

// затворен правоъгълник:
addPolyline([[0,0], [100,0], [100,50], [0,50]], true);

// форма на канал с две полуокръжности:
addPolyline([[0,60], [80,60,1], [80,80], [0,80,1]], true);

// зигзагообразна линия с относителни координати:
addPolyline([[0,100], [10,10], [10,-10], [10,10], [10,-10]], false, true);

addSpline

addSpline(fitPoints, closed)

Добавя сплайн през дадените точки на напасване. fitPoints е масив от масиви [x, y] или обекти RVector. Ако closed е true, сплайнът е затворен (периодичен).

// отворен сплайн:
addSpline([[0,0], [30,40], [60,0], [90,40]], false);

// затворен сплайн:
addSpline([[0,60], [40,80], [80,60], [40,100]], true);

Урокът Изпълнение на скриптове от файл показва още един пример, който изчертава крива на Лисажу като сплайн.

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)

Добавя едноредов текст в дадената позиция. Всички аргументи след позицията са незадължителни:

• height: височина на текста (по подразбиране 1)
• angle: ъгъл на текста в градуси (по подразбиране 0)
• font: име на шрифта (по подразбиране "Standard")
• vAlign: вертикално подравняване: RS.VAlignTop (по подразбиране), RS.VAlignMiddle, RS.VAlignBase или RS.VAlignBottom
• hAlign: хоризонтално подравняване: RS.HAlignLeft (по подразбиране), RS.HAlignCenter или RS.HAlignRight
• bold, italic: true за получер или курсивен текст (само за шрифтове 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])

Добавя плътно запълнена област (solid) с три или четири ъгъла. Обърнете внимание, че ъглите на четириъгълна запълнена област се задават в зигзагообразен ред: първи ъгъл, втори ъгъл, след това ъгълът срещу втория ъгъл и ъгълът срещу първия ъгъл. За да създадете триъгълник, подайте третия ъгъл два пъти.

// запълнен квадрат:
addSolid(0,0, 50,0, 0,50, 50,50);

// запълнен триъгълник:
addSolid([60,0], [110,0], [85,50], [85,50]);

Добавяне на форми, графични обекти и други обекти

Следващите функции добавят към чертежа обекти, създадени с пълния API на QCAD. Те са полезни, когато специализираните функции за създаване по-горе не покриват определен случай.

addShape

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

Добавя дадената форма (RLine, RArc, RCircle, REllipse, RPolyline, RSpline, RPoint, …) като нов обект в текущия слой. По желание могат да се зададат цвят (RColor), тип линия (име или ID) и дебелина на линията (например RLineweight.Weight050). По подразбиране се използват текущият цвят, тип линия ByLayer и дебелина на линията 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)

Добавя всички форми от дадения масив като нови обекти.

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)

Добавя дадения обект (REntity) към чертежа. Ако не е зададен цвят, се използва текущият цвят.

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)

Добавя произволен обект (графичен обект, слой, блок, …) към чертежа и връща добавения обект.

// добавяне на блок с име "Marker", съдържащ кръстче:
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);

// вмъкване на блока два пъти:
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)

Изтрива дадения обект от чертежа. За изтриване на графични обекти обикновено е по-удобна функцията deleteEntity.

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

Слоеве и атрибути

addLayer

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

Добавя нов слой с даденото име. По желание могат да се зададат името на цвета (по подразбиране "white", който се показва в черно на бял фон), името на типа линия (по подразбиране "CONTINUOUS") и дебелината на линията (по подразбиране RLineweight.Weight000). Връща новия слой или undefined, ако вече съществува слой с даденото име.

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

hasLayer

hasLayer(name)

Връща true, ако в чертежа съществува слой с даденото име.

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

setCurrentLayer

setCurrentLayer(name)

Задава текущия слой. Всички обекти, добавени след това, се поставят в този слой.

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

setCurrentColor

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

Задава цвета на обектите, които се добавят след това. Цветът може да бъде зададен като обект RColor или като стойности за червено, зелено и синьо (0-255). Използвайте new RColor(RColor.ByLayer), за да върнете цвета на „По слой“.

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

Извличане на информация за обекти

getEntity

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

Връща обекта за дадената препратка към обект, т.е. обекта с даденото ID, текущото състояние на дадения обект или обекта, най-близо до дадената позиция. Връща undefined, ако не е намерен обект.

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

// circle все още съдържа стария център, getEntity връща текущото състояние:
getEntity(circle).getCenter();     // връща 10,0

// обектът, най-близо до 30,0:
getEntity(30,0).getRadius();       // връща 20

getShape

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

Връща геометрията на дадения обект като форма (RLine за линия, RArc за дъга, RPolyline за полилиния, …). Формите могат да се използват за геометрични изчисления, без да се променя чертежът.

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

var pl = getShape(50,0);
pl.getLength();                    // връща 150

getClosestEntity

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

Връща обекта, който е най-близо до дадената позиция. Ако е зададен range, се вземат предвид само обектите, които са на разстояние до тази стойност от позицията. Връща undefined, ако не е намерен обект.

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

getClosestEntity(50,10).getStartPoint();     // връща 0,0
getClosestEntity([50,25], 5);               // връща undefined

getEntityShape

getEntityShape(entity, position)

Връща формата на дадения обект. При сложни обекти, които се състоят от няколко форми (препратки към блокове, щриховки, размери, текстове), се връща формата, най-близо до дадената позиция. Позицията е незадължителна.

// препратка към блок, съдържащ правоъгълник:
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)));

// формата на препратката към блок близо до 40,10 (правоъгълникът):
var s = getEntityShape(getEntity(ref), new RVector(41,10));
s.getLength();                     // връща 120

getIntersectionPoints

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

Връща масив с пресечните точки на двата дадени обекта или форми. Обектите могат да се зададат като обекти, ID на обекти или форми. Ако limited е false, обектите се третират като безкрайни (линиите са продължени, дъгите се разглеждат като пълни окръжности). По подразбиране е true.

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

// маркиране на пресечните точки с малки окръжности:
for (var i=0; i<ips.length; i++) {
    addCircle(ips[i], 2);
}

isPosition и toVector

isPosition(value)
toVector(value)

isPosition връща true, ако дадената стойност е позиция (RVector или масив от две или три числа). toVector преобразува позиция, зададена като масив, в RVector. Тези функции са полезни, когато пишете собствени функции, които приемат позиции по същия начин като 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]);                 // връща true
isPosition("abc");                 // връща false

Промяна на обекти

Трансформации

move

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

Премества дадения обект с даденото отместване.

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

rotate

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

Завърта дадения обект на дадения ъгъл в градуси около дадения център. Ако не е зададен център, обектът се завърта около началото на координатната система 0,0.

// ветрило от линии, завъртени около 0,0:
for (var a=0; a<360; a+=30) {
    var l = addLine(10,0, 50,0);
    rotate(l, a);
}

// завъртане на квадрат около неговия център:
var sq = addPolyline([[100,0], [120,0], [120,20], [100,20]], true);
rotate(sq, 45, [110,10]);

scale

scale(entity, factor)
scale(entity, factor, cx, cy)
scale(entity, factor, [cx, cy])
scale(entity, [sx, sy], [cx, cy])

Мащабира дадения обект с дадения коефициент. Точката на фокусиране (точката, която остава на място) по подразбиране е началото на координатната система 0,0. Различни коефициенти за X и Y могат да се зададат като масив [sx, sy]. Обърнете внимание, че някои обекти, като окръжности и дъги, не могат да бъдат мащабирани с различни коефициенти по X и 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(...))

Отразява огледално дадения обект спрямо оста, определена от две точки.

var pl = addPolyline([[10,0], [40,0], [40,30]], false);
// огледално отражение спрямо оста Y:
mirror(pl, 0,0, 0,100);

За да запазите оригинала и да създадете огледално отразено копие, първо добавете копие на обекта:

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

Подрязване и удължаване

trim

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

Подрязва обекта trimEntity до ограничаващия обект limitingEntity. Частта от подрязвания обект в позицията на щракване trimPos се запазва. Ако двата обекта не се пресичат, обектът се удължава до ограничаващия обект. Ако има няколко пресечни точки, се използва тази, която е най-близо до позицията на щракване limitingPos. Ако trimBoth е true, двата обекта се подрязват един спрямо друг.

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

// запазва се лявата част, сега линията завършва в 70,0:
trim(line, [10,0], limit);

// удължаване на линия до окръжност:
var line = addLine(0,0, 50,0);
var circle = addCircle(100,0, 20);

// удължаване до пресечната точка с окръжността, най-близо до 80,0:
trim(line, [25,0], circle, [80,0]);      // сега линията завършва в 80,0

trimBoth

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

Подрязва или удължава двата обекта до тяхната пресечна точка. Това е съкратен вариант на trim с trimBoth, зададено на true.

// две линии, които не се допират, се удължават, за да образуват ъгъл в 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)

Удължава дадения обект с дадената стойност. Отрицателните стойности скъсяват обекта. По подразбиране обектът се удължава в крайната си точка. Подайте true за start, за да го удължите вместо това в началната му точка, или подайте позиция близо до края, който трябва да бъде удължен.

var line = addLine(0,0, 100,0);
lengthen(line, 20);              // сега линията завършва в 120,0
lengthen(line, true, -10);       // сега линията започва в 10,0

var arc = addArc(0,50, 30, 0, 90);
lengthen(arc, [30,50], 10);      // удължаване на дъгата в началната ѝ точка

breakOut

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

Изрязва сегмента на дадения обект в дадената позиция. Сегментът завършва в най-близките пресечни точки с други обекти от двете страни на позицията. Ако от едната страна няма пресечна точка, сегментът продължава до края на обекта. Ако removeSegment е true (по подразбиране), сегментът се изтрива. В противен случай той се запазва като отделен обект.

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

// премахване на частта от линията между 30,0 и 70,0:
breakOut(line, [50,0]);

autoTrim

autoTrim(entity, pos)
autoTrim(pos)

Обратното на breakOut: запазва само сегмента на дадения обект в дадената позиция и премахва останалото. Сегментът завършва в най-близките пресечни точки с други обекти от двете страни на позицията.

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

// запазва се само частта между 30,0 и 70,0:
autoTrim(line, [50,0]);

divide

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

Разделя дадения обект в дадената позиция. Отворен обект (линия, дъга, отворена полилиния, …) се разделя на две части в една позиция или на три части в две позиции. Затворените обекти (окръжности, пълни елипси, затворени полилинии) изискват две позиции и се разделят на две части.

var line = addLine(0,0, 100,0);
divide(line, [40,0]);            // две линии: 0..40 и 40..100

var circle = addCircle(0,50, 20);
divide(circle, [20,50], [-20,50]);   // две полуокръжности

Ъгли

round

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

Закръглява ъгъла между два обекта с дъга с дадения радиус (закръгление). Позициите на щракване указват кои краища на обектите се закръглят. Ако trim е true (по подразбиране), двата обекта се подрязват до закръгляващата дъга.

// правоъгълник със закръглени ъгли:
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);

Ъглите на полилиния също могат да бъдат закръглени, като се подаде една и съща полилиния два пъти с позиция на щракване върху всеки от двата сегмента:

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

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

Скосява ъгъла между два обекта с права линия (фаска). distance1 е разстоянието на линията на фаската от ъгъла по първия обект, distance2 – по втория обект (по подразбиране е равно на distance1). Ако trim е true (по подразбиране), двата обекта се подрязват до линията на фаската. chamfer е псевдоним на 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)

Създава успоредни линии на линии, концентрични дъги и окръжности или еквидистантни (отместени) криви на елипси и други обекти. number е броят на успоредните криви, които да се създадат (по подразбиране 1). Успоредните криви се създават от двете страни на обекта, освен ако не е зададена страна, или като позиция sidePos до обекта, или като side (RS.LeftHand, RS.RightHand или RS.BothSides). Отместването на полилинии и сплайни е достъпно само в QCAD Professional.

var line = addLine(0,0, 100,0);
offset(line, 5);                 // по една успоредна линия от всяка страна

var line2 = addLine(0,30, 100,30);
offset(line2, 5, 2, RS.LeftHand);    // две успоредни линии от лявата страна (отгоре)

var circle = addCircle(50,80, 10);
offset(circle, [50,95], 3, 4);   // четири концентрични окръжности отвън

reverse

reverse(entity)
reverse(x, y)

Обръща посоката на дадения обект, т.е. разменя началната и крайната му точка.

var line = addLine(0,0, 100,0);
line = reverse(line);
line.getStartPoint();            // връща 100,0

explode

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

Разбива дадения обект на по-прости обекти: полилинии на линии и дъги, препратки към блокове на тяхното съдържание, текстове на линии и сплайни, размери и щриховки на линии, дъги и т.н. Оригиналният обект се изтрива.

options е незадължителен обект с настройки, които иначе се вземат от предпочитанията на приложението, например { splineSegments: 64, textToPolylines: true }. Поддържаните опции са: splineTolerance, splineSegments, ellipseSegments, splinesToLineSegments, textToPolylines, textSplineToLineOrArc, multilineTextToSimpleText и circlesToPolylines.

var pl = addPolyline([[0,0], [100,0,1], [100,50], [0,50]], true);
explode(pl);                     // три линии и една дъга

stretch

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

Разтяга всички обекти в правоъгълната област, определена от два ъгъла, с даденото отместване. Обектите, които лежат изцяло в областта, се преместват, а обектите, които пресичат границата на областта, се разтягат (преместват се само крайните точки в областта). Областта може да бъде зададена и като RBox или като затворена форма RPolyline. Ако в чертежа има избрани обекти, се разтягат само избраните обекти.

// правоъгълник от линии:
addLine(0,0, 100,0);
addLine(100,0, 100,50);
addLine(100,50, 0,50);
addLine(0,50, 0,0);

// разширяване на правоъгълника с 50 единици чрез разтягане на дясната му страна:
stretch([80,-10], [120,60], [50,0]);

deleteEntity

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

Изтрива дадения обект от чертежа.

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

deleteEntity(l1);                // чрез обекта
deleteEntity(l2.getId());        // чрез ID на обекта
deleteEntity(50,20);             // чрез позиция

paste

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

Поставя съдържанието на документа sourceDocument в интерфейса на документа destination или в текущия чертеж, ако destination е undefined. Поставеното съдържание се премества с offset, мащабира се с scale и се завърта на rotation градуса. Всички аргументи са задължителни:

• flipHorizontal, flipVertical: true за обръщане на съдържанието
• toCurrentLayer: true за поставяне на всички обекти в текущия слой
• overwriteLayers, overwriteBlocks: true за презаписване на съществуващи слоеве или блокове със същото име

// създаване на символ в документ извън екрана:
var symbol = createDocument();
startTransaction(symbol);
addCircle(0,0, 10);
addLine(-10,0, 10,0);
addLine(0,-10, 0,10);
endTransaction();

// поставяне три пъти в текущия чертеж:
for (var i=0; i<3; i++) {
    paste(symbol, undefined, [i*50, 0], 1+i*0.5, i*15, false, false, false, false, false);
}

Транзакции

startTransaction и endTransaction

startTransaction()
startTransaction(document)
endTransaction()

По подразбиране всяко извикване на Simple API се прилага към чертежа незабавно и може да бъде отменено поотделно. Между startTransaction() и endTransaction() всички промени се събират и се прилагат заедно при извикването на endTransaction. Това има две предимства:

• Много по-бързо е при добавяне на много обекти.
• Всички промени могат да бъдат отменени с една-единствена стъпка.

Ако на startTransaction се подаде документ (RDocument) или интерфейс на документ (RDocumentInterface), всички промени се прилагат към този документ вместо към текущия чертеж. Това е полезно за създаване на чертежи във фонов режим, например за да се експортират във файл (вижте createDocumentInterface).

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

Когато работите с транзакции, имайте предвид следното:

• В рамките на транзакцията промените все още не са част от чертежа. Функциите за промяна като trim или round не могат да се отнасят към обекти, добавени в същата транзакция.
• Обектите, върнати от функциите за създаване в рамките на транзакция, нямат валидно ID, дори и след endTransaction. За да промените такива обекти по-късно, посочете ги чрез позиция.
• Всички обекти, добавени в рамките на транзакция, се поставят в слоя, който е текущ при извикването на endTransaction. Задайте текущия слой преди започване на транзакцията и използвайте отделни транзакции за различните слоеве.

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

// посочване на новите линии чрез позиция, за да се закръгли ъгълът:
round([50,0], [100,25], 10);

getTransactionDocument и getTransactionDocumentInterface

getTransactionDocument()
getTransactionDocumentInterface()

Връщат документа или интерфейса на документа, към който се прилага текущата транзакция. Извън транзакции се връщат текущият документ и интерфейсът на документа.

var doc = createDocument();
startTransaction(doc);
addLine(0,0, 10,0);
getTransactionDocument() === doc;    // връща true
endTransaction();

getOperation

getOperation()

Връща операцията (RAddObjectsOperation) на текущата транзакция. Извън транзакция се връща нова операция, която трябва да бъде приложена изрично. Това е предназначено за напреднала употреба, например за комбиниране на извиквания на Simple API с пълния 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();

Изглед

autoZoom

autoZoom()

Мащабира текущия изглед така, че целият чертеж да бъде видим.

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)

Мащабира изгледа до дадения обект, форма или правоъгълна област. margin е полето около областта в пиксели (по подразбиране 10).

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

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

Документи и приложение

getMainWindow

getMainWindow()

Връща прозореца на приложението QCAD (RMainWindowQt).

getMainWindow().windowTitle;

getDocumentInterface

getDocumentInterface()

Връща интерфейса на документа (RDocumentInterface) на текущия чертеж. Интерфейсът на документа свързва документа с неговите изгледи и предоставя функции за импортиране и експортиране на файлове, прилагане на операции, отмяна и повторение.

addLine(0,0, 100,0);
getDocumentInterface().undo();       // премахва линията отново

getDocument

getDocument()

Връща текущия документ (RDocument). Документът съдържа всички обекти, слоеве, блокове и т.н. на чертежа и предоставя функции за тяхното извличане.

addLine(0,0, 100,0);
addCircle(0,0, 10);
getDocument().queryAllEntities().length;     // брой на обектите в чертежа

getGraphicsView

getGraphicsView()

Връща текущия или последния активен изглед (RGraphicsView) на текущия чертеж.

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

createDocument

createDocument()

Създава нов празен документ в паметта, който не се показва в прозорец. Такъв документ извън екрана може да бъде запълнен с помощта на транзакция и след това поставен в чертеж (вижте paste).

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

doc.queryAllEntities().length;       // връща 2

createDocumentInterface

createDocumentInterface()

Създава нов празен документ в паметта заедно с интерфейс на документа. Интерфейсът на документа може да се използва за импортиране или експортиране на файлове.

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

disableInput()
enableInput()
isInputEnabled()

disableInput деактивира прозореца на приложението QCAD, за да предотврати въвеждане от потребителя, например по време на продължителни операции или анимации. enableInput отново активира прозореца на приложението, а isInputEnabled връща true, ако в момента въвеждането от потребителя е разрешено. Винаги се уверявайте, че въвеждането е разрешено отново в края на вашия скрипт.

update

update()

Обработва чакащите събития, така че потребителският интерфейс да се обновява по време на продължителни операции. Въвеждането от потребителя трябва да бъде деактивирано с disableInput преди извикването на update.

sleep

sleep(milliseconds)

Спира изпълнението на скрипта за даденото време в милисекунди, като същевременно поддържа потребителския интерфейс актуален. Въвеждането от потребителя трябва да бъде деактивирано с disableInput преди извикването на sleep.

Следващият пример използва disableInput, sleep и enableInput, за да покаже проста анимация:

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)

Показва предупредително съобщение. В Скрипт Shell предупрежденията се показват в хронологията на командите. В противен случай предупрежденията се извеждат в конзолата.

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

Въвеждане от потребителя

Следващите функции показват прост диалогов прозорец, за да поискат стойност от потребителя. Ако потребителят откаже диалоговия прозорец, се връща undefined.

getInt

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

Иска от потребителя цяло число. value е началната стойност (по подразбиране 0), step е стъпката на числовото поле със стрелки (по подразбиране 1), min и max са разрешеният диапазон.

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)

Иска от потребителя число. value е началната стойност (по подразбиране 0), decimals е броят на показваните десетични знаци (по подразбиране 1), min и max са разрешеният диапазон.

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

getText

getText(title, prompt, text)

Иска от потребителя текст. text е началният текст (по подразбиране празен).

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

getItem

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

Позволява на потребителя да избере елемент от падащ списък. items е низ с всички елементи, разделени със separator (по подразбиране ","). index е индексът на първоначално избрания елемент (по подразбиране 0). Връща избрания елемент или undefined, ако диалоговият прозорец е отказан.

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

Пример: фланец

Този пример комбинира няколко функции на Simple API, за да начертае фланец с окръжност на центровете на отворите, отвори за болтове в отделен слой и правоъгълен изрез със закръглени ъгли:

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

// контур:
setCurrentLayer("0");
addCircle(0,0, 100);

// окръжност на центровете на отворите и осови линии:
setCurrentLayer("Center Lines");
addCircle(0,0, 75);
addLine(-110,0, 110,0);
addLine(0,-110, 0,110);

// отвори за болтове, добавени в една транзакция:
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();

// квадратен изрез със закръглени ъгли в центъра:
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();

Линиите на изреза се добавят без транзакция, така че да могат да бъдат подадени директно на round. Отворите за болтове се добавят в транзакция, което е по-бързо и позволява отменянето им с една стъпка.