A Simple API

Introdução

A Simple API do QCAD é um pequeno conjunto de funções globais de script que simplificam tarefas comuns, como adicionar entidades a um desenho, consultar entidades e modificá-las (mover, aparar, arredondar cantos, criar paralelas com afastamento, …). Ela foi projetada principalmente para uso no Script Shell e para scripts procedurais curtos que são executados a partir de um arquivo, mas pode ser usada a partir de qualquer script.

A Simple API abrange apenas uma pequena parte da API completa do QCAD. Como ela própria é escrita em ECMAScript (JavaScript), é também um bom ponto de partida para aprender como funciona a API subjacente do QCAD. O código-fonte pode ser encontrado nos arquivos scripts/simple.js e scripts/simple_*.js do código-fonte do QCAD.

Usar a Simple API

No Script Shell (Miscelânea > Desenvolvimento > Script Shell) e em scripts iniciados com Miscelânea > Desenvolvimento > Executar script, todas as funções da Simple API estão disponíveis diretamente. Digite, por exemplo:

addLine(0,0, 100,100);

Nos seus próprios arquivos de script, por exemplo em ações de script interativas ou ferramentas de linha de comando, inclua primeiro o arquivo simple.js:

include("scripts/simple.js");

addLine(0,0, 100,100);

Todas as funções operam sobre o desenho que está aberto no momento na janela do aplicativo QCAD, a menos que uma transação seja usada para redirecioná-las para outro documento (veja Transações).

Todos os exemplos desta página podem ser colados no Script Shell de um desenho vazio. Cada exemplo cria as entidades de que precisa. Use Ver > Zoom automático ou a função autoZoom() para ver o resultado.

Convenções

Coordenadas

As posições podem ser passadas de três maneiras diferentes:

• Como dois números separados: addLine(0,0, 100,100)
• Como um array de dois números: addLine([0,0], [100,100])
• Como objeto vetor: addLine(new RVector(0,0), new RVector(100,100))

Os ângulos são sempre dados em graus, exceto os parâmetros inicial e final de elipses, que são dados em radianos.

Referências a entidades

As funções que trabalham com uma entidade existente aceitam a entidade de várias formas:

• Um ID de entidade (número), por exemplo 1234.
• Um objeto de entidade conforme retornado pelas funções de criação, por exemplo o valor de retorno de addLine(...).
• Uma posição no desenho ([x,y] ou RVector): é usada a entidade mais próxima da posição dada.
• Uma forma (por exemplo new RLine(0,0, 100,0)): a operação é aplicada apenas à forma, o desenho não é alterado.

var l = addLine(0,0, 100,0);
move(l, [0,10]);              // por objeto de entidade
move(l.getId(), [0,10]);      // por ID de entidade
move([50,20], [0,10]);        // por posição: a entidade mais próxima de 50,20

Posições de clique

Algumas operações dependem de onde uma entidade é clicada ao usar a ferramenta equivalente de forma interativa. Ao aparar, a parte da entidade na posição de clique é mantida; ao arredondar e chanfrar cantos, são arredondadas as extremidades das entidades mais próximas das posições de clique; e o afastamento cria paralelas do lado da posição de clique.

Na Simple API, uma posição de clique pode seguir cada referência a entidade. Se uma entidade for referenciada por uma posição, essa posição também serve como posição de clique. Se nenhuma posição de clique for dada, é usado o ponto médio da entidade:

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

// aparar line até limit, mantendo a parte da linha em 10,0:
trim(line, [10,0], limit);

Valores de retorno

• As funções de criação retornam a entidade adicionada. A entidade pode ser passada a outras funções ou consultada para obter informações (por exemplo getId(), getLength() ou getStartPoint()).
• As transformações (move, rotate, scale, mirror, lengthen, reverse) retornam a entidade modificada.
• As outras funções de modificação (trim, round, bevel, offset, breakOut, autoTrim, divide, explode, stretch) retornam a transação que foi aplicada ao desenho ou undefined se a operação falhou.
• Se forem passadas formas em vez de entidades, as transformações modificam as formas dadas e todas as outras funções retornam as formas resultantes como um array.

