http://docs.kde.org/
TerugKatePart uitbreidenVolgende

Scripting met JavaScript

De editor-component van KatePart is eenvoudig uit te breiden met scripts. De scripttaal is ECMAScript (breed bekend als JavaScript). KatePart ondersteunt twee soorten scripts: inspringen en commandoregelscripts. Een functionaliteit gelijk aan opdrachtregelscripts wordt ook geleverd in de snippets plug-in.

Inspringscripts

Inspringscripts - ook genoemd indenteerders - laten de broncode inspringen bij het typen van tekst. Na het indrukken van de toets Enter zal het inspringniveau vaak toenemen.

De volgende secties beschrijven stap voor stap hoe het skelet voor een eenvoudige indenteerder te maken. Als eerste stap, maak een nieuw bestand *.js aan, bijv. met de naam javascript.js in de lokale thuismap $XDG_DATA_HOME/katepart5/script/indentation. Waarin de omgevingsvariabele XDG_DATA_HOME typisch expandeert tot ofwel ~/.local of ~/.local/share.

Op Windows® zijn deze bestanden gelokaliseerd in %USERPROFILE%\AppData\Local\katepart5\script\indentation. %USERPROFILE% wordt gewoonlijk C:\\Users\\gebruiker.

De kop van het inspringscript

De kop van het bestand javascript.js is ingebed als JSON aan het begin van het document als volgt: 

var kate-script = {
 * "name": JavaScript
 * "author": Voorbeeldnaam <voorbeeld.naam@een.adres.org>,
 * "license": "BSD License"
 * "revision": 1,
 * "kate-version": "5.1",
 * "required-syntax-style": javascript,
 * "indent-languages": ["javascript"],
 * "priority": 0,
 *}; // kate-script-header, moet aan het begin van het bestand staan zonder commentaar

Elk item wordt nu in detail uitgelegd:

  • name [vereist]: Dit is de naam van de indenteerder die in het menu Hulpmiddelen → Inspringen verschijnt en in de configuratiedialoog.

  • author [optioneel]: De naam van de auteur en contactinformatie.

  • license [optioneel]: Korte vorm van de licentie, zoals BSD License of LGPLv3.

  • revision [vereist]: De revisie van het script. Dit getal moet verhoogd worden wanneer het script wordt gewijzigd.

  • kate-version [required]: Minimaal vereiste versie van KatePart.

  • required-syntax-style [optioneel]: De vereiste stijl voor de syntaxis, die overeenkomt met de gespecificeerde style in bestanden voor accentuering van syntaxis. Dit is belangrijk voor indenteerders die vertrouwen op specifieke informatie voor accentuering in het document. Als een vereiste syntaxisstijl is gespecificeerd, zal de indenteerder alleen beschikbaar zijn wanneer het juiste programma voor accentuering actief is. Dit voorkomt “ongedefinieerd gedrag” veroorzaakt door de indenteerder te gebruiken zonder het verwachte schema voor accentuering. De Ruby indenteerder, bijvoorbeeld, maakt hier gebruik van in de bestanden ruby.js en ruby.xml.

  • indent-languages [optioneel]: JSON array van syntaxis stijlen die de indenteerder correct kan laten inspringen, bijv.: ["c++", "java"].

  • priority [optioneel]: Als verschillende indenteerders geschikt zij voor een bepaald bestand om te accentueren, dan bepaalt de prioriteit welke indenteerder als standaard wordt gekozen.

De broncode van de indenteerder

Nadat de header is gespecificeerd, legt deze sectie uit hoe het script voor inspringen zelf werkt. Het basis sjabloon van de inhoud ziet er uit als volgt: 

// vereiste js-bibliotheken van katepart, bijv. range.js als u Range gebruikt
require ("range.js");
triggerCharacters = "{}/:;";
function indent(line, indentWidth, ch)
{
    // aangeroepen voor elk teken nieuwe-regel (ch == '\n') en alle tekens gespecificeerd in
    // de globale variabele triggerCharacters. Bij het aanroepen van Hulpmiddelen → Inspringen formatteren
    // is de variabele ch leeg, i.e. ch == ''.
    //
    // zie ook: Scripting API
    return -2;
}

De functie indent() heeft drie parameters:

  • line: de regel die moet inspringen

  • indentWidth: de inspringbreedte in aantal spaties

  • ch: of een teken nieuwe-regel (ch == '\n'), het activeringsteken gespecificeerd in triggerCharacters of leeg als de gebruiker de actie Hulpmiddelen → Uitlijnen heeft gestart.

De terugkeerwaarde van de functie indent() specificeert hoe de regel zal worden ingesprongen. Als de terugkeerwaarde een eenvoudig geheel getal is, wordt deze geïnterpreteerd als volgt:

  • terugkeerwaarde -2: niets doen

  • terugkeerwaarde -1: behoudt het inspringen (zoekt naar voorgaande niet-blanko regel)

  • terugkeerwaarde 0: getallen >= 0 specificeer de insringdiepte in spaties

Alternatief, een reeks van twee elementen kan worden teruggegeven:

  • geef [ indent, align ] terug;

