Die Simple API

Einführung

Die QCAD Simple API ist eine kleine Sammlung globaler Skriptfunktionen, die häufige Aufgaben vereinfachen, etwa das Hinzufügen von Objekten zu einer Zeichnung, das Abfragen von Objekten und deren Bearbeitung (Verschieben, Trimmen, Runden, Äquidistanten erstellen, …). Sie ist vor allem für die Verwendung in der Skriptshell und für kurze prozedurale Skripte gedacht, die aus einer Datei ausgeführt werden, kann aber in jedem Skript verwendet werden.

Die Simple API deckt nur einen kleinen Teil der vollständigen QCAD-API ab. Da sie selbst in ECMAScript (JavaScript) geschrieben ist, ist sie auch ein guter Ausgangspunkt, um zu lernen, wie die zugrunde liegende QCAD-API funktioniert. Der Quellcode befindet sich in den Dateien scripts/simple.js und scripts/simple_*.js des QCAD-Quellcodes.

Die Simple API verwenden

In der Skriptshell (Diverses > Entwicklung > Skriptshell) und in Skripten, die mit Diverses > Entwicklung > Skript starten gestartet werden, stehen alle Funktionen der Simple API direkt zur Verfügung. Geben Sie zum Beispiel Folgendes ein:

addLine(0,0, 100,100);

In Ihren eigenen Skriptdateien, zum Beispiel in interaktiven Skriptaktionen oder Kommandozeilenwerkzeugen, binden Sie zuerst die Datei simple.js ein:

include("scripts/simple.js");

addLine(0,0, 100,100);

Alle Funktionen arbeiten mit der Zeichnung, die aktuell im QCAD-Anwendungsfenster geöffnet ist, es sei denn, sie werden mit einer Transaktion auf ein anderes Dokument umgeleitet (siehe Transaktionen).

Alle Beispiele auf dieser Seite können in die Skriptshell einer leeren Zeichnung eingefügt werden. Jedes Beispiel erstellt die Objekte, die es benötigt. Verwenden Sie Ansicht > Auto Ansicht oder die Funktion autoZoom(), um das Ergebnis zu sehen.

Konventionen

Koordinaten

Positionen können auf drei verschiedene Arten übergeben werden:

• Als zwei separate Zahlen: addLine(0,0, 100,100)
• Als Array mit zwei Zahlen: addLine([0,0], [100,100])
• Als Vektorobjekt: addLine(new RVector(0,0), new RVector(100,100))

Winkel werden immer in Grad angegeben, mit Ausnahme der Start- und Endparameter von Ellipsen, die im Bogenmass angegeben werden.

Objektreferenzen

Funktionen, die mit einem bestehenden Objekt arbeiten, akzeptieren das Objekt in verschiedenen Formen:

• Eine Objekt-ID (Zahl), zum Beispiel 1234.
• Das Objekt selbst, wie es von den Erstellungsfunktionen zurückgegeben wird, zum Beispiel der Rückgabewert von addLine(...).
• Eine Position in der Zeichnung ([x,y] oder RVector): Es wird das Objekt verwendet, das der angegebenen Position am nächsten liegt.
• Eine Form (zum Beispiel new RLine(0,0, 100,0)): Die Operation wird nur auf die Form angewendet, die Zeichnung wird nicht verändert.

var l = addLine(0,0, 100,0);
move(l, [0,10]);              // über das Objekt
move(l.getId(), [0,10]);      // über die Objekt-ID
move([50,20], [0,10]);        // über die Position: das Objekt, das 50,20 am nächsten liegt

Klickpositionen

Einige Operationen hängen davon ab, wo ein Objekt angeklickt wird, wenn das entsprechende Werkzeug interaktiv verwendet wird. Beim Trimmen bleibt der Teil des Objekts an der Klickposition erhalten, beim Runden und Abschrägen werden die Enden der Objekte gerundet bzw. abgeschrägt, die den Klickpositionen am nächsten liegen, und Äquidistanten werden auf der Seite der Klickposition erstellt.

In der Simple API kann auf jede Objektreferenz eine Klickposition folgen. Wird ein Objekt über eine Position referenziert, dient diese Position auch als Klickposition. Wird keine Klickposition angegeben, wird der Mittelpunkt des Objekts verwendet:

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

// line an limit trimmen, den Teil der Linie bei 10,0 behalten:
trim(line, [10,0], limit);

Rückgabewerte

