# Utöka &kate;

## Inledning

Som alla avancerade editorer erbjuder &kate; en mängd sätt att utöka dess funktionalitet. Du kan skriva enkla skript för att lägga till funktionalitet med Javascript, lägga till utökad funktionalitet i editorkomponenten med Insticksprogram för editorkomponenten, eller lägga till ännu mer funktionalitet i själva editorn med insticksprogram för programmet &kate; skrivna i C++ eller &pate; insticksprogram skriva i Python. Till sist, när du väl har utökat &kate;, är du välkommen att gå med och dela med dig av dina förbättringar med hela världen.

## Skapa skript med Javascript

Sedan &kappname; 3.4 i &kde; 4.4 kan &kappname;s editorkomponent enkelt utökas genom att skriva skript. Skriptspråket är ECMAscript (känt överallt som Javascript). &kappname; stöder två sorters skript: intenterings- och kommandoradskript.

### Indenteringsskript

Indenteringsskript, som också kallas indenterare, indenterar automatiskt källkoden medan texten skrivs in. Som ett exempel, efter att ha tryckt på returtangenten ökar ofta indenteringsnivån.

Följande avsnitt beskriver steg för steg hur skelettet för en enkel indenterare skapas. Som ett första steg, skapa en ny `*.js`-fil, som t.ex. heter `javascript.js` i den lokala hemkatalogen `$KDEHOME/share/apps/katepart/script/indentation`.

#### Indenteringsskriptets huvud

Huvudet i filen `javascript.js` är inbäddat i en kommentar, och har följande form:

    /* kate-script
     * name: JavaScript
     * author: Exempel Namn <exempel.namn@någon.adress.org>
     * license: BSD
     * revision: 1
     * kate-version: 3.4
     * required-syntax-style: javascript
     * indent-languages: javascript
     * priority: 0
     * i18n-catalog: min_katalog
     *
     * En rad utan ett kolon ':' stoppar tolkning av huvudet. Alltså kan du lägga till valfri
     * text här som en detaljerad licens.
     */

Varje post förklaras nu i detalj:

- `kate-script` [krävs]: Textsträngen måste finnas på första raden i `*.js`-filen, annars hoppar &kappname; över skriptet.

- `name` [krävs]: Detta är indenterarens namn som visas i menyn Verktyg Indentering och i inställningsdialogrutan.

- `author` [valfri]: Upphovsmannens namn och kontaktinformation.

- `license` [valfri]: Kort form av licensen, såsom BSD eller LGPLv3.

- `revision` [krävs]: Skriptets utgåva. Numret ska ökas så fort skriptet ändras.

- `kate-version` [krävs]: Lägsta version av &kappname; som krävs.

- `required-syntax-style` [valfri]: Lista åtskild med komman av syntaxfärgläggningsstilar som krävs. Det är viktigt för indenterare som förlitar sig på specifik syntaxfärgläggningsinformation i dokumentet. Om en krävd syntaxstil specificeras, är bara indenteraren tillgänglig när lämplig syntaxfärgläggning är aktiv. Det förhindrar odefinierat beteende orsakat av att använda indenteraren utan den förväntade färgläggningsmetoden. Exempelvis använder sig Ruby-indenteraren sig av det i filen `ruby.js` och `ruby.xml`.

- `indent-languages` [valfri]: Lista åtskild med kommatecken av syntaxstilar som indenteraren kan indentera korrekt, t.ex. c++, java.

- `priority` [valfri]: Om flera indenterare är lämpliga för en viss färglagd fil, bestämmer prioriteten vilken indenterare som väljes som standardindenterare.

- `i18n-catalog` [valfri]: Ytterligare meddelandekatalog (`po`-fil) inläst för översättning av indenterare från tredjepart.

&kappname; läser alla par av formen `nyckel`: `värde` till ett kolon inte längre hittas. Det betyder att huvudet kan innehålla valfri text som en licens, vilket visas i exemplet.

#### Indenteringens källkod

Efter att ha specificerat huvudet, förklarar det här avsnittet hur själva indenteringsskriptet fungerar. Det grundläggande skelettet för implementeringen ser ut så här:

    // nödvändiga katepart js bibliotek, t.ex. range.js om Range används
    require ("range.js");

    triggerCharacters = "{}/:;";
    function indent(line, indentWidth, ch)
    {
        // anropas för varje nyrad (ch == '\n') och alla tecken angivna i
        // den globala variabeln triggerCharacters. Vid anrop av VerktygJustera
        // är variabeln ch tom, dvs. ch == ''.
        //
        // se också: Programmeringsgränssnittet för skripthantering
        return -2;
    }

Funktionen `indent()` har tre parametrar:

