L'API Simple

Introduction

L’API Simple de QCAD est un petit ensemble de fonctions de script globales qui simplifient les tâches courantes telles que l’ajout d’entités à un dessin, l’interrogation d’entités et leur modification (déplacer, ajuster, arrondir, décaler, …). Elle est principalement conçue pour être utilisée dans le Script Shell et pour de courts scripts procéduraux exécutés depuis un fichier, mais elle peut être utilisée depuis n’importe quel script.

L’API Simple ne couvre qu’une petite partie de l’API complète de QCAD. Comme elle est elle-même écrite en ECMAScript (JavaScript), elle constitue également un bon point de départ pour apprendre le fonctionnement de l’API de QCAD sous-jacente. Le code source se trouve dans les fichiers scripts/simple.js et scripts/simple_*.js du code source de QCAD.

Utiliser l’API Simple

Dans le Script Shell (Divers > Développement > Script Shell) et dans les scripts lancés avec Divers > Développement > Lancer le script, toutes les fonctions de l’API Simple sont directement disponibles. Tapez par exemple :

addLine(0,0, 100,100);

Dans vos propres fichiers de script, par exemple dans des actions de script interactives ou des outils en ligne de commande, incluez d’abord le fichier simple.js :

include("scripts/simple.js");

addLine(0,0, 100,100);

Toutes les fonctions agissent sur le dessin actuellement ouvert dans la fenêtre de l’application QCAD, à moins qu’une transaction ne soit utilisée pour les rediriger vers un autre document (voir Transactions).

Tous les exemples de cette page peuvent être collés dans le Script Shell d’un dessin vide. Chaque exemple crée les entités dont il a besoin. Utilisez Affichage > Zoom automatique ou la fonction autoZoom() pour voir le résultat.

Conventions

Coordonnées

Les positions peuvent être transmises de trois manières différentes :

• Sous forme de deux nombres distincts : addLine(0,0, 100,100)
• Sous forme de tableau de deux nombres : addLine([0,0], [100,100])
• Sous forme d’objet vecteur : addLine(new RVector(0,0), new RVector(100,100))

Les angles sont toujours indiqués en degrés, sauf les paramètres de début et de fin des ellipses, qui sont indiqués en radians.

Références d’entités

Les fonctions qui agissent sur une entité existante acceptent l’entité sous différentes formes :

• Un ID d’entité (nombre), par exemple 1234.
• Un objet entité tel que renvoyé par les fonctions de création, par exemple la valeur de retour de addLine(...).
• Une position dans le dessin ([x,y] ou RVector) : l’entité la plus proche de la position donnée est utilisée.
• Une forme (par exemple new RLine(0,0, 100,0)) : l’opération est appliquée uniquement à la forme, le dessin n’est pas modifié.

var l = addLine(0,0, 100,0);
move(l, [0,10]);              // par objet entité
move(l.getId(), [0,10]);      // par ID d'entité
move([50,20], [0,10]);        // par position : l'entité la plus proche de 50,20

Positions de clic

Certaines opérations dépendent de l’endroit où l’on clique sur une entité lorsque l’outil équivalent est utilisé de manière interactive. L’ajustement conserve la partie de l’entité située à la position de clic, l’arrondi et le chanfrein s’appliquent aux extrémités des entités les plus proches des positions de clic, et le décalage crée des parallèles du côté de la position de clic.

Dans l’API Simple, une position de clic peut suivre chaque référence d’entité. Si une entité est référencée par une position, cette position sert également de position de clic. Si aucune position de clic n’est donnée, le point milieu de l’entité est utilisé :

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

// ajuster line à limit, conserver la partie de line située à 10,0 :
trim(line, [10,0], limit);

Valeurs de retour

• Les fonctions de création renvoient l’entité ajoutée. L’entité peut être transmise à d’autres fonctions ou interrogée pour obtenir des informations (par exemple getId(), getLength() ou getStartPoint()).
• Les transformations (move, rotate, scale, mirror, lengthen, reverse) renvoient l’entité modifiée.
• Les autres fonctions de modification (trim, round, bevel, offset, breakOut, autoTrim, divide, explode, stretch) renvoient la transaction qui a été appliquée au dessin, ou undefined si l’opération a échoué.
• Si des formes sont transmises au lieu d’entités, les transformations modifient les formes données et toutes les autres fonctions renvoient les formes résultantes sous forme de tableau.