• Erstellungsfunktionen geben das hinzugefügte Objekt zurück. Das Objekt kann an andere Funktionen übergeben oder nach Informationen abgefragt werden (zum Beispiel getId(), getLength() oder getStartPoint()).
• Transformationen (move, rotate, scale, mirror, lengthen, reverse) geben das geänderte Objekt zurück.
• Andere Bearbeitungsfunktionen (trim, round, bevel, offset, breakOut, autoTrim, divide, explode, stretch) geben die Transaktion zurück, die auf die Zeichnung angewendet wurde, oder undefined, wenn die Operation fehlgeschlagen ist.
• Werden statt Objekten Formen übergeben, ändern Transformationen die übergebenen Formen, und alle anderen Funktionen geben die resultierenden Formen als Array zurück.

Fehlgeschlagene Operationen lösen keinen Fehler aus. Stattdessen wird in der Skriptshell eine Warnung angezeigt, zum Beispiel «Objekt kann nicht getrimmt werden.».

Objekte erstellen

addPoint

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

Fügt an der angegebenen Position ein Punktobjekt hinzu.

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

addLine

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

Fügt eine Linie vom Startpunkt zum Endpunkt hinzu.

// ein Dreieck:
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])

Fügt eine unendliche Linie (Konstruktionslinie) durch den Basispunkt x,y mit der Richtung dx,dy hinzu. Die Richtung wird relativ zum Basispunkt angegeben.

// horizontale und 45-Grad-Konstruktionslinie durch 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)

Fügt einen Bogen mit dem angegebenen Mittelpunkt, Radius, Startwinkel und Endwinkel hinzu. Winkel werden in Grad angegeben. Bögen verlaufen im Gegenuhrzeigersinn vom Startwinkel zum Endwinkel, es sei denn, reversed ist true (optional, Standard ist false).

// Viertelbogen von 0 bis 90 Grad:
addArc(0,0, 50, 0, 90);

// Bogen im Uhrzeigersinn von 0 bis 90 Grad (die anderen drei Viertel):
addArc([0,0], 40, 0, 90, true);

addCircle

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

Fügt einen Kreis mit dem angegebenen Mittelpunkt und Radius hinzu.

// konzentrische Kreise:
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)

Fügt eine Ellipse oder einen Ellipsenbogen hinzu. mx,my ist der Endpunkt der Hauptachse, relativ zum Mittelpunkt. ratio ist das Verhältnis zwischen Neben- und Hauptachse. startParam und endParam sind die Ellipsenparameter im Bogenmass, bei denen die Ellipse beginnt und endet. Verwenden Sie 0 und 2*Math.PI für eine vollständige Ellipse.

// vollständige Ellipse mit einem Hauptradius von 50 und einem Nebenradius von 25:
addEllipse(0,0, 50,0, 0.5, 0, 2*Math.PI, false);

// obere Hälfte einer gedrehten Ellipse:
addEllipse([0,0], [30,30], 0.3, 0, Math.PI, false);

addPolyline

addPolyline(points, closed, relative)

Fügt eine Polylinie durch die angegebenen Eckpunkte hinzu. points ist ein Array von Eckpunkten, die jeweils als [x, y], [x, y, bulge] oder [x, y, bulge, relative] angegeben werden. Anstelle von x, y kann ein RVector verwendet werden.

• bulge (Wölbung) legt die Form des Segments fest, das an diesem Eckpunkt beginnt: 0 (Standard) für ein gerades Segment, 1 für einen Halbkreis im Gegenuhrzeigersinn, -1 für einen Halbkreis im Uhrzeigersinn. Andere Werte erzeugen dazwischenliegende Bogensegmente (die Wölbung ist der Tangens eines Viertels des Bogenwinkels).
• relative: true, wenn die Koordinaten dieses Eckpunkts relativ zum vorherigen Eckpunkt sind.
• closed: true, um die Polylinie zu schliessen (Standard ist false).
• relative: true, um die Koordinaten aller Eckpunkte als relativ zum jeweils vorherigen Eckpunkt zu behandeln (Standard ist false).

// geschlossenes Rechteck:
addPolyline([[0,0], [100,0], [100,50], [0,50]], true);

// Langloch mit zwei Halbkreisen:
addPolyline([[0,60], [80,60,1], [80,80], [0,80,1]], true);

// Zickzacklinie mit relativen Koordinaten:
addPolyline([[0,100], [10,10], [10,-10], [10,10], [10,-10]], false, true);