- `line`: raden som ska indenteras

- `indentWidth`: indenteringsbredden i antal mellanslag

- `ch`: antingen ett nyradstecken (`ch == '\n'`), avtryckartecknet angivet i `triggerCharacters` eller tom om användaren utförde åtgärden Verktyg Justera.

Returvärdet från funktionen `indent()` anger hur raden kommer att indenteras. Om returvärdet är ett enkelt heltal, tolkas det på följande sätt:

- returvärde `-2`: gör ingenting

- returvärde `-1`: behåll indentering (söker efter föregående icke tomma rad)

- returvärde `0`: tal >= 0 anger indenteringsdjupet i mellanslag

Som alternativ kan ett fält med två element returneras.

- `return [ indent, align ];`

I detta fall är det först elementet indenteringsdjupet ovan med samma betydelse för specialvärden. Det andra elementet är dock ett absolutvärde som representerar en kolumn för justering. Om värdet är större än indenteringsvärdet, representerar skillnaden ett antal mellanslag att lägga till efter indentering av den första parametern. Annars ignoreras det andra numret. Att använda tabulator och mellanslag för indentering kallas ofta blandat läge.

Betrakta följande exempel: Antag att tabulator används för indentering, och tabulatorbredden är inställd till 4. Här representerar <tab> en tabulator, och '.' ett mellanslag.

    1: <tab><tab>anropa("Hej",
    2: <tab><tab>......."allesamman");

Vid indentering av rad 2, returnerar funktionen `indent()` [8, 15]. Som resultat infogas två tabulatorer för att indentera till kolumn 8, och 7 mellanslag läggs till för att justera den andra parametern under den första, så att den förblir justerad om filen visas med en annan tabulatorbredd.

En standardinstallation av &kde; levererar &kappname; med flera indenterare. Den motsvarande Javascript-koden finns i `$KDEDIR/share/apps/katepart/script/indentation`.

Att utveckla en indenterare kräver att skript läses in igen för att se om ändringar beter sig lämpligt. Istället för att starta om programmet, byt helt enkelt till kommandoraden och utför kommandot `reload-scripts`.

Om du utvecklar användbara skript, fundera på att bidra med det till &kappname;-projektet genom att kontakta e-postlistan.

### Kommandoradskript

Eftersom det är svårt att uppfylla allas behov, stöder &kappname; små hjälpverktyg för snabb textbehandling via den inbyggda kommandoraden. Exempelvis är kommandot `sort` implementerat som ett skript. Det här avsnittet förklarar hur man skapar `*.js`-filer för att utöka &kappname; med godtyckliga hjälpskript.

Kommandoradskript är placerade i samma katalog som indenteringsskript. Som ett första steg, skapa alltså en ny `*.js`-fil som heter `mina_verktyg.js` i den lokala hemkatalogen `$KDEHOME/share/apps/katepart/script/commands`.

#### Kommandoradskriptets huvud

Huvudet för varje kommandoradsskript är inbäddat i en kommentar och har följande form:

    /* kate-script
     * author: Exempel Namn <exempel.namn@någon.adress.org>
     * license: BSD
     * revision: 1
     * kate-version: 3.4
     * type: commands
     * functions: sort, format-paragraph
     * i18n-catalog: min_katalog
     *
     * En rad utan ett kolon ':' stoppar tolkning av huvudet. Alltså kan du lägga till valfri
     * text här som en detaljerad licens.
     */

Varje post förklaras nu i detalj:

- `kate-script` [krävs]: Textsträngen måste finnas på första raden i `*.js`-filen, annars hoppar &kappname; över skriptet.

- `author` [valfri]: Upphovsmannens namn och kontaktinformation.

- `license` [valfri]: Kort form av licensen, såsom BSD eller LGPLv3.

- `revision` [krävs]: Skriptets utgåva. Numret ska ökas så fort skriptet ändras.

- `kate-version` [krävs]: Lägsta version av &kappname; som krävs.

- `functions` [krävs]: Lista åtskild med kommatecken av kommandon i skriptet.

- `i18n-catalog` [valfri]: Ytterligare meddelandekatalog (`po`-fil) inläst för översättning av skript från tredjepart.

&kappname; läsera alla par av formen `nyckel`: `värde` till ett kolon inte längre hittas. Det betyder att huvudet kan innehålla valfri text som en licens, vilket visas i exemplet. Värdet på nyckeln functions är en lista åtskild med kommatecken av kommandon för kommandoraden. Det betyder att ett enda skript innehåller ett godtyckligt antal kommandon för kommandoraden. Varje funktion är tillgänglig via &kappname;s inbyggda kommandorad.

#### Skriptets källkod