Les opérations qui échouent ne déclenchent pas d’erreur. À la place, un avertissement est affiché dans le Script Shell, par exemple « Entité ne peut pas être ajuster. ».

Créer des entités

addPoint

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

Ajoute une entité point à la position donnée.

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

addLine

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

Ajoute une ligne du point de départ au point d’arrivée.

// un triangle :
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])

Ajoute une ligne infinie (ligne de construction) passant par le point de base x,y avec la direction dx,dy. La direction est donnée par rapport au point de base.

// lignes de construction horizontale et à 45 degrés passant par 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)

Ajoute un arc avec le centre, le rayon, l’angle de départ et l’angle d’arrivée donnés. Les angles sont en degrés. Les arcs vont dans le sens inverse des aiguilles d’une montre de l’angle de départ à l’angle d’arrivée, sauf si reversed vaut true (facultatif, la valeur par défaut est false).

// quart d'arc de 0 à 90 degrés :
addArc(0,0, 50, 0, 90);

// arc dans le sens des aiguilles d'une montre de 0 à 90 degrés (les trois autres quarts) :
addArc([0,0], 40, 0, 90, true);

addCircle

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

Ajoute un cercle avec le centre et le rayon donnés.

// cercles concentriques :
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)

Ajoute une ellipse ou un arc elliptique. mx,my est l’extrémité du grand axe, par rapport au centre. ratio est le rapport entre le petit axe et le grand axe. startParam et endParam sont les paramètres de l’ellipse en radians où l’ellipse commence et se termine. Utilisez 0 et 2*Math.PI pour une ellipse complète.

// ellipse complète avec un grand rayon de 50 et un petit rayon de 25 :
addEllipse(0,0, 50,0, 0.5, 0, 2*Math.PI, false);

// moitié supérieure d'une ellipse pivotée :
addEllipse([0,0], [30,30], 0.3, 0, Math.PI, false);

addPolyline

addPolyline(points, closed, relative)

Ajoute une polyligne passant par les sommets donnés. points est un tableau de sommets, chacun donné sous la forme [x, y], [x, y, bulge] ou [x, y, bulge, relative]. Au lieu de x, y, un RVector peut être utilisé.

• bulge définit la forme du segment qui commence à ce sommet : 0 (par défaut) pour un segment droit, 1 pour un demi-cercle dans le sens inverse des aiguilles d’une montre, -1 pour un demi-cercle dans le sens des aiguilles d’une montre. Les autres valeurs créent des segments d’arc intermédiaires (le renflement est la tangente du quart de l’angle de l’arc).
• relative : true si les coordonnées de ce sommet sont relatives au sommet précédent.
• closed : true pour fermer la polyligne (la valeur par défaut est false).
• relative : true pour traiter les coordonnées de tous les sommets comme relatives au sommet précédent (la valeur par défaut est false).

// rectangle fermé :
addPolyline([[0,0], [100,0], [100,50], [0,50]], true);

// forme de rainure avec deux demi-cercles :
addPolyline([[0,60], [80,60,1], [80,80], [0,80,1]], true);

// ligne en zigzag avec des coordonnées relatives :
addPolyline([[0,100], [10,10], [10,-10], [10,10], [10,-10]], false, true);

addSpline

addSpline(fitPoints, closed)

Ajoute une spline passant par les points d’ajustement donnés. fitPoints est un tableau de tableaux [x, y] ou d’objets RVector. Si closed vaut true, la spline est fermée (périodique).

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

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

Le tutoriel Exécuter des scripts depuis un fichier présente un autre exemple qui trace une courbe de Lissajous sous forme de 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)

Ajoute un texte d’une seule ligne à la position donnée. Tous les arguments qui suivent la position sont facultatifs :

• height : hauteur du texte (par défaut 1)
• angle : angle du texte en degrés (par défaut 0)
• font : nom de la police (par défaut "Standard")
• vAlign : alignement vertical : RS.VAlignTop (par défaut), RS.VAlignMiddle, RS.VAlignBase ou RS.VAlignBottom
• hAlign : alignement horizontal : RS.HAlignLeft (par défaut), RS.HAlignCenter ou RS.HAlignRight
• bold, italic : true pour un texte en gras ou en italique (polices TrueType uniquement)

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