As operações que falham não geram um erro. Em vez disso, é exibido um aviso no Script Shell, por exemplo «Entidade não pode ser aparada.».

Criar entidades

addPoint

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

Adiciona uma entidade de ponto na posição dada.

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

addLine

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

Adiciona uma linha do ponto inicial ao ponto final.

// um triângulo:
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])

Adiciona uma linha infinita (linha de construção) que passa pelo ponto base x,y com a direção dx,dy. A direção é dada em relação ao ponto base.

// linhas de construção horizontal e a 45 graus passando por 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)

Adiciona um arco com o centro, o raio, o ângulo inicial e o ângulo final dados. Os ângulos são em graus. Os arcos vão no sentido anti-horário do ângulo inicial ao ângulo final, a menos que reversed seja true (opcional, o padrão é false).

// quarto de arco de 0 a 90 graus:
addArc(0,0, 50, 0, 90);

// arco no sentido horário de 0 a 90 graus (os outros três quartos):
addArc([0,0], 40, 0, 90, true);

addCircle

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

Adiciona um círculo com o centro e o raio dados.

// círculos concêntricos:
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)

Adiciona uma elipse ou um arco elíptico. mx,my é o ponto final do eixo maior, em relação ao centro. ratio é a razão entre o eixo menor e o eixo maior. startParam e endParam são os parâmetros da elipse em radianos onde a elipse começa e termina. Use 0 e 2*Math.PI para uma elipse completa.

// elipse completa com raio maior de 50 e raio menor de 25:
addEllipse(0,0, 50,0, 0.5, 0, 2*Math.PI, false);

// metade superior de uma elipse girada:
addEllipse([0,0], [30,30], 0.3, 0, Math.PI, false);

addPolyline

addPolyline(points, closed, relative)

Adiciona uma polilinha que passa pelos vértices dados. points é um array de vértices, cada um dado como [x, y], [x, y, bulge] ou [x, y, bulge, relative]. Em vez de x, y, pode ser usado um RVector.

• bulge (bojo) define a forma do segmento que começa neste vértice: 0 (padrão) para um segmento reto, 1 para um semicírculo no sentido anti-horário, -1 para um semicírculo no sentido horário. Outros valores criam segmentos de arco intermediários (o bojo é a tangente de um quarto do ângulo do arco).
• relative: true se as coordenadas deste vértice forem relativas ao vértice anterior.
• closed: true para fechar a polilinha (o padrão é false).
• relative: true para tratar as coordenadas de todos os vértices como relativas ao vértice anterior (o padrão é false).

// retângulo fechado:
addPolyline([[0,0], [100,0], [100,50], [0,50]], true);

// forma de rasgo oblongo com dois semicírculos:
addPolyline([[0,60], [80,60,1], [80,80], [0,80,1]], true);

// linha em zigue-zague com coordenadas relativas:
addPolyline([[0,100], [10,10], [10,-10], [10,10], [10,-10]], false, true);

addSpline

addSpline(fitPoints, closed)

Adiciona uma spline que passa pelos pontos de ajuste dados. fitPoints é um array de arrays [x, y] ou de objetos RVector. Se closed for true, a spline é fechada (periódica).

// spline aberta:
addSpline([[0,0], [30,40], [60,0], [90,40]], false);

// spline fechada:
addSpline([[0,60], [40,80], [80,60], [40,100]], true);

O tutorial Executar scripts a partir de um arquivo mostra outro exemplo que traça uma curva de Lissajous como spline.

addSimpleText

addSimpleText(text, x, y)
addSimpleText(text, x, y, height, angle, font, vAlign, hAlign, bold, italic)
addSimpleText(text, [x, y], height, angle, font, vAlign, hAlign, bold, italic)

Adiciona um texto de linha única na posição dada. Todos os argumentos após a posição são opcionais:

