De Simple API

Inleiding

De QCAD Simple API is een kleine verzameling globale scriptfuncties die veelvoorkomende taken vereenvoudigen, zoals het toevoegen van objecten aan een tekening, het opvragen van objecten en het wijzigen ervan (verplaatsen, trimmen, afronden, parallellen maken, …). Ze is vooral bedoeld voor gebruik in de Script Shell en voor korte procedurele scripts die vanuit een bestand worden uitgevoerd, maar ze kan in elk script worden gebruikt.

De Simple API omvat slechts een klein deel van de volledige QCAD-API. Omdat ze zelf in ECMAScript (JavaScript) is geschreven, is ze ook een goed startpunt om te leren hoe de onderliggende QCAD-API werkt. De broncode vindt u in de bestanden scripts/simple.js en scripts/simple_*.js van de QCAD-broncode.

De Simple API gebruiken

In de Script Shell (Diverse > Ontwikkeling > Script Shell) en in scripts die worden gestart met Diverse > Ontwikkeling > Afscript uitvoeren, zijn alle functies van de Simple API direct beschikbaar. Typ bijvoorbeeld:

addLine(0,0, 100,100);

Voeg in uw eigen scriptbestanden, bijvoorbeeld in interactieve scriptacties of opdrachtregelprogramma’s, eerst het bestand simple.js in:

include("scripts/simple.js");

addLine(0,0, 100,100);

Alle functies werken op de tekening die op dat moment in het QCAD-toepassingsvenster is geopend, tenzij een transactie wordt gebruikt om ze naar een ander document om te leiden (zie Transacties).

Alle voorbeelden op deze pagina kunnen in de Script Shell van een lege tekening worden geplakt. Elk voorbeeld maakt de objecten aan die het nodig heeft. Gebruik Aanzicht > Auto zoom of de functie autoZoom() om het resultaat te zien.

Conventies

Coördinaten

Posities kunnen op drie verschillende manieren worden doorgegeven:

• Als twee afzonderlijke getallen: addLine(0,0, 100,100)
• Als array van twee getallen: addLine([0,0], [100,100])
• Als vectorobject: addLine(new RVector(0,0), new RVector(100,100))

Hoeken worden altijd in graden opgegeven, behalve de start- en eindparameters van ellipsen, die in radialen worden opgegeven.

Objectreferenties

Functies die met een bestaand object werken, accepteren het object in verschillende vormen:

• Een object-ID (getal), bijvoorbeeld 1234.
• Het object zelf, zoals het door de aanmaakfuncties wordt geretourneerd, bijvoorbeeld de retourwaarde van addLine(...).
• Een positie in de tekening ([x,y] of RVector): het object dat het dichtst bij de opgegeven positie ligt, wordt gebruikt.
• Een vorm (bijvoorbeeld new RLine(0,0, 100,0)): de bewerking wordt alleen op de vorm toegepast, de tekening wordt niet gewijzigd.

var l = addLine(0,0, 100,0);
move(l, [0,10]);              // via het object
move(l.getId(), [0,10]);      // via het object-ID
move([50,20], [0,10]);        // via de positie: het object dat het dichtst bij 50,20 ligt

Klikposities

Sommige bewerkingen hangen af van waar op een object wordt geklikt wanneer het overeenkomstige gereedschap interactief wordt gebruikt. Bij trimmen blijft het deel van het object bij de klikpositie behouden, bij afronden en afschuinen worden de uiteinden van de objecten afgerond of afgeschuind die het dichtst bij de klikposities liggen, en bij offset worden parallellen aan de kant van de klikpositie gemaakt.

In de Simple API kan op elke objectreferentie een klikpositie volgen. Als een object via een positie wordt gerefereerd, dient die positie ook als klikpositie. Als er geen klikpositie wordt opgegeven, wordt het middelpunt van het object gebruikt:

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

// line trimmen tot limit, het deel van de lijn bij 10,0 behouden:
trim(line, [10,0], limit);

