# &kappname; laiendamine

## Sissejuhatus

Nagu kõik rohkete võimalustega tekstiredaktorid pakub &kate; hulgaliselt võimalusi oma funktsionaalsust laiendada. Võib kirjutada lihtsaid skripte funktsionalsuse laiendamiseks JavaScripti abil, suurendada redaktorikomponendi funktsionaalsust redaktorikomponendi pluginatega või lausa täiendada redaktori enda funktsionaalsust &kate; rakenduse C++-keeles kirjutatud pluginatega või Pythonis kirjutatud &pate; pluginatega. Aga lõpuks, kui oled &kate; laiendamise alal midagi ära teinud, kutsume sind meiega liituma ja jagama oma täiendusi ka ülejäänud maailmaga!

## Skriptid JavaScriptiga

Alates &kappname; versioonist 3.4, mis tuleb koos &kde; 4.4-ga, saab &kappname; redaktorikomponenti hõlpsalt laiendada skriptidega. Skriptikeeleks on ECMAScript (rohkem tuntud kui JavaScript). &kappname; toetab kaht laadi skripte: taande- ja käsureaskriptid.

### Taandeskriptid

Taandeskriptid või ka treppimisskriptid annavad lähtekoodile selle kirjutamise ajal automaatselt vajaliku taande. Näiteks Enter-klahvi vajutades taandetase tihtipeale suureneb.

Järgnevates sektsioonides kirjeldame samm-sammult lihtsa taandeskripti loomist. Kõigepealt loo uus `*.js`-fail, näiteks `javascript.js` oma kohalikus kodukataloogi kataloogis `$KDEHOME/share/apps/katepart/script/indentation`.

#### Taandeskripti päis

Faili `javascript.js` on põimitud kommentaarina ning näeb välja selline:

    /* kate-script
     * name: JavaScript
     * author: Example Name <example.name@some.address.org>
     * license: BSD
     * revision: 1
     * kate-version: 3.4
     * required-syntax-style: javascript
     * type: indentation
     * required-syntax-style: javascript
     * indent-languages: javascript
     * priority: 0
     * i18n-catalog: mycatalog
     *
     * Rida ilma koolonita ':' peatab päise parsimise. See tähendab, et sa võid siia
     * lisada muud teksti, näiteks üksikasjaliku litsentsi.
     */

Allpool selgitatakse põhjalikult iga kirjet:

- `kate-script` [kohustuslik]: see tekstistring peab esinema `*.js`-faili esimesel real, vastasel juhul jätab &kappname; skripti lihtsalt vahele.

- `name` [kohustuslik]: see on taandeskripti nimi, nagu seda näeb menüüs Tööriistad Treppimine ja seadistustedialoogis.

- `author` [pole kohustuslik]: autori nimi ja kontaktteave.

- `license` [pole kohustuslik]: litsents lühidalt, näiteks BSD või LGPLv3.

- `revision` [kohustuslik]: skripti versioon. Seda arvu tuleb alati suurendada, kui skripti muudetakse.

- `kate-version` [kohustuslik]: &kappname; minimaalne nõutav versioon.

- `required-syntax-style` [pole kohustuslik]: komadega eraldatud nõutavate süntaksi esiletõstmise stiilide loend. See on oluline taandeskriptide puhul, mis toetuvad teatavale dokumendis leiduvale esiletõstmise teabele. Kui nõutav süntaksistiil on määratud, saab taandeskripti kasutada ainult siis, kui aktiivne on sobiv esiletõstmise skeem. See takistab sobimatut käitumist, mis võib tekkida, kui taandeskripti kasutatakse eeldatud esiletõstmise skeemita. Näiteks Ruby taandeskript kasutab sellist võimalust failides `ruby.js` ja `ruby.xml`.

- `indent-languages` [pole kohustuslik]: komadega eraldatud süntaksistiilide loend, mille puhul taandeskript suudab korrektselt treppimist rakendada, näiteks c++, java.

- `priority` [pole kohustuslik]: kui teatava esiletõstmisega faili puhul sobib mitu taandeskripti, siis prioriteet määrab, millist neist kasutatakse vaikimisi.

- `i18n-catalog` [pole kohustuslik]: täiendav tõlkesõnumite kataloog (`po`-fail), mis laaditakse kolmanda poole taandemääratluste tõlgete saamiseks.

&kappname; loeb kõik paarid `võti`:`väärtus`, kuni ei leia enam koolonit. See tähendab, et päis võib sisaldada suvalist teksti, näiteks litsentsi, nagu oli näha näites.

#### Taandeskripti lähtekood

Kui päis on defineeritud, siis siin osas saab aimu, kuidas töötab taandeskript ise. Põhimõtteliselt näeb see välja nii:

    // nõutavad katepart js teegid, nt. range.js, kui kasutad Range'i
    require ("range.js");

    triggerCharacters = "{}/:;";
    function indent(line, indentWidth, ch)
    {
        // called for each newline (ch == '\n') and all characters specified in
        // the global variable triggerCharacters. When calling ToolsAlign
        // the variable ch is empty, i.e. ch == ''.
        //
        // see also: Scripting API
        return -2;
    }