• height: altura do texto (padrão 1)
• angle: ângulo do texto em graus (padrão 0)
• font: nome da fonte (padrão "Standard")
• vAlign: alinhamento vertical: RS.VAlignTop (padrão), RS.VAlignMiddle, RS.VAlignBase ou RS.VAlignBottom
• hAlign: alinhamento horizontal: RS.HAlignLeft (padrão), RS.HAlignCenter ou RS.HAlignRight
• bold, italic: true para texto em negrito ou itálico (somente fontes 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])

Adiciona uma área de preenchimento sólido com três ou quatro vértices. Observe que os vértices de um sólido de quatro lados são dados em ordem de zigue-zague: primeiro vértice, segundo vértice, depois o vértice oposto ao segundo e o vértice oposto ao primeiro. Para criar um triângulo, passe o terceiro vértice duas vezes.

// quadrado preenchido:
addSolid(0,0, 50,0, 0,50, 50,50);

// triângulo preenchido:
addSolid([60,0], [110,0], [85,50], [85,50]);

Adicionar formas, entidades e objetos

As funções a seguir adicionam ao desenho objetos que foram criados com a API completa do QCAD. Elas são úteis quando as funções de criação especializadas acima não cobrem um determinado caso.

addShape

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

Adiciona a forma dada (RLine, RArc, RCircle, REllipse, RPolyline, RSpline, RPoint, …) como nova entidade na camada atual. Opcionalmente, podem ser dados uma cor (RColor), um tipo de linha (nome ou ID) e uma espessura de linha (por exemplo RLineweight.Weight050). Por padrão, são usados a cor atual, o tipo de linha ByLayer e a espessura de linha 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)

Adiciona todas as formas do array dado como novas entidades.

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)

Adiciona a entidade dada (REntity) ao desenho. Se nenhuma cor for dada, é usada a cor atual.

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)

Adiciona qualquer objeto (entidade, camada, bloco, …) ao desenho e retorna o objeto adicionado.

// adicionar um bloco chamado "Marker" com uma cruz dentro:
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);

// inserir o bloco duas vezes:
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)

Exclui o objeto dado do desenho. Para excluir entidades, a função deleteEntity geralmente é mais prática.

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

Camadas e atributos

addLayer

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

Adiciona uma nova camada com o nome dado. Opcionalmente, podem ser dados o nome da cor (padrão "white", que é exibida em preto sobre um fundo branco), o nome do tipo de linha (padrão "CONTINUOUS") e a espessura de linha (padrão RLineweight.Weight000). Retorna a nova camada ou undefined se já existir uma camada com o nome dado.

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

hasLayer

hasLayer(name)

Retorna true se existir no desenho uma camada com o nome dado.

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

setCurrentLayer

setCurrentLayer(name)

Define a camada atual. Todas as entidades adicionadas posteriormente são colocadas nesta camada.

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

setCurrentColor

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

Define a cor das entidades adicionadas posteriormente. A cor pode ser dada como objeto RColor ou como valores de vermelho, verde e azul (0-255). Use new RColor(RColor.ByLayer) para redefinir a cor para «Pela camada».

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

Consultar entidades

getEntity

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

Retorna a entidade correspondente à referência dada, ou seja, a entidade com o ID dado, o estado atual da entidade dada ou a entidade mais próxima da posição dada. Retorna undefined se nenhuma entidade for encontrada.

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

// circle ainda contém o centro antigo, getEntity retorna o estado atual:
getEntity(circle).getCenter();     // retorna 10,0

// entidade mais próxima de 30,0:
getEntity(30,0).getRadius();       // retorna 20

getShape

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

Retorna a geometria da entidade dada como forma (RLine para uma linha, RArc para um arco, RPolyline para uma polilinha, …). As formas podem ser usadas para cálculos geométricos sem alterar o desenho.

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

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

getClosestEntity

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

Retorna a entidade mais próxima da posição dada. Se range for dado, são consideradas apenas as entidades dentro dessa distância da posição. Retorna undefined se nenhuma entidade for encontrada.

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

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