addSpline

addSpline(fitPoints, closed)

Fügt einen Spline durch die angegebenen Anpassungspunkte hinzu. fitPoints ist ein Array von [x, y]-Arrays oder RVector-Objekten. Ist closed gleich true, wird der Spline geschlossen (periodisch).

// offener Spline:
addSpline([[0,0], [30,40], [60,0], [90,40]], false);

// geschlossener Spline:
addSpline([[0,60], [40,80], [80,60], [40,100]], true);

Das Tutorial Skripte aus einer Datei ausführen zeigt ein weiteres Beispiel, das eine Lissajous-Kurve als Spline plottet.

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)

Fügt an der angegebenen Position einen einzeiligen Text hinzu. Alle Argumente nach der Position sind optional:

• height: Texthöhe (Standard 1)
• angle: Textwinkel in Grad (Standard 0)
• font: Name der Schriftart (Standard "Standard")
• vAlign: vertikale Ausrichtung: RS.VAlignTop (Standard), RS.VAlignMiddle, RS.VAlignBase oder RS.VAlignBottom
• hAlign: horizontale Ausrichtung: RS.HAlignLeft (Standard), RS.HAlignCenter oder RS.HAlignRight
• bold, italic: true für fetten oder kursiven Text (nur TrueType-Schriftarten)

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

Fügt eine gefüllte Fläche (2D-Volumenkörper) mit drei oder vier Ecken hinzu. Beachten Sie, dass die Ecken eines vierseitigen 2D-Volumenkörpers in Zickzack-Reihenfolge angegeben werden: erste Ecke, zweite Ecke, dann die der zweiten Ecke gegenüberliegende Ecke und die der ersten Ecke gegenüberliegende Ecke. Um ein Dreieck zu erstellen, übergeben Sie die dritte Ecke zweimal.

// gefülltes Quadrat:
addSolid(0,0, 50,0, 0,50, 50,50);

// gefülltes Dreieck:
addSolid([60,0], [110,0], [85,50], [85,50]);

Formen, Zeichnungsobjekte und Objekte hinzufügen

Die folgenden Funktionen fügen der Zeichnung Objekte hinzu, die mit der vollständigen QCAD-API erstellt wurden. Sie sind nützlich, wenn die oben beschriebenen spezialisierten Erstellungsfunktionen einen bestimmten Fall nicht abdecken.

addShape

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

Fügt die angegebene Form (RLine, RArc, RCircle, REllipse, RPolyline, RSpline, RPoint, …) als neues Objekt auf dem aktuellen Layer hinzu. Optional können eine Farbe (RColor), ein Linientyp (Name oder ID) und eine Linienbreite (zum Beispiel RLineweight.Weight050) angegeben werden. Standardmässig werden die aktuelle Farbe, der Linientyp ByLayer und die Linienbreite ByLayer verwendet.

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)

Fügt alle Formen im angegebenen Array als neue Objekte hinzu.

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)

Fügt das angegebene Objekt (REntity) zur Zeichnung hinzu. Wird keine Farbe angegeben, wird die aktuelle Farbe verwendet.

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)

Fügt ein beliebiges Objekt (Zeichnungsobjekt, Layer, Block, …) zur Zeichnung hinzu und gibt das hinzugefügte Objekt zurück.

// einen Block namens "Marker" mit einem Kreuz darin hinzufügen:
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);

// den Block zweimal einfügen:
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)

Löscht das angegebene Objekt aus der Zeichnung. Zum Löschen von Zeichnungsobjekten ist die Funktion deleteEntity meist bequemer.

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

Layer und Attribute

addLayer

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

Fügt einen neuen Layer mit dem angegebenen Namen hinzu. Optional können der Farbname (Standard "white", wird auf weissem Hintergrund schwarz dargestellt), der Linientypname (Standard "CONTINUOUS") und die Linienbreite (Standard RLineweight.Weight000) angegeben werden. Gibt den neuen Layer zurück oder undefined, wenn bereits ein Layer mit dem angegebenen Namen existiert.

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

hasLayer

hasLayer(name)

Gibt true zurück, wenn in der Zeichnung ein Layer mit dem angegebenen Namen existiert.

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

setCurrentLayer

setCurrentLayer(name)

Legt den aktuellen Layer fest. Alle danach hinzugefügten Objekte werden auf diesem Layer platziert.

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

setCurrentColor

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