Alla funktioner specificerade i huvudet måste implementeras i skriptet. Exempelvis måste skriptfilen i exemplet ovan implementera de två funktionerna `sort` och `format-paragraph`. Alla funktioner har följande syntax:

    // nödvändiga katepart.js bibliotek, t.ex. range.js om Range används
    require ("range.js");

    function <namn>(arg1, arg2, ...)
    {
        // ... implementering, se också: Programmeringsgränssnittet för skripthantering
    }

Argument på kommandoraden skickas till funktionen som `arg1`, `arg2`, etc. För att ge dokumentation av varje kommando, implementera helt enkelt funktionen '`help`' på följande sätt:

    function help(cmd)
    {
        if (cmd == "sort") {
            return "Sortera markerad text.";
        } else if (cmd == "...") {
            // ...
        }
    }

Att utföra `help sort` på kommandoraden anropar hjälpfunktionen med argumentet `cmd` inställd till det givna kommandot, dvs. `cmd == "sort"`. &kappname; visar därefter den returnerade texten som dokumentation för användaren. Försäkra dig om att översätta strängarna.

##### Tilldela genvägar

För att kunna tilldela genvägar, måste skriptet tillhandahålla en funktion som heter `action` enligt följande:

    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") {
            // samma för nästa åtgärd
        }
        return a;
    }

Funktionens parameter `cmd` anger kommandot som genvägen begärs för. Det finns flera fält som du måste ange i Javascript-objektet som returneras:

- `a.text` [krävs]: Texten visas i menyn Verktyg Skript. Försäkra dig om att du använder `i18n` för översättning.

- `a.icon` [valfri]: Ikonen visas intill texten i menyn. Alla &kde;:s ikonnamn kan användas här.

- `a.category` [valfri]: Om en kategori anges, visas skriptet i en undermeny. Försäkra dig om att använda `i18n` för översättning.

- `a.interactive` [valfri]: If the script needs user input, set this to `true`.

- `a.shortcut` [valfri]: Genvägen som anges här är förvald genväg. Exempel: Ctrl+Alt+t. Se Qt:s dokumentation för ytterligare detaljinformation.

Att utveckla ett kommandoradskript kräver att skript läses in igen för att se om ändringar beter sig lämpligt. Istället för att starta om programmet, byt helt enkelt till kommandoraden och utför kommandot `reload-scripts`.

Om du utvecklar användbara skript, fundera på att bidra med det till &kappname;-projektet genom att kontakta e-postlistan.

### Programmeringsgränssnittet för skripthantering

Programmeringsgränssnittet för skripthantering som presenteras här är tillgängligt i alla skript, dvs. indenteringsskript och kommandon för kommandoraden. Klasserna `Cursor` och `Range` tillhandahålls av biblioteksfiler i `$KDEDIR/share/apps/katepart/libraries`. Om du vill använda dem i skriptet, vilket behöver använda vissa av funktionerna i `Document` eller `View` , inkludera det nödvändiga biblioteket med:

    // nödvändiga katepart.js bibliotek, t.ex. range.js om Range används
    require ("range.js");

För att utöka det vanliga skriptprogrammeringsgränssnittet med egna funktioner och prototyper, skapa helt enkelt en ny fil i &kde;:s lokala inställningskatalog `$KDEHOME/share/apps/katepart/libraries` och inkludera den i skriptet med:

    require ("mitt_skriptnamn.js");

För att utöka befintliga prototyper som `Cursor` eller `Range`, är det rekommenderade sättet inte att ändra den globala `*.js`-filen. Ändra istället prototypen för `Cursor` i Javascript efter att `cursor.js` har inkluderats i skriptet via `require`.

#### Markörer och intervall

Eftersom &kappname; är en texteditor är alla programmeringsgränssnitt baserade på markörer och intervall om det är möjligt. En markör (Cursor) är ett enkelt par `(rad, kolumn)`, som representerar en textposition i dokumentet. Ett intervall (Range) omfattar text från en markörs startposition till en markörs slutposition. Programmeringsgränssnittet förklaras i detalj i följande avsnitt.

##### Prototypen för Cursor

    Cursor();

- Konstruktor. Returnerar en markör på position `(0, 0)`.

  Exempel: `var cursor = new Cursor();`

    Cursor(int rad, int kolumn);

- Konstruktor. Returnerar en markör på position (rad, kolumn).

  Exempel: `var cursor = new Cursor(3, 42);`

    Cursor(Cursor annan);

- Kopieringskonstruktor. Returnerar en kopia av markören `annan`.

  Exempel: `var copy = new Cursor(other);`

    Cursor Cursor.clone();