In dit geval is het eerste element de inspringdiepte zoals hierboven met dezelfde betekenis van de speciale waarden. Het tweede element is een absolute waarde die een kolom aangeeft voor “uitlijning”. Als deze waarde groter is dan de inspringwaarde, dan is het verschil een aantal spaties dat na het inspringen van de eerste parameter moet worden toegevoegd. Anders wordt het tweede getal genegeerd. Tabs en spaties voor inspringen gebruiken wordt vaak “gemengde modus” genoemd.

beschouw het volgende voorbeeld: Neem aan dat tabs worden gebruikt voor inspringen en tabbreedte is ingesteld op 4. <tab> vertegenwoordigt hier een tab-teken en '.' een spatie: 

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

Bij inspringen van regel 2 zal de functie indent() [8, 15] als terugkeerwaarde geven. Als resultaat worden hier twee tabs ingevoegd om in te springen tot kolom 8 en worden 7 spaties toegevoegd om de tweede parameter uit te lijnen onder de eerste, zodat het uitgelijnd blijft als het bestand wordt bekeken met een andere tabbreedte.

Een standaard KDE installatie levert bij KatePart verschillende indenteerders. De overeenkomstige JavaScript broncode kan worden gevonden in $XDG_DATA_DIRS/katepart5/script/indentation.

Op Windows® zijn deze bestanden gelokaliseerd in %USERPROFILE%\AppData\Local\katepart5\script\indentation. %USERPROFILE% wordt gewoonlijk C:\\Users\\gebruiker.

Ontwikkeling van een indenteerder vereist herladen van de scripts om te zien of de wijzigingen zich netjes gedragen. In plaats van het opnieuw opstarten van de toepassing, schakel eenvoudig om naar de commandoregel en start het commando reload-scripts.

Als u bruikbare scripts ontwikkeld overweeg dan deze aan het KatePart-project bij te dragen door een mengverzoek naar our GitLab project.

Commandoregelscripts

Opmerking

Een functionaliteit gelijk aan opdrachtregelscripts wordt ook geleverd in de snippets plug-in. Deze plug-in kan een gemakkelijker startpunt leveren, speciaal voor kleine eigen scripts.

Omdat het moeilijk is om aan de noden van iedereen te voldoen, ondersteunt KatePart kleine hulpmiddelen voor snelle tekstmanipulatie via de ingebouwde commandoregel. Het commando sort is bijvoorbeeld geïmplementeerd als een script. Deze sectie legt uit hoe *.js bestanden aan te maken om KatePart uit te breiden met willekeurige hulpscripts.

Commandoregelscripts staan in dezelfde map als inspringscripts. Dus als eerste stap maakt u een nieuw *.js bestand aan genaamd myutils.js in de lokale map $XDG_DATA_HOME/katepart5/script/commands. De omgevingsvariabele XDG_DATA_HOME daarin expandeert typisch tot ofwel ~/.local of ~/.local/share.

Op Windows® zijn deze bestanden gelokaliseerd in %USERPROFILE%\AppData\Local\katepart5\script\commands. %USERPROFILE% wordt gewoonlijk C:\\Users\\user.

De kop van het commandoregelscript

De header van elke commandoregelscript is ingebed in JSON aan het begin van het script als volgt: 

var katescript = {
    "author": "Voorbeeldnaam <voorbeeld.naam@een.adres.org>",
    "license": "LGPLv2+",
    "revision": 1,
    "kate-version": "5.1",
    "functions": ["sort", "moveLinesDown"],
    "actions": [
        {   "function": "sort",
            "name": "Sort Selected Text",
            "category": "Editing",
            "interactive": "false"
        },
        {   "function": "moveLinesDown",
            "name": "Move Lines Down",
            "category": "Editing",
            "shortcut": "Ctrl+Shift+Down",
            "interactive": "false"
        }
    ]
}; // kate-script-header, moet zich bevinden aan het begin van het bestand zonder commentaar

Elk item wordt nu in detail uitgelegd:

  • author [optioneel]: De naam van de auteur en contactinformatie.

  • license [optioneel]: Korte vorm van de licentie, zoals BSD licentie of LGPLv2.

  • revision [vereist]: De revisie van het script. Dit getal moet verhoogd worden wanneer het script wordt gewijzigd.

  • kate-version [required]: Minimaal vereiste versie van KatePart.

  • functions [vereist]: JSON-array met commando's in het script.

  • actions [optioneel]: JSON Array van JSON objecten die de acties definiëren die verschijnen in het menu van de toepassing. Gedetailleerde informatie wordt in de sectie Koppelen van sneltoetsen.

Omdat de waarde van functions een JSON array is, is een enkel script in staat een willekeurig aantal commandoregels te bevatten. Elke functie is beschikbaar via ingebouwde commandoregel van KatePart.

De broncode van het script

Alle in de kop gespecificeerde functies moeten worden geïmplementeerd in het script. Het script-bestand uit het bovenstaande voorbeeld moet de twee functies sort en moveLinesDown implementeren. Alle functies hebben de volgende syntaxis: 

// vereiste js-bibliotheken van katepart, bijv. range.js als u Range gebruikt
require ("range.js");

function <naam>(arg1, arg2, ...)
{
    // ... implementatie, zie ook: Scripting API
}