Ajoute une surface à remplissage uni (solide) à trois ou quatre coins. Notez que les coins d’un solide à quatre côtés sont donnés en zigzag : premier coin, deuxième coin, puis le coin opposé au deuxième coin et le coin opposé au premier coin. Pour créer un triangle, indiquez deux fois le troisième coin.

// carré rempli :
addSolid(0,0, 50,0, 0,50, 50,50);

// triangle rempli :
addSolid([60,0], [110,0], [85,50], [85,50]);

Ajouter des formes, des entités et des objets

Les fonctions suivantes ajoutent au dessin des objets créés avec l’API complète de QCAD. Elles sont utiles lorsque les fonctions de création spécialisées ci-dessus ne couvrent pas un cas particulier.

addShape

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

Ajoute la forme donnée (RLine, RArc, RCircle, REllipse, RPolyline, RSpline, RPoint, …) en tant que nouvelle entité sur le calque courant. Une couleur (RColor), un type de ligne (nom ou ID) et une épaisseur de ligne (par exemple RLineweight.Weight050) peuvent être indiqués en option. Par défaut, la couleur courante, le type de ligne ByLayer et l’épaisseur de ligne ByLayer sont utilisés.

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)

Ajoute toutes les formes du tableau donné en tant que nouvelles entités.

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)

Ajoute l’entité donnée (REntity) au dessin. Si aucune couleur n’est indiquée, la couleur courante est utilisée.

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)

Ajoute n’importe quel objet (entité, calque, bloc, …) au dessin et renvoie l’objet ajouté.

// ajouter un bloc nommé "Marker" contenant une croix :
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);

// insérer le bloc deux fois :
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)

Supprime l’objet donné du dessin. Pour supprimer des entités, la fonction deleteEntity est généralement plus pratique.

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

Calques et attributs

addLayer

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

Ajoute un nouveau calque portant le nom donné. Le nom de la couleur (par défaut "white", affiché en noir sur fond blanc), le nom du type de ligne (par défaut "CONTINUOUS") et l’épaisseur de ligne (par défaut RLineweight.Weight000) peuvent être indiqués en option. Renvoie le nouveau calque, ou undefined si un calque portant ce nom existe déjà.

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

hasLayer

hasLayer(name)

Renvoie true si un calque portant le nom donné existe dans le dessin.

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

setCurrentLayer

setCurrentLayer(name)

Définit le calque courant. Toutes les entités ajoutées ensuite sont placées sur ce calque.

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

setCurrentColor

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

Définit la couleur des entités ajoutées ensuite. La couleur peut être indiquée sous forme d’objet RColor ou de valeurs rouge, vert, bleu (0-255). Utilisez new RColor(RColor.ByLayer) pour réinitialiser la couleur sur « Par calque ».

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

Interroger des entités

getEntity

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

Renvoie l’entité correspondant à la référence d’entité donnée, c’est-à-dire l’entité ayant l’ID donné, l’état actuel de l’entité donnée ou l’entité la plus proche de la position donnée. Renvoie undefined si aucune entité n’est trouvée.

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

// circle contient toujours l'ancien centre, getEntity renvoie l'état actuel :
getEntity(circle).getCenter();     // renvoie 10,0

// entité la plus proche de 30,0 :
getEntity(30,0).getRadius();       // renvoie 20

getShape

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

Renvoie la géométrie de l’entité donnée sous forme de forme (RLine pour une ligne, RArc pour un arc, RPolyline pour une polyligne, …). Les formes peuvent être utilisées pour des calculs géométriques sans modifier le dessin.

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

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

getClosestEntity

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

Renvoie l’entité la plus proche de la position donnée. Si range est indiqué, seules les entités situées à cette distance de la position ou moins sont prises en compte. Renvoie undefined si aucune entité n’est trouvée.

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

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

getEntityShape

getEntityShape(entity, position)

Renvoie la forme de l’objet entité donné. Pour les entités complexes composées de plusieurs formes (références de bloc, hachures, cotations, textes), la forme la plus proche de la position donnée est renvoyée. La position est facultative.