- Returnerar en klon av markören.

  Exempel: `var clone = cursor.clone();`

    Cursor.setPosition(int rad, int kolumn);

- Ställer in markörens position till `rad` och `kolumn`.

  Sedan: &kde; 4.11

    bool Cursor.isValid();

- Kontrollera om markören är giltig. Markören är ogiltig om rad och/eller kolumn har värdet `-1`.

  Exampel: `var valid = cursor.isValid();`

    Cursor Cursor.invalid();

- Returnerar en ny ogiltig markör placerad på `(-1, -1)`.

  Exempel: `var invalidCursor = cursor.invalid();`

    int Cursor.compareTo(Cursor annan);

- Jämför den här markören med markören `annan`. Returnerar

  - `-1`, om den här markören är placerad innan markören `annan`,

  - `0`, om båda markörerna är lika, och

  - `+1`, om den här markören är placerad efter markören `annan`.

    bool Cursor.equals(Cursor annan);

- Returnerar `sant` om den här markören och markören `annan` är lika, annars `falskt`.

    String Cursor.toString();

- Returnerar markören som en sträng på formen `Cursor(rad, kolumn)`.

##### Prototyp för Range

    Range();

- Konstruktor. Att anropa `new Range()` returnerar intervallet (0, 0) - (0, 0).

    Range(Cursor start, Cursor slut);

- Konstruktor. Att anropa `new Range(`start`, `slut`)` returnerar intervallet (`start`, `slut`).

    Range(int startrad, int startkolumn, int slutrad, int slutkolumn);

- Constructor. Calling `new Range(`startrad`, `startkolumn`, `slutrad`, `slutkolumn`)` returnerar intervallet från (`startrad`, `startkolumn`) to (`startrad`, `slutkolumn`).

    Range(Range annat);

- Kopieringskonstruktor. Returnerar en kopia av intervallet `annat`.

    Range Range.clone();

- Returnerar en klon av intervallet.

  Exempel: `var clone = range.clone();`

    bool Range.isEmpty();

- Returnerar `sant` om både start- och slutmarkörerna är lika.

  Exempel: `var empty = range.isEmpty();`

  Sedan: &kde; 4.11

    bool Range.isValid();

- Returnerar `sant` om både start- och slutmarkörerna är giltiga, annars `falskt`.

  Exempel: `var valid = range.isValid();`

    Range Range.invalid();

- Returnerar intervallet från (-1, -1) till (-1, -1).

    bool Range.contains(Cursor markör);

- Returnerar `true` om intervallet innehåller markörpositionen, annars `false`.

    bool Range.contains(Range annat);

- Returnerar `sant` om det här intervallet innehåller intervallet `annat`, annars `falskt`.

    bool Range.containsColumn(int kolumn);

- Returnerar `sant` om `kolumn` är i det halvöppna intervallet `[startkolumn, slutkolumn)`, annars `falskt`.

    bool Range.containsLine(int rad);

- Returnerar `sant` om `rad` är i det halvöppna intervallet `[startrad, slutrad)`, annars `falskt`.

    bool Range.overlaps(Range annat);

- Returnerar `sant` om det här intervallet och intervallet `annat` delar ett gemensamt område, annars `falskt`.

    bool Range.overlapsLine(int rad);

- Returnerar `sant` om `rad` är i intervallet `[startrad, slutrad]`, annars `falskt`.

    bool Range.overlapsColumn(int kolumn);

- Returnerar `sant` om `kolumn` är i intervallet `[startkolumn, slutkolumn]`, annars `falskt`.

    bool Range.onSingleLine();

- Returnerar `sant` om intervallet startar och slutar på samma rad, dvs. om `Range.start.line == Range.end.line`.

  Sedan: &kde; 4.9

    bool Range.equals(Range annan);

- Returnerar `sant` om det här intervallet och intervallet `annat` är lika, annars `falskt`.

    String Range.toString();

- Returnerar intervallet som en sträng på formen `Range(Cursor(rad, kolumn), Cursor(rad, kolumn))`.

#### Globala funktioner

Det här avsnittet listar alla globala funktioner.

##### Att läsa och inkludera filer

    String read(String fil);

- Söker efter angiven `fil` relativt i förhållande till katalogen `katepart/script/files` och returnerar innehållet som en sträng.

    void require(String fil);

- Söker efter angiven `fil` relativt i förhållande till katalogen `katepart/script/libraries` och utvärdera den. Internt skyddas `require` från att samma `fil` inkluderas flera gånger.

  Sedan: &kde; 4.10

##### Felsökning

    void debug(String text);

- Skriver ut `text` på `standardutmatningen` i terminalen som startade programmet.

##### Översättning