Retourwaarden

• Aanmaakfuncties retourneren het toegevoegde object. Het object kan aan andere functies worden doorgegeven of worden opgevraagd voor informatie (bijvoorbeeld getId(), getLength() of getStartPoint()).
• Transformaties (move, rotate, scale, mirror, lengthen, reverse) retourneren het gewijzigde object.
• Andere wijzigingsfuncties (trim, round, bevel, offset, breakOut, autoTrim, divide, explode, stretch) retourneren de transactie die op de tekening is toegepast, of undefined als de bewerking is mislukt.
• Als in plaats van objecten vormen worden doorgegeven, wijzigen transformaties de opgegeven vormen en retourneren alle andere functies de resulterende vormen als array.

Mislukte bewerkingen veroorzaken geen fout. In plaats daarvan wordt in de Script Shell een waarschuwing getoond, bijvoorbeeld “Object kan niet worden getrimmed.”.

Objecten aanmaken

addPoint

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

Voegt een puntobject toe op de opgegeven positie.

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

addLine

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

Voegt een lijn toe van het startpunt naar het eindpunt.

// een driehoek:
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])

Voegt een oneindige lijn (constructielijn) toe door het basispunt x,y met de richting dx,dy. De richting wordt relatief ten opzichte van het basispunt opgegeven.

// horizontale constructielijn en constructielijn onder 45 graden door 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)

Voegt een boog toe met het opgegeven middelpunt, de opgegeven straal, starthoek en eindhoek. Hoeken worden in graden opgegeven. Bogen lopen tegen de klok in van de starthoek naar de eindhoek, tenzij reversed gelijk is aan true (optioneel, standaard is false).

// kwartboog van 0 tot 90 graden:
addArc(0,0, 50, 0, 90);

// boog met de klok mee van 0 tot 90 graden (de andere drie kwarten):
addArc([0,0], 40, 0, 90, true);

addCircle

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

Voegt een cirkel toe met het opgegeven middelpunt en de opgegeven straal.

// concentrische cirkels:
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)

Voegt een ellips of ellipsboog toe. mx,my is het eindpunt van de hoofdas, relatief ten opzichte van het middelpunt. ratio is de verhouding tussen de korte en de lange as. startParam en endParam zijn de ellipsparameters in radialen waar de ellips begint en eindigt. Gebruik 0 en 2*Math.PI voor een volledige ellips.

// volledige ellips met een grote straal van 50 en een kleine straal van 25:
addEllipse(0,0, 50,0, 0.5, 0, 2*Math.PI, false);

// bovenste helft van een geroteerde ellips:
addEllipse([0,0], [30,30], 0.3, 0, Math.PI, false);

addPolyline

addPolyline(points, closed, relative)

Voegt een polylijn toe door de opgegeven hoekpunten. points is een array van hoekpunten, elk opgegeven als [x, y], [x, y, bulge] of [x, y, bulge, relative]. In plaats van x, y kan een RVector worden gebruikt.

• bulge (ronding) bepaalt de vorm van het segment dat bij dit hoekpunt begint: 0 (standaard) voor een recht segment, 1 voor een halve cirkel tegen de klok in, -1 voor een halve cirkel met de klok mee. Andere waarden maken boogsegmenten daartussenin (de ronding is de tangens van een kwart van de booghoek).
• relative: true als de coördinaten van dit hoekpunt relatief zijn ten opzichte van het vorige hoekpunt.
• closed: true om de polylijn te sluiten (standaard is false).
• relative: true om de coördinaten van alle hoekpunten als relatief ten opzichte van het vorige hoekpunt te behandelen (standaard is false).

// gesloten rechthoek:
addPolyline([[0,0], [100,0], [100,50], [0,50]], true);

// sleufvorm met twee halve cirkels:
addPolyline([[0,60], [80,60,1], [80,80], [0,80,1]], true);

