http://docs.kde.org/
FöregåendeUtöka KatePartNästa

Skapa skript med JavaScript

KateParts editorkomponent kan enkelt utökas genom att skriva skript. Skriptspråket är ECMAscript (känt överallt som JavaScript). KatePart 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 $XDG_DATA_HOME/katepart5/script/indentation. I detta expanderas miljövariabeln XDG_DATA_DIRS typiskt antingen som ~/.local eller ~/.local/share.

På Windows® är filerna placerade i %USERPROFILE%\AppData\Local\katepart5\script\indentation. %USERPROFILE% expanderas oftast till C:\\Users\\användare.

Indenteringsskriptets huvud

Huvudet i filen javascript.js är inbäddat som JSON i början av dokumentet enligt följande: 

var katescript = {
    "name": "JavaScript",
    "author": "Exempelnamn <exempel.namn@någon.adress.org>",
    "license": "BSD-licens",
    "revision": 1,
    "kate-version": "5.1",
    "required-syntax-style": "javascript",
    "indent-languages": ["javascript"],
    "priority": 0,
}; // kate-script-header, måste finnas i början av filen utan kommentarer

Varje post förklaras nu i detalj:

  • 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-licensen eller LGPLv3.

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

  • kate-version [krävs]: Lägsta version av KatePart som krävs.

  • required-syntax-style [valfri]: Syntaxstilen som krävs, som matchar angiven stil i syntaxfärgläggningsfiler. 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]: JSON-fält 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.

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 Verktyg → Formatera indentering
    // ä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 → Formatera indentering.

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 KatePart med flera indenterare. Den motsvarande JavaScript-koden finns i $XDG_DATA_DIRS/katepart5/script/indentation.

På Windows® är filerna placerade i %USERPROFILE%\AppData\Local\katepart5\script\indentation. %USERPROFILE% expanderas oftast till C:\\Users\\användare.

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 KatePart-projektet genom att kontakta e-postlistan.

Kommandoradskript

Eftersom det är svårt att uppfylla allas behov, stöder KatePart 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 KatePart 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 $XDG_DATA_HOME/katepart5/script/commands. I detta expanderas miljövariabeln XDG_DATA_DIRS typiskt antingen som ~/.local eller ~/.local/share.

På Windows® är filerna placerade i %USERPROFILE%\AppData\Local\katepart5\script\commands. %USERPROFILE% expanderas oftast till C:\\Users\\användare.

Kommandoradskriptets huvud

Huvudet för varje kommandoradskript är inbäddat som JSON i början av skriptet enligt följande: 

var katescript = {
    "author": "Exempelnamn <exempel.namn@någon.adress.org>",
    "license": "LGPLv2+",
    "revision": 1,
    "kate-version": "5.1",
    "functions": ["sort", "moveLinesDown"],
    "actions": [
        {  "function": "sort",
            "name": "Sortera markerad text",
            "category": "Editing",
            "interactive": "false"
        },
        {   "function": "moveLinesDown",
            "name": "Flytta rader neråt",
            "category": "Editing",
            "shortcut": "Ctrl+Shift+Down",
            "interactive": "false"
        }
    ]
}; // kate-script-header, måste finnas i början av filen utan kommentarer

Varje post förklaras nu i detalj:

  • author [valfri]: Upphovsmannens namn och kontaktinformation.

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

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

  • kate-version [krävs]: Lägsta version av KatePart som krävs.

  • functions [krävs]: JSON-fält av kommandon i skriptet.

  • actions [valfri]: Ett JSON-fält av JSON-objekt som definierar åtgärderna som visas i programmenyn. Detaljerad information tillhandahålls i avsnittet Tilldela genvägar.

Eftersom värdet på functions är ett JSON-fält, kan ett enda skript innehålla godtyckligt antal kommandon för kommandoraden. Varje funktion är tillgänglig via KateParts 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 moveLinesDown. 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". KatePart visar därefter den returnerade texten som dokumentation för användaren. Försäkra dig om att översätta strängarna.

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.

Tilldela genvägar

För att göra det möjligt att komma åt skripten i programmenyn och tilldela genvägar, måste skriptet tillhandahålla ett lämpligt skripthuvud. I exemplet ovan, visas båda funktionerna sort och moveLinesDown i menyn på grund a följande del av skripthuvudet: 

var katescript = {
    ...
    "actions": [
        {   "function": "sort",
            "name": "Sortera markerad text",
            "icon": "",
            "category": "Editing",
            "interactive": "false"
        },
        {   "function": "moveLinesDown",
            "name": "Flytta rader neråt",
            "icon": "",
            "category": "Editing",
            "shortcut": "Ctrl+Shift+Down",
            "interactive": "false"
        }
    ]
};

Fälten för en åtgärd är följande:

  • function [krävs]: Funktionen som ska visas i menyn Verktyg → Skript.

  • name [krävs]: Texten visas i skriptmenyn.

  • icon [valfri]: Ikonen visas intill texten i menyn. Alla KDE:s ikonnamn kan användas här.

  • category [valfri]: Om en kategori anges, visas skriptet i en undermeny.

  • 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.

  • interactive [valfri]: Om skriptet kräver användarinmatning via kommandoraden, ange det här som true.

Om du utvecklar användbara skript, fundera på att bidra med det till KatePart-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 $XDG_DATA_DIRS/katepart5/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 $XDG_DATA_HOME/katepart5/libraries och inkludera den i skriptet med: 