För att stödja fullständig landsanpassning, finns det flera funktioner för att översätta strängar i skript, närmare bestämt `i18n`, `i18nc`, `i18np` och `i18ncp`. Funktionerna beter sig exakt likadant som &kde;:s översättningsfunktioner.

Översättningsfunktionerna översätter strängarna de omger via &kde;:s översättningssystem till det språk som används i programmet. Strängar i skript som utvecklas i &kappname;s officiella källkod extraheras automatiskt och är översättningsbara. Med andra ord, som utvecklare av &kappname; behöver man inte bry dig om att extrahera och översätta meddelanden. För skript från tredjepart som utvecklas utanför &kde;, måste man dock extrahera och översätta meddelandena själv. En översättningskatalog som innehåller alla översatta strängar måste distribueras tillsammans med skriptet. Dessutom måste skriptets huvud explicit definiera katalogen som ska läsas in genom att ange `i18n-catalog`.

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

- Översätter `text` till språket som används av programmet. Parametrarna `arg1`, ... , är valfria och används för att ersätta platsmarkörerna `%1`, `%2`, etc.

    void i18nc(String sammanhang, String text, arg1, ...);

- Översätter `text` till språket som används av programmet. Dessutom är strängen `sammanhang` synlig för översättare, så att de kan tillhandahålla en bättre översättning. Parametrarna `arg1`, ... , är valfria och används för att ersätta platsmarkörerna `%1`, `%2`, etc.

    void i18np(String singularis, String pluralis, int antal, arg1, ...);

- Översätter antingen `singularis` eller `pluralis` till språket som används av programmet, beroende på angivet `antal`. Parametrarna `arg1`, ... , är valfria och används för att ersätta platsmarkörerna `%1`, `%2`, etc.

    void i18ncp(String sammanhang, String singularis, String pluralis, int antal, arg1, ...);

- Översätter antingen `singularis` eller `pluralis` till språket som används av programmet, beroende på angivet `antal`. Dessutom är strängen `sammanhang` synlig för översättare, så att de kan tillhandahålla en bättre översättning. Parametrarna `arg1`, ... , är valfria och används för att ersätta platsmarkörerna `%1`, `%2`, etc.

#### Programmeringsgränssnittet för vyn

När ett skript håller på att köras, finns det en global variabel `view` som representerar den för närvarande aktiva editorvyn. Det följande är en lista med alla tillgängliga funktioner i View.

    Cursor view.cursorPosition()

- Returnerar den nuvarande markörpositionen i vyn.

    void view.setCursorPosition(int rad, int kolumn);
    void view.setCursorPosition(Cursor markör);

- Ställ in den nuvarande markörpositionen till antingen (rad, kolumn) eller till den givna markören.

    Cursor view.virtualCursorPosition();

- Returnerar den virtuella markörpositionen, där varje tabulator räknas som motsvarande antal mellanslag, beroende på nuvarande tabulatorbredd.

    void view.setVirtualCursorPosition(int rad, int kolumn);
    void view.setVirtualCursorPosition(Cursor markör);

- Ställ in den nuvarande virtuella markörpositionen till (rad, kolumn) eller till den givna markören.

    String view.selectedText();

- Returnerar den markerade texten. Om ingen text är markerad, är den returnerade strängen tom.

    bool view.hasSelection();

- Returnerar `true` om vyn har markerad text, annars `false`.

    Range view.selection();

- Returnerar det markerade textintervallet. Det returnerade intervallet är ogiltigt om det inte finns någon markerad text.

    void view.setSelection(Range intervall);

- Ställer in markerad text till angivet intervall.

    void view.removeSelectedText();

- Tar bort den markerade texten. Om vyn inte har någon markerad text, händer ingenting.

    void view.selectAll();

- Markerar hela texten i dokumentet.

    void view.clearSelection();

- Rensar textmarkeringen utan att ta bort texten.

#### Programmeringsgränssnittet för dokumentet

När ett skript håller på att köras, finns det en global variabel `document` som representerar det för närvarande aktiva dokumentet. Det följande är en lista med alla tillgängliga funktioner i Document.

    String document.fileName();

- Returnerar dokumentets filnamn eller en tom sträng för osparade textbuffrar.

    String document.url();

- Returnerar dokumentets fullständiga webbadress eller en tom sträng för osparade textbuffrar.

    String document.mimeType();

- Returnerar dokumentets Mime-typ eller Mime-typen `application/octet-stream` om ingen lämplig Mime-typ kunde hittas.

    String document.encoding();

- Returnerar den nuvarande kodningen använd för att spara filen.

    String document.highlightingMode();

- Returnerar det allmänna färgläggningsläget som används för hela dokumentet.

    String document.highlightingModeAt(Cursor pos);