getEntityShape

getEntityShape(entity, position)

Retorna a forma do objeto de entidade dado. Para entidades complexas compostas de várias formas (referências de bloco, hachuras, cotas, textos), é retornada a forma mais próxima da posição dada. A posição é opcional.

// uma referência de bloco de um bloco com um retângulo:
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)));

// forma da referência de bloco perto de 40,10 (o retângulo):
var s = getEntityShape(getEntity(ref), new RVector(41,10));
s.getLength();                     // retorna 120

getIntersectionPoints

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

Retorna um array com os pontos de interseção das duas entidades ou formas dadas. As entidades podem ser dadas como objetos de entidade, IDs de entidade ou formas. Se limited for false, as entidades são tratadas como se fossem infinitas (linhas prolongadas, arcos como círculos completos). O padrão é true.

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

// marcar as interseções com pequenos círculos:
for (var i=0; i<ips.length; i++) {
    addCircle(ips[i], 2);
}

isPosition e toVector

isPosition(value)
toVector(value)

isPosition retorna true se o valor dado for uma posição (RVector ou array de dois ou três números). toVector converte uma posição dada como array em um RVector. Essas funções são úteis ao escrever suas próprias funções que aceitam posições da mesma forma que a 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]);                 // retorna true
isPosition("abc");                 // retorna false

Modificar entidades

Transformações

move

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

Move a entidade dada pelo deslocamento dado.

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

rotate

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

Gira a entidade dada pelo ângulo dado em graus em torno do centro dado. Se nenhum centro for dado, a entidade é girada em torno da origem 0,0.

// um leque de linhas, girado em torno de 0,0:
for (var a=0; a<360; a+=30) {
    var l = addLine(10,0, 50,0);
    rotate(l, a);
}

// girar um quadrado em torno do seu centro:
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])

Escala a entidade dada pelo fator dado. O ponto de foco (o ponto que permanece no lugar) é, por padrão, a origem 0,0. Fatores diferentes para X e Y podem ser dados como array [sx, sy]. Observe que algumas entidades, como círculos e arcos, não podem ser escaladas com fatores diferentes em X e 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(...))

Espelha a entidade dada em relação ao eixo definido por dois pontos.

var pl = addPolyline([[10,0], [40,0], [40,30]], false);
// espelhar em relação ao eixo Y:
mirror(pl, 0,0, 0,100);

Para manter o original e criar uma cópia espelhada, adicione primeiro uma cópia da entidade:

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

Aparar e alongar

trim

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

Apara a entidade trimEntity até a entidade limitadora limitingEntity. A parte da entidade aparada na posição de clique trimPos é mantida. Se as duas entidades não se cruzarem, a entidade é prolongada até a entidade limitadora. Se houver várias interseções, é usada a mais próxima da posição de clique limitingPos. Se trimBoth for true, as duas entidades são aparadas uma em relação à outra.

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

// manter a parte esquerda, a linha agora termina em 70,0:
trim(line, [10,0], limit);

// prolongar uma linha até um círculo:
var line = addLine(0,0, 50,0);
var circle = addCircle(100,0, 20);

// prolongar até a interseção com o círculo mais próxima de 80,0:
trim(line, [25,0], circle, [80,0]);      // a linha agora termina em 80,0

trimBoth

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

Apara ou prolonga as duas entidades até o seu ponto de interseção. É um atalho para trim com trimBoth definido como true.

// duas linhas que não se tocam são prolongadas para formar um canto em 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)

Alonga a entidade dada pelo valor dado. Valores negativos encurtam a entidade. Por padrão, a entidade é alongada no seu ponto final. Passe true para start para alongá-la no seu ponto inicial ou passe uma posição próxima da extremidade que deve ser alongada.

var line = addLine(0,0, 100,0);
lengthen(line, 20);              // a linha agora termina em 120,0
lengthen(line, true, -10);       // a linha agora começa em 10,0

var arc = addArc(0,50, 30, 0, 90);
lengthen(arc, [30,50], 10);      // alongar o arco no seu ponto inicial

