Interaktiivsed skriptitegevused

Sissejuhatus

Skriptitegevused on skriptid, mis lisavad kirje menüüsse ja/või tööriistaribale ning suudavad käsitleda kasutaja suhtlust. Skriptitegevused jäävad aktiivseks, kuni kasutaja need lõpetab või kuni need ise lõpetavad.

Sündmused

Niipea kui skriptitegevus käivitatakse, käsitleb see mitmesuguseid sündmusi kuni lõpetamiseni. Sündmus on midagi, mis toimub siis, kui midagi juhtub. Näiteks kui skriptitegevus käivitatakse, kutsutakse beginEvent. Kui kasutaja klõpsab objektil, käivitub sündmus pickEntity, kui kasutaja klõpsab koordinaadil, toimub sündmus pickCoordinate jne.

Skriptitegevuse minimaalne struktuur on järgmine:

include("scripts/EAction.js");

function ExMyMinimal(guiAction) {
    EAction.call(this, guiAction);
}

ExMyMinimal.prototype = new EAction();

ExMyMinimal.init = function(basePath) {
    var action = new RGuiAction(qsTr("&Minimal Example"), RMainWindowQt.getMainWindow());
    action.setRequiresDocument(true);
    action.setScriptFile(basePath + "/ExMyMinimal.js");
    action.setGroupSortOrder(100000);
    action.setSortOrder(0);
    action.setWidgetNames(["ExamplesMenu"]);
};

See näidisskript lisab menüü Muu > Näited alaossa. Menüü tekst on “Minimal Example”.

Pange tähele, et selleks, et skript leitaks, peab failinimi ühtima klassi nimega, st antud juhul “ExMyMinimal.js”. Samuti peab see asuma sama nimega kataloogis “ExMyMinimal”, nii et selle skripti võib näiteks paigutada asukohta scripts/Misc/ExMyMinimal/ExMyMinimal.js.

Samuti saate paigutada oma skriptid kohalikku kausta scripts oma kodukaustas. Täpse kausta väljaselgitamiseks avage teabedialoog (Abi > QCAD-ist…) ja minge vahekaardile Süsteem. Seal näete andmete asukohta kirje Data directory juures. See on kataloog, mille alla peate looma alamkausta nimega scripts ning selle sisse alamkaustad, üks kaust iga skriptitööriista kohta, näiteks /tee/andmekataloogini/scripts/MyScripts/MyScript1/MyScript1.js

Täpne asukoht sõltub teie süsteemist ja selle seadistusest.

beginEvent’i lisamine

Ülalolev skript on täielikult töötav ja seda saab käivitada. Käivitamisel ei tee see aga tegelikult midagi. Pealegi jääb skript pärast käivitamist aktiivseks, kuni kasutaja selle parema hiireklõpsuga lõpetab. Selle muutmiseks rakendame beginEvent’i, et printida midagi QCAD-i käsuajalukku ja tegevus lõpetada:

include("scripts/EAction.js");

function ExMyMinimal(guiAction) {
    EAction.call(this, guiAction);
}

ExMyMinimal.prototype = new EAction();

ExMyMinimal.prototype.beginEvent = function() {
    EAction.prototype.beginEvent.call(this);

    EAction.handleUserMessage("Hello World!");

    this.terminate();
};

ExMyMinimal.init = function(basePath) {
    var action = new RGuiAction(qsTr("&Minimal Example"), RMainWindowQt.getMainWindow());
    action.setRequiresDocument(true);
    action.setScriptFile(basePath + "/ExMyMinimal.js");
    action.setGroupSortOrder(100000);
    action.setSortOrder(0);
    action.setWidgetNames(["ExamplesMenu"]);
};

Kui tööriist Muu > Näited > Minimal Example nüüd käivitatakse, prindib see käsuajalukku “Hello World!” (rida 12) ja seejärel lõpetab (rida 14).

Kui skript ei vaja mingit kasutaja suhtlust, saab sellist skripti kasutada menüü lisamiseks, mis teeb midagi ära ja seejärel lõpetab. Selliste tegevuste näited on Vaade > Automaatne suum, Vali > Vali kõik, Redigeeri > Kustuta jne.

Suhtluse lisamine

Niipea kui skript vajab mingit kasutaja suhtlust, peame rakendama rohkem sündmusekäsitlejaid ja andma skriptile teada, mida kasutaja peab järgmisena tegema (nt objekti valimine või koordinaadi määramine). Järgmises sammus siseneme olekusse, milles tegevus ootab kasutajalt koordinaati. Seejärel joonistame ringi igasse asukohta, kuhu kasutaja klõpsab või mille sisestab.

include("scripts/EAction.js");

function ExMyMinimal(guiAction) {
    EAction.call(this, guiAction);

    this.pos = undefined;
}

ExMyMinimal.prototype = new EAction();

ExMyMinimal.prototype.beginEvent = function() {
    EAction.prototype.beginEvent.call(this);

    var di = this.getDocumentInterface();
    di.setClickMode(RAction.PickCoordinate);
};

ExMyMinimal.prototype.pickCoordinate = function(event, preview) {
    this.pos = event.getModelPosition();

    if (preview) {
        this.updatePreview();
    }
    else {
        this.applyOperation();
    }
};

ExMyMinimal.prototype.getOperation = function(preview) {
    var doc = this.getDocument();

    var op = new RAddObjectOperation();
    var circle = new RCircle(this.pos, 1);
    op.addObject(shapeToEntity(doc, circle));
    return op;
};

ExMyMinimal.init = function(basePath) {
    var action = new RGuiAction(qsTr("&Minimal Example"), RMainWindowQt.getMainWindow());
    action.setRequiresDocument(true);
    action.setScriptFile(basePath + "/ExMyMinimal.js");
    action.setGroupSortOrder(100000);
    action.setSortOrder(0);
    action.setWidgetNames(["ExamplesMenu"]);
};