De argumenten in de commandoregel worden doorgegeven naar de functie als arg1, arg2, etc. Om documentatie voor elk commando te leveren, implementeert u eenvoudig de functie 'help' als volgt: 

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

uitvoeren van help sort in de commandoregel roept deze help-functie op met het argument cmd ingesteld op het gegeven commando, bijv. cmd == "sort". KatePart laat dan de teruggeleverde tekst zien als documentatie voor de gebruiker. Zorg er voor dat de tekenreeksen vertaald zijn.

Ontwikkeling van een commandoregelscript vereist herladen van de scripts om te zien of de wijzigingen zich netjes gedragen. In plaats van het opnieuw opstarten van de toepassing, schakel eenvoudig om naar de commandoregel en start het commando reload-scripts.

Koppelen van sneltoetsen

Om de scripts toegankelijk te maken in het menu van de toepassing en sneltoetsen toe te kunnen, moet het script een juiste script-header leveren. In het bovenstaande voorbeeld, verschijnen beide functies sort en moveLinesDown in het menu vanwege het volgende deel in de script-header: 

var katescript = {
    ...
    "actions": [
        {   "function": "sort",
            "name": "Sort Selected Text",
            "icon": "",
            "category": "Editing",
            "interactive": "false"
        },
        {   "function": "moveLinesDown",
            "name": "Move Lines Down",
            "icon": "",
            "category": "Editing",
            "shortcut": "Ctrl+Shift+Down",
            "interactive": "false"
        }
    ]
};

De velden voor een actie zijn als volgt:

  • function [vereist]: De functie die zou moeten verschijnen in het menu Hulpmiddelen → Scripts.

  • name [vereist]: De tekst verschijnt het script-menu.

  • icon [optioneel]: Het pictogram verschijnt naast de tekst in het menu. Alle pictogramnamen van KDE kunnen hier worden gebruikt.

  • category [optioneel]: Als een categorie wordt gespecificeerd, verschijnt het script in een submenu.

  • shortcut [optioneel]: De hier gegeven sneltoets is de standaard sneltoets. Voorbeeld: Ctrl+Alt+t. Zie de Qt™-documentatie voor verdere details.

  • interactive [optioneel]: Als het script invoer van de gebruiker in de commandoregel nodig heeft, zet dit dan op true.

Als u bruikbare scripts ontwikkeld overweeg dan deze aan het KatePart-project bij te dragen door een mengverzoek naar our GitLab project.

API voor scripts maken

De API voor scripts hier aanwezig is beschikbaar voor alle scripts, bijv. scripts voor inspringen en opdrachtregels. De klassen Cursor en Range worden geleverd door biblitheekbestanden in $XDG_DATA_DIRS/katepart5/libraries. Als u ze in uw script wilt gebruiken, wat nodig is om bepaalde Document of View-functies te gebruiken, voeg dan de benodigde bibliotheek in met: 

// vereiste js-bibliotheken van katepart, bijv. range.js als u Range gebruikt
require ("range.js");

Om de standaard API voor scripting uit te breiden met uw eigen functies en prototypen, maak gewoon een nieuw bestand aan in de lokale configuratiemap van KDE $XDG_DATA_HOME/apps/katepart5/libraries en voeg deze in in uw script met: 

require ("mijnscriptnaamhier.js");

Op Windows® zijn deze bestanden gelokaliseerd in %USERPROFILE%\AppData\Local\katepart5\libraries. %USERPROFILE% wordt gewoonlijk C:\\Users\\user.

Om bestaande prototypes zoals Cursor of Reeks uit te breiden, os de aanbevolen manier om niet de globale *.js bestanden te wijzigen. In plaats daarvan wijzigt u het prototype Cursor in JavaScript nadat cursor.js is ingevoegd in uw script via require.

Cursors en bereiken

Omdat KatePart is een tekstbewerker is, is alles voor de API voor scripting, waar mogelijk, gebaseerd op cursors en reeksen. Een cursor is een eenvoudig een paar (regel, kolom) die een tekstpositie in het document weergeeft. Een reeks omspant tekst van een begincursorpositie tot een eincursorpositie. De API wordt in de volgende secties in detail uitgelegd.

Het prototype van cursor
Cursor();

Constructor. Levert een cursor terug op positie (0, 0).

Voorbeeld: var cursor = new Cursor(); 

Cursor(int regel, int kolom);

Constructor. Levert een cursor terug op positie (regel, kolom).

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

Cursor(Cursor andere);

Constructor kopiëren. Geeft een kopie van de cursor andere.

Voorbeeld:var copy = nieuwe cursor(andere); 

Cursor Cursor.clone();

Geeft een kloon van de cursor terug.

Voorbeeld: var clone = cursor.clone(); 

Cursor.setPosition(int regel, int kolom);

Stel de cursorpositie in op regel en kolom.

Sinds: KDE 4.11 

bool Cursor.isValid();

Controleert of de cursor geldig is. De cursor is ongeldig indien lijn en/of kolom ingesteld zijn op -1.

Voorbeeld: var valid = cursor.isValid(); 

Cursor Cursor.invalid();

Geeft een nieuwe ongeldige cursor op locatie (-1, -1).

Voorbeeld:var invalidCursor = cursor.invalid(); 

int Cursor.compareTo(Cursor andere);