breakOut

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

Rompe o segmento da entidade dada na posição dada. O segmento termina nas interseções mais próximas com outras entidades de cada lado da posição. Se não houver interseção de um lado, o segmento se estende até a extremidade da entidade. Se removeSegment for true (padrão), o segmento é excluído. Caso contrário, ele é mantido como uma entidade separada.

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

// remover a parte da linha entre 30,0 e 70,0:
breakOut(line, [50,0]);

autoTrim

autoTrim(entity, pos)
autoTrim(pos)

O oposto de breakOut: mantém apenas o segmento da entidade dada na posição dada e remove o restante. O segmento termina nas interseções mais próximas com outras entidades de cada lado da posição.

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

// manter apenas a parte entre 30,0 e 70,0:
autoTrim(line, [50,0]);

divide

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

Divide a entidade dada na posição dada. Uma entidade aberta (linha, arco, polilinha aberta, …) é dividida em duas partes com uma posição ou em três partes com duas posições. Entidades fechadas (círculos, elipses completas, polilinhas fechadas) exigem duas posições e são divididas em duas partes.

var line = addLine(0,0, 100,0);
divide(line, [40,0]);            // duas linhas: 0..40 e 40..100

var circle = addCircle(0,50, 20);
divide(circle, [20,50], [-20,50]);   // dois semicírculos

Cantos

round

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

Arredonda o canto entre duas entidades com um arco do raio dado (concordância). As posições de clique indicam quais extremidades das entidades são arredondadas. Se trim for true (padrão), as duas entidades são aparadas até o arco de concordância.

// um retângulo com cantos arredondados:
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);

Os cantos de uma polilinha também podem ser arredondados, passando a mesma polilinha duas vezes com uma posição de clique em cada um dos dois segmentos:

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

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

Chanfra o canto entre duas entidades com uma linha reta (chanfro). distance1 é a distância da linha de chanfro até o canto ao longo da primeira entidade, distance2 ao longo da segunda entidade (o padrão é distance1). Se trim for true (padrão), as duas entidades são aparadas até a linha de chanfro. chamfer é um alias de 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)

Cria paralelas a linhas, arcos e círculos concêntricos ou curvas paralelas (com afastamento) a elipses e outras entidades. number é o número de paralelas a criar (padrão 1). As paralelas são criadas dos dois lados da entidade, a menos que seja dado um lado, seja como posição sidePos junto à entidade ou como side (RS.LeftHand, RS.RightHand ou RS.BothSides). O afastamento de polilinhas e splines está disponível apenas no QCAD Professional.

var line = addLine(0,0, 100,0);
offset(line, 5);                 // uma paralela de cada lado

var line2 = addLine(0,30, 100,30);
offset(line2, 5, 2, RS.LeftHand);    // duas paralelas do lado esquerdo (acima)

var circle = addCircle(50,80, 10);
offset(circle, [50,95], 3, 4);   // quatro círculos concêntricos do lado de fora

reverse

reverse(entity)
reverse(x, y)

Inverte a direção da entidade dada, ou seja, troca o seu ponto inicial pelo ponto final.

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

explode

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

Explode a entidade dada em entidades mais simples: polilinhas em linhas e arcos, referências de bloco em seu conteúdo, textos em linhas e splines, cotas e hachuras em linhas, arcos etc. A entidade original é excluída.

options é um objeto opcional com configurações que, de outra forma, são obtidas das preferências do aplicativo, por exemplo { splineSegments: 64, textToPolylines: true }. As opções suportadas são: splineTolerance, splineSegments, ellipseSegments, splinesToLineSegments, textToPolylines, textSplineToLineOrArc, multilineTextToSimpleText e circlesToPolylines.

var pl = addPolyline([[0,0], [100,0,1], [100,50], [0,50]], true);
explode(pl);                     // três linhas e um arco

stretch

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