// zigzaglijn met relatieve coördinaten:
addPolyline([[0,100], [10,10], [10,-10], [10,10], [10,-10]], false, true);

addSpline

addSpline(fitPoints, closed)

Voegt een spline toe door de opgegeven plaatsingspunten. fitPoints is een array van [x, y]-arrays of RVector-objecten. Als closed gelijk is aan true, wordt de spline gesloten (periodiek).

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

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

De tutorial Scripts uitvoeren vanuit een bestand toont nog een voorbeeld dat een Lissajous-kromme als spline plot.

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)

Voegt een tekst van één regel toe op de opgegeven positie. Alle argumenten na de positie zijn optioneel:

• height: teksthoogte (standaard 1)
• angle: teksthoek in graden (standaard 0)
• font: naam van het lettertype (standaard "Standard")
• vAlign: verticale uitlijning: RS.VAlignTop (standaard), RS.VAlignMiddle, RS.VAlignBase of RS.VAlignBottom
• hAlign: horizontale uitlijning: RS.HAlignLeft (standaard), RS.HAlignCenter of RS.HAlignRight
• bold, italic: true voor vette of cursieve tekst (alleen TrueType-lettertypen)

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

Voegt een gevuld vlak (solid) met drie of vier hoeken toe. Let op: de hoeken van een vierzijdig gevuld vlak worden in zigzagvolgorde opgegeven: eerste hoek, tweede hoek, dan de hoek tegenover de tweede hoek en de hoek tegenover de eerste hoek. Om een driehoek te maken, geeft u de derde hoek twee keer door.

// gevuld vierkant:
addSolid(0,0, 50,0, 0,50, 50,50);

// gevulde driehoek:
addSolid([60,0], [110,0], [85,50], [85,50]);

Vormen, tekenobjecten en objecten toevoegen

De volgende functies voegen objecten die met de volledige QCAD-API zijn gemaakt aan de tekening toe. Ze zijn nuttig wanneer de bovenstaande gespecialiseerde aanmaakfuncties een bepaald geval niet dekken.

addShape

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

Voegt de opgegeven vorm (RLine, RArc, RCircle, REllipse, RPolyline, RSpline, RPoint, …) als nieuw object toe op de huidige laag. Optioneel kunnen een kleur (RColor), een lijntype (naam of ID) en een lijndikte (bijvoorbeeld RLineweight.Weight050) worden opgegeven. Standaard worden de huidige kleur, lijntype ByLayer en lijndikte ByLayer gebruikt.

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)

Voegt alle vormen in de opgegeven array als nieuwe objecten toe.

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)

Voegt het opgegeven object (REntity) toe aan de tekening. Als er geen kleur wordt opgegeven, wordt de huidige kleur gebruikt.

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)

Voegt een willekeurig object (tekenobject, laag, blok, …) toe aan de tekening en retourneert het toegevoegde object.

// een blok met de naam "Marker" met een kruis erin toevoegen:
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);

// het blok twee keer invoegen:
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)

Verwijdert het opgegeven object uit de tekening. Om tekenobjecten te verwijderen, is de functie deleteEntity meestal handiger.

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

Lagen en attributen

addLayer

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

Voegt een nieuwe laag met de opgegeven naam toe. Optioneel kunnen de kleurnaam (standaard "white", wat op een witte achtergrond zwart wordt weergegeven), de lijntypenaam (standaard "CONTINUOUS") en de lijndikte (standaard RLineweight.Weight000) worden opgegeven. Retourneert de nieuwe laag of undefined als er al een laag met de opgegeven naam bestaat.

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

hasLayer

hasLayer(name)

Retourneert true als er in de tekening een laag met de opgegeven naam bestaat.

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

setCurrentLayer

setCurrentLayer(name)

Stelt de huidige laag in. Alle daarna toegevoegde objecten worden op deze laag geplaatst.

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

setCurrentColor

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