Legt die Farbe für Objekte fest, die danach hinzugefügt werden. Die Farbe kann als RColor-Objekt oder als Rot-, Grün- und Blauwerte (0-255) angegeben werden. Verwenden Sie new RColor(RColor.ByLayer), um die Farbe auf «Von Layer» zurückzusetzen.

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

Objekte abfragen

getEntity

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

Gibt das Objekt für die angegebene Objektreferenz zurück, d. h. das Objekt mit der angegebenen ID, den aktuellen Zustand des angegebenen Objekts oder das Objekt, das der angegebenen Position am nächsten liegt. Gibt undefined zurück, wenn kein Objekt gefunden wird.

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

// circle enthält noch den alten Mittelpunkt, getEntity gibt den aktuellen Zustand zurück:
getEntity(circle).getCenter();     // gibt 10,0 zurück

// Objekt, das 30,0 am nächsten liegt:
getEntity(30,0).getRadius();       // gibt 20 zurück

getShape

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

Gibt die Geometrie des angegebenen Objekts als Form zurück (RLine für eine Linie, RArc für einen Bogen, RPolyline für eine Polylinie, …). Formen können für geometrische Berechnungen verwendet werden, ohne die Zeichnung zu verändern.

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

var pl = getShape(50,0);
pl.getLength();                    // gibt 150 zurück

getClosestEntity

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

Gibt das Objekt zurück, das der angegebenen Position am nächsten liegt. Ist range angegeben, werden nur Objekte berücksichtigt, die innerhalb dieses Abstands von der Position liegen. Gibt undefined zurück, wenn kein Objekt gefunden wird.

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

getClosestEntity(50,10).getStartPoint();     // gibt 0,0 zurück
getClosestEntity([50,25], 5);               // gibt undefined zurück

getEntityShape

getEntityShape(entity, position)

Gibt die Form des angegebenen Objekts zurück. Bei komplexen Objekten, die aus mehreren Formen bestehen (Blockreferenzen, Schraffuren, Bemassungen, Texte), wird die Form zurückgegeben, die der angegebenen Position am nächsten liegt. Die Position ist optional.

// eine Blockreferenz eines Blocks mit einem Rechteck:
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)));

// Form der Blockreferenz in der Nähe von 40,10 (das Rechteck):
var s = getEntityShape(getEntity(ref), new RVector(41,10));
s.getLength();                     // gibt 120 zurück

getIntersectionPoints

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

Gibt ein Array mit den Schnittpunkten der beiden angegebenen Objekte oder Formen zurück. Objekte können als Objekte, Objekt-IDs oder Formen angegeben werden. Ist limited gleich false, werden die Objekte so behandelt, als wären sie unendlich (Linien verlängert, Bögen als Vollkreise). Standard ist true.

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

// die Schnittpunkte mit kleinen Kreisen markieren:
for (var i=0; i<ips.length; i++) {
    addCircle(ips[i], 2);
}

isPosition und toVector

isPosition(value)
toVector(value)

isPosition gibt true zurück, wenn der angegebene Wert eine Position ist (RVector oder Array mit zwei oder drei Zahlen). toVector wandelt eine als Array angegebene Position in einen RVector um. Diese Funktionen sind nützlich, wenn Sie eigene Funktionen schreiben, die Positionen auf dieselbe Weise akzeptieren wie die 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]);                 // gibt true zurück
isPosition("abc");                 // gibt false zurück

Objekte bearbeiten

Transformationen

move

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

Verschiebt das angegebene Objekt um den angegebenen Versatz.

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

rotate

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

Rotiert das angegebene Objekt um den angegebenen Winkel in Grad um das angegebene Zentrum. Wird kein Zentrum angegeben, wird das Objekt um den Ursprung 0,0 rotiert.

// ein Fächer aus Linien, rotiert um 0,0:
for (var a=0; a<360; a+=30) {
    var l = addLine(10,0, 50,0);
    rotate(l, a);
}

// ein Quadrat um seinen Mittelpunkt rotieren:
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])

Skaliert das angegebene Objekt um den angegebenen Faktor. Der Fokuspunkt (der Punkt, der an seinem Platz bleibt) ist standardmässig der Ursprung 0,0. Unterschiedliche Faktoren für X und Y können als Array [sx, sy] angegeben werden. Beachten Sie, dass einige Objekte wie Kreise und Bögen nicht mit unterschiedlichen Faktoren in X und Y skaliert werden können.

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 das angegebene Objekt an der durch zwei Punkte definierten Achse.