// une référence de bloc d'un bloc contenant un rectangle :
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)));

// forme de la référence de bloc près de 40,10 (le rectangle) :
var s = getEntityShape(getEntity(ref), new RVector(41,10));
s.getLength();                     // renvoie 120

getIntersectionPoints

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

Renvoie un tableau contenant les points d’intersection des deux entités ou formes données. Les entités peuvent être indiquées sous forme d’objets entité, d’ID d’entité ou de formes. Si limited vaut false, les entités sont traitées comme si elles étaient infinies (lignes prolongées, arcs considérés comme des cercles complets). La valeur par défaut est true.

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

// marquer les intersections par de petits cercles :
for (var i=0; i<ips.length; i++) {
    addCircle(ips[i], 2);
}

isPosition et toVector

isPosition(value)
toVector(value)

isPosition renvoie true si la valeur donnée est une position (RVector ou tableau de deux ou trois nombres). toVector convertit une position donnée sous forme de tableau en RVector. Ces fonctions sont utiles pour écrire vos propres fonctions qui acceptent des positions de la même manière que l’API Simple.

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]);                 // renvoie true
isPosition("abc");                 // renvoie false

Modifier des entités

Transformations

move

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

Déplace l’entité donnée du décalage donné.

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

rotate

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

Fait pivoter l’entité donnée de l’angle donné en degrés autour du centre donné. Si aucun centre n’est indiqué, l’entité pivote autour de l’origine 0,0.

// un éventail de lignes, pivotées autour de 0,0 :
for (var a=0; a<360; a+=30) {
    var l = addLine(10,0, 50,0);
    rotate(l, a);
}

// faire pivoter un carré autour de son centre :
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])

Met à l’échelle l’entité donnée selon le facteur donné. Le point central (le point qui reste en place) est par défaut l’origine 0,0. Des facteurs différents pour X et Y peuvent être indiqués sous forme de tableau [sx, sy]. Notez que certaines entités, comme les cercles et les arcs, ne peuvent pas être mises à l’échelle avec des facteurs différents en X et en 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(...))

Crée la symétrie de l’entité donnée par rapport à l’axe défini par deux points.

var pl = addPolyline([[10,0], [40,0], [40,30]], false);
// symétrie par rapport à l'axe Y :
mirror(pl, 0,0, 0,100);

Pour conserver l’original et créer une copie symétrique, ajoutez d’abord une copie de l’entité :

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

Ajuster et allonger

trim

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

Ajuste l’entité trimEntity à l’entité limitante limitingEntity. La partie de l’entité ajustée située à la position de clic trimPos est conservée. Si les deux entités ne se coupent pas, l’entité est prolongée jusqu’à l’entité limitante. S’il existe plusieurs intersections, celle qui est la plus proche de la position de clic limitingPos est utilisée. Si trimBoth vaut true, les deux entités sont ajustées l’une à l’autre.

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

// conserver la partie gauche, line se termine maintenant à 70,0 :
trim(line, [10,0], limit);

// prolonger une ligne jusqu'à un cercle :
var line = addLine(0,0, 50,0);
var circle = addCircle(100,0, 20);

// prolonger jusqu'à l'intersection avec le cercle la plus proche de 80,0 :
trim(line, [25,0], circle, [80,0]);      // line se termine maintenant à 80,0

trimBoth

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

Ajuste ou prolonge les deux entités jusqu’à leur point d’intersection. C’est un raccourci pour trim avec trimBoth défini sur true.

// deux lignes qui ne se touchent pas sont prolongées pour former un coin en 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)

Allonge l’entité donnée de la valeur donnée. Les valeurs négatives raccourcissent l’entité. Par défaut, l’entité est allongée à son point d’arrivée. Passez true pour start afin de l’allonger plutôt à son point de départ, ou passez une position proche de l’extrémité à allonger.

var line = addLine(0,0, 100,0);
lengthen(line, 20);              // line se termine maintenant à 120,0
lengthen(line, true, -10);       // line commence maintenant à 10,0

var arc = addArc(0,50, 30, 0, 90);
lengthen(arc, [30,50], 10);      // allonger l'arc à son point de départ

breakOut

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