Estica todas as entidades na área retangular definida por dois cantos pelo deslocamento dado. As entidades que estão completamente dentro da área são movidas; as entidades que cruzam o limite da área são esticadas (apenas os pontos finais dentro da área são movidos). A área também pode ser dada como RBox ou como forma RPolyline fechada. Se houver entidades selecionadas no desenho, apenas as entidades selecionadas são esticadas.

// um retângulo feito de linhas:
addLine(0,0, 100,0);
addLine(100,0, 100,50);
addLine(100,50, 0,50);
addLine(0,50, 0,0);

// tornar o retângulo 50 unidades mais largo esticando o seu lado direito:
stretch([80,-10], [120,60], [50,0]);

deleteEntity

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

Exclui a entidade dada do desenho.

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

deleteEntity(l1);                // por entidade
deleteEntity(l2.getId());        // por ID de entidade
deleteEntity(50,20);             // por posição

paste

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

Cola o conteúdo do documento sourceDocument na interface de documento destination ou no desenho atual se destination for undefined. O conteúdo colado é movido por offset, escalado por scale e girado por rotation graus. Todos os argumentos são obrigatórios:

• flipHorizontal, flipVertical: true para espelhar o conteúdo
• toCurrentLayer: true para colar todas as entidades na camada atual
• overwriteLayers, overwriteBlocks: true para sobrescrever camadas ou blocos existentes com o mesmo nome

// criar um símbolo em um documento fora da tela:
var symbol = createDocument();
startTransaction(symbol);
addCircle(0,0, 10);
addLine(-10,0, 10,0);
addLine(0,-10, 0,10);
endTransaction();

// colá-lo três vezes no desenho atual:
for (var i=0; i<3; i++) {
    paste(symbol, undefined, [i*50, 0], 1+i*0.5, i*15, false, false, false, false, false);
}

Transações

startTransaction e endTransaction

startTransaction()
startTransaction(document)
endTransaction()

Por padrão, cada chamada da Simple API é aplicada imediatamente ao desenho e pode ser desfeita individualmente. Entre startTransaction() e endTransaction(), todas as alterações são reunidas e aplicadas em conjunto quando endTransaction é chamado. Isso tem duas vantagens:

• É muito mais rápido ao adicionar muitas entidades.
• Todas as alterações podem ser desfeitas em um único passo.

Se um documento (RDocument) ou uma interface de documento (RDocumentInterface) for passado para startTransaction, todas as alterações são aplicadas a esse documento em vez do desenho atual. Isso é útil para criar desenhos em segundo plano, por exemplo para exportá-los para um arquivo (veja createDocumentInterface).

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

Observe o seguinte ao trabalhar com transações:

• Dentro de uma transação, as alterações ainda não fazem parte do desenho. Funções de modificação como trim ou round não podem se referir a entidades adicionadas na mesma transação.
• As entidades retornadas por funções de criação dentro de uma transação não têm um ID válido, nem mesmo após endTransaction. Para modificar essas entidades mais tarde, refira-se a elas pela posição.
• Todas as entidades adicionadas dentro de uma transação são colocadas na camada que é a atual quando endTransaction é chamado. Defina a camada atual antes de iniciar a transação e use transações separadas para camadas diferentes.

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

// referir-se às novas linhas pela posição para arredondar o canto:
round([50,0], [100,25], 10);

getTransactionDocument e getTransactionDocumentInterface

getTransactionDocument()
getTransactionDocumentInterface()

Retornam o documento ou a interface de documento ao qual a transação atual se aplica. Fora de transações, são retornados o documento e a interface de documento atuais.

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

getOperation

getOperation()

Retorna a operação (RAddObjectsOperation) da transação atual. Fora de uma transação, é retornada uma nova operação que precisa ser aplicada explicitamente. Isso se destina a uso avançado, por exemplo para combinar chamadas da Simple API com a API completa do 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();

Vista

autoZoom

autoZoom()

Aplica zoom à vista atual de modo que todo o desenho fique visível.

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)

Aplica zoom à entidade, forma ou área retangular dada. margin é a margem em torno da área em pixels (padrão 10).

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

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