- Returnerar färgläggningsläget som används på den givna positionen i dokumentet.

    Array document.embeddedHighlightingModes();

- Returnerar ett fält med färgläggningslägen inbäddade i det här dokumentet.

    bool document.isModified();

- Returnerar `true` om dokumentet har osparade ändringar (är modifierat), annars `false`.

    String document.text();

- Returnerar dokumentets hela innehåll i en enda textsträng. Nya rader är markerade med nyradstecknet `\n`.

    String document.text(int från_rad, int från_kolumn, int till_rad, int till_kolumn);
    String document.text(Cursor från, Cursor till);
    String document.text(Range intervall);

- Returnerar texten i det angivna intervallet. Det rekommenderas att använda markör- och intervallbaserade versioner för bättre läsbarhet hos källkoden.

    String document.line(int rad);

- Returnerar den givna textraden som en sträng. Strängen är tom om den begärda raden är utanför tillgängligt intervall.

    String document.wordAt(int rad, int kolumn);
    String document.wordAt(Cursor markör);

- Returnerar ordet på den angivna markörposition.

    Range document.wordRangeAt(int rad, int kolumn);
    Range document.wordRangeAt(Cursor markör);

- Returnerar intervallet för ordet på den givna markörpositionen. Det returnerade intervallet är ogiltigt (se Range.isValid()) om textpositionen är efter ett radslut. Om det inte finns något ord vid den givna markörpositionen returneras ett tomt intervall.

  Sedan: &kde; 4.9

    String document.charAt(int rad, int kolumn);
    String document.charAt(Cursor markör);

- Returnerar tacknet på den angivna markörpositionen.

    String document.firstChar(int rad);

- Returnerar det första tecknet på angiven `rad` som inte är ett blanktecken. Det första tecknet finns på kolumn 0. Om raden är tom, eller bara innehåller blanktecken, är den returnerade strängen tom.

    String document.lastChar(int rad);

- Returnerar det sista tecknet på angiven `rad` som inte är ett blanktecken. Om raden är tom, eller bara innehåller blanktecken, är den returnerade strängen tom.

    bool document.isSpace(int rad, int kolumn);
    bool document.isSpace(Cursor markör);

- Returnerar `sant` om tecknet på den givna markörpositionen är ett blanktecken, annars `falskt`.

    bool document.matchesAt(int rad, int kolumn, String text);
    bool document.matchesAt(Cursor markör, String text);

- Returnerar `sant` om given `text` matchar på den motsvarande markörpositionen, annars `falskt`.

    bool document.startsWith(int rad, String text, bool hoppa_över_blanktecken);

- Returnerar `sant` om raden börjar med `text`, annars `falskt`. Argumentet `hoppa_över_blanktecken` bestämmer om inledande blanktecken ignoreras.

    bool document.endsWith(int rad, String text, bool hoppa_över_blanktecken);

- Returnerar `sant` om raden slutar med `text`, annars `falskt`. Argumentet `hoppa_över_blanktecken` bestämmer om inledande blanktecken ignoreras.

    bool document.setText(String text);

- Anger hela dokumentets text.

    bool document.clear();

- Tar bort hela texten i dokumentet.

    bool document.truncate(int rad, int kolumn);
    bool document.truncate(Cursor markör);

- Avkortar den givna raden på den givna kolumnen eller markörpositionen. Returnerar `sant` om det lyckas, eller `falskt` om den givna raden inte ingår i dokumentets intervall.

    bool document.insertText(int rad, int kolumn, String text);
    bool document.insertText(Cursor markör, String text);

- Infogar `text` på den givna markörpositionen. Returnerar `sant` om det lyckas, eller `falskt` om dokumentet är skrivskyddat.

    bool document.removeText(int från_rad, int från_kolumn, int till_rad, int till_kolumn);
    bool document.removeText(Cursor från, Cursor till);
    bool document.removeText(Range intervall);

- Tar bort text i det givna intervallet. Returnerar `sant` om det lyckas, eller `falskt` om dokumentet är skrivskyddat.

    bool document.insertLine(int rad, String text);

- Infogar text på den givna raden. Returnerar `sant` om det lyckas, eller `falskt` om dokumentet är skrivskyddat eller raden inte ingår i dokumentets intervall.

    bool document.removeLine(int rad);

- Tar bort den givna textraden. Returnerar `sant` om det lyckas, eller `falskt` om dokumentet är skrivskyddat eller raden inte ingår i dokumentets intervall.

    bool document.wrapLine(int rad, int kolumn);
    bool document.wrapLine(Cursor markör);