Supprime le segment de l’entité donnée situé à la position donnée. Le segment se termine aux intersections les plus proches avec d’autres entités de part et d’autre de la position. S’il n’y a pas d’intersection d’un côté, le segment s’étend jusqu’à l’extrémité de l’entité. Si removeSegment vaut true (par défaut), le segment est supprimé. Sinon, il est conservé en tant qu’entité distincte.

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

// supprimer la partie de la ligne entre 30,0 et 70,0 :
breakOut(line, [50,0]);

autoTrim

autoTrim(entity, pos)
autoTrim(pos)

L’inverse de breakOut : conserve uniquement le segment de l’entité donnée situé à la position donnée et supprime le reste. Le segment se termine aux intersections les plus proches avec d’autres entités de part et d’autre de la position.

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

// conserver uniquement la partie entre 30,0 et 70,0 :
autoTrim(line, [50,0]);

divide

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

Divise l’entité donnée à la position donnée. Une entité ouverte (ligne, arc, polyligne ouverte, …) est divisée en deux parties à une position ou en trois parties à deux positions. Les entités fermées (cercles, ellipses complètes, polylignes fermées) nécessitent deux positions et sont divisées en deux parties.

var line = addLine(0,0, 100,0);
divide(line, [40,0]);            // deux lignes : 0..40 et 40..100

var circle = addCircle(0,50, 20);
divide(circle, [20,50], [-20,50]);   // deux demi-cercles

Coins

round

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

Arrondit le coin entre deux entités avec un arc du rayon donné (congé). Les positions de clic indiquent quelles extrémités des entités sont arrondies. Si trim vaut true (par défaut), les deux entités sont ajustées à l’arc d’arrondi.

// un rectangle aux coins arrondis :
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);

Les coins d’une polyligne peuvent également être arrondis, en passant deux fois la même polyligne avec une position de clic sur chacun des deux segments :

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

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

Chanfreine le coin entre deux entités avec une ligne droite (chanfrein). distance1 est la distance de la ligne de chanfrein au coin le long de la première entité, distance2 le long de la seconde entité (par défaut distance1). Si trim vaut true (par défaut), les deux entités sont ajustées à la ligne de chanfrein. chamfer est un 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)

Crée des parallèles à des lignes, des arcs et cercles concentriques ou des courbes parallèles à des ellipses et à d’autres entités. number est le nombre de parallèles à créer (par défaut 1). Les parallèles sont créées des deux côtés de l’entité, sauf si un côté est indiqué, soit sous forme de position sidePos à côté de l’entité, soit sous forme de side (RS.LeftHand, RS.RightHand ou RS.BothSides). Le décalage de polylignes et de splines n’est disponible que dans QCAD Professional.

var line = addLine(0,0, 100,0);
offset(line, 5);                 // une parallèle de chaque côté

var line2 = addLine(0,30, 100,30);
offset(line2, 5, 2, RS.LeftHand);    // deux parallèles du côté gauche (au-dessus)

var circle = addCircle(50,80, 10);
offset(circle, [50,95], 3, 4);   // quatre cercles concentriques à l'extérieur

reverse

reverse(entity)
reverse(x, y)

Inverse le sens de l’entité donnée, c’est-à-dire intervertit son point de départ et son point d’arrivée.

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

explode

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

Décompose l’entité donnée en entités plus simples : les polylignes en lignes et en arcs, les références de bloc en leur contenu, les textes en lignes et en splines, les cotations et les hachures en lignes, arcs, etc. L’entité d’origine est supprimée.

options est un objet facultatif contenant des paramètres qui sont sinon repris des préférences de l’application, par exemple { splineSegments: 64, textToPolylines: true }. Les options prises en charge sont : splineTolerance, splineSegments, ellipseSegments, splinesToLineSegments, textToPolylines, textSplineToLineOrArc, multilineTextToSimpleText et circlesToPolylines.

var pl = addPolyline([[0,0], [100,0,1], [100,50], [0,50]], true);
explode(pl);                     // trois lignes et un arc

stretch

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

Étire toutes les entités de la zone rectangulaire définie par deux coins selon le décalage donné. Les entités entièrement situées à l’intérieur de la zone sont déplacées, les entités qui croisent la limite de la zone sont étirées (seules les extrémités situées à l’intérieur de la zone sont déplacées). La zone peut aussi être indiquée sous forme de RBox ou de forme RPolyline fermée. Si des entités sont sélectionnées dans le dessin, seules les entités sélectionnées sont étirées.