Vergelijkt deze cursor met de cursor andere. Geeft terug

  • -1, indien deze cursor zich bevindt voor de cursor andere,

  • 0, indien beide cursors gelijk zijn

  • +1, als deze cursor gelokaliseerd is na de cursor andere.

bool Cursor.equals(Cursor andere);

Geeft true terug, als deze cursor en de cursor andere gelijk zijn, anders false. 

String Cursor.toString();

Geeft de cursor terug als een tekenreeks met de vorm “Cursor(regel, kolom)”.

Het prototype Range
Range();

Constructor. Aanroepen van new Range() geeft een bereik op (0, 0) - (0, 0) terug. 

Range(Cursor begin, Cursor eind);

Constructor. Aanroepen van new Range(begin, eind) geeft de Reeks (begin, eind) terug. 

Range(int beginRegel, int beginKolom, int eindRegel, int eindKolom);

Constructor. Aanroepen van new Range(beginRegel, beginKolom, eindeRegel, eindKolom) geeft de Reeks van (beginRegel, beginKolom) tot (eindeRegel, eindKolom). 

Range(Range andere);

Constructor kopiëren. Geeft een kopie terug van Range andere. 

Reeks Range.clone();

Geeft een kloon van de reeks terug.

Voorbeeld: var clone = range.clone(); 

bool Range.isEmpty();

Geeft true terug, als zowel begin als einde cursor gelijk zijn.

Voorbeeld: var empty = range.isEmpty();

Sinds: KDE 4.11 

bool Range.isValid();

Geeft true terug, als zowel begin als einde cursor geldig zijn, anders false.

Voorbeeld: var valid = range.isValid(); 

Range Range.invalid();

Geeft de Reeks van (-1, -1) tot (-1, -1) terug. 

bool Range.contains(Cursor cursor);

Geeft true terug, als de reeks de cursorpositie bevat, anders false. 

bool Range.contains(Range andere);

Geeft true terug, als deze reeks de Reeksandere bevat, anders false. 

bool Range.containsColumn(int kolom);

Geeft true terug, als kolom zich in het half open interval [start.column, end.column) bevindt, anders false. 

bool Range.containsLine(int regel);

Geeft true terug, als regel zich in het half open interval [start.line, end.line) bevindt, anders false. 

bool Range.overlaps(Range overig);

Geeft true terug, als deze reeks en de reeksoverig een gebied delen, anders false. 

bool Range.overlapsLine(int regel);

Geeft true terug, als regel zich in het interval [start.line, end.line) bevindt, anders false. 

bool Range.overlapsColumn(int kolom);

Geeft true terug, als kolom zich in het interval [start.column, end.column) bevindt, anders false. 

bool Range.onSingleLine();

Geeft true terug, als zowel begin als einde van de reeks op dezelfde regel, bijv. als Range.start.line == Range.end.line.

Sinds: KDE 4.9 

bool Range.equals(Range overig);

Geeft true terug, als deze reeks de Reeks andere gelijk zijn, anders false. 

String Range.toString();

Geeft de reeks terug als een tekenreeks van de vorm “Range(Cursor(line, column), Cursor(line, column))”.

Globale functies

Deze sectie geeft een lijst met alle globale functies.

Lezen & invoegen van bestanden
String read(String bestand);

Zal het gegeven bestand zoeken relatief ten opzichte van de map katepart5/script/files en en de inhoud teruggeven als een tekenreeks. 

void require(String bestand);

Zal het gegeven bestand zoeken relatief ten opzichte van de map katepart5/script/libraries en het evalueren. require is intern beschermd tegen meervoudig invoegen van hetzelfde bestand.

Sinds: KDE 4.10

Debugging
void debug(String tekst);

Stuurt tekst naar stdout in de console na het starten van de toepassing.

Vertaling

Om volledige lokalisatie te ondersteunen zijn er verschillende functies om tekenreeksen in scripts te vertalen, namelijk i18n, i18nc, i18np en i18ncp. Deze functies gedragen zich op precies dezelfde manier zoals in Vertalingsfuncties van KDE.

De vertalingfuncties vertalen de omwikkelde tekenreeksen via het vertalingssysteem van KDE naar de in de toepassing gebruikte taal. Tekenreeksen in scripts die worden ontwikkeld in de officiële broncode van KatePart worden automatisch geëxtraheerd en vertaalbaar gemaakt. Met andere woorden, als ontwikkelaar van KatePart hoeft u zich niet bezig te houden met extraheren en vertalen. Opgemerkt moet echter worden dat de vertaling alleen werkt binnen de infrastructuur van $kde;. Dat wil zeggen dat nieuwe tekenreeksen in scripts van derden ontwikkeld buiten KDE niet worden vertaald. Neem dus in overweging om uw scripts aan Kate bij te dragen zodat vertaling mogelijk wordt. 

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

Vertaalt text in de taal die wordt gebruikt door de toepassing. De argumenten arg1, ..., zijn optioneel en worden gebruikt om plaatshouders %1, %2, etc. te vervangen.

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

Vertaalt text in de taal die wordt gebruikt door de toepassing. Bovendien is de tekenreeks context zichtbaar voor de vertalers, zodat zij een betere vertaling kunnen produceren. De argumenten arg1, ..., zijn optioneel en worden gebruikt om plaatshouders %1, %2, etc. te vervangen.