Funktsioonil `indent()` on kolm parameetrit:

- `line`: rida, mida asutakse treppima

- `indentWidth`: treppimise ehk taande laius tühimärkide arvuna

- `ch`: kas reavahetuse sümbol (`ch == '\n'`), käivitamissümbol, mille määrab kindlaks `triggerCharacters` või ka tühi, kui kasutaja kustub välja toimingu Tööriistad Joondamine.

Funktsiooni `indent()` tagastatav väärtus määrab, kuidas rida trepitakse. Kui tagastatud väärtus on lihtsalt täisarv, tõlgendatakse seda järgnevalt:

- tagastatud väärtus `-2`: ei tehta midagi

- tagastatud väärtus `-1`: säilitatakse taandus (otsitakse eelmist mittetühja rida)

- tagastatud väärtus `0`: arv >= 0 määrab taandesügavuse tühimärkide arvuna

Teise võimalusena tagastatakse kahest elemendist koosnev massiiv:

- `return [ indent, align ];`

Sel juhul on esimene element taandesügavus nagu ülal ja samade eriväärtustega. Teine element on aga absoluutväärtus, mis tähistab joonduse veergu. Kui see väärtus on suurem kui taande väärtus, tähistab nende erinevus tühimärkide arvu, mis tuleb lisada esimese parameetriga määratud taande järele. Muul juhul teist arvu eiratakse. Tabeldusmärkide ja tühimärkide kasutamist treppimisel nimetatakse sageli segarežiimiks.

Vaatame järgmist näidet. Eeldame, et treppimiseks kasutatakse tabeldusmärke ning nende laiuseks on määratud 4. <tab> tähistab tabeldusmärki ja '.' tühimärki:

    1: <tab><tab>foobar("hello",
    2: <tab><tab>......."world");

Teise taandega rea puhul tagastab funktsioon `indent()` [8, 15]. Seepärast lisatakse kaks tabeldusmärki veeru 8 treppimiseks ning 7 tühimärki teise parameetri joondamiseks esimese alla, et see oleks joondatud ka siis, kui faili vaadatakse mõne muu tabeldusmärgi laiusega.

&kde; vaikimisi paigalduse puhul pakub &kappname; mitut taandeskripti. Vastava JavaScripti lähtekoodi leiab kataloogist `$KDEDIR/share/apps/katepart/script/indentation`.

Taandeskripti arendamiseks tuleb skriptid taaslaadida, et näha, kas muudatused, mida nad teevad, on korrektsed. Terve rakenduse taaskäivitamise asemel lülitu lihtsalt käsureale ja anna käsk `reload-scripts`.

Kui lood mõne kasuliku skripti, võiksid kaaluda selle annetamist ka &kappname; hüvanguks. Selleks võib ühendust võtta postiloendis.

### Käsureaskriptid

Et kõigi vajadusi on ühekorraga raske rahuldada, toetab &kappname; pisikesi abitööriistu teksti kiireks töötlemiseks sisseehitatud käsurea abil. Näiteks käsk `sort` on teostatud skriptina. Järgnevas osas selgitatakse, kuidas luua `*.js`-faile &kappname; laiendamiseks mis tahes abiskriptidega.

Käsureaskriptid paiknevad samas kataloogis taandeskriptidega. Niisiis, esimese sammuna loo uus `*.js`-fail nimega `myutils.js` kohalikus kodukataloogis `$KDEHOME/share/apps/katepart/script/commands`.

#### Käsureaskripti päis

Kõigi käsureaskriptide päis on põimitud kommentaarina ning näeb välja selline:

    /* kate-script
     * author: Example Name <example.name@some.address.org>
     * license: BSD
     * revision: 1
     * kate-version: 3.4
     * functions: sort, format-paragraph
     * i18n-catalog: mycatalog
     *
     * Rida ilma koolonita ':' peatab päise parsimise. See tähendab, et sa võid siia
     * lisada muud teksti, näiteks üksikasjaliku litsentsi.
     */

Allpool selgitatakse põhjalikult iga kirjet:

- `kate-script` [kohustuslik]: see tekstistring peab esinema `*.js`-faili esimesel real, vastasel juhul jätab &kappname; skripti lihtsalt vahele.

- `author` [pole kohustuslik]: autori nimi ja kontaktteave.

- `license` [pole kohustuslik]: litsents lühidalt, näiteks BSD või LGPLv3.

- `revision` [kohustuslik]: skripti versioon. Seda arvu tuleb alati suurendada, kui skripti muudetakse.

- `kate-version` [kohustuslik]: &kappname; minimaalne nõutav versioon.

- `functions` [kohustuslik]: komadega eraldatud skripti käskude loend.

- `i18n-catalog` [pole kohustuslik]: täiendav tõlkesõnumite kataloog (`po`-fail), mis laaditakse kolmanda poole skriptide tõlgete saamiseks.