// un rectangle composé de lignes :
addLine(0,0, 100,0);
addLine(100,0, 100,50);
addLine(100,50, 0,50);
addLine(0,50, 0,0);

// élargir le rectangle de 50 unités en étirant son côté droit :
stretch([80,-10], [120,60], [50,0]);

deleteEntity

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

Supprime l’entité donnée du dessin.

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

deleteEntity(l1);                // par entité
deleteEntity(l2.getId());        // par ID d'entité
deleteEntity(50,20);             // par position

paste

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

Colle le contenu du document sourceDocument dans l’interface de document destination, ou dans le dessin courant si destination vaut undefined. Le contenu collé est déplacé de offset, mis à l’échelle selon scale et pivoté de rotation degrés. Tous les arguments sont obligatoires :

• flipHorizontal, flipVertical : true pour retourner le contenu
• toCurrentLayer : true pour coller toutes les entités sur le calque courant
• overwriteLayers, overwriteBlocks : true pour écraser les calques ou blocs existants portant le même nom

// créer un symbole dans un document hors écran :
var symbol = createDocument();
startTransaction(symbol);
addCircle(0,0, 10);
addLine(-10,0, 10,0);
addLine(0,-10, 0,10);
endTransaction();

// le coller trois fois dans le dessin courant :
for (var i=0; i<3; i++) {
    paste(symbol, undefined, [i*50, 0], 1+i*0.5, i*15, false, false, false, false, false);
}

Transactions

startTransaction et endTransaction

startTransaction()
startTransaction(document)
endTransaction()

Par défaut, chaque appel de l’API Simple est immédiatement appliqué au dessin et peut être annulé individuellement. Entre startTransaction() et endTransaction(), toutes les modifications sont collectées et appliquées ensemble lors de l’appel de endTransaction. Cela présente deux avantages :

• C’est beaucoup plus rapide lors de l’ajout de nombreuses entités.
• Toutes les modifications peuvent être annulées en une seule étape.

Si un document (RDocument) ou une interface de document (RDocumentInterface) est transmis à startTransaction, toutes les modifications sont appliquées à ce document au lieu du dessin courant. C’est utile pour créer des dessins en arrière-plan, par exemple pour les exporter dans un fichier (voir createDocumentInterface).

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

Tenez compte des points suivants lorsque vous travaillez avec des transactions :

• Au sein d’une transaction, les modifications ne font pas encore partie du dessin. Les fonctions de modification telles que trim ou round ne peuvent pas faire référence à des entités ajoutées dans la même transaction.
• Les entités renvoyées par les fonctions de création au sein d’une transaction n’ont pas d’ID valide, pas même après endTransaction. Pour modifier ces entités par la suite, faites-y référence par leur position.
• Toutes les entités ajoutées au sein d’une transaction sont placées sur le calque qui est courant au moment de l’appel de endTransaction. Définissez le calque courant avant de démarrer la transaction et utilisez des transactions distinctes pour des calques différents.

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

// faire référence aux nouvelles lignes par leur position pour arrondir le coin :
round([50,0], [100,25], 10);

getTransactionDocument et getTransactionDocumentInterface

getTransactionDocument()
getTransactionDocumentInterface()

Renvoient le document ou l’interface de document auquel s’applique la transaction en cours. En dehors des transactions, le document courant et l’interface de document courante sont renvoyés.

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

getOperation

getOperation()

Renvoie l’opération (RAddObjectsOperation) de la transaction en cours. En dehors d’une transaction, une nouvelle opération est renvoyée, qui doit être appliquée explicitement. Cette fonction est destinée à un usage avancé, par exemple pour combiner des appels de l’API Simple avec l’API complète de 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();

Vue

autoZoom

autoZoom()

Zoome la vue courante de sorte que l’ensemble du dessin soit visible.

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)

Zoome sur l’entité, la forme ou la zone rectangulaire donnée. margin est la marge autour de la zone en pixels (par défaut 10).

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

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

Documents et application

getMainWindow

getMainWindow()

Renvoie la fenêtre de l’application QCAD (RMainWindowQt).