void i18np(String enkelvoud, String meervoud, int nummer, arg1, ...);

Vertaalt ofwel enkelvoud of meervoud in de taal die wordt gebruikt door de toepassing, afhankelijk van het gegeven nummer. De argumenten arg1, ..., zijn optioneel en worden gebruikt om plaatshouders %1, %2, etc. te vervangen.

void i18ncp(String context, String eenvoud, String meervoud, int nummer, arg1, ...);

Vertaalt enkelvoud ofmeervoud in de taal die wordt gebruikt door de toepassing, afhankelijk van het gegeven nummer. Bovendien is de tekenreeks context zichtbaar voor de vertalers, zodat zij een betere vertaling kunnen produceren. De argumenten arg1, ..., zijn optioneel en worden gebruikt om plaatshouders %1, %2, etc. te vervangen.

De API voor weergave

Wanneer een script wordt uitgevoerd, dan is er een globale variabele “view” die de huidige actieve editor-view representeert. Het volgende is een lijst met alle beschikbare weergavefuncties. 

void view.copy()

Kopieer de selectie als er een is, anders de huidige regel als de optie [ ] Kopieer/knip de huidige regel als er geen selectie is is gezet.

Sinds: KDE Frameworks™ 5.79

void view.cut()

Knip de selectie als er een is, anders de huidige regel als de optie [ ] Kopieer/knip de huidige regel als er geen selectie is is gezet.

Sinds: KDE Frameworks™ 5.79

void view.paste()

De inhoud van het klembord plakken.

Sinds: KDE Frameworks™ 5.79

Cursor view.cursorPosition()

Geeft de huidige cursorpositie in het beeld terug.

void view.setCursorPosition(int line, int column);
void view.setCursorPosition(Cursor cursor);

Stelt de huidige cursorpositie in op ofwel (regel, kolom) of op de gegeven cursor. 

Cursor view.virtualCursorPosition();

Geeft de virtuele cursorpositie terug waarin elke tab telt voor de overeenkomstige hoeveelheid spaties afhankelijk van de huidige tabbreedte. 

void view.setVirtualCursorPosition(int line, int column);
void view.setVirtualCursorPosition(Cursor cursor);

Stelt de huidige virtuele cursorpositie in op (regel, kolom) of op de gegeven cursor. 

String view.selectedText();

Geeft de geselecteerde tekst terug. Als er geen tekst is geselecteerd dan is de tekenreeks leeg. 

bool view.hasSelection();

Geeft true terug, als het beeld geselecteerde tekst heeft, anders false. 

Range view.selection();

Geeft de geselecteerde tekstreeks terug. Als er geen tekst is geselecteerd dan is de tekenreeks ongeldig. 

void view.setSelection(Range reeks);

Stelt de geselecteerde tekst in op de gegeven reeks. 

void view.removeSelectedText();

Verwijder de geselecteerde tekst. Als het beeld geen geselecteerde tekst bevat, dan doet dit niets. 

void view.selectAll();

Selecteert de gehele tekst in het document. 

void view.clearSelection();

Wist de tekstselectie zonder de tekst te verwijderen. 

void view.setBlockSelection(bool on);

Modus blokselectie aan- of uitzetten. 

bool view.blockSelection();

Geeft true terug, als modus blokselectie aan is, anders false. 

void view.align(Range reeks);

Regels opnieuw laten inspringen binnen reeks volgens de huidige instellingen voor inspringen. 

void view.alignOn(Range reeks, String patroon = "");

Lijnt regels uit in de reeks op de kolom gegeven door de reguliere expressie patroon. Met een leeg patroon zal er standaard uitgelijnd worden op het eerste niet-blanke teken. Als het patroon een vangst heeft zal het inspringen op de gevangen overeenkomst.

Voorbeelden:

view.alignOn(document.documentRange(), '-'); zal spaties invoegen vóór de eerste - van elke regel om ze allemaal uit te lijnen op dezelfde kolom.

view.alignOn(document.documentRange(), ':\\s+(.)'); zal spaties invoegen vóór het eerste niet-blanke teken dat verschijnt na een dubbelepunt om ze allemaal op dezelfde kolom uit te lijnen.

object view.executeCommand(String commando,
                           String argumenten,
                           Range reeks);

Voert het opdrachtregelcommando commando uit met de optionele argumenten argumenten en de optionele reeks. Het terugontvangen object heeft een eigenschap boolean object.ok die aangeeft of uitvoeren van het commando met succes was. In geval van een fout, bevat de tekenreeks object.status een foutbericht.

Sinds: KDE Frameworks™ 5.50

Range view.searchText(Range reeks,
                      String patroon,
                      bool achterwaarts = false);

Naar het eerste voorkomen van patroon zoeken in reeks en de overeenkomende reeks teruggeven. Zoeken wordt achterwaarts uitgevoerd als de optionele booleaanse parameter achterwaarts is ingesteld op true.

De teruggegeven reeks is ongeldig (zie Range.isValid()) als patroon niet wordt gevonden in reeks.

Sinds: KDE Frameworks™ 5.97

De API van Document