var pl = addPolyline([[10,0], [40,0], [40,30]], false);
// an der Y-Achse spiegeln:
mirror(pl, 0,0, 0,100);

Um das Original zu behalten und eine gespiegelte Kopie zu erstellen, fügen Sie zuerst eine Kopie des Objekts hinzu:

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

Trimmen und Verlängern

trim

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

Trimmt das Objekt trimEntity am limitierenden Objekt limitingEntity. Der Teil des getrimmten Objekts an der Klickposition trimPos bleibt erhalten. Schneiden sich die beiden Objekte nicht, wird das Objekt bis zum limitierenden Objekt verlängert. Gibt es mehrere Schnittpunkte, wird derjenige verwendet, der der Klickposition limitingPos am nächsten liegt. Ist trimBoth gleich true, werden beide Objekte aneinander getrimmt.

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

// den linken Teil behalten, die Linie endet nun bei 70,0:
trim(line, [10,0], limit);

// eine Linie bis zu einem Kreis verlängern:
var line = addLine(0,0, 50,0);
var circle = addCircle(100,0, 20);

// bis zum Schnittpunkt mit dem Kreis verlängern, der 80,0 am nächsten liegt:
trim(line, [25,0], circle, [80,0]);      // die Linie endet nun bei 80,0

trimBoth

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

Trimmt oder verlängert beide Objekte bis zu ihrem Schnittpunkt. Dies ist eine Kurzform für trim mit trimBoth gleich true.

// zwei Linien, die sich nicht berühren, werden verlängert und bilden eine Ecke bei 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)

Verlängert das angegebene Objekt um den angegebenen Betrag. Negative Beträge verkürzen das Objekt. Standardmässig wird das Objekt an seinem Endpunkt verlängert. Übergeben Sie true für start, um es stattdessen an seinem Startpunkt zu verlängern, oder übergeben Sie eine Position in der Nähe des Endes, das verlängert werden soll.

var line = addLine(0,0, 100,0);
lengthen(line, 20);              // die Linie endet nun bei 120,0
lengthen(line, true, -10);       // die Linie beginnt nun bei 10,0

var arc = addArc(0,50, 30, 0, 90);
lengthen(arc, [30,50], 10);      // den Bogen an seinem Startpunkt verlängern

breakOut

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

Bricht das Segment des angegebenen Objekts an der angegebenen Position aus. Das Segment endet an den nächstgelegenen Schnittpunkten mit anderen Objekten auf beiden Seiten der Position. Gibt es auf einer Seite keinen Schnittpunkt, reicht das Segment bis zum Ende des Objekts. Ist removeSegment gleich true (Standard), wird das Segment gelöscht. Andernfalls bleibt es als separates Objekt erhalten.

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

// den Teil der Linie zwischen 30,0 und 70,0 entfernen:
breakOut(line, [50,0]);

autoTrim

autoTrim(entity, pos)
autoTrim(pos)

Das Gegenteil von breakOut: Behält nur das Segment des angegebenen Objekts an der angegebenen Position und entfernt den Rest. Das Segment endet an den nächstgelegenen Schnittpunkten mit anderen Objekten auf beiden Seiten der Position.

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

// nur den Teil zwischen 30,0 und 70,0 behalten:
autoTrim(line, [50,0]);

divide

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

Trennt das angegebene Objekt an der angegebenen Position. Ein offenes Objekt (Linie, Bogen, offene Polylinie, …) wird an einer Position in zwei Teile oder an zwei Positionen in drei Teile getrennt. Geschlossene Objekte (Kreise, vollständige Ellipsen, geschlossene Polylinien) erfordern zwei Positionen und werden in zwei Teile getrennt.

var line = addLine(0,0, 100,0);
divide(line, [40,0]);            // zwei Linien: 0..40 und 40..100

var circle = addCircle(0,50, 20);
divide(circle, [20,50], [-20,50]);   // zwei Halbkreise

Ecken

round

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

Rundet die Ecke zwischen zwei Objekten mit einem Bogen des angegebenen Radius (Verrundung). Die Klickpositionen geben an, welche Enden der Objekte gerundet werden. Ist trim gleich true (Standard), werden beide Objekte am Rundungsbogen getrimmt.

// ein Rechteck mit gerundeten Ecken:
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);

Auch die Ecken einer Polylinie können gerundet werden, indem dieselbe Polylinie zweimal übergeben wird, mit je einer Klickposition auf jedem der beiden Segmente:

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

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