&kappname; loeb kõik paarid `võti`:`väärtus`, kuni ei leia enam koolonit. See tähendab, et päis võib sisaldada suvalist teksti, näiteks litsentsi, nagu ka eespool olnud näiteks. Võtme functions väärtus on komadega eraldatud käsureakäskude loend. See tähendab, et üks skript võib sisaldada suvalisel hulgal käsureakäske. Kõik funktsioonid on saadaval &kappname; sisseehitatud käsurea vahendusel.

#### Skripti lähtekood

Kõik päises osutatud funktsioonid tuleb skriptis teostada. Nii peab näiteks ülaltoodud näites esitatud skript teostama kaks funktsiooni: `sort` ja `format-paragraph`. Kõigil funktsioonidel on järgmine süntaks:

    // nõutavad katepart js teegid, nt. range.js, kui kasutad Range'i
    require ("range.js");

    function <nimi>(arg1, arg2, ...)
    {
        // ... implementation, see also: Scripting API
    }

Argumendid edastatakse käsureal funktsioonile kujul `arg1`, `arg2` jne. Kõigi käskude kohta dokumentatsiooni pakkumiseks teosta lihtsalt funktsioon '`help`':

    function help(cmd)
    {
        if (cmd == "sort") {
            return i18n("Sort the selected text.");
        } else if (cmd == "...") {
            // ...
        }
    }

Käsureal `help sort` käivitamine kutsub välja abifunktsiooni argumendiga `cmd`, mille väärtuseks on määratud antud käsk, s.t `cmd == "sort"`. &kappname; tagastab seejärel teksti kasutajale nähtava dokumentatsioonina. Kontrolli kindlasti, et ikka tõlgid stringid.

##### Kiirklahvid

Kiirklahvide omistamiseks peab skript pakkuma järgmisel moel funktsiooni `action`:

    function action(cmd)
    {
        var a = new Object();
        if (cmd == "sort") {
            a.text = i18n("Sort Selected Text");
            a.icon = "";
            a.category = "";
            a.interactive = false;
            a.shortcut = "";
        } else if (cmd == "moveLinesDown") {
            // same for next action
        }
        return a;
    }

Funktsiooni parameeter `cmd` määrab käsu, mille jaoks kiirklahv on mõeldud. Tagastatavas JavaScripti objektis tuleb määrata ära mitu välja:

- `a.text` [kohustuslik]: tekst, mida näeb menüüs Tööriistad Skriptid. Kontrolli, et kasutaksid tõlgete jaoks `i18n`.

- `a.icon` [pole kohustuslik]: ikoon, mida näeb menüüs teksti kõrval. Siin võib kasutada kõiki &kde; ikooninimesid.

- `a.category` [pole kohustuslik]: kategooria määramisel näeb skripti alammenüüs. Kontrolli, et kasutaksid tõlgete jaoks `i18n`.

- `a.interactive`: kui skript vajab kasutajapoolset sisendit, tuleb selle väärtuseks määrata `true`.

- `a.shortcut` [pole kohustuslik]: siin määratud kiirklahv on vaikimisi kiirklahv. Näide: Ctrl+Alt+t. Täpsemalt kõneldakse sellest Qt dokumentatsioonis.

Käsureaskripti arendamiseks tuleb skriptid taaslaadida, et näha, kas muudatused, mida nad teevad, on korrektsed. Terve rakenduse taaskäivitamise asemel lülitu lihtsalt käsureale ja anna käsk `reload-scripts`.

Kui lood mõne kasuliku skripti, võiksid kaaluda selle annetamist ka &kappname; hüvanguks. Selleks võib ühendust võtta postiloendis.

### Skriptimise API

Siinne skriptimise API on saadaval kõigis skriptides, s.t nii taande- kui ka käsureaskriptides. Klasse `Cursor` ja `Range` pakuvad teegifailid kataloogis `$KDEDIR/share/apps/katepart/libraries`. Kui soovid neid oma skriptis kasutada, mis on nõutav mõningate klasside `Document` või `View` funktsioonide kasutamiseks, kaasa palun vajalik teek järgmiselt:

    // nõutavad katepart js teegid, nt. range.js , kui kasutad Range'i
    require ("range.js");

Standardse skriptimise API laiendamiseks oma funktsioonide ja prototüüpidega loo lihtsalt uus fail &kde; kohalikus seadistuste kataloogis `$KDEHOME/share/apps/katepart/libraries` ja kaasa see oma skripti järgmiselt:

    require ("myscriptnamehere.js");

Olemasolevate prototüüpide, näiteks `Cursor` või `Range`, laiendamiseks ei ole soovitatav muuta globaalseid `*.js`-faile. Selle asemel muuda prototüüpi `Cursor` JavaScriptis pärast seda, kui `cursor.js` on `require` abil skripti kaasatud.

#### Kursorid ja vahemikud

Kuna &kappname; on tekstiredaktor, siis on kogu skriptimise API aluseks, nii palju kui võimalik, kursorid ja vahemikud. Kursor kujutab endast lihtsat `(rida,veerg)` määratlust, mis näitab ära teksti asukoha dokumendis. Vahemik aga paneb paika tekstivahemiku kursori algasukohast selle lõppasukohani. API seletatakse üksikasjalikult lahti järgmistes lõikudes.