Wanneer een script uitgevoerd wordt is er een globale variabele “document” die het huidige actieve document representeert. Het volgende is een lijst met alle beschikbare documentfuncties. 

String document.fileName();

Geeft de bestandsnaam van het document terug of een lege tekenreeks voor niet opgeslagen tekstbuffers. 

String document.url();

Geeft de volledige URL van het document terug of een lege tekenreeks voor niet opgeslagen tekstbuffers. 

String document.mimeType();

Geeft het MIME-type van het document terug of het MIME-type application/octet-stream als er geen toepasselijk MIME-type gevonden kan worden. 

String document.encoding();

Geeft de nu gebruikte codering terug om het bestand op te slaan. 

String document.highlightingMode();

Geeft de gebruikte globale accentueringmodus terug voor het gehele document. 

String document.highlightingModeAt(Cursor pos);

Geeft de gebruikte accentueringmodus terug op de gegeven positie in het document. 

Array document.embeddedHighlightingModes();

Geeft een reeks van accentueringmodi terug ingebed in dit document. 

bool document.isModified();

Geeft true terug, als het document niet opgeslagen wijzigingen heeft(gemodificeerd), anders false. 

String document.text();

Geef de gehele inhoud van het document terug in een enkele tekenreeks. Nieuwe regels zijn gemarkeerd met het teken nieuw-regel “\n”. 

String document.text(int vanafRegel, int vanafKolom, int totRegel, int totKolom);
String document.text(Cursor vanaf, Cursor tot);
String document.text(Range bereik);

Geeft de tekst terug in het gegeven bereik. Het is aanbevolen de cursor te gebruiken en een versie gebaseerd op bereik voor betere leesbaarheid van de broncode. 

String document.line(int regel);

Geeft de gegeven tekstregel terug als tekenreeks. De tekenreeks is leeg als de gevraagde regel buiten het bereik ligt. 

String document.wordAt(int regel, int kolom);
String document.wordAt(Cursor cursor);

Geeft het woord terug op de gegeven cursorpositie. 

Range document.wordRangeAt(int regel, int kolom);
Range document.wordRangeAt(Cursor cursor);

Geeft de reeks van het woord op de gegeven cursorpositie terug. De teruggeven reeks is ongeldig (zie Range.isValid()), als de tekstpositie zich na het eind van een regel bevindt. Als er geen woord is op de gegeven cursorpositie, zal een lege reeks worden teruggegeven.

Sinds: KDE 4.9 

String document.charAt(int regel, int kolom);
String document.charAt(Cursor cursor);

Geeft het teken terug op de gegeven cursorpositie. 

String document.firstChar(int regel);

Geeft het eerste teken in de gegeven regel terug die geen witruimte is. Het eerste teken is in kolom 0. Als de regel leeg of alleen witruimte bevat, dan is de teruggegeven tekenreeks leeg. 

String document.lastChar(int regel);

Geeft het laatste teken in de gegeven regel terug die geen witruimte is. Als de regel leeg of alleen witruimte bevat, dan is de teruggegeven tekenreeks leeg. 

bool document.isSpace(int regel, int kolom);
bool document.isSpace(Cursor cursor);

Geeft true terug, als het teken op de gegeven cursorpositie gelijk is aan een witruimte, anders false. 

bool document.matchesAt(int regel, int kolom, String tekst);
bool document.matchesAt(Cursor cursor, String tekst);

Geeft true terug, als de gegeven tekst overeenkomt met de overeenkomstige cursorpositie, anders false. 

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

Geeft true terug als de regel begint met tekst, anders false. Het argument skipWhiteSpaces bepaalt of voorloopwitruimte genegeerd worden. 

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

Geeft true terug als de regel eindigt met tekst, anders false. Het argument skipWhiteSpaces bepaalt of witruimte achteraan genegeerd wordt. 

bool document.setText(String tekst);

Stelt de gehele documenttekst in. 

bool document.clear();

Verwijdert de gehele tekst uit het document. 

bool document.truncate(int regel, int kolom);
bool document.truncate(Cursor cursor);

Kap de gegeven regel op de gegeven kolom of cursorpositie af. Geeft true terug bij succes of false als de gegeven regel geen deel is van het documentbereik. 

bool document.insertText(int regel, int kolom, String tekst);
bool document.insertText(Cursor cursor, String tekst);

Voeg de tekst op de cursorpositie in. Geeft true terug bij succes of false, als het document alleen-lezen is. 

bool document.removeText(int vanafRegel, int vanafKolom, int totRegel, int totKolom);
bool document.removeText(Cursor vanaf, Cursor tot);
bool document.removeText(Range bereik);

Verwijdert de tekst in het gegeven bereik. Geeft true terug bij succes of false, als het document alleen-lezen is. 

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

Voegt tekst in de gegeven regel in. Geeft true terug bij succes of false, als het document alleen-lezen is of de regel niet in het documentbereik ligt. 

bool document.removeLine(int regel);

Verwijdert de gegeven tekstregel. Geeft true terug bij succes of false, als het document alleen-lezen is of de regel niet in het documentbereik ligt. 

bool document.wrapLine(int regel, int kolom);
bool document.wrapLine(Cursor cursor);