Schrägt die Ecke zwischen zwei Objekten mit einer geraden Linie ab (Fase). distance1 ist der Abstand der Fasenlinie von der Ecke entlang des ersten Objekts, distance2 entlang des zweiten Objekts (Standard ist distance1). Ist trim gleich true (Standard), werden beide Objekte an der Fasenlinie getrimmt. chamfer ist ein Alias für 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)

Erstellt Parallelen zu Linien, konzentrische Bögen und Kreise oder Äquidistanten (parallele Kurven) von Ellipsen und anderen Objekten. number ist die Anzahl der zu erstellenden Parallelen (Standard 1). Die Parallelen werden auf beiden Seiten des Objekts erstellt, es sei denn, es wird eine Seite angegeben, entweder als Position sidePos neben dem Objekt oder als side (RS.LeftHand, RS.RightHand oder RS.BothSides). Äquidistanten zu Polylinien und Splines sind nur in QCAD Professional verfügbar.

var line = addLine(0,0, 100,0);
offset(line, 5);                 // je eine Parallele auf jeder Seite

var line2 = addLine(0,30, 100,30);
offset(line2, 5, 2, RS.LeftHand);    // zwei Parallelen auf der linken Seite (oberhalb)

var circle = addCircle(50,80, 10);
offset(circle, [50,95], 3, 4);   // vier konzentrische Kreise aussen

reverse

reverse(entity)
reverse(x, y)

Kehrt die Richtung des angegebenen Objekts um, d. h. vertauscht seinen Start- und Endpunkt.

var line = addLine(0,0, 100,0);
line = reverse(line);
line.getStartPoint();            // gibt 100,0 zurück

explode

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

Bricht das angegebene Objekt in einfachere Objekte auf: Polylinien in Linien und Bögen, Blockreferenzen in ihren Inhalt, Texte in Linien und Splines, Bemassungen und Schraffuren in Linien, Bögen usw. Das ursprüngliche Objekt wird gelöscht.

options ist ein optionales Objekt mit Einstellungen, die andernfalls aus den Applikationseinstellungen übernommen werden, zum Beispiel { splineSegments: 64, textToPolylines: true }. Unterstützte Optionen sind: splineTolerance, splineSegments, ellipseSegments, splinesToLineSegments, textToPolylines, textSplineToLineOrArc, multilineTextToSimpleText und circlesToPolylines.

var pl = addPolyline([[0,0], [100,0,1], [100,50], [0,50]], true);
explode(pl);                     // drei Linien und ein Bogen

stretch

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

Streckt alle Objekte im rechteckigen Bereich, der durch zwei Ecken definiert ist, um den angegebenen Versatz. Objekte, die vollständig innerhalb des Bereichs liegen, werden verschoben, Objekte, welche die Grenze des Bereichs kreuzen, werden gestreckt (nur die Endpunkte innerhalb des Bereichs werden verschoben). Der Bereich kann auch als RBox oder als geschlossene RPolyline-Form angegeben werden. Sind in der Zeichnung Objekte selektiert, werden nur die selektierten Objekte gestreckt.

// ein Rechteck aus Linien:
addLine(0,0, 100,0);
addLine(100,0, 100,50);
addLine(100,50, 0,50);
addLine(0,50, 0,0);

// das Rechteck um 50 Einheiten breiter machen, indem seine rechte Seite gestreckt wird:
stretch([80,-10], [120,60], [50,0]);

deleteEntity

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

Löscht das angegebene Objekt aus der Zeichnung.

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

deleteEntity(l1);                // über das Objekt
deleteEntity(l2.getId());        // über die Objekt-ID
deleteEntity(50,20);             // über die Position

paste

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

Fügt den Inhalt des Dokuments sourceDocument in die Dokumentschnittstelle destination ein oder in die aktuelle Zeichnung, wenn destination gleich undefined ist. Der eingefügte Inhalt wird um offset verschoben, um scale skaliert und um rotation Grad rotiert. Alle Argumente sind erforderlich:

• flipHorizontal, flipVertical: true, um den Inhalt zu spiegeln
• toCurrentLayer: true, um alle Objekte auf dem aktuellen Layer einzufügen
• overwriteLayers, overwriteBlocks: true, um bestehende Layer oder Blöcke mit demselben Namen zu überschreiben