Documentos e aplicativo

getMainWindow

getMainWindow()

Retorna a janela do aplicativo QCAD (RMainWindowQt).

getMainWindow().windowTitle;

getDocumentInterface

getDocumentInterface()

Retorna a interface de documento (RDocumentInterface) do desenho atual. A interface de documento conecta um documento às suas vistas e fornece funções para importar e exportar arquivos, aplicar operações, desfazer e refazer.

addLine(0,0, 100,0);
getDocumentInterface().undo();       // remove a linha novamente

getDocument

getDocument()

Retorna o documento atual (RDocument). O documento contém todas as entidades, camadas, blocos etc. de um desenho e fornece funções para consultá-los.

addLine(0,0, 100,0);
addCircle(0,0, 10);
getDocument().queryAllEntities().length;     // número de entidades no desenho

getGraphicsView

getGraphicsView()

Retorna a vista atual ou a última vista ativa (RGraphicsView) do desenho atual.

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

createDocument

createDocument()

Cria na memória um novo documento vazio que não é exibido em uma janela. Esse documento fora da tela pode ser preenchido usando uma transação e depois colado em um desenho (veja paste).

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

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

createDocumentInterface

createDocumentInterface()

Cria na memória um novo documento vazio juntamente com uma interface de documento. A interface de documento pode ser usada para importar ou exportar arquivos.

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

disableInput()
enableInput()
isInputEnabled()

disableInput desativa a janela do aplicativo QCAD para impedir a entrada do usuário, por exemplo durante operações longas ou animações. enableInput ativa novamente a janela do aplicativo e isInputEnabled retorna true se a entrada do usuário estiver ativada no momento. Certifique-se sempre de reativar a entrada no final do seu script.

update

update()

Processa os eventos pendentes para que a interface do usuário seja atualizada durante operações longas. A entrada do usuário deve ser desativada com disableInput antes de chamar update.

sleep

sleep(milliseconds)

Pausa o script pelo tempo dado em milissegundos, mantendo a interface do usuário atualizada. A entrada do usuário deve ser desativada com disableInput antes de chamar sleep.

O exemplo a seguir usa disableInput, sleep e enableInput para mostrar uma animação simples:

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)

Exibe uma mensagem de aviso. No Script Shell, os avisos são exibidos no histórico de comandos. Caso contrário, os avisos são impressos no console.

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

Entrada do usuário

As funções a seguir exibem uma caixa de diálogo simples para pedir um valor ao usuário. Se o usuário cancelar a caixa de diálogo, é retornado undefined.

getInt

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

Pede ao usuário um número inteiro. value é o valor inicial (padrão 0), step o incremento da caixa numérica (padrão 1), min e max o intervalo permitido.

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)

Pede ao usuário um número. value é o valor inicial (padrão 0), decimals o número de casas decimais exibidas (padrão 1), min e max o intervalo permitido.

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

getText

getText(title, prompt, text)

Pede ao usuário um texto. text é o texto inicial (padrão vazio).

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

getItem

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

Permite que o usuário escolha um item de uma lista suspensa. items é uma string com todos os itens separados por separator (padrão ","). index é o índice do item selecionado inicialmente (padrão 0). Retorna o item escolhido ou undefined se a caixa de diálogo for cancelada.

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

Exemplo: um flange

Este exemplo combina várias funções da Simple API para desenhar um flange com um círculo de furação, furos para parafusos em uma camada separada e um recorte retangular com cantos arredondados:

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

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

// círculo de furação e linhas de centro:
setCurrentLayer("Center Lines");
addCircle(0,0, 75);
addLine(-110,0, 110,0);
addLine(0,-110, 0,110);

// furos para parafusos, adicionados em uma única transação:
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();

// recorte quadrado com cantos arredondados no centro:
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();

As linhas do recorte são adicionadas sem transação, para que possam ser passadas diretamente para round. Os furos para parafusos são adicionados em uma transação, o que é mais rápido e permite desfazê-los em um único passo.