- Radbryter raden vid den givna markörpositionen. Returnerar `sant` om det lyckas, eller `falskt`, t.ex. om rad < 0.

  Sedan: &kde; 4.9

    void document.joinLines(int startrad, int slutrad);

- Sammanfogar rader från `startrad` till `slutrad`. Två på varandra följande rader åtskiljs alltid med exakt ett mellanslag.

    int document.lines();

- Returnerar antal rader i dokumentet.

    int document.length();

- Returnerar antal tecken i dokumentet.

    int document.lineLength(int rad);

- Returnerar längden på `rad`.

    void document.editBegin();

- Startar en redigeringsgrupp för gruppering av ångra/gör om. Försäkra dig om att alltid anropa `editEnd()` lika många gånger som du anropar `editBegin()`. Att anropa `editBegin()` använder en referensräknare internt, dvs. anropet kan nästlas.

    void document.editEnd();

- Avslutar en redigeringsgrupp. Det sista anropet av `editEnd()` (dvs. det för det första anropet till `editBegin()`) avslutar redigeringssteget.

    int document.firstColumn(int rad);

- Returnerar det första tecknet som inte är ett blanktecken på given `rad`. Om det bara finns blanktecken på raden, är returvärdet `-1`.

    int document.lastColumn(int rad);

- Returnerar det sista tecknet som inte är ett blanktecken på given `rad`. Om det bara finns blanktecken på raden, är returvärdet `-1`.

    int document.prevNonSpaceColumn(int rad, int kolumn);
    int document.prevNonSpaceColumn(Cursor markör);

- Returnerar kolumnen med ett tecken som inte är ett blanktecken med början på given markörposition genom att söka bakåt.

    int document.nextNonSpaceColumn(int rad, int kolumn);
    int document.nextNonSpaceColumn(Cursor markör);

- Returnerar kolumnen med ett tecken som inte är ett blanktecken med början på given markörposition genom att söka framåt.

    int document.prevNonEmptyLine(int rad);

- Returnerar nästa rad som inte är tom och som innehåller tecken som inte är blanktecken, genom att söka bakåt.

    int document.nextNonEmptyLine(int rad);

- Returnerar nästa rad som inte är tom och som innehåller tecken som inte är blanktecken, genom att söka framåt.

    bool document.isInWord(String tecken, int egenskap);

- Returnerar `sant`, om givet `tecken` med given `egenskap` kan vara en del av ett ord, annars `falskt`.

    bool document.canBreakAt(String tecken, int egenskap);

- Returnerar `sant`, om givet `tecken` med given `egenskap` är lämpat att bryta en rad, annars `falskt`.

    bool document.canComment(int startegenskap, int slutegenskap);

- Returnerar `sant` om ett intervall som börjar och slutar med den givna egenskapen är lämpat att kommenteras bort, annars `falskt`.

    String document.commentMarker(int egenskap);

- Returnerar kommentarmarkören för enraderskommentarar för en given `egenskap`.

    String document.commentStart(int egenskap);

- Returnerar kommentarmarkören för början av flerraderskommentarer för en given `egenskap`.

    String document.commentEnd(int egenskap);

- Returnerar kommentarmarkören för slutet av flerraderskommentarer för en given `egenskap`.

    int document.attribute(int rad, int kolumn);
    int document.attribute(Cursor markör);

- Returnerar egenskapen på den angivna markörpositionen.

    bool document.isAttribute(int rad, int kolumn, int egenskap);
    bool document.isAttribute(Cursor markör, int egenskap);

- Returnerar `sant` om egenskapen på den givna markörpositionen är lika med `egenskap`, annars `falskt`.

    String document.attributeName(int rad, int kolumn);
    String document.attributeName(Cursor markör);

- Returnerar egenskapsnamnet som läsbar text. Det är lika med namnet `itemData` i syntaxfärgläggningsfilerna.

    bool document.isAttributeName(int rad, int kolumn, String namn);
    bool document.isAttributeName(Cursor markör, String namn);

- Returnerar `sant` om egenskapsnamnet på en viss markörposition motsvara givet `namn`, annars `falskt`.

    String document.variable(String nyckel);

- Returnerar värdet på den begärda dokumentvariabeln `nyckel`. Om dokumentvariabeln inte finns, är returvärdet en tom sträng.

    String document.setVariable(String nyckel, String värde);

- Ställ in värdet på den begärda dokumentvariabeln `nyckel`. Returnerar värdet av den inställda variabeln.

  Se också: Kate-dokumentvariabler

  Sedan: &kde; 4.8

    int document.firstVirtualColumn(int rad);

- Returnerar den virtuella kolumnen för det första tecknet som inte är ett blanktecken på den givna raden, eller `-1` om raden är tom eller bara innehåller blanktecken.

    int document.lastVirtualColumn(int rad);