Breekt de regel op de gegeven cursorpositie op. Geeft true terug bij succes, anders false, bijv. als regel < 0.

Sinds: KDE 4.9 

void document.joinLines(int beginRegel, int eindRegel);

Voegt de regels vanaf beginRegel tot eindRegel samen. Twee elkaar opvolgende tekstregels worden altijd gescheiden door een enkele spatie. 

int document.lines();

Geeft het aantal regels in het document terug. 

bool document.isLineModified(int regel);

Geeft true terug, als regel nu niet opgeslagen gegevens bevat.

Sinds: KDE 5.0 

bool document.isLineSaved(int regel);

Geeft true terug, als regel is gewijzigd, maar het document is opgeslagen. Dus bevat de regel nu geen niet opgeslagen gegevens.

Sinds: KDE 5.0 

bool document.isLineTouched(int regel);

Geeft true terug, als regel nu niet opgeslagen gegevens bevat of eerder is gewijzigd.

Sinds: KDE 5.0 

void document.findTouchedLine(int beginRegel, bool oplaag);

Zoek naar de volgende aangeraakte regel beginnend bij regel. Het zoeken wordt uitgevoerd ofwel omhoog of omlaag afhankelijk van de zoekrichting gespecificeerd in omlaag.

Sinds: KDE 5.0 

int document.length();

Geeft het aantal tekens in het document terug. 

int document.lineLength(int regel);

Geeft de lengte van de regel terug. 

void document.editBegin();

Begint een bewerkingsgroep voor groepering van ongedaan maken/opnieuw doen. Controleer altijd of editEnd() is aangeroepen als u editBegin() aanroept. Aanroepen van editBegin() gebruikt intern een referentieteller, bijv. deze aanroep kan genest worden. 

void document.editEnd();

Beëindigt een bewerkingsgroep. De laatst aanroep van editEnd() (bijv. diegene voor de eerste aanroep van editBegin()) beëindigt de bewerkingsstap. 

int document.firstColumn(int regel);

Geeft de eerste niet-witruimte kolom in de gegeven regel terug. Als er alleen witruimte in de regel bevindt, dan is de terugkeerwaarde -1. 

int document.lastColumn(int regel);

Geeft de laatste niet-witruimte kolom in de gegeven regel terug. Als er alleen witruimte in de regel bevindt, dan is de terugkeerwaarde -1. 

int document.prevNonSpaceColumn(int regel, int kolom);
int document.prevNonSpaceColumn(Cursor cursor);

Geeft de kolom terug met een niet-witruimte teken beginnend bij de gegeven cursorpositie en achterwaarts zoeken. 

int document.nextNonSpaceColumn(int regel, int kolom);
int document.nextNonSpaceColumn(Cursor cursor);

Geeft de kolom terug met een niet-witruimte teken beginnend bij de gegeven cursorpositie en voorwaarts zoeken. 

int document.prevNonEmptyLine(int regel);

Geeft de volgende niet-lege regel terug met een niet-witruimte tekens en achterwaarts zoeken. 

int document.nextNonEmptyLine(int regel);

Geeft de volgende niet-lege regel terug met een niet-witruimte teken en voorwaarts zoeken. 

bool document.isInWord(String teken, int attribuut);

Geeft true terug, als het gegeven teken met het gegeven attribuut deel van een woord kan zijn, anders false. 

bool document.canBreakAt(String teken, int attribuut);

Geeft true terug, als het gegeven teken met het gegeven attribuut geschikt is om een regel af te breken, anders false. 

bool document.canComment(int beginAttribuut, int eindAttribuut);

Geeft true terug, als een bereik beginnend en eindigend met de gegeven attributen geschikt is om als commentaar te worden aangemerkt, anders false. 

String document.commentMarker(int attribuut);

Geeft de markeerder voor commentaar terug voor commentaar op een enkele regel voor een gegeven attribuut. 

String document.commentStart(int attribuut);

Geeft de markeerder voor commentaar terug voor begin van commentaar over meerdere regels voor een gegeven attribuut. 

String document.commentEnd(int attribuut);

Geeft de markeerder voor commentaar terug voor het einde van commentaar over meerdere regels voor een gegeven attribuut. 

Range document.documentRange();

Geeft een reeks terug die het gehele document omvat. 

Cursor documentEnd();

Geeft een cursor terug gepositioneerd in de laatste kolom van de laatste regel in het document. 

bool isValidTextPosition(int regel, int kolom);
bool isValidTextPosition(Cursor cursor);

Geeft true terug, als de gegeven cursorpositie is gepositioneerd op een geldige tekstpositie. Een tekstpositie is alleen geldig als het is gelokaliseerd aan het begin, in het midden, of aan het eind van een geldige regel. Verder is een tekstpositie ongeldig als het is gelokaliseerd in een Unicode-surrogaat.

Sinds: KDE 5.0 

int document.attribute(int regel, int kolom);
int document.attribute(Cursor cursor);

Geeft het attribuut terug op de gegeven cursorpositie. 

bool document.isAttribute(int regel, int kolom, int attribuut);
bool document.isAttribute(Cursor cursor, int attribuut);

Geeft true terug, als het attribuut op de gegeven cursorpositie gelijk is aan attribuut, anders false. 