##### Kursori prototüüp

    Cursor();

- Konstruktor. Tagastab kursori asukohas `(0, 0)`.

  Näide: `var cursor = new Cursor();`

    Cursor(int rida, int veerg);

- Konstruktor. Tagastab kursori asukohas (rida, veerg).

  Näide: `var cursor = new Cursor(3, 42);`

    Cursor(Cursor other);

- Koopia konstruktor. Tagastab kursori koopia `other`.

  Näide: `var copy = new Cursor(other);`

    Cursor Cursor.clone();

- Tagastab kursori klooni.

  Näide: `var clone = cursor.clone();`

    Cursor.setPosition(int rida, int veerg);

- Määrab kursori asukoha `rea` ja `veeruga`.

  Alates: &kde; 4.11

    bool Cursor.isValid();

- Kontrollib, kas kursor on korrektne. Kursor ei ole korrektne, kui rida ja/või veeru väärtuseks on määratud `-1`.

  Näide: `var valid = cursor.isValid();`

    Cursor Cursor.invalid();

- Tagastab uue ebakorrektse kursori asukohas `(-1, -1)`.

  Näide: `var invalidCursor = cursor.invalid();`

    int Cursor.compareTo(Cursor other);

- Võrdleb antud kursorit kursoriga `other`. Tagastab

  - `-1`, kui antud kursor paikneb enne kursorit `other`,

  - `0`, kui mõlemad kursorid on võrdsed,

  - `-+1`, kui antud kursor paikneb pärast kursorit `other`.

    bool Cursor.equals(Cursor other);

- Tagastab `true`, kui antud kursor ja kursor `other` on võrdsed, vastasel juhul `false`.

    String Cursor.toString();

- Tagastab kursori stringina kujul `Cursor(rida, veerg)`.

##### Vahemiku prototüüp

    Range();

- Konstruktor `new Range()` väljakutsumine tagastab vahemiku (0, 0) - (0, 0).

    Range(Cursor algus, Cursor lõpp);

- Konstruktor `new Range(`algus`, `lõpp`)` väljakutsumine tagastab vahemiku (`algus`, `lõpp`).

    Range(int algusRida, int algusVeerg, int lõppRida, int lõppVeerg);

- Konstruktor. `new Range(`algusRida`, `algusVeerg`, `lõppRida`, `lõppVeerg`)` tagastab vahemiku alates (`algusRida`, `algusVeerg`) kuni (`lõppRida`, `lõppVeerg`).

    Range(Range other);

- Koopia konstruktor. Tagastab vahemiku koopia `other`.

    Range Range.clone();

- Tagastab vahemiku klooni.

  Näide: `var clone = range.clone();`

    bool Range.isEmpty();

- Tagastab `true`, kui nii algus- kui ka lõppkursor on võrdsed.

  Näide: `var empty = range.isEmpty();`

  Alates: &kde; 4.11

    bool Range.isValid();

- Tagastab `true`, kui nii algus- kui ka lõppkursor on korrektsed, vastasel juhul `false`.

  Näide: `var valid = range.isValid();`

    Range Range.invalid();

- Tagastab vahemiku alates (-1, -1) kuni (-1, -1).

    bool Range.contains(Cursor kursor);

- Tagastab `true`, kui antud vahemik sisaldab kursori asukohta, vastasel juhul `false`.

    bool Range.contains(Range other);

- Tagastab `true`, kui antud vahemik sisaldab vahemikku `other`, vastasel juhul `false`.

    bool Range.containsColumn(int veerg);

- Tagastab `true`, kui `veerg` paikneb vahemikus `[start.column, end.column)`, vastasel juhul `false`.

    bool Range.containsLine(int rida);

- Tagastab `true`, kui `rida` paikneb vahemikus `[start.line, end.line)`, vastasel juhul `false`.

    bool Range.overlaps(Range other);

- Tagastab `true`, kui antud vahemikul ja vahemikul `other` on ühine piirkond, vastasel juhul `false`.

    bool Range.overlapsLine(int rida);

- Tagastab `true`, kui `rida` paikneb vahemikus `[start.line, end.line]`, vastasel juhul `false`.

    bool Range.overlapsColumn(int veerg);

- Tagastab `true`, kui `veerg` paikneb vahemikus `[start.column, end.column]`, vastasel juhul `false`.

    bool Range.onSingleLine();

- Tagastab `true`, kui vahemik algab ja lõpeb samal real, s.t. kui `Range.start.line == Range.end.line`

  Alates: &kde; 4.9

    bool Range.equals(Range other);

- Tagastab `true`, kui antud vahemik ja vahemik `other` on võrdsed, vastasel juhul `false`.

    String Range.toString();

- Tagastab vahemiku stringina kujul `Range(Cursor(rida, veerg), Cursor(rida, veerg))`.

#### Globaalsed funktsioonid

See sektsioon loetleb kõik globaalsed funktsioonid.

##### Failide lugemine ja kaasamine

    String read(String fail);