Stelt de kleur in voor objecten die daarna worden toegevoegd. De kleur kan worden opgegeven als RColor-object of als rood-, groen- en blauwwaarden (0-255). Gebruik new RColor(RColor.ByLayer) om de kleur terug te zetten op “Door laag bepaald”.

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

Objecten opvragen

getEntity

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

Retourneert het object voor de opgegeven objectreferentie, d.w.z. het object met het opgegeven ID, de huidige toestand van het opgegeven object of het object dat het dichtst bij de opgegeven positie ligt. Retourneert undefined als er geen object wordt gevonden.

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

// circle bevat nog het oude middelpunt, getEntity retourneert de huidige toestand:
getEntity(circle).getCenter();     // retourneert 10,0

// object dat het dichtst bij 30,0 ligt:
getEntity(30,0).getRadius();       // retourneert 20

getShape

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

Retourneert de geometrie van het opgegeven object als vorm (RLine voor een lijn, RArc voor een boog, RPolyline voor een polylijn, …). Vormen kunnen worden gebruikt voor geometrische berekeningen zonder de tekening te wijzigen.

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

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

getClosestEntity

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

Retourneert het object dat het dichtst bij de opgegeven positie ligt. Als range is opgegeven, worden alleen objecten binnen die afstand van de positie in aanmerking genomen. Retourneert undefined als er geen object wordt gevonden.

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

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

getEntityShape

getEntityShape(entity, position)

Retourneert de vorm van het opgegeven object. Bij complexe objecten die uit meerdere vormen bestaan (blokreferenties, arceringen, bematingen, teksten), wordt de vorm geretourneerd die het dichtst bij de opgegeven positie ligt. De positie is optioneel.

// een blokreferentie van een blok met een rechthoek:
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)));

// vorm van de blokreferentie nabij 40,10 (de rechthoek):
var s = getEntityShape(getEntity(ref), new RVector(41,10));
s.getLength();                     // retourneert 120

getIntersectionPoints

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

Retourneert een array met de snijpunten van de twee opgegeven objecten of vormen. Objecten kunnen worden opgegeven als objecten, object-ID’s of vormen. Als limited gelijk is aan false, worden de objecten behandeld alsof ze oneindig zijn (lijnen verlengd, bogen als volledige cirkels). Standaard is true.

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

// de snijpunten markeren met kleine cirkels:
for (var i=0; i<ips.length; i++) {
    addCircle(ips[i], 2);
}

isPosition en toVector

isPosition(value)
toVector(value)

isPosition retourneert true als de opgegeven waarde een positie is (RVector of array van twee of drie getallen). toVector zet een als array opgegeven positie om in een RVector. Deze functies zijn nuttig wanneer u eigen functies schrijft die posities op dezelfde manier accepteren als de 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]);                 // retourneert true
isPosition("abc");                 // retourneert false

Objecten wijzigen

Transformaties

move

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

Verplaatst het opgegeven object over de opgegeven verschuiving.

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

rotate

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

Roteert het opgegeven object over de opgegeven hoek in graden rond het opgegeven middelpunt. Als er geen middelpunt wordt opgegeven, wordt het object rond de oorsprong 0,0 geroteerd.

// een waaier van lijnen, geroteerd rond 0,0:
for (var a=0; a<360; a+=30) {
    var l = addLine(10,0, 50,0);
    rotate(l, a);
}

// een vierkant rond zijn middelpunt roteren:
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])

Schaalt het opgegeven object met de opgegeven factor. Het basispunt (het punt dat op zijn plaats blijft) is standaard de oorsprong 0,0. Verschillende factoren voor X en Y kunnen als array [sx, sy] worden opgegeven. Let op: sommige objecten, zoals cirkels en bogen, kunnen niet met verschillende factoren in X en Y worden geschaald.

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(...))

Spiegelt het opgegeven object in de as die door twee punten wordt gedefinieerd.

var pl = addPolyline([[10,0], [40,0], [40,30]], false);
// spiegelen in de Y-as:
mirror(pl, 0,0, 0,100);

