Simple API

Введение

Simple API QCAD — это небольшой набор глобальных скриптовых функций, которые упрощают типичные задачи, такие как добавление объектов в чертёж, опрос объектов и их изменение (перемещение, усечение, скругление, смещение, …). Он предназначен в основном для использования в оболочке сценария и для коротких процедурных скриптов, которые запускаются из файла, но его можно использовать в любом скрипте.

Simple API охватывает лишь небольшую часть полного API QCAD. Поскольку он сам написан на ECMAScript (JavaScript), он также является хорошей отправной точкой для изучения того, как работает базовый API QCAD. Исходный код находится в файлах scripts/simple.js и scripts/simple_*.js исходного кода QCAD.

Использование Simple API

В оболочке сценария (Разное > Разработка > Оболочка сценария) и в скриптах, запущенных с помощью Разное > Разработка > Запустить сценарий, все функции Simple API доступны напрямую. Введите, например:

addLine(0,0, 100,100);

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

include("scripts/simple.js");

addLine(0,0, 100,100);

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

Все примеры на этой странице можно вставить в оболочку сценария пустого чертежа. Каждый пример создаёт необходимые ему объекты. Используйте Просмотр > Автоматическое масштабирование или функцию autoZoom(), чтобы увидеть результат.

Соглашения

Координаты

Позиции можно передавать тремя различными способами:

• В виде двух отдельных чисел: addLine(0,0, 100,100)
• В виде массива из двух чисел: addLine([0,0], [100,100])
• В виде объекта-вектора: addLine(new RVector(0,0), new RVector(100,100))

Углы всегда задаются в градусах, за исключением начального и конечного параметров эллипсов, которые задаются в радианах.

Ссылки на объекты

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

• Идентификатор объекта (число), например 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]);      // по идентификатору объекта
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, если операция не удалась.
• Если вместо объектов передаются фигуры, преобразования изменяют переданные фигуры, а все остальные функции возвращают полученные фигуры в виде массива.

Неудачные операции не вызывают ошибку. Вместо этого в оболочке сценария выводится предупреждение, например «Объект не может быть усечён.».

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

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

Добавляет область сплошной заливки с тремя или четырьмя углами. Обратите внимание, что углы четырёхугольной заливки задаются в зигзагообразном порядке: первый угол, второй угол, затем угол напротив второго угла и угол напротив первого угла. Чтобы создать треугольник, передайте третий угол дважды.

// залитый квадрат:
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), тип линии (имя или идентификатор) и вес линии (например 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])

Возвращает объект для указанной ссылки на объект, т. е. объект с указанным идентификатором, текущее состояние указанного объекта или объект, ближайший к указанной позиции. Возвращает 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)

Возвращает массив точек пересечения двух указанных объектов или фигур. Объекты можно указать как сами объекты, их идентификаторы или фигуры. Если 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());        // по идентификатору объекта
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, не могут ссылаться на объекты, добавленные в той же транзакции.
• Объекты, возвращаемые функциями создания внутри транзакции, не имеют действительного идентификатора, даже после 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()

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

sleep

sleep(milliseconds)

Приостанавливает скрипт на указанное время в миллисекундах, продолжая при этом обновлять пользовательский интерфейс. Перед вызовом sleep ввод пользователя должен быть заблокирован с помощью disableInput.

В следующем примере 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)

Показывает предупреждающее сообщение. В оболочке сценария предупреждения отображаются в истории команд. В остальных случаях предупреждения выводятся в консоль.

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. Отверстия под болты добавляются в транзакции, что быстрее и позволяет отменить их за один шаг.