- See otsib määratud `faili`, mis on antud suhtelisena kataloogi `katepart/script/files` suhtes, ning tagastab selle sisu stringina.

    void require(String fail);

- See otsib määratud `faili`, mis on antud suhtelisena kataloogi `katepart/script/files`, ja hindab seda. `require` on sisemiselt kaitstud sama `faili` mitmekordse kaasamise vastu.

  Alates: &kde; 4.10

##### Silumine

    void debug(String tekst);

- Näitab `tekst`i standardväljundis `stdout` samas konsoolis, kus rakendus käivitati.

##### Tõlkimine

Täieliku lokaliseerimise pakkumiseks on olemas mitu funktsiooni, mille abil tõlkida skriptide stringe, nimelt `i18n`, `i18nc`, `i18np` ja `i18ncp`. Need funktsioonid toimivad täpselt nii nagu &kde; tõlkimisfunktsioonid.

Tõlkimisfunktsioonid tõlgivad tõlkimiseks määratud stringid &kde; tõlkesüsteemi kaudu rakenduse kasutatavasse keelde. Ametlikus &kappname; lähtekoodis arendatud skriptide stringid hangitakse ja tõlgitakse automaatselt. See tähendab, et &kappname; arendajana ei ole vaja pead vaevata tõlkesõnumite saatusega. Kuid kolmanda poole skriptide puhul, mida arendatakse väljaspool &kde;-d, tuleb sõnumid ise kätte saada ja tõlkida lasta. Skriptiga tuleb kaasa panna tõlkekataloog, mis sisaldab kõiki tõlgitavaid stringe. Lisaks peab skripti päises konkreetselt ära määrama laaditava kataloogi, milleks on mõeldud `i18n-catalog`.

    void i18n(String tekst, arg1, ...);

- Tõlgib `tekst`i rakenduse kasutatavasse keelde. Argumendid `arg1`, ... ei ole kohustuslikud ning neid kasutatakse kohatäitjate `%1`, `%2` jne. asendamiseks.

    void i18nc(String kontekst, String tekst, arg1, ...);

- Tõlgib `tekst`i rakenduse kasutatavasse keelde. Lisaks näevad tõlkijad stringi `kontekst`, mis aitab neil paremini leida õiget tõlkevastet. Argumendid `arg1`, ... ei ole kohustuslikud ning neid kasutatakse kohatäitjate `%1`, `%2` jne. asendamiseks.

    void i18np(String ainsus, String mitmus, int arv, arg1, ...);

- Tõlgib kas `ainsus`e või `mitmus`e rakenduse kasutatavasse keelde sõltuvalt määratud `arv`ust. Argumendid `arg1`, ... ei ole kohustuslikud ning neid kasutatakse kohatäitjate `%1`, `%2` jne. asendamiseks.

    void i18ncp(String kontekst, String ainsus, String mitmus, int arv, arg1, ...);

- Tõlgib kas `ainsus`e või `mitmus`e rakenduse kasutatavasse keelde sõltuvalt määratud `arv`ust. Lisaks näevad tõlkijad stringi `kontekst`, mis aitab neil paremini leida õiget tõlkevastet. Argumendid `arg1`, ... ei ole kohustuslikud ning neid kasutatakse kohatäitjate `%1`, `%2` jne. asendamiseks.

#### Vaate API

Skripti käivitamisel on alati olemas globaalne muutuja `view`, mis tähistab aktiivset redaktorivaadet. Järgnevalt on loetletud saadaolevad vaatefunktsioonid.

    Cursor view.cursorPosition()

- Tagastab aktiivse kursori asukoha vaates.

    void view.setCursorPosition(int rida, int veerg);
    void view.setCursorPosition(Cursor kursor);

- Määrab aktiivse kursori asukoha kas (rida, veerg) või määratud kursori järgi.

    Cursor view.virtualCursorPosition();

- Tagastab virtuaalse kursori asukoha tabeldusmärgis, arvestades tabeldusmärgile taande puhul määratud tühimärkide arvu.

    void view.setVirtualCursorPosition(int rida, int veerg);
    void view.setVirtualCursorPosition(Cursor kursor);

- Määrab aktiivse virtuaalse kursori asukoha kas (rida, veerg) või määratud kursori järgi.

    String view.selectedText();

- Tagastab valitud teksti. Kui teksti pole valitud, on tagastatav string tühi.

    bool view.hasSelection();

- Tagastab `true`, kui vaade sisaldab valitud teksti, vastasel juhul `false`.

    Range view.selection();

- Tagastab valitud teksti vahemiku. Tagastatud vahemik on vigane, kui teksti pole valitud.

    void view.setSelection(Range vahemik);

- Määrab valitud teksti valitud vahemikku.

    void view.removeSelectedText();

- Eemaldab valitud teksti. Kui vaates pole valitud teksti, ei tee midagi.

    void view.selectAll();

- Valib kogu dokumendi teksti.

    void view.clearSelection();

- Puhastab tekstivaliku ilma teksti eemaldamata.

#### Dokumendi API