Om het origineel te behouden en een gespiegelde kopie te maken, voegt u eerst een kopie van het object toe:

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

Trimmen en verlengen

trim

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

Trimt het object trimEntity tot het beperkende object limitingEntity. Het deel van het getrimde object bij de klikpositie trimPos blijft behouden. Als de twee objecten elkaar niet snijden, wordt het object verlengd tot het beperkende object. Als er meerdere snijpunten zijn, wordt het snijpunt gebruikt dat het dichtst bij de klikpositie limitingPos ligt. Als trimBoth gelijk is aan true, worden beide objecten tot elkaar getrimd.

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

// het linkerdeel behouden, de lijn eindigt nu bij 70,0:
trim(line, [10,0], limit);

// een lijn tot een cirkel verlengen:
var line = addLine(0,0, 50,0);
var circle = addCircle(100,0, 20);

// verlengen tot het snijpunt met de cirkel dat het dichtst bij 80,0 ligt:
trim(line, [25,0], circle, [80,0]);      // de lijn eindigt nu bij 80,0

trimBoth

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

Trimt of verlengt beide objecten tot hun snijpunt. Dit is een verkorte vorm van trim met trimBoth ingesteld op true.

// twee lijnen die elkaar niet raken, worden verlengd en vormen een hoek bij 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)

Verlengt het opgegeven object met de opgegeven lengte. Negatieve waarden korten het object in. Standaard wordt het object bij zijn eindpunt verlengd. Geef true door voor start om het in plaats daarvan bij zijn startpunt te verlengen, of geef een positie door nabij het uiteinde dat moet worden verlengd.

var line = addLine(0,0, 100,0);
lengthen(line, 20);              // de lijn eindigt nu bij 120,0
lengthen(line, true, -10);       // de lijn begint nu bij 10,0

var arc = addArc(0,50, 30, 0, 90);
lengthen(arc, [30,50], 10);      // de boog bij zijn startpunt verlengen

breakOut

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

Breekt het segment van het opgegeven object op de opgegeven positie uit. Het segment eindigt bij de dichtstbijzijnde snijpunten met andere objecten aan weerszijden van de positie. Als er aan één kant geen snijpunt is, loopt het segment door tot het uiteinde van het object. Als removeSegment gelijk is aan true (standaard), wordt het segment verwijderd. Anders blijft het als afzonderlijk object behouden.

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

// het deel van de lijn tussen 30,0 en 70,0 verwijderen:
breakOut(line, [50,0]);

autoTrim

autoTrim(entity, pos)
autoTrim(pos)

Het tegenovergestelde van breakOut: behoudt alleen het segment van het opgegeven object op de opgegeven positie en verwijdert de rest. Het segment eindigt bij de dichtstbijzijnde snijpunten met andere objecten aan weerszijden van de positie.

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

// alleen het deel tussen 30,0 en 70,0 behouden:
autoTrim(line, [50,0]);

divide

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

Splitst het opgegeven object op de opgegeven positie. Een open object (lijn, boog, open polylijn, …) wordt op één positie in twee delen of op twee posities in drie delen gesplitst. Gesloten objecten (cirkels, volledige ellipsen, gesloten polylijnen) vereisen twee posities en worden in twee delen gesplitst.

var line = addLine(0,0, 100,0);
divide(line, [40,0]);            // twee lijnen: 0..40 en 40..100

var circle = addCircle(0,50, 20);
divide(circle, [20,50], [-20,50]);   // twee halve cirkels

Hoeken

round

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

Rondt de hoek tussen twee objecten af met een boog met de opgegeven straal (afronding). De klikposities geven aan welke uiteinden van de objecten worden afgerond. Als trim gelijk is aan true (standaard), worden beide objecten tot de afrondingsboog getrimd.

// een rechthoek met afgeronde hoeken:
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);

Ook de hoeken van een polylijn kunnen worden afgerond, door dezelfde polylijn twee keer door te geven met een klikpositie op elk van de twee segmenten:

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

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