- Returnerar den virtuella kolumnen för det sista tecknet som inte är ett blanktecken på den givna raden, eller `-1` om raden är tom eller bara innehåller blanktecken.

    int document.toVirtualColumn(int rad, int kolumn);
    int document.toVirtualColumn(Cursor markör);
    Cursor document.toVirtualCursor(Cursor markör);

- Konverterar den givna verkliga markörpositionen till en virtuell markörposition, och returnerar antingen ett heltal eller ett markörobjekt.

    int document.fromVirtualColumn(int rad, int virtuell_kolumn);
    int document.fromVirtualColumn(Cursor virtuell_markör);
    Cursor document.fromVirtualCursor(Cursor virtuell_markör);

- Konverterar den givna virtuella markörpositionen till en verklig markörposition, och returnerar antingen ett heltal eller ett markörobjekt.

    Cursor document.anchor(int rad, int kolumn, Char tecken);
    Cursor document.anchor(Cursor markör, Char tecken);

- Söker bakåt efter det givna tecknet med början på den givna markören. Om exempelvis '(' anges som tecken, returnerar funktionen positionen på ett inledande '('. Det sker med referensräkning, dvs. andra '(...)' ignoreras.

    Cursor document.rfind(int rad, int kolumn, String text, int egenskap = -1);
    Cursor document.rfind(Cursor markör, String text, int egenskap = -1);

- Söker bakåt efter den givna texten med lämplig `egenskap`. Argumentet `egenskap` ignoreras om det anges som `-1`. Den returnerade markören är ogiltig om texten inte kunde hittas.

    int document.defStyleNum(int rad, int kolumn);
    int document.defStyleNum(Cursor markör);

- Returnerar standardstilen som används på den givna markörpositionen.

    bool document.isCode(int rad, int kolumn);
    bool document.isCode(Cursor markör);

- Returnerar `sant` om egenskapen på given markörposition inte är lika med någon av följande stilar: `dsComment`, `dsString`, `dsRegionMarker`, `dsChar`, `dsOthers`.

    bool document.isComment(int rad, int kolumn);
    bool document.isComment(Cursor markör);

- Returnerar `sant`, om egenskapen för tecknet på markörpositionen är `dsComment`, annars `falskt`.

    bool document.isString(int rad, int kolumn);
    bool document.isString(Cursor markör);

- Returnerar `sant`, om egenskapen för tecknet på markörpositionen är `dsString`, annars `falskt`.

    bool document.isRegionMarker(int rad, int kolumn);
    bool document.isRegionMarker(Cursor markör);

- Returnerar `sant`, om egenskapen för tecknet på markörpositionen är `dsRegionMarker`, annars `falskt`.

    bool document.isChar(int rad, int kolumn);
    bool document.isChar(Cursor markör);

- Returnerar `sant`, om egenskapen för tecknet på markörpositionen är `dsChar`, annars `falskt`.

    bool document.isOthers(int rad, int kolumn);
    bool document.isOthers(Cursor markör);

- Returnerar `sant`, om egenskapen för tecknet på markörpositionen är `dsOthers`, annars `falskt`.

## Editorkomponentens utökningar

Utökningar av editorkomponenten utökar Kate-delprogrammet, den avancerade texteditorkomponenten som används inne i många &kde;-program, såsom &kate;, &kwrite;, Kile och KDevelop. Att skapa ett insticksprogram för editorkomponenten låter dig utöka editorns funktionalitet i något eller alla dessa program.

För att komma igång, se Handledningen om insticksprogram för KTextEditor på &kde;:s teknikbas. För ännu mer, se den avancerade handledningen, också på teknikbasen.

Du hittar den fullständiga dokumentationen av programmeringsgränssnittet i &kde;:s referens för programmeringsgränssnitt.

## C++ insticksprogram för programmet &kate;

Insticksprogram för programmet Kate utökar funktionaliteten hos själva editorn &kate; på alla sätt man kan tänka sig, med användning av samma programspråk som &kate; är skrivet i, C++.

För att komma igång, se handledningen Skriva ett insticksprogram för &kate;på &kate;s webbplats. Det finns också ett klassiskt Hello world exempelinsticksprogram inkluderat i &kate;s källkod.

## &pate; Python-insticksprogram

&pate; insticksprogram låter dig också utöka &kate;s funktionalitet på vilket sätt du vill, med användning av programspråket Python.

För att komma igång, se utvecklarguiden för Python-insticksprogram på &kate;s webbplats.

Du kan också komma åt referensen för programmeringsgränssnittet på skärmen Inställning av &pate;.