Skripti käivitamisel on alati olemas globaalne muutuja `document`, mis tähistab aktiivset dokumenti. Järgnevalt on loetletud saadaolevad dokumendifunktsioonid.

    String document.fileName();

- Tagastab dokumendi failinime või tühja stringi salvestamata tekstipuhvri korral.

    String document.url();

- Tagastab dokumendi täieliku URL-i või tühja stringi salvestamata tekstipuhvri korral.

    String document.mimeType();

- Tagastab dokumendi MIME tüübi või MIME tüübi `application/octet-stream`, kui sobivat MIME tüüpi ei leita.

    String document.encoding();

- Tagastab faili salvestamisel kasutatava kodeeringu.

    String document.highlightingMode();

- Tagastab kogu dokumendis kasutatava globaalse esiletõstmise režiimi.

    String document.highlightingModeAt(Cursor asukoht);

- Tagastab dokumendi määratud asukohas kasutatava esiletõstmise režiimi.

    Array document.embeddedHighlightingModes();

- Tagastab dokumenti põimitud esiletõstmise režiimide massiivi.

    bool document.isModified();

- Tagastab `true`, kui dokument sisaldab salvestamata muudatusi, vastasel juhul `false`.

    String document.text();

- Tagastab kogu dokumendi sisu üheainsa tekstistringina. Reavahetusi tähistavad reavahetussümbolid `\n`.

    String document.text(int alatesReast, int alatesVeerust, int kuniReani, int kuniVeeruni);
    String document.text(Cursor alates, Cursor kuni);
    String document.text(Range vahemik);

- Tagastab teksti määratud vahemikust. Lähtekoodi parema loetavuse huvides on soovitatav kasutada kursorile ja vahemikule tuginevaid versioone.

    String document.line(int rida);

- Tagastab valitud teksti stringina. String on tühi, kui soovitud rida jääb vahemikust välja.

    String document.wordAt(int rida, int veerg);
    String document.wordAt(Cursor kursor);

- Tagastab sõna määratud kursori asukohas.

    Range document.wordRangeAt(int rida, int veerg);
    Range document.wordRangeAt(Cursor kursor);

- Tagastab sõnade vahemiku määratud kursori asukohas. Tagastatav vahemik on vigane (vt. Range.isValid()), kui teksti asukoht on pärast rea lõppu. Kui määratud kursori asukohas sõna pole, tagastatakse tühi vahemik.

  Alates: &kde; 4.9

    String document.charAt(int rida, int veerg);
    String document.charAt(Cursor kursor);

- Tagastab sümboli määratud kursori asukohas.

    String document.firstChar(int rida);

- Tagastab määratud `rea`

    String document.lastChar(int rida);

- Tagastab määratud `rea` esimese märgi, mis ei ole tühimärk. Kui rida on tühi või sisaldab ainult tühimärke, on tagastatud string tühi.

    bool document.isSpace(int rida, int veerg);
    bool document.isSpace(Cursor kursor);

- Tagastab `true`, kui määratud kursori asukohas paiknev märk on tühimärk, vastasel juhul `false`.

    bool document.matchesAt(int rida, int veerg, String tekst);
    bool document.matchesAt(Cursor kursor, String tekst);

- Tagastab `true`, kui määratud `tekst` sobib tekstiga määratud kursori asukohas, vastasel juhul `false`.

    bool document.startsWith(int rida, String tekst, bool skipWhiteSpaces);

- Tagastab `true`, kui rida algab `tekstiga`, vastasel juhul `false`. Argument `skipWhiteSpaces` määrab, kas alustavaid tühimärke eiratakse või mitte.

    bool document.endsWith(int rida, String tekst, bool skipWhiteSpaces);

- Tagastab `true`, kui rida lõpeb `tekstiga`, vastasel juhul `false`. Argument `skipWhiteSpaces` määrab, kas lõpetavaid tühimärke eiratakse või mitte.

    bool document.setText(String tekst);

- Määrab kogu dokumendi teksti.

    bool document.clear();

- Eemaldab kogu dokumendi teksti.

    bool document.truncate(int rida, int veerg);
    bool document.truncate(Cursor kursor);

- Kärbib määratud rea määratud veeruga või kursori asukohaga. Tagastab `true` õnnestumise korral või `false`, kui määratud rida ei kuulu dokumendi vahemikku.

    bool document.insertText(int rida, int veerg, String tekst);
    bool document.insertText(Cursor kursor, String tekst);

- Lisab `teksti` määratud kursori asukohta. Tagastab `true` õnnestumise korral või `false`, kui dokument on kirjutuskaitstud.

    bool document.removeText(int alatesReast, int alatesVeerust, int kuniReani, int kuniVeeruni);
    bool document.removeText(Cursor alates, Cursor kuni);
    bool document.removeText(Range vahemik);

- Eemaldab teksti määratud vahemikus. Tagastab `true` õnnestumise korral või `false`, kui dokument on kirjutuskaitstud.

    bool document.insertLine(int rida, String tekst);

- Lisab teksti määratud reale. Tagastab `true` õnnestumise korral või `false`, kui dokument on kirjutuskaitstud või rida ei paikne dokumendi vahemikus.

    bool document.removeLine(int rida);