Schuint de hoek tussen twee objecten af met een rechte lijn (afschuining). distance1 is de afstand van de afschuiningslijn tot de hoek langs het eerste object, distance2 langs het tweede object (standaard gelijk aan distance1). Als trim gelijk is aan true (standaard), worden beide objecten tot de afschuiningslijn getrimd. chamfer is een alias voor 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)

Maakt parallellen aan lijnen, concentrische bogen en cirkels of offsetcurven (parallelle curven) van ellipsen en andere objecten. number is het aantal te maken parallellen (standaard 1). De parallellen worden aan beide zijden van het object gemaakt, tenzij een zijde wordt opgegeven, ofwel als positie sidePos naast het object, ofwel als side (RS.LeftHand, RS.RightHand of RS.BothSides). Offset van polylijnen en splines is alleen beschikbaar in QCAD Professional.

var line = addLine(0,0, 100,0);
offset(line, 5);                 // één parallel aan elke zijde

var line2 = addLine(0,30, 100,30);
offset(line2, 5, 2, RS.LeftHand);    // twee parallellen aan de linkerzijde (erboven)

var circle = addCircle(50,80, 10);
offset(circle, [50,95], 3, 4);   // vier concentrische cirkels aan de buitenkant

reverse

reverse(entity)
reverse(x, y)

Draait de richting van het opgegeven object om, d.w.z. verwisselt zijn start- en eindpunt.

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

explode

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

Splitst het opgegeven object op in eenvoudigere objecten: polylijnen in lijnen en bogen, blokreferenties in hun inhoud, teksten in lijnen en splines, bematingen en arceringen in lijnen, bogen enz. Het oorspronkelijke object wordt verwijderd.

options is een optioneel object met instellingen die anders uit de toepassingsvoorkeuren worden overgenomen, bijvoorbeeld { splineSegments: 64, textToPolylines: true }. Ondersteunde opties zijn: splineTolerance, splineSegments, ellipseSegments, splinesToLineSegments, textToPolylines, textSplineToLineOrArc, multilineTextToSimpleText en circlesToPolylines.

var pl = addPolyline([[0,0], [100,0,1], [100,50], [0,50]], true);
explode(pl);                     // drie lijnen en één boog

stretch

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

Rekt alle objecten in het rechthoekige gebied dat door twee hoeken wordt gedefinieerd, over de opgegeven verschuiving. Objecten die volledig binnen het gebied liggen, worden verplaatst; objecten die de grens van het gebied kruisen, worden gerekt (alleen de eindpunten binnen het gebied worden verplaatst). Het gebied kan ook als RBox of als gesloten RPolyline-vorm worden opgegeven. Als er in de tekening objecten zijn geselecteerd, worden alleen de geselecteerde objecten gerekt.

// een rechthoek van lijnen:
addLine(0,0, 100,0);
addLine(100,0, 100,50);
addLine(100,50, 0,50);
addLine(0,50, 0,0);

// de rechthoek 50 eenheden breder maken door de rechterzijde te rekken:
stretch([80,-10], [120,60], [50,0]);

deleteEntity

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

Verwijdert het opgegeven object uit de tekening.

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

deleteEntity(l1);                // via het object
deleteEntity(l2.getId());        // via het object-ID
deleteEntity(50,20);             // via de positie

paste

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

Plakt de inhoud van het document sourceDocument in de documentinterface destination, of in de huidige tekening als destination gelijk is aan undefined. De geplakte inhoud wordt verplaatst over offset, geschaald met scale en over rotation graden geroteerd. Alle argumenten zijn verplicht:

• flipHorizontal, flipVertical: true om de inhoud te spiegelen
• toCurrentLayer: true om alle objecten op de huidige laag te plakken
• overwriteLayers, overwriteBlocks: true om bestaande lagen of blokken met dezelfde naam te overschrijven