String document.attributeName(int regel, int kolom);
String document.attributeName(Cursor cursor);

Geeft de attribuutnaam terug als leesbare tekst. Dit is gelijk aan de itemData-naam in de syntaxis-accentuering-bestanden. 

bool document.isAttributeName(int regel, int kolom, String naam);
bool document.isAttributeName(Cursor cursor, String naam);

Geeft true terug, als de attribuutnaam op een bepaalde cursorpositie overeenkomt met de gegeven naam, anders false. 

String document.variable(String sleutel);

Geeft de waarde terug van de gevraagde documentvariabele sleutel. Als de documentvariabele niet bestaat, wordt een lege tekenreeks teruggegeven. 

void document.setVariable(String sleutel, String waarde);

Stelt de waarde in van de gevraagde documentvariabele sleutel.

Zie ook: Documentvariabelen van Kate

Sinds: KDE 4.8 

int document.firstVirtualColumn(int regel);

Geeft de virtuele kolom terug van het eerste niet-witruimte-teken in de gegeven regel of -1, als de regel leeg is of alleen witruimte-tekens bevat. 

int document.lastVirtualColumn(int regel);

Geeft de virtuele kolom terug van het laatste niet-witruimte-teken in de gegeven regel of -1, als de regel leeg is of alleen witruimte-tekens bevat. 

int document.toVirtualColumn(int regel, int kolom);
int document.toVirtualColumn(Cursor cursor);
Cursor document.toVirtualCursor(Cursor cursor);

Converteert de gegeven “echte” cursorpositie naar een virtuele cursorpositie, geeft ofwel een int terug of een cursor-object. 

int document.fromVirtualColumn(int regel, int virtueleKolom);
int document.fromVirtualColumn(Cursor virtueleCursor);
Cursor document.fromVirtualCursor(Cursor virtueleCursor);

Converteert de gegeven virtuele cursorpositie naar een “echte” cursorpositie, geeft ofwel een int terug of een cursor-object. 

Cursor document.anchor(int regel, int kolom, Char teken);
Cursor document.anchor(Cursor cursor, Char teken);

Zoekt achterwaarts naar het gegeven teken te beginnen vanaf de gegeven cursor. Als voorbeeld, als '(' als teken wordt meegegeven, dan geeft deze functie de positie terug van de openingings '('. Dit houdt rekening met aantallen, bijv. andere '(...)' worden genegeerd. 

Cursor document.rfind(int regel, int kolom, String tekst, int attribuut = -1);
Cursor document.rfind(Cursor cursor, String tekst, int attribuut = -1);

Zoek de gegeven tekst achterwaarts met het juiste attribuut. Het argument attribuut wordt genegeerd als het is ingesteld op -1. De teruggegeven cursor is ongeldig, als de tekst niet is gevonden. 

int document.defStyleNum(int regel, int kolom);
int document.defStyleNum(Cursor cursor);

Geeft de standaard stijl terug op de gegeven cursorpositie. 

bool document.isCode(int regel, int kolom);
bool document.isCode(Cursor cursor);

Geeft true terug, als het attribuut op de gegeven cursorpositie niet gelijk is aan alle volgende stijlen: dsComment, dsString, dsRegionMarker, dsChar, dsOthers. 

bool document.isComment(int regel, int kolom);
bool document.isComment(Cursor cursor);

Geeft true terug, als het attribuut van het teken op de cursorpositie gelijk is aan dsComment, anders false. 

bool document.isString(int regel, int kolom);
bool document.isString(Cursor cursor);

Geeft true terug, als het attribuut van het teken op de cursorpositie gelijk is aan dsString, anders false. 

bool document.isRegionMarker(int regel, int kolom);
bool document.isRegionMarker(Cursor cursor);

Geeft true terug, als het attribuut van het teken op de cursorpositie gelijk is aan dsRegionMarker,anders false. 

bool document.isChar(int regel, int kolom);
bool document.isChar(Cursor cursor);

Geeft true terug, als het attribuut van het teken op de cursorpositie gelijk is aan dsChar, anders false. 

bool document.isOthers(int regel, int kolom);
bool document.isOthers(Cursor cursor);

Geeft true terug, als het attribuut van het teken op de cursorpositie gelijk is aan dsOthers, anders false. 

void document.indent(Range reeks, int aantal);

Laat alle regels in reeks inspringen door aantal tabs of aantal keren tabSize spaties in te voegen afhankelijk van de voorkeur van de gebruiker. De parameter aantal kan negatief zijn.

De API voor bewerken

Naast het document en weergave-API, is er een algemene bewerker-API die functies levert voor algemene functionaliteit voor bewerken met een script. 

Tekenreeks editor.clipboardText();

Geeft de tekst terug die actief is in het globale klembord.

Sinds: KDE Frameworks™ 5.50

String editor.clipboardHistory();

De bewerker houdt een klembordgeschiedenis vast die tot 10 klemborditems bevat. Deze functie geeft alle items terug die actief zijn in de klembordgeschiedenis.

Sinds: KDE Frameworks™ 5.50

void editor.setClipboardText(String tekst);

Stel de inhoud van het klembord in op tekst. De tekst zal toegevoegd worden aan de geschiedenis van het klembord.

Sinds: KDE Frameworks™ 5.50