getMainWindow().windowTitle;

getDocumentInterface

getDocumentInterface()

Renvoie l’interface de document (RDocumentInterface) du dessin courant. L’interface de document relie un document à ses vues et fournit des fonctions pour importer et exporter des fichiers, appliquer des opérations, annuler et rétablir.

addLine(0,0, 100,0);
getDocumentInterface().undo();       // supprime à nouveau la ligne

getDocument

getDocument()

Renvoie le document courant (RDocument). Le document contient toutes les entités, calques, blocs, etc. d’un dessin et fournit des fonctions pour les interroger.

addLine(0,0, 100,0);
addCircle(0,0, 10);
getDocument().queryAllEntities().length;     // nombre d'entités dans le dessin

getGraphicsView

getGraphicsView()

Renvoie la vue courante ou la dernière vue active (RGraphicsView) du dessin courant.

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

createDocument

createDocument()

Crée un nouveau document vide en mémoire, qui n’est affiché dans aucune fenêtre. Un tel document hors écran peut être rempli à l’aide d’une transaction, puis collé dans un dessin (voir paste).

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

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

createDocumentInterface

createDocumentInterface()

Crée un nouveau document vide en mémoire, ainsi qu’une interface de document. L’interface de document peut être utilisée pour importer ou exporter des fichiers.

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

disableInput()
enableInput()
isInputEnabled()

disableInput désactive la fenêtre de l’application QCAD afin d’empêcher les saisies de l’utilisateur, par exemple pendant de longues opérations ou des animations. enableInput réactive la fenêtre de l’application et isInputEnabled renvoie true si les saisies de l’utilisateur sont actuellement activées. Veillez toujours à réactiver les saisies à la fin de votre script.

update

update()

Traite les événements en attente afin que l’interface utilisateur soit mise à jour pendant les longues opérations. Les saisies de l’utilisateur doivent être désactivées avec disableInput avant d’appeler update.

sleep

sleep(milliseconds)

Met le script en pause pendant la durée donnée en millisecondes, tout en maintenant l’interface utilisateur à jour. Les saisies de l’utilisateur doivent être désactivées avec disableInput avant d’appeler sleep.

L’exemple suivant utilise disableInput, sleep et enableInput pour afficher une animation simple :

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)

Affiche un message d’avertissement. Dans le Script Shell, les avertissements sont affichés dans l’historique des commandes. Sinon, les avertissements sont écrits dans la console.

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

Saisies de l’utilisateur

Les fonctions suivantes affichent une boîte de dialogue simple pour demander une valeur à l’utilisateur. Si l’utilisateur annule la boîte de dialogue, undefined est renvoyé.

getInt

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

Demande un nombre entier à l’utilisateur. value est la valeur initiale (par défaut 0), step le pas du champ numérique (par défaut 1), min et max la plage autorisée.

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)

Demande un nombre à l’utilisateur. value est la valeur initiale (par défaut 0), decimals le nombre de décimales affichées (par défaut 1), min et max la plage autorisée.

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

getText

getText(title, prompt, text)

Demande un texte à l’utilisateur. text est le texte initial (vide par défaut).

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

getItem

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

Permet à l’utilisateur de choisir un élément dans une liste déroulante. items est une chaîne contenant tous les éléments séparés par separator (par défaut ","). index est l’indice de l’élément sélectionné initialement (par défaut 0). Renvoie l’élément choisi, ou undefined si la boîte de dialogue a été annulée.

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

Exemple : une bride

Cet exemple combine plusieurs fonctions de l’API Simple pour dessiner une bride avec un cercle de perçage, des trous de boulons sur un calque séparé et une découpe rectangulaire aux coins arrondis :

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

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

// cercle de perçage et lignes d'axe :
setCurrentLayer("Center Lines");
addCircle(0,0, 75);
addLine(-110,0, 110,0);
addLine(0,-110, 0,110);

// trous de boulons, ajoutés en une seule transaction :
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();

// découpe carrée aux coins arrondis au centre :
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();

Les lignes de la découpe sont ajoutées sans transaction, de sorte qu’elles peuvent être transmises directement à round. Les trous de boulons sont ajoutés dans une transaction, ce qui est plus rapide et permet de les annuler en une seule étape.