// een symbool maken in een niet-weergegeven document:
var symbol = createDocument();
startTransaction(symbol);
addCircle(0,0, 10);
addLine(-10,0, 10,0);
addLine(0,-10, 0,10);
endTransaction();

// het drie keer in de huidige tekening plakken:
for (var i=0; i<3; i++) {
    paste(symbol, undefined, [i*50, 0], 1+i*0.5, i*15, false, false, false, false, false);
}

Transacties

startTransaction en endTransaction

startTransaction()
startTransaction(document)
endTransaction()

Standaard wordt elke aanroep van de Simple API direct op de tekening toegepast en kan afzonderlijk ongedaan worden gemaakt. Tussen startTransaction() en endTransaction() worden alle wijzigingen verzameld en samen toegepast wanneer endTransaction wordt aangeroepen. Dit heeft twee voordelen:

• Het is veel sneller wanneer er veel objecten worden toegevoegd.
• Alle wijzigingen kunnen in één enkele stap ongedaan worden gemaakt.

Als een document (RDocument) of documentinterface (RDocumentInterface) aan startTransaction wordt doorgegeven, worden alle wijzigingen op dat document toegepast in plaats van op de huidige tekening. Dit is nuttig om tekeningen op de achtergrond te maken, bijvoorbeeld om ze naar een bestand te exporteren (zie createDocumentInterface).

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

Let op het volgende bij het werken met transacties:

• Binnen een transactie maken de wijzigingen nog geen deel uit van de tekening. Wijzigingsfuncties zoals trim of round kunnen niet verwijzen naar objecten die in dezelfde transactie zijn toegevoegd.
• Objecten die binnen een transactie door aanmaakfuncties worden geretourneerd, hebben geen geldig ID, ook niet na endTransaction. Om zulke objecten later te wijzigen, verwijst u ernaar via hun positie.
• Alle objecten die binnen een transactie worden toegevoegd, worden geplaatst op de laag die huidig is wanneer endTransaction wordt aangeroepen. Stel de huidige laag in voordat u de transactie start en gebruik afzonderlijke transacties voor verschillende lagen.

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

// via de positie naar de nieuwe lijnen verwijzen om de hoek af te ronden:
round([50,0], [100,25], 10);

getTransactionDocument en getTransactionDocumentInterface

getTransactionDocument()
getTransactionDocumentInterface()

Retourneren het document of de documentinterface waarop de huidige transactie van toepassing is. Buiten transacties worden het huidige document en de huidige documentinterface geretourneerd.

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

getOperation

getOperation()

Retourneert de bewerking (RAddObjectsOperation) van de huidige transactie. Buiten een transactie wordt een nieuwe bewerking geretourneerd die expliciet moet worden toegepast. Dit is bedoeld voor gevorderd gebruik, bijvoorbeeld om aanroepen van de Simple API te combineren met de volledige QCAD-API.

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

Weergave

autoZoom

autoZoom()

Zoomt de huidige weergave zo, dat de hele tekening zichtbaar is.

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)

Zoomt in op het opgegeven object, de opgegeven vorm of het opgegeven rechthoekige gebied. margin is de marge rond het gebied in pixels (standaard 10).

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

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

Documenten en toepassing

getMainWindow

getMainWindow()

Retourneert het QCAD-toepassingsvenster (RMainWindowQt).

getMainWindow().windowTitle;

getDocumentInterface

getDocumentInterface()

Retourneert de documentinterface (RDocumentInterface) van de huidige tekening. De documentinterface verbindt een document met zijn weergaven en biedt functies om bestanden te importeren en exporteren, bewerkingen toe te passen, ongedaan te maken en opnieuw toe te passen.

addLine(0,0, 100,0);
getDocumentInterface().undo();       // verwijdert de lijn weer

getDocument

getDocument()

Retourneert het huidige document (RDocument). Het document bevat alle objecten, lagen, blokken enz. van een tekening en biedt functies om deze op te vragen.