beginEvent’is me ei lõpeta tegevust enam kohe, vaid laseme sellel töötada, kuni kasutaja selle lõpetab (parem klõps või Escape). Seejärel rakendame pickCoordinate’i, et salvestada hiirekursori asukoht või sisestatud koordinaat ning kas uuendada eelvaadet või rakendada operatsioon (st lisada ring). pickCoordinate’i kutsutakse iga kord, kui kasutaja liigutab hiirt, et kuvada kavandatava operatsiooni eelvaade. Kui kasutaja klõpsab või sisestab koordinaadi, kutsutakse seda parameetriga preview väärtusega false, mis näitab, et lõplik koordinaat on valitud või sisestatud.

updatePreview real 22 kuvab getOperation’i tagastatud operatsiooni eelvaate, samas kui applyOperation real 25 tegelikult rakendab operatsiooni meie dokumendile.

getOperation tuleb rakendada nii, et see tagastaks operatsiooni, mille eelvaadet kuvada või mida dokumendile rakendada. See on veidi keerukam kui see, mida nägime ülal lihtsa API puhul. Seda seetõttu, et üht operatsiooni saab kasutada mitme objekti lisamiseks, objektide muutmiseks või objektide kustutamiseks.

Vidinate lisamine valikute tööriistaribale

Meie näites joonistatud ringil on alati raadius 1 joonistusühik (vt rida 33). Järgmises sammus tahame lubada kasutajal sisestada ringi raadiuse. QCAD kasutab selliste tööriistaparameetrite kuvamiseks ja muutmiseks tavaliselt ülal olevat valikute tööriistariba. Selleks peame määrama, milliseid vidinaid tahame valikute tööriistaribal kuvada ja milliseid parameetreid need juhivad. Seda saab teha UI-failiga, XML-failiga, mis määratleb vidina ja selle sisu. UI-faile saab mugavalt kujundada tarkvaraga nimega Qt Designer, mis on Qt tööriistakomplekti osa. Selles näites kasutame lihtsat UI-faili, mille saab luua ka tekstiredaktoris (fail ExMyMinimal.ui):

<?xml version="1.0" encoding="UTF-8"?>
<ui version="4.0">
    <class>ExMyMinimal</class>
    <widget class="QWidget" name="ExMyMinimal">
        <layout class="QHBoxLayout">
            <item>
                <widget class="QLabel" name="RadiusLabel">
                    <property name="text">
                        <string>&amp;Radius:</string>
                    </property>
                    <property name="buddy">
                        <cstring>Radius</cstring>
                    </property>
                </widget>
            </item>
            <item>
                <widget class="RMathLineEdit" name="Radius">
                    <property name="text">
                        <string notr="true">1</string>
                    </property>
                </widget>
            </item>
        </layout>
    </widget>
    <customwidgets>
        <customwidget>
            <class>RMathLineEdit</class>
            <extends>QLineEdit</extends>
            <header>RMathLineEdit.h</header>
        </customwidget>
    </customwidgets>
    <resources/>
    <connections/>
</ui>

UI-fail määratleb kaks vidinat: sildi (QLabel) ja tekstivälja (RMathLineEdit). Oluline on tekstivälja nimi (“Radius”). Vidin lingitakse selle nime kaudu automaatselt meie skriptiga. Kõik, mida peame skriptis tegema, on määrata, millist UI-faili tahame kasutada (rida 9), ja rakendada uus sündmusekäsitleja nimega slotRadiusChanged, see on “slot” + [meie tekstivälja nimi] + “Changed” (rida 45):

include("scripts/EAction.js");

function ExMyMinimal(guiAction) {
    EAction.call(this, guiAction);

    this.pos = undefined;
    this.radius = undefined;

    this.setUiOptions("ExMyMinimal.ui");
}

ExMyMinimal.prototype = new EAction();

ExMyMinimal.prototype.beginEvent = function() {
    EAction.prototype.beginEvent.call(this);

    var di = this.getDocumentInterface();
    di.setClickMode(RAction.PickCoordinate);
};

ExMyMinimal.prototype.pickCoordinate = function(event, preview) {
    this.pos = event.getModelPosition();

    if (preview) {
        this.updatePreview();
    }
    else {
        this.applyOperation();
    }
};

ExMyMinimal.prototype.getOperation = function(preview) {
    if (isNull(this.pos) || isNull(this.radius)) {
        return undefined;
    }

    var doc = this.getDocument();

    var op = new RAddObjectOperation();
    var circle = new RCircle(this.pos, this.radius);
    op.addObject(shapeToEntity(doc, circle));
    return op;
};

ExMyMinimal.prototype.slotRadiusChanged = function(v) {
    this.radius = v;
    this.updatePreview();
};

ExMyMinimal.init = function(basePath) {
    var action = new RGuiAction(qsTr("&Minimal Example"), RMainWindowQt.getMainWindow());
    action.setRequiresDocument(true);
    action.setScriptFile(basePath + "/ExMyMinimal.js");
    action.setGroupSortOrder(100000);
    action.setSortOrder(0);
    action.setWidgetNames(["ExamplesMenu"]);
};

Seda uut funktsiooni slotRadiusChanged kutsutakse iga kord, kui kasutaja sisestab uue raadiuse. See seab liikmemuutuja this.radius, mida omakorda kasutatakse ringi loomisel funktsioonis getOperation.

Kõik QCAD-i skriptid põhinevad ühel selles õpetuses kirjeldatud kontseptsioonil.

Kuna iga QCAD-i tööriist on kõige ülemisel tasemel realiseeritud skriptina, on saadaval palju näidisskripte. Need leiate meie git-hoidlast.