- Eemaldab määratud tekstirea. Tagastab `true` õnnestumise korral või `false`, kui dokument on kirjutuskaitstud või rida ei paikne dokumendi vahemikus.

    bool document.wrapLine(int rida, int veerg);
    bool document.wrapLine(Cursor kursor);

- Murrab rida määratud kursori asukohas. Tagastab `true` õnnestumise korral või `false`, kui nt. rida < 0.

  Alates: &kde; 4.9

    void document.joinLines(int algusRida, int lõppRida);

- Ühendab read alates `algusRida` to `lõppRida`. Kaht järjestikust tekstirida eraldab alati üks tühik.

    int document.lines();

- Tagastab dokumendi ridade arvu.

    int document.length();

- Tagastab dokumendi sümbolite arvu.

    int document.lineLength(int rida);

- Tagastab `rea` pikkuse.

    void document.editBegin();

- Alustab redigeerimisrühma tagasivõtmiste või uuestitegemiste rühmitamiseks. Kontrolli, et `editEnd()` oleks alati sama palju välja kutsutud kui `editBegin()`. `editBegin()` väljakutse kasutab seesmiselt referentsarvestit, s.t selle väljakutse korral on võimalik pesastamine.

    void document.editEnd();

- Lõpetab redigeerimisrühma. Viimane `editEnd()` väljakutse (s.t see, mis vastab esimesele `editBegin()` väljakutsele) lõpetab redigeerimisastme.

    int document.firstColumn(int rida);

- Tagastab määratud `rea` esimese mittetühimärgiga veeru. Kui real on ainult tühimärgid, tagastatakse `-1`.

    int document.lastColumn(int rida);

- Tagastab määratud `rea` viimase mittetühimärgiga veeru. Kui real on ainult tühimärgid, tagastatakse `-1`.

    int document.prevNonSpaceColumn(int rida, int veerg);
    int document.prevNonSpaceColumn(Cursor kursor);

- Tagastab mittetühimärkidega veeru alates aktiivsest kursori asukohast tagasisuunas otsides.

    int document.nextNonSpaceColumn(int rida, int veerg);
    int document.nextNonSpaceColumn(Cursor kursor);

- Tagastab mittetühimärkidega veeru alates aktiivsest kursori asukohast edasisuunas otsides.

    int document.prevNonEmptyLine(int rida);

- Tagastab järgmise mittetühimärkidega mittetühja rea, otsides tagasisuunas.

    int document.nextNonEmptyLine(int rida);

- Tagastab järgmise mittetühimärkidega mittetühja rea, otsides edasisuunas.

    bool document.isInWord(String sümbol, int atribuut);

- Tagastab `true`, kui määratud `sümbol` määratud `atribuudiga` võib olla sõna osa, vastasel juhul `false`.

    bool document.canBreakAt(String sümbol, int atribuut);

- Tagastab `true`, kui määratud `sümbol` määratud `atribuudiga` sobib reamurdmiseks, vastasel juhul `false`.

    bool document.canComment(int algusAtribuut, int lõppAtribuut);

- Tagastab `true`, kui määratud atribuudiga algav ja lõppev vahemik sobib kommenteerimiseks, vastasel juhul `false`.

    String document.commentMarker(int atribuut);

- Tagastab kommentaaritähise määratud `atribuudiga` üherealise kommentaari puhul.

    String document.commentStart(int atribuut);

- Tagastab kommentaaritähise määratud `atribuudiga` mitmerealise kommentaari alguse puhul.

    String document.commentEnd(int atribuut);

- Tagastab kommentaaritähise määratud `atribuudiga` mitmerealise kommentaari lõpu puhul.

    int document.attribute(int rida, int veerg);
    int document.attribute(Cursor kursor);

- Tagastab atribuudi määratud kursori asukohas.

    bool document.isAttribute(int rida, int veerg, int atribuut);
    bool document.isAttribute(Cursor kursor, int atribuut);

- Tagastab `true`, kui kursori asukohas paiknev atribuut on võrdne `atribuudiga`, vastasel juhul `false`.

    String document.attributeName(int rida, int veerg);
    String document.attributeName(Cursor kursor);

- Tagastab atribuudi nime inimloetava tekstina. See võrdub nimega `itemData` süntaksi esiletõstmise failides.

    bool document.isAttributeName(int rida, int veerg, String nimi);
    bool document.isAttributeName(Cursor kursor, String nimi);

- Tagastab `true`, kui kursori asukohas paikneva atribuudi nimi sobib määratud `nimega`, vastasel juhul `false`.

    String document.variable(String võti);

- Tagastab soovitud dokumendi muutuja `võti` väärtuse. Kui dokumendi muutujat ei ole olemas, tagastatakse tühi string.

    String document.setVariable(String võti, String väärtus);

- Soovitud dokumendi muutuja `võtme` väärtuse määramine. Tagastab määratud muutuja väärtuse.

  Vaata ka: Kate dokumendi muutujad

  Alates: &kde; 4.8

    int document.firstVirtualColumn(int rida);