addLine(0,0, 100,0);
addCircle(0,0, 10);
getDocument().queryAllEntities().length;     // aantal objecten in de tekening

getGraphicsView

getGraphicsView()

Retourneert de huidige of laatst actieve weergave (RGraphicsView) van de huidige tekening.

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

createDocument

createDocument()

Maakt een nieuw, leeg document in het geheugen aan dat niet in een venster wordt weergegeven. Zo’n niet-weergegeven document kan met een transactie worden gevuld en vervolgens in een tekening worden geplakt (zie paste).

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

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

createDocumentInterface

createDocumentInterface()

Maakt een nieuw, leeg document in het geheugen aan, samen met een documentinterface. De documentinterface kan worden gebruikt om bestanden te importeren of te exporteren.

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

disableInput()
enableInput()
isInputEnabled()

disableInput schakelt het QCAD-toepassingsvenster uit om gebruikersinvoer te voorkomen, bijvoorbeeld tijdens lange bewerkingen of animaties. enableInput schakelt het toepassingsvenster weer in en isInputEnabled retourneert true als gebruikersinvoer op dat moment is ingeschakeld. Zorg er altijd voor dat de invoer aan het einde van uw script weer wordt ingeschakeld.

update

update()

Verwerkt wachtende gebeurtenissen, zodat de gebruikersinterface tijdens lange bewerkingen wordt bijgewerkt. Gebruikersinvoer moet met disableInput worden uitgeschakeld voordat update wordt aangeroepen.

sleep

sleep(milliseconds)

Pauzeert het script gedurende de opgegeven tijd in milliseconden en houdt de gebruikersinterface intussen up-to-date. Gebruikersinvoer moet met disableInput worden uitgeschakeld voordat sleep wordt aangeroepen.

Het volgende voorbeeld gebruikt disableInput, sleep en enableInput om een eenvoudige animatie te tonen:

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)

Toont een waarschuwing. In de Script Shell worden waarschuwingen in de opdrachtregelgeschiedenis getoond. Anders worden waarschuwingen naar de console geschreven.

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

Gebruikersinvoer

De volgende functies tonen een eenvoudig dialoogvenster om de gebruiker om een waarde te vragen. Als de gebruiker het dialoogvenster annuleert, wordt undefined geretourneerd.

getInt

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

Vraagt de gebruiker om een geheel getal. value is de beginwaarde (standaard 0), step de stapgrootte van de spinbox (standaard 1), min en max het toegestane bereik.

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)

Vraagt de gebruiker om een getal. value is de beginwaarde (standaard 0), decimals het aantal weergegeven decimalen (standaard 1), min en max het toegestane bereik.

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

getText

getText(title, prompt, text)

Vraagt de gebruiker om een tekst. text is de begintekst (standaard leeg).

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

getItem

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

Laat de gebruiker een item kiezen uit een vervolgkeuzelijst. items is een tekenreeks met alle items, gescheiden door separator (standaard ","). index is de index van het aanvankelijk geselecteerde item (standaard 0). Retourneert het gekozen item of undefined als het dialoogvenster is geannuleerd.

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

Voorbeeld: een flens

Dit voorbeeld combineert meerdere functies van de Simple API om een flens te tekenen met een steekcirkel, boutgaten op een afzonderlijke laag en een afgeronde rechthoekige uitsparing:

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

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

// steekcirkel en hartlijnen:
setCurrentLayer("Center Lines");
addCircle(0,0, 75);
addLine(-110,0, 110,0);
addLine(0,-110, 0,110);

// boutgaten, toegevoegd in één transactie:
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();

// afgeronde vierkante uitsparing in het midden:
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();

De lijnen van de uitsparing worden zonder transactie toegevoegd, zodat ze direct aan round kunnen worden doorgegeven. De boutgaten worden in een transactie toegevoegd, wat sneller is en ervoor zorgt dat ze in één stap ongedaan kunnen worden gemaakt.