QCad Scripting Manual

4 Getting Started

Creating Scripts

To create new scripts for QCad, you can use any plain text editor you prefer. You can also use the Integrated Development Environment of QCad, but if you are familiar with a better editor, feel free to use that instead.

Header

Although not necessary, every script should start with a comment describing its function and author. Comment sections start with /* and end with */, as shown below.

/**
* Demonstrates some basic scripting functions of QCad.
*
* Author: Tux
* Date: 2005/01/27
*/

This header is completely optional, but it is strongly recommended to include at least your name and the date of last modification.

The Main Function

Every script needs at least one function in order to be runnable. This function is the start point of execution when the script is run. It may call other functions that are defined in the same source file. To avoid confusion, it's a good idea to always call this function 'main'. The main function does not have any parameters. It is defined as shown below:

function main() {
// code...
}

With this declaration alone you already have a runnable script. It won't do anything, but main() should be callable and not produce any errors.

Initializing Important Objects

When writing a script for QCad you will most likely want to access the current drawing document (for example to add new entities). The current document can be accessed by creating a variable and initializing it to be a document:

var doc;
doc = new Document;

This might look like creating a new document, but all it does is to create a new scripting wrapper for the current drawing document. After this initialization, you can use the functions of the Document class to modify the document.

If you want to add a line from position 10,30 to 55,75, as an example, use the following code:

var line = new Line(doc, 10,30, 55,75);
doc.addEntity(line);

Here's the whole script again to add a line to the current document:

/**
* Demonstrates some basic scripting functions of QCad.
*
* Author: Tux
* Date: 2005/01/27
*/
function main() {
    var doc;

    doc = new Document;

    var line = new Line(doc, 10,30, 55,75);
    doc.addEntity(line);
}

If you try this script, you will most likely realize that the line does not appear on the screen. However, if you refresh the screen, for example by doing an auto zoom, the line is there. What happens is, that the line is added but the graphics view is not updated. To do that automatically too, you need another object: the View object:

var view;
view = new View;

Similar like with the document this does not create a new view but simply a wrapper for the current graphics view. Now you can use the view object to refresh the view automatically after adding the line:

/**
* Demonstrates some basic scripting functions of QCad.
*
* Author: Tux
* Date: 2005/01/27
*/
function main() {
    var doc;
    var view;

    doc = new Document;
    view = new View;

    var line = new Line(doc, 10,30, 55,75);
    doc.addEntity(line);

    view.redraw();
}

With this simple example you already see how scripting usually works. All you have to know now, is what other objects there are and what functions they offer. The next couple of chapters will give you an overview of the most important objects and functions.