// ein Symbol in einem nicht angezeigten Dokument erstellen:
var symbol = createDocument();
startTransaction(symbol);
addCircle(0,0, 10);
addLine(-10,0, 10,0);
addLine(0,-10, 0,10);
endTransaction();

// es dreimal in die aktuelle Zeichnung einfügen:
for (var i=0; i<3; i++) {
    paste(symbol, undefined, [i*50, 0], 1+i*0.5, i*15, false, false, false, false, false);
}

Transaktionen

startTransaction und endTransaction

startTransaction()
startTransaction(document)
endTransaction()

Standardmässig wird jeder Aufruf der Simple API sofort auf die Zeichnung angewendet und kann einzeln rückgängig gemacht werden. Zwischen startTransaction() und endTransaction() werden alle Änderungen gesammelt und gemeinsam angewendet, wenn endTransaction aufgerufen wird. Dies hat zwei Vorteile:

• Es ist viel schneller, wenn viele Objekte hinzugefügt werden.
• Alle Änderungen können in einem einzigen Schritt rückgängig gemacht werden.

Wird ein Dokument (RDocument) oder eine Dokumentschnittstelle (RDocumentInterface) an startTransaction übergeben, werden alle Änderungen auf dieses Dokument statt auf die aktuelle Zeichnung angewendet. Dies ist nützlich, um Zeichnungen im Hintergrund zu erstellen, zum Beispiel um sie in eine Datei zu exportieren (siehe createDocumentInterface).

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

Beachten Sie Folgendes beim Arbeiten mit Transaktionen:

• Innerhalb einer Transaktion sind die Änderungen noch nicht Teil der Zeichnung. Bearbeitungsfunktionen wie trim oder round können sich nicht auf Objekte beziehen, die in derselben Transaktion hinzugefügt wurden.
• Objekte, die von Erstellungsfunktionen innerhalb einer Transaktion zurückgegeben werden, haben keine gültige ID, auch nicht nach endTransaction. Um solche Objekte später zu bearbeiten, referenzieren Sie sie über ihre Position.
• Alle innerhalb einer Transaktion hinzugefügten Objekte werden auf dem Layer platziert, der beim Aufruf von endTransaction aktuell ist. Legen Sie den aktuellen Layer vor dem Start der Transaktion fest und verwenden Sie separate Transaktionen für verschiedene Layer.

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

// die neuen Linien über ihre Position referenzieren, um die Ecke zu runden:
round([50,0], [100,25], 10);

getTransactionDocument und getTransactionDocumentInterface

getTransactionDocument()
getTransactionDocumentInterface()

Geben das Dokument bzw. die Dokumentschnittstelle zurück, auf die sich die aktuelle Transaktion bezieht. Ausserhalb von Transaktionen werden das aktuelle Dokument und die aktuelle Dokumentschnittstelle zurückgegeben.

var doc = createDocument();
startTransaction(doc);
addLine(0,0, 10,0);
getTransactionDocument() === doc;    // gibt true zurück
endTransaction();

getOperation

getOperation()

Gibt die Operation (RAddObjectsOperation) der aktuellen Transaktion zurück. Ausserhalb einer Transaktion wird eine neue Operation zurückgegeben, die explizit angewendet werden muss. Dies ist für fortgeschrittene Anwendungen gedacht, zum Beispiel um Aufrufe der Simple API mit der vollständigen QCAD-API zu kombinieren.

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

Ansicht

autoZoom

autoZoom()

Zoomt die aktuelle Ansicht so, dass die gesamte Zeichnung sichtbar ist.

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 auf das angegebene Objekt, die angegebene Form oder den angegebenen rechteckigen Bereich. margin ist der Rand um den Bereich in Pixeln (Standard 10).

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

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

Dokumente und Anwendung

getMainWindow

getMainWindow()

Gibt das QCAD-Anwendungsfenster (RMainWindowQt) zurück.

getMainWindow().windowTitle;

getDocumentInterface

getDocumentInterface()

Gibt die Dokumentschnittstelle (RDocumentInterface) der aktuellen Zeichnung zurück. Die Dokumentschnittstelle verbindet ein Dokument mit seinen Ansichten und stellt Funktionen zum Importieren und Exportieren von Dateien, zum Anwenden von Operationen sowie zum Rückgängigmachen und Wiederherstellen bereit.

addLine(0,0, 100,0);
getDocumentInterface().undo();       // entfernt die Linie wieder

getDocument

getDocument()