- Tagastab määratud rea esimese mittetühimärgi virtuaalse veeru või `-1`, kui rida on tühi või sisaldab ainult tühimärke.

    int document.lastVirtualColumn(int rida);

- Tagastab määratud rea viimase mittetühimärgi virtuaalse veeru või `-1`, kui rida on tühi või sisaldab ainult tühimärke.

    int document.toVirtualColumn(int rida, int veerg);
    int document.toVirtualColumn(Cursor kursor);
    Cursor document.toVirtualCursor(Cursor kursor);

- Teisendab määratud reaalse kursori asukoha virtuaalseks kursori asukohaks, tagastades täisarvu või objekti Cursor.

    int document.fromVirtualColumn(int rida, int virtuaalneVeerg);
    int document.fromVirtualColumn(Cursor virtuaalneKursor);
    Cursor document.fromVirtualCursor(Cursor virtuaalneKursor);

- Teisendab määratud virtuaalse kursori asukoha reaalseks kursori asukohaks. tagastades täisarvu või objekti Cursor.

    Cursor document.anchor(int rida, int veerg, Char sümbol);
    Cursor document.anchor(Cursor kursor, Char sümbol);

- Otsib määratud sümbolit tagasisuunas alates määratud kursorist. Kui näiteks '(' edastatakse sümbolina, tagastab see funktsioon avava '(' asukoha. Referentsarvestust, s.t teisi '(...)', eiratakse.

    Cursor document.rfind(int rida, int veerg, String tekst, int atribuut = -1);
    Cursor document.rfind(Cursor kursor, String tekst, int atribuut = -1);

- Otsib tagasisuunas määratud teksti sobiva `atribuudiga`. Argumenti `atribuut` eiratakse, kui selle väärtuseks on määratud `-1`. Tagastatud kursor on vigane, kui teksti ei leita.

    int document.defStyleNum(int rida, int veerg);
    int document.defStyleNum(Cursor kursor);

- Tagastab määratud kursori asukohas kasutatud vaikimisi stiili.

    bool document.isCode(int rida, int veerg);
    bool document.isCode(Cursor kursor);

- Tagastab `true`, kui määratud kursori asukohas paiknev atribuut ei ole võrdne kõigi järgnevate stiilidega: `dsComment`, `dsString`, `dsRegionMarker`, `dsChar`, `dsOthers`.

    bool document.isComment(int rida, int veerg);
    bool document.isComment(Cursor kursor);

- Tagastab `true`, kui kursori asukohas paikneva sümboli atribuut on `dsComment`, vastasel juhul `false`.

    bool document.isString(int rida, int veerg);
    bool document.isString(Cursor kursor);

- Tagastab `true`, kui kursori asukohas paikneva sümboli atribuut on `dsString`, vastasel juhul `false`.

    bool document.isRegionMarker(int rida, int veerg);
    bool document.isRegionMarker(Cursor kursor);

- Tagastab `true`, kui kursori asukohas paikneva sümboli atribuut on `dsRegionMarker`, vastasel juhul `false`.

    bool document.isChar(int rida, int veerg);
    bool document.isChar(Cursor kursor);

- Tagastab `true`, kui kursori asukohas paikneva sümboli atribuut on `dsChar`, vastasel juhul `false`.

    bool document.isOthers(int rida, int veerg);
    bool document.isOthers(Cursor kursor);

- Tagastab `true`, kui kursori asukohas paikneva sümboli atribuut on `dsOthers`, vastasel juhul `false`.

## Redaktorikomponendi laiendused

Redaktorikomponendi laiendused laiendavad KateParti ehk täiustatud tekstiredaktori komponenti, mida kasutavad paljud &kde; rakendused, näiteks &kate;, &kwrite;, Kile ja KDevelop. Redaktorikimponendi plugina loomine võimaldab laiendada redaktori funktsionaalsust kõigis mainitud ja mainimata rakendustes.

Alustamiseks uuri KTextEditori plugina õppematerjali &kde; TechBase'is. Veel põhjalikumaks tutvumiseks uuri ka põhjalikumat õppematerjali samuti TechBase'is.

Soovi ja vajaduse korral leiab täieliku API dokumentatsiooni &kde; API baasis.

## &kate; (C++) rakenduse pluginad

Kate rakenduse pluginad laiendavad &kate; redaktori enda funktsionaalsust kõikvõimalikul moel, kasutades sama programmeerimiskeelt, milles on kirjutatud ka &kate; - C++.

Alustamiseks uuri &kate; plugina kirjutamise õppematerjali &kate; veebileheküljel. Lisaks on olemas ka klassikaline Tere, maailm! näiteplugin, mis on kaasas juba &kate; lähtekoodiga.

## &pate; Pythoni pluginad

&pate; pluginad võimaldavad samuti laiendada &kate; funktsionaalsust kõikvõimalikul moel, kasutades selleks Pythoni programmeerimiskeelt.

Alustamiseks uuri Pythoni plugina arendaja juhiseid &kate; veebileheküljel.

Samuti võib tutvuda API põhjaliku ülevaatega &pate; seadistamise ekraanil.