require ("mitt_skriptnamn.js");

På Windows® är filerna placerade i %USERPROFILE%\AppData\Local\katepart5\libraries. %USERPROFILE% expanderas oftast till C:\\Users\\användare.

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 KatePart ä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 katepart5/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 katepart5/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 KateParts officiella källkod extraheras automatiskt och är översättningsbara. Med andra ord, som utvecklare av KatePart behöver man inte bry dig om att extrahera och översätta meddelanden. Observera dock att översättningen bara fungerar inne i KDE:s infrastruktur, nya strängar i skript från tredjepart som utvecklas utanför KDE, översätts inte. Överväg därför gärna att bidra med dina skript till Kate så att en passande översättning blir möjlig. 

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. 

void view.copy()

Kopiera markeringen om det finns någon, annars aktuell rad om alternativet [ ] Kopiera eller klipp ut nuvarande rad om markering saknas är aktiverat.

Sedan: KDE Ramverk 5.79

void view.cut()

Klipp ut markeringen om det finns någon, annars aktuell rad om alternativet [ ] Kopiera eller klipp ut nuvarande rad om markering saknas är aktiverat.

Sedan: KDE Ramverk 5.79

void view.paste()

Klistra in klippbordets innehåll.

Sedan: KDE Ramverk 5.79

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. 

void view.setBlockSelection(bool on);

Sätt på eller stäng av blockmarkering. 

bool view.blockSelection();

Returnerar true om blockmarkering är på, annars false. 

void view.align(Range intervall);

Indentera rader på ett riktigt sätt igen inom intervall enligt aktuella indenteringsinställningar. 

void view.alignOn(Range intervall, String mönster = "");

Justerar rader i intervall i kolumnen som anges av det reguljära uttrycket mönster. Med ett tomt mönster justeras de normalt på den första tecknet som inte är ett blanktecken. Om mönstret har en platsmarkör indenterar det där markören matchar.

Exempel:

view.alignOn(document.documentRange(), '-'); infogar mellanslag innan första - på varje rad för att justera alla på samma kolumn.

view.alignOn(document.documentRange(), ':\\s+(.)'); infogar mellanslag före det första tecknet som inte är ett blanktecken efter ett kolon för att justera alla till samma kolumn.

object view.executeCommand(String kommando,
                           String argument,
                           Range intervall);

Kör kommandoradskommandot kommando med de valfria argumenten argument och ett valfritt intervall. Returnerat objekt har den Booleska egenskapen objekt.ok som anger om körning av kommando lyckades. I händelse av fel, innehåller strängen objekt.status ett felmeddelande.

Sedan: KDE Ramverk 5.50

Range view.searchText(Range intervall,
                      String mönster,
                      bool bakåt = false);

Sök efter den första förekomsten av mönster i intervall och returnerar det matchade intervallet. Sökningen utförs bakåt om den valfria booleska parametern bakåt är inställd till true.

Det returnerade intervallet är ogiltigt (se Range.isValid()) om mönster inte hittas i intervall.

Sedan: KDE Ramverk 5.97

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. 

bool document.isLineModified(int rad);

Returnerar sant om rad för närvarande innehåller osparad data.

Since: KDE 5.0 

bool document.isLineSaved(int rad);

Returnerar sant om rad har ändrats, men dokumentet har sparats. Sålunda innehåller raden för närvarande ingen osparad data.

Since: KDE 5.0 

bool document.isLineTouched(int rad);

Returnerar sant om rad för närvarande innehåller osparad data eller tidigare har ändrats.

Since: KDE 5.0 

bool document.findTouchedLine(int startrad, bool ner);

Sök efter nästa ändrade rad med början på rad. Sökningen utförs antingen uppåt eller neråt beroende på sökriktningen angiven med ner.

Since: KDE 5.0 

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. 

Range document.documentRange();

Returnerar ett intervall som omfattar hela dokumentet. 

Cursor documentEnd();

Returnerar en markör placerad på den sista radens sista kolumn i dokumentet. 

bool isValidTextPosition(int rad, int kolumn);
bool isValidTextPosition(Cursor markör);

Returnerar sant om den angivna markörpositionen är placerad på en giltig textposition. En textposition är bara giltig om den finns i början av, mitten av eller slutet av en giltig rad. Dessutom är en textposition ogiltig om den är placerad i ett Unicode-surrogat.

Since: KDE 5.0 

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. 

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

Ställ in värdet på den begärda dokumentvariabeln nyckel.

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. 

void document.indent(Range intervall, int ändring);

Indentera alla rader i intervall med ändring tabulatortecken eller ändring gånger tabulatorstorlek mellanslag beroende på användarens inställningar. Parametern ändring kan vara negativ.

Programmeringsgränssnittet för editorn

Förutom dokumentet och programmeringsgränssnittet för vyn, finns ett generellt programmeringsgränssnitt för editorn som tillhandahåller funktioner för allmän redigeringsskriptfunktionalitet. 

String editor.clipboardText();

Returnerar texten som för närvarande finns i det globala klippbordet.

Sedan: KDE Ramverk 5.50

String editor.clipboardHistory();

Editorn har en klippbordshistorik som innehåller upp till tio klippbordsposter. Funktionen returnerar alla poster som för närvarande finns i klippbordshistoriken.

Sedan: KDE Ramverk 5.50

void editor.setClipboardText(String text);

Ställ in klippbordets innehåll till text. text läggs till i klippbordshistoriken.

Sedan: KDE Ramverk 5.50