Gibt das aktuelle Dokument (RDocument) zurück. Das Dokument enthält alle Objekte, Layer, Blöcke usw. einer Zeichnung und stellt Funktionen zu deren Abfrage bereit.

addLine(0,0, 100,0);
addCircle(0,0, 10);
getDocument().queryAllEntities().length;     // Anzahl der Objekte in der Zeichnung

getGraphicsView

getGraphicsView()

Gibt die aktuelle oder zuletzt aktive Ansicht (RGraphicsView) der aktuellen Zeichnung zurück.

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

createDocument

createDocument()

Erstellt ein neues, leeres Dokument im Speicher, das in keinem Fenster angezeigt wird. Ein solches nicht angezeigtes Dokument kann mit einer Transaktion gefüllt und dann in eine Zeichnung eingefügt werden (siehe paste).

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

doc.queryAllEntities().length;       // gibt 2 zurück

createDocumentInterface

createDocumentInterface()

Erstellt ein neues, leeres Dokument im Speicher zusammen mit einer Dokumentschnittstelle. Die Dokumentschnittstelle kann zum Importieren oder Exportieren von Dateien verwendet werden.

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

disableInput()
enableInput()
isInputEnabled()

disableInput deaktiviert das QCAD-Anwendungsfenster, um Benutzereingaben zu verhindern, zum Beispiel während langer Operationen oder Animationen. enableInput aktiviert das Anwendungsfenster wieder, und isInputEnabled gibt true zurück, wenn Benutzereingaben aktuell aktiviert sind. Stellen Sie immer sicher, dass die Eingabe am Ende Ihres Skripts wieder aktiviert wird.

update

update()

Verarbeitet anstehende Ereignisse, damit die Benutzeroberfläche während langer Operationen aktualisiert wird. Benutzereingaben müssen vor dem Aufruf von update mit disableInput deaktiviert werden.

sleep

sleep(milliseconds)

Hält das Skript für die angegebene Zeit in Millisekunden an und hält dabei die Benutzeroberfläche auf dem neuesten Stand. Benutzereingaben müssen vor dem Aufruf von sleep mit disableInput deaktiviert werden.

Das folgende Beispiel verwendet disableInput, sleep und enableInput, um eine einfache Animation anzuzeigen:

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)

Zeigt eine Warnmeldung an. In der Skriptshell werden Warnungen in der Befehlszeilen-Historie angezeigt. Andernfalls werden Warnungen auf der Konsole ausgegeben.

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

Benutzereingaben

Die folgenden Funktionen zeigen einen einfachen Dialog an, um den Benutzer nach einem Wert zu fragen. Bricht der Benutzer den Dialog ab, wird undefined zurückgegeben.

getInt

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

Fragt den Benutzer nach einer Ganzzahl. value ist der Anfangswert (Standard 0), step die Schrittweite des Drehfelds (Standard 1), min und max der zulässige Bereich.

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)

Fragt den Benutzer nach einer Zahl. value ist der Anfangswert (Standard 0), decimals die Anzahl der angezeigten Dezimalstellen (Standard 1), min und max der zulässige Bereich.

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

getText

getText(title, prompt, text)

Fragt den Benutzer nach einem Text. text ist der Anfangstext (Standard leer).

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

getItem

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

Lässt den Benutzer einen Eintrag aus einer Dropdown-Liste auswählen. items ist ein String mit allen Einträgen, getrennt durch separator (Standard ","). index ist der Index des anfangs ausgewählten Eintrags (Standard 0). Gibt den gewählten Eintrag zurück oder undefined, wenn der Dialog abgebrochen wurde.

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

Beispiel: Ein Flansch

Dieses Beispiel kombiniert mehrere Funktionen der Simple API, um einen Flansch mit einem Lochkreis, Schraubenlöchern auf einem separaten Layer und einer abgerundeten rechteckigen Aussparung zu zeichnen:

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

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

// Lochkreis und Mittellinien:
setCurrentLayer("Center Lines");
addCircle(0,0, 75);
addLine(-110,0, 110,0);
addLine(0,-110, 0,110);

// Schraubenlöcher, in einer Transaktion hinzugefügt:
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();

// abgerundete quadratische Aussparung in der Mitte:
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();

Die Linien der Aussparung werden ohne Transaktion hinzugefügt, damit sie direkt an round übergeben werden können. Die Schraubenlöcher werden in einer Transaktion hinzugefügt, was schneller ist und es ermöglicht, sie in einem Schritt rückgängig zu machen.