http://docs.kde.org/
ZurückKatePart erweiternWeiter

Scripting mit JavaScript

Die Editorkomponente von KatePart kann durch Skripte erweitert werden. Als Skriptsprache wird ECMAScript verwendet, das auch unter dem Namen JavaScript bekannt ist. In KatePart können zwei Arten von Skripten benutzt werden: Einrückungs- und Befehlszeilenskripte.

Einrückungsskripte

Mit Einrückungsskripten wird der Quelltext automatisch bei der Eingabe eingerückt. Nach Drücken der Eingabetaste wird die Einrückungstiefe zum Beispiel oft vergrößert.

Die folgenden Abschnitte beschreiben Schritt für Schritt, wie das Gerüst für ein einfaches Einrückungsskript entsteht. Zuerst wird eine neue *.js-Datei z. B. mit dem Namen $XDG_DATA_HOME/katepart5/script/indentation erzeugt. Darin wird die Umgebungsvariable XDG_DATA_HOME normalerweise entweder zu ~/.local oder ~/.local/share erweitert.

Auf Windows®-Systemen finden Sie diese Dateien unter %USERPROFILE%\AppData\Local\katepart5\indentation. Dabei ist %USER% normalerweise C:\\Users\\user.

Der Vorspann des Einrückungsskripts

Der Vorspann der Datei javascript.js ist als JSON am Anfang des Dokumentes eingebettet und hat folgende Form: 

var katescript = {
    "name": "JavaScript",
    "author": "Example Name <example.name@some.address.org>",
    "license": "BSD License",
    "revision": 1,
    "kate-version": "5.1",
    "required-syntax-style": "javascript",
    "indent-languages": ["javascript"],
    "priority": 0,
}; // kate-script-header, muss am Anfang der Datei stehen und darf keine Kommentare enthalten

Jede Zeile wird jetzt im Detail erklärt:

  • name [erforderlich]: Dies ist der Name des Skripts, der im Menü Extras → Einrückung und im Einrichtungsdialog angezeigt wird.

  • author [optional]: Der Name des Autors und weitere Kontaktinformationen.

  • license [optional]: Kurzform der Lizenz, wie zum Beispiel BSD-Lizenz oder LGPLv3.

  • revision [erforderlich]: Die Version des Skripts, sie sollte bei jeder Änderung des Skripts erhöht werden.

  • kate-version [required]: Minimal erforderliche KatePart-Version.

  • required-syntax-style [optional]: Der erforderliche Sytaxstil, der zum angebenen style in Syntaxhervorhebungs-Stildateien passt. Dies ist wichtig für Einrückungsskripte, die besondere Informationen über die Hervorhebung im Dokument benötigen. Wenn ein erforderlicher Syntaxstil angegeben ist, ist das Einrückungsskript nur verfügbar, wenn auch die zugehörige Hervorhebung aktiviert ist. Dies verhindert ein „nicht definiertes Verhalten“ beim Verwenden einer Einrückung ohne das erwartete Hervorhebungschema. Ein Beispiel dafür ist das Einrückungsskript für Ruby, das diese Option in den Dateien ruby.js und ruby.xml benutzt.

  • indent-languages [optional]: JSON-Feld von Syntaxstilen, die das Skript richtig einrücken kann, z. B.: ["c++", "java"].

  • priority [optional]: Wenn es mehrere Einrückungsskripte für eine bestimmte hervorgehobene Datei gibt, bestimmt die Priorität, welches Skript als Standard verwendet wird.

Der Quelltext des Einrückungsskripts

Nachdem der Vorspann beschrieben wurde, erklärt dieser Abschnitt wie das Einrückungsskript selbst funktioniert. Die Basisvorlage für den Quelltext sieht so aus:

// benötigt die Bibliothek „katepart js“ z. B. range.js wenn Range benutzt wird
require ("range.js");
  
triggerCharacters = "{}/:;";
function indent(line, indentWidth, ch)
{
    // wird für jedem Zeilenumbruch (ch == '\n') und alle in der 
    // globalen Variable triggerCharacters festgelegten Zeichen aufgerufen. Wenn Extras → Ausrichten
    // gewählt wird, ist die Variable ch leer, d. h. ch == ''.
    //
    // siehe auch: Skript-API
    return -2;
}

Die Funktion indent() hat drei Argumente:

  • line: die Zeile die eingerückt werden soll

  • indentWidth: die Einrückungstiefe mit der Anzahl der Leerzeichen

  • ch: entweder das Zeichen für Zeilenumbruch (ch == '\n'), ein in triggerCharacters festgelegtes Zeichen oder ein leeres Zeichen, wenn der Benutzer die Aktion Extras → Ausrichten aufgerufen hat.

Der Rückgabewert der Funktion indent() bestimmt, wie die Zeile eingerückt wird. Ist dieser Wert eine Ganze Zahl, wird sie wie folgt interpretiert:

  • Rückgabewert -2: keine Aktion

  • Rückgabewert -1: Einrückung beibehalten (sucht nach vorherigen nicht leeren Zeilen)

  • Rückgabewert 0: eine Zahl >= 0 gibt die Anzahl der Leerzeichen zum Einrücken an

Alternativ kann ein Feld mit zwei Elementen zurückgegeben werden:

  • Rückgabewert [ indent, align ];

In diesem Fall ist das erste Element die Einrückungstiefe wie oben mit derselben Bedeutung spezieller Werte. Das zweite Element ist ein absoluter Wert für die Spalte der „Ausrichtung“. Ist dieser Wert größer als der Einrückungswert, legt die Differenz der Werte die Anzahl von Leerzeichen fest, die zum ersten Wert für die gesamte Einrückung hinzuaddiert werden. Anderenfalls wird der zweite Rückgabewert ignoriert. Die Benutzung von Tabulator- und Leerzeichen wird oft als „Mischmodus“ bezeichnet.

Betrachten Sie das folgende Beispiel: Angenommen das Tabulatorzeichen wird zur Einrückung verwendet und die Tabulatorweite beträgt 4. Hier steht <tab> für den Tabulator und '.' für ein Leerzeichen: 

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

Beim Einrücken der Zeile 2 gibt die Funktion indent() [8, 15] zurück. Daher werden zwei Tabulatoren für das Einrücken bis Spalte 8 und noch zusätzlich 7 Leerzeichen hinzugefügt. Dadurch steht der zweite Parameter unter dem ersten und bleibt auch so ausgerichtet, wenn die Datei mit einer anderen Tabulatorweite angezeigt wird.

In der Standardinstallation von KDE wird KatePart mit einigen Einrückungsskripten installiert. Die entsprechenden JavaScript-Quelltexte finden Sie unter $XDG_DATA_DIRS/katepart5/script/indentation.

Auf Windows®-Systemen finden Sie diese Dateien unter %USERPROFILE%\AppData\Local\katepart5\indentation. Dabei ist %USER% normalerweise C:\\Users\\user.

Bei der Entwicklung eines Einrückungsskripts muss das Skript wieder neu geladen werden, um testen zu können, ob es richtig funktioniert. Anstatt das ganze Programm neu zu starten, wechseln Sie zur Befehlszeile und geben reload-scripts ein.

Wenn Sie nützliche Skripte entwickelt haben, sollten Sie darüber nachdenken, sie zum KatePart-Projekt hinzufügen. Schreiben Sie dazu an die Mailingliste.

Befehlszeilenskripte

Da nicht alle gewünschten Funktionen in KatePart eingebaut werden können, ist es möglich, kleine Hilfsskripte für die schnelle Änderung von Textes mit der eingebauten Befehlszeile auszuführen. Der Befehl sort ist zum Beispiel als Skript geschrieben. Dieser Abschnitt erklärt, wie *.js-Dateien erstellt werden, um die Fähigkeiten von KatePart mit beliebigen Hilfsskripten zu erweitern.

Befehlszeilenskripte werden im gleichen Ordner wie Einrückungsskripte gespeichert. Zuerst erstellen Sie eine neue *.js-Datei namens myutils.js im lokalen persönlichen Ordner $XDG_DATA_HOME/katepart5/script/commands. Darin wird die Umgebungsvariable XDG_DATA_HOME normalerweise entweder zu ~/.local oder ~/.local/share erweitert.

Auf Windows®-Systemen finden Sie diese Dateien unter %USERPROFILE%\AppData\Local\katepart5\commands. Dabei ist %USERPROFILE% normalerweise C:\\Users\\user.

Der Vorspann des Befehlszeilenskripts

Der Vorspann jedes Befehlszeilen-Skripts ist in der JSON-Datei am Anfang des Skripts so eingebettet: 

var katescript = {
    "author": "Example Name <example.name@some.address.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, muss am Anfang der Datei stehen und darf keine Kommentare enthalten

Jede Zeile wird jetzt im Detail erklärt:

  • author [optional]: Der Name des Autors und weitere Kontaktinformationen.

  • license [optional]: Kurzform der Lizenz, wie zum Beispiel BSD-Lizenz oder LGPLv2.

  • revision [erforderlich]: Die Version des Skripts, sie sollte bei jeder Änderung des Skripts erhöht werden.

  • kate-version [required]: Minimal erforderliche KatePart-Version.

  • functions [erforderlich]: JSON-Feld der Befehle im Skript.

  • actions [optional]: JSON-Feld mit JSON-Objekten, das die Aktionen festlegt, die im Anwendungsmenü erscheinen sollen. Weitergehende Informationen finden Sie im Abschnitt Kurzbefehle festlegen.

Da der Inhalt von functions ein JSON-Feld ist, kann ein einzelnes Skript eine beliebige Anzahl von Befehlen für die Befehlszeile enthalten. Jede Funktion ist durch die eingebaute Befehlszeile in KatePart verfügbar.

Der Quelltext des Skripts

Alle im Vorspann aufgeführten Funktionen müssen im Skript implementiert werden. Im oben gezeigten Skript müssen zum Beispiel die beiden Funktionen sort und moveLinesDown implementiert werden. Alle Funktionen haben folgende Syntax: 

// benötigt die Bibliothek „katepart js“ z. B. range.js wenn Range benutzt wird
require ("range.js");
function <name>(arg1, arg2, ...)
{
    // ... Implementierung, siehe auch: Skript-API
}

Argumente in der Befehlszeile werden der Funktion als arg1, arg2 usw. übergeben. Um für jeden Befehl eine Dokumentation zu Verfügung zu stellen, verwenden Sie die Funktion „help“ wie im folgenden Beispiel: 

function help(cmd)
{
    if (cmd == "sort") {
        return i18n("Sortiert den ausgewählten Text.");
    } else if (cmd == "...") {
        // ...
    }
}

Durch den Aufruf von help sort auf der Befehlszeile wird dann diese Hilfefunktion mit dem Argument cmd für den verwendeten Befehl benutzt, d. h. mit cmd == "sort". zeigt Kate den zurückgegebenen Text als Hilfe für den Benutzer an. Denken Sie daran, die Texte zu übersetzen .

Bei der Entwicklung eines Befehlszeilenskripts muss das Skript wieder neu geladen werden, um testen zu können, ob es richtig funktioniert. Anstatt das ganze Programm neu zu starten, wechseln Sie zur Befehlszeile und geben reload-scripts ein.

Kurzbefehle festlegen

Das Skript braucht einen passenden Skript-Header, der die Skripte über das Anwendungsmenü verfügbar macht. Im Beispiel erscheinen die Funktionen sort und moveLinesDown im Menü. Das wird durch den folgenden Skript-Header erreicht: 

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"
        }
    ]
};

Die Felder für eine Aktion lauten wie folgt:

  • function [erforderlich]: Die Funktion, die im Menü Extras → Skripte erscheint.

  • name [erforderlich]: Der Text, der im Menü Skript angezeigt wird.

  • icon [optional]: Dieses Symbol erscheint neben dem Text im Menü. Alle KDE-Symbolnamen können hier benutzt werden.

  • category [optional]: Wenn eine Kategorie angegeben ist, dann erscheint das Skript in einem Untermenü.

  • shortcut [optional]: Der hier angegebene Kurzbefehl ist der Standard. Beispiel: Ctrl+Alt+T. Sehen Sie in der Qt™-Dokumentation für weitere Einzelheiten nach.

  • interactive [optional]: Wenn das Skript Benutzereingaben auf der Befehlszeile braucht, dann setzen Sie diesen Parameter auf true.

Wenn Sie nützliche Skripte entwickelt haben, sollten Sie darüber nachdenken, sie zum KatePart-Projekt hinzufügen. Schreiben Sie dazu an die Mailingliste.

Skript-API

Die hier vorgestellte Programmierschnittstelle (API) ist in allen Skripten verfügbar, d. h. in Einrückungs- und Befehlszeilenskripten. Die Klassen Cursor und Range werden durch die Bibliotheksdateien in $XDG_DATA_DIRS/katepart5/libraries bereit gestellt. Wenn Sie sie in Ihren Skripten verwenden möchten, was für einige der Funktionen Document oder View erforderlich ist, fügen Sie bitte die benötigte Bibliothek wie folgt ein: 

// benötigt die Bibliothek „katepart js“ z. B. range.js wenn Range benutzt wird
require ("range.js");

Um die Standard-Skript-API mit eigenen Funktionen und Prototypen zu erweitern, erzeugen Sie eine neue Datei im lokalen Einrichtungsordner für KDE $XDG_DATA_HOME/katepart5/libraries und schließen Sie sie in Ihr Skript mit folgendem Befehl ein: 

require ("myscriptnamehere.js");

Auf Windows®-Systemen finden Sie diese Dateien unter %USERPROFILE%\AppData\Local\katepart5\libraries. Dabei ist %USERPROFILE% normalerweise C:\\Users\\user.

Um vorhandene Prototypen wie Cursor oder Range zu erweitern, wird empfohlen, nicht die globalen *.js-Dateien zu ändern. Ändern Sie stattdessen den Cursor-Prototyp in JavaScript, nachdem cursor.js in Ihrem Skript mit require eingefügt ist.

Cursor und Bereiche

Da KatePart ein Texteditor ist, basiert die Skript-API soweit möglich auf Cursor und Bereichen. Ein Cursor ist ein einfaches Tupel (Zeile, Spalte) für eine Textposition im Dokument. Ein Bereich umfasst Text vom Start bis zum Ende der Cursor-Position. Die Programmschnittstelle wird in den nächsten Abschnitten im Einzelnen erläutert.

Der Cursor-Prototyp
Cursor();

Konstruktor. Gibt einen Cursor an der Position (0, 0) zurück.

Beispiel: var cursor = new Cursor(); 

Cursor(int zeile, int spalte);

Konstruktor. Gibt einen Cursor an der Position (zeile, spalte) zurück.

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

Cursor(Cursor other);

Kopierkonstruktor. Gibt die Kopie des Cursors other zurück.

Beispiel: var copy = new Cursor(cursor); 

Cursor Cursor.clone();

Gibt einen Klon des Cursors zurück.

Beispiel: var clone = cursor.clone(); 

Cursor.setPosition(int zeile, int spalte);

Setzt die Cursor-Position auf zeile und spalte.

Since: KDE 4.11 

bool Cursor.isValid();

Überprüft, ob der Cursor gültig ist. Ein Cursor ist ungültig, wenn die Zeile und oder die Spalte den Wert -1 haben.

Beispiel: var valid = cursor.isValid(); 

Cursor Cursor.invalid();

Gibt einen neuen ungültigen Cursor an der Position (-1, -1) zurück.

Beispiel: var invalidCursor = cursor.invalid(); 

int Cursor.compareTo(Cursor other);

Vergleicht diesen Cursor mit dem Cursor other. Gibt folgende Werte zurück:

  • -1, wenn dieser Cursor sich vor dem Cursor other befindet,

  • 0, wenn beide Cursor an der gleichen Stelle stehen und

  • +1, wenn dieser Cursor sich hinter dem Cursor other befindet.

bool Cursor.equals(Cursor other);

Gibt true zurück, wenn dieser Cursor und der Cursor other gleich sind, sonst false. 

String Cursor.toString();

Gibt den Cursor als Zeichenfolge in der Form „Cursor(zeile, spalte)“ zurück.

Der Bereich-Prototyp
Range();

Konstruktor. Der Aufruf new Range() gibt einen Bereich von (0, 0) - (0, 0) zurück. 

Range(Cursor start, Cursor ende);

Konstruktor. Der Aufruf new Range(start, end) gibt einen Bereich von (start, ende) zurück. 

Range(int startZeile, int startspalte, int endZeile, int endSpalte);

Konstruktor. Der Aufruf von new Range(startZeile, startSpalte, endZeile, endSpalte). Gibt den Bereich von (startZeile, startSpalte) bis (endZeile, endSpalte) zurück. 

Range(Range other);

Kopierkonstruktor. Gibt eine Kopie von Range other zurück. 

Range Range.clone();

Gibt einen Klon des Bereichs zurück.

Beispiel: var clone = range.clone(); 

bool Range.isEmpty();

Gibt true zurück, wenn der Start- und der End-Cursor gleich sind.

Beispiel: var empty = range.isEmpty();

Since: KDE 4.11 

bool Range.isValid();

Gibt true zurück, wenn sowohl Start- als auch End-Cursor gültig sind, sonst false.

Beispiel: var valid = range.isValid(); 

Range Range.invalid();

Gibt den Bereich von (-1, -1) bis (-1, -1) zurück. 

bool Range.contains(Cursor cursor);

Gibt true zurück, wenn dieser Bereich die Cursor-Position enthält, sonst false. 

bool Range.contains(Range other);

Gibt true zurück, wenn dieser Bereich den Bereich other enthält, sonst false. 

bool Range.containsColumn(int spalte);

Gibt true zurück, wenn spalte in dem halboffenen Intervall [start.spalte, end.spalte) liegt, sonst false. 

bool Range.containsLine(int zeile);

Gibt true zurück, wenn zeile in dem halboffenen Intervall [start.zeile, end.zeile) liegt, sonst false. 

bool Range.overlaps(Range other);

Gibt true zurück, wenn dieser Bereich und der Bereich other sich überlappen, sonst false. 

bool Range.overlapsLine(int zeile);

Gibt true zurück, wenn zeile in dem Intervall [start.zeile, end.zeile] liegt, sonst false. 

bool Range.overlapsColumn(int spalte);

Gibt true zurück, wenn spalte in dem Intervall [start.spalte, end.spalte] liegt, sonst false. 

bool Range.onSingleLine();

Gibt true zurück, wenn der Bereich in der gleichen Zeile beginnt und endet, d. h. wenn Range.start.line == Range.end.line ist.

Seit: KDE 4.9 

bool Range.equals(Range other);

Gibt true zurück, wenn dieser Bereich und der Bereich other gleich sind, sonst false. 

String Range.toString();

Gibt den Bereich als Zeichenfolge in der Form „Range(Cursor(zeile, spalte), Cursor(zeile, spalte))“ zurück.

Globale Funktionen

Dieser Abschnitt listet alle globalen Funktionen auf.

Lesen & Einfügen von Dateien
String read(String datei);

Sucht nach der angegebenen datei relativ zum Ordner katepart/script/files und gibt den Inhalt der Datei als String zurück. 

void require(String datei);

Sucht die angegebene datei relativ zum Ordner katepart/script/libraries und wertet sie aus. require verhindert intern, dass die gleiche datei mehrfach eingeschlossen wird.

Seit: KDE 4.10

Fehlersuche
void debug(String text);

Gibt den text auf der Standardausgabe stdout in der Konsole aus, von der das Programm gestartet wurde.

Übersetzung

Die Lokalisierung wird durch einige Funktionen zum Übersetzen von Zeichenfolgen in Skripten unterstützt, so durch i18n, i18nc, i18np und i18ncp. Diese Funktionen arbeiten genau wie auf der Seite KDE's Übersetzungsfunktionen beschrieben.

Die Übersetzungsfunktionen übersetzen die eingepackten Zeichenfolgen durch KDE's Übersetzungssystem in die Sprache, die in der Anwendung benutzt wird. Zeichenfolgen in Skripten, die in den offiziellen KatePart-Quellen entwickelt werden, werden automatisch extrahiert und sind übersetzbar. Anders gesagt, müssen Sie sich als Entwickler von KatePart nicht um das Extrahieren und Übersetzen kümmern. Achtung, diese Funktionalität gibt es nur innerhalb der KDE-Infrastruktur. Neue Texte in Skripten, die von Anderen ausserhalb von KDE entwickelt wurden, werden nicht automatisch übersetzt. Bitte denken Sie darüber nach, solche Skripte an KDE zu geben, so dass die korrekte Übersetzung möglich wird. 

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

Übersetzt text in die von der Anwendung benutzte Sprache. Die Argumente arg1, ..., sind optional und werden benutzt, um die Platzhalter %1, %2 usw. zu ersetzen.

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

Übersetzt text in die von der Anwendung benutzte Sprache. Zusätzlich ist die Zeichenfolge context sichtbar, so dass Übersetzer bessere Übersetzungen anfertigen können. Die Argumente arg1, ..., sind optional und werden benutzt, um die Platzhalter %1, %2 usw.. zu ersetzen.

void i18np(String singular, String plural, int number, arg1, ...);

Übersetzt entweder singular oder plural in die von der Anwendung benutzte Sprache. Dies ist abhängig von der angegebenen number. Die Argumente arg1, ..., sind optional und werden benutzt, um die Platzhalter %1, %2 usw.. zu ersetzen.

void i18ncp(String context, String singular, String plural, int number, arg1, ...);

Übersetzt entweder singular oder plural in die von der Anwendung benutzte Sprache. Dies ist abhängig von der angegebenen number. Zusätzlich ist die Zeichenfolge context sichtbar, so dass Übersetzer bessere Übersetzungen anfertigen können. Die Argumente arg1, ..., sind optional und werden benutzt, um die Platzhalter %1, %2 usw.. zu ersetzen.

Die Programmschnittstelle zur Ansicht

Für jedes ausgeführte Skript gibt es eine globale Variable „view“, für die aktuelle Editoransicht. Im Folgenden finden Sie eine Liste aller verfügbaren Funktionen für eine Ansicht. 

void view.copy()

Kopiert eine vorhandene Auswahl, ansonsten die aktuelle Zeile, wenn die Einstellung [ ] Die aktuelle Zeile kopieren/ausschneiden, wenn keine Markierung vorliegt aktiviert ist.

Seit KDE Frameworks™ 5.79

void view.cut()

Schneidet eine vorhandene Auswahl, ansonsten die aktuelle Zeile aus, wenn die Einstellung [ ] Die aktuelle Zeile kopieren/ausschneiden, wenn keine Markierung vorliegt aktiviert ist.

Seit KDE Frameworks™ 5.79

void view.paste()

Inhalt der Zwischenablage einfügen.

Seit KDE Frameworks™ 5.79

Cursor view.cursorPosition()

Gibt die aktuelle Position des Cursors in der Ansicht zurück.

void view.setCursorPosition(int zeile, int spalte);
void view.setCursorPosition(Cursor cursor);

Setzt die aktuelle Position des Cursors entweder auf (zeile, spalte) oder auf den angegebenen Cursor. 

Cursor view.virtualCursorPosition();

Gibt die virtuelle Cursor-Position zurück, dabei wird jeder Tabulator mit der Anzahl der Leerzeichen entsprechend der aktuellen Tabulatorweite berechnet. 

void view.setVirtualCursorPosition(int zeile, int spalte);
void view.setVirtualCursorPosition(Cursor cursor);

Setzt die aktuelle Position des virtuellen Cursors entweder auf (zeile, spalte) oder auf den angegebenen Cursor. 

String view.selectedText();

Gibt den ausgewählten Text zurück. Ist kein Text ausgewählt, wird eine leere Zeichenfolge zurückgegeben. 

bool view.hasSelection();

Gibt true zurück, wenn die Ansicht ausgewählten Text enthält, sonst false. 

Range view.selection();

Gibt den ausgewählten Textbereich zurück. Der zurückgegebene Bereich ist ungültig, wenn kein Text ausgewählt ist. 

void view.setSelection(Range range);

Setzt den ausgewählten Text zum angegebenen Bereich. 

void view.removeSelectedText();

Entfernt den ausgewählten Text. Wenn in der Ansicht kein Text ausgewählt ist, passiert nichts. 

void view.selectAll();

Wählt den gesamten Text im Dokument aus. 

void view.clearSelection();

Löscht die Textauswahl, aber nicht den Text selbst. 

object view.executeCommand(String command,
                           String args,
                           Range range);

Führt den Befehl command mit den optionalen Argumenten args und range aus. Das zurückgegebene objecthat die boolesche Eigenschaft object.ok, mit der angegeben wird, ob der Befehl command erfolgreich ausgeführt wurde. Bei einem Fehler enthält object.status die Fehlermeldung.

Seit KDE Frameworks™ 5.50

Die Programmschnittstelle zum Dokument

Für jedes ausgeführte Skript gibt es eine globale Variable „document“, die das aktuelle Dokument verweist. Im Folgenden finden Sie eine Liste aller verfügbaren Funktionen für ein Dokument. 

String document.fileName();

Gibt den Dateinamen des Dokuments zurück oder eine leere Zeichenfolge für nicht gespeicherte Textpuffer. 

String document.url();

Gibt die vollständige URL des Dokuments zurück oder eine leere Zeichenfolge für nicht gespeicherte Textpuffer. 

String document.mimeType();

Gibt den MIME-Typ des Dokuments zurück oder application/octet-stream, wenn kein passender MIME-Typ gefunden wurde. 

String document.encoding();

Gibt die aktuell verwendete Kodierung zum Speichern der Datei zurück. 

String document.highlightingMode();

Gibt den globalen Hervorhebungsmodus für das gesamte Dokument zurück. 

String document.highlightingModeAt(Cursor pos);

Gibt den Hervorhebungsmodus an der angegebenen Cursor-Position im Dokument zurück. 

Array document.embeddedHighlightingModes();

Gibt ein Feld von Hervorhebungsmodi zurück, die in diesem Dokument eingebettet sind.. 

bool document.isModified();

Gibt true zurück, wenn das Dokument ungespeicherte Änderungen enthält, sonst false. 

String document.text();

Gibt den gesamten Inhalt des Dokuments in einer einzigen Zeichenfolge zurück. Zeilenumbrüche werden mit dem zugehörigen Zeichen „\n“ markiert. 

String document.text(int vonZeile, int vonSpalte, int bisZeile, int bisSpalte);
String document.text(Cursor von, Cursor bis);
String document.text(Range range);

Gibt den Text im angegebenen Bereich zurück. Es wird empfohlen, die Cursor- und Bereichsbasierte Version zu benutzen, dadurch ist der Quelltext besser lesbar. 

String document.line(int zeile);

Gibt die angegebene Textzeile als Zeichenfolge zurück. Die Zeichenfolge ist leer, wenn die angeforderte Zeile außerhalb des Bereichs liegt. 

String document.wordAt(int zeile, int spalte);
String document.wordAt(Cursor cursor);

Gibt das Wort an der angegebenen Cursor-Position zurück. 

Range document.wordRangeAt(int zeile, int spalte);
Range document.wordRangeAt(Cursor cursor);

Gibt den Bereich des Wortes an der angegebenen Cursor-Position zurück. Der zurückgegebene Bereich ist ungültig (siehe Range.isValid()), wenn die Textposition nach dem Zeilenende liegt. Befindet sich an der angegebenen Cursor-Position kein Wort, wird ein leere Bereich zurückgegeben.

Seit: KDE 4.9 

String document.charAt(int zeile, int spalte);
String document.charAt(Cursor cursor);

Gibt das Zeichen an der aktuellen Cursor-Position zurück. 

String document.firstChar(int zeile);

Gibt in der angegebenen zeile das erste Zeichen zurück, das kein Leerraumzeichen ist. Wenn die Zeile leer ist oder nur Leerraumzeichen enthält, wird eine leere Zeichenfolge zurückgegeben. 

String document.lastChar(int zeile);

Gibt in der angegebenen zeile das letzten Zeichen zurück, das kein Leerraumzeichen ist. Wenn die Zeile leer ist oder nur Leerraumzeichen enthält, wird eine leere Zeichenfolge zurückgegeben. 

bool document.isSpace(int zeile, int spalte);
bool document.isSpace(Cursor cursor);

Gibt true zurück, wenn das Zeichen an der angegebenen Cursor-Position ein Leerraumzeichen ist, sonst false. 

bool document.matchesAt(int line, int column, String text);
bool document.matchesAt(Cursor cursor, String text);

Gibt true zurück, wenn der angegebene text mit der zugehörigen Cursor-Position übereinstimmt, sonst false. 

bool document.startsWith(int zeile, String text, bool skipWhiteSpaces);

Gibt true zurück, wenn die Zeile mit text beginnt, sonst false. Das Argument skipWhiteSpaces bestimmt, ob führende Leerraumzeichen ignoriert werden. 

bool document.endsWith(int zeile, String text, bool skipWhiteSpaces);

Gibt true zurück, wenn die Zeile mit text endet, sonst false. Das Argument skipWhiteSpaces bestimmt, ob angehängte Leerraumzeichen ignoriert werden. 

bool document.setText(String text);

Setzt den Text für das gesamte Dokument. 

bool document.clear();

Löscht den gesamten Text im Dokument. 

bool document.truncate(int zeile, int spalte);
bool document.truncate(Cursor cursor);

Schneidet die angegebene Zeile an der Spalte oder an der Cursor-Position ab. War das erfolgreich, wird true zurückgegeben, oder false, wenn die angegeben Zeile nicht im Bereich des Dokuments liegt. 

bool document.insertText(int zeile, int spalte, String text);
bool document.insertText(Cursor cursor, String text);

Fügt den text an der angegebenen Cursor-Position ein. War das erfolgreich, wird true zurückgegeben, oder false, wenn das Dokument im Nur-Lesen-Modus geöffnet wurde. 

bool document.removeText(int vonZeile, int vonSpalte, int bisZeile, int bisSpalte);
bool document.removeText(Cursor von, Cursor bis);
bool document.removeText(Range bereich);

Löscht den Text im angegebenen Bereich. War das erfolgreich, wird true zurückgegeben, oder false, wenn das Dokument im Nur-Lesen-Modus geöffnet wurde. 

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

Fügt Text in einer angegebenen Zeile ein. War das erfolgreich, wird true zurückgegeben, oder false, wenn das Dokument im Nur-Lesen-Modus geöffnet wurde oder die Zeile nicht mehr im Bereich des Dokuments liegt. 

bool document.removeLine(int zeile);

Löscht die angegebene Textzeile. War das erfolgreich, wird true zurückgegeben, oder false, wenn das Dokument im Nur-Lesen-Modus geöffnet wurde oder die Zeile nicht mehr im Bereich des Dokuments liegt. 

bool document.wrapLine(int zeile, int spalte);
bool document.wrapLine(Cursor cursor);

Bricht die Zeile an der angegebenen Cursor-Position um. War das erfolgreich, wird true zurückgegeben, ansonsten false, z. B. wenn die angegeben Zeilennummer < 0 ist.

Seit: KDE 4.9 

void document.joinLines(int startZeile, int endZeile);

Verbindet die Zeilen von startZeile bis endZeile. Zwei aufeinanderfolgende Textzeilen werden immer mit einem einzelnen Leerzeichen getrennt. 

int document.lines();

Gibt die Zeilenanzahl des Dokuments zurück. 

bool document.isLineModified(int zeile);

Gibt true zurück, wenn die zeile noch nicht gespeicherte Daten enthält.

Seit: KDE 5.0 

bool document.isLineSaved(int zeile);

Gibt true zurück, wenn zeile geändert und das Dokument gespeichert wurde. Folglich enthält die aktuelle Zeile keine ungesicherten Daten.

Seit: KDE 5.0 

bool document.isLineTouched(int zeile);

Gibt true zurück, wenn zeile ungesicherte Daten enthält oder geändert wurde.

Seit: KDE 5.0 

void document.findTouchedLine(int startZeile, bool nach unten);

Suche nach der nächsten Zeile, die ungesicherte Daten enthält oder geändert wurde. Die Suche wird in der startZeile begonnen und in der Richtung durchgeführt, die in nach unten angegeben ist.

Seit: KDE 5.0 

int document.length();

Gibt die Anzahl der Zeichen des Dokuments zurück. 

int document.lineLength(int zeile);

Gibt die Länge der zeile zurück. 

void document.editBegin();

Beginnt eine Bearbeitungsgruppe für die Gruppierung von Rückgängig/Wiederherstellen. Achten Sie darauf, editEnd() immer genauso oft wie editBegin() zu benutzen. Der Aufruf von editBegin() verwendet intern einen Referenzzähler, d. h. diese Aufrufe können geschachtelt werden. 

void document.editEnd();

Beendet eine Bearbeitungsgruppe. Der letzte Aufruf von editEnd() (d. h. der Aufruf zum ersten Aufruf von editBegin()) beendet den Bearbeitungsschritt. 

int document.firstColumn(int zeile);

Gibt die erste Spalte in der angegebenen zeile zurück, die kein Leerraumzeichen enthält. Besteht die Zeile nur aus Leerraumzeichen, wird -1 zurückgegeben. 

int document.lastColumn(int zeile);

Gibt die letzte Spalte in der angegebenen zeile zurück, die kein Leerraumzeichen enthält. Besteht die Zeile nur aus Leerraumzeichen, wird -1 zurückgegeben. 

int document.prevNonSpaceColumn(int zeile, int spalte);
int document.prevNonSpaceColumn(Cursor cursor);

Gibt die Spalte zurück, die keine Leerraumzeichen enthält. Die Suche beginnt an der angegebenen Cursor-Position und erfolgt dabei rückwärts. 

int document.nextNonSpaceColumn(int zeile, int spalte);
int document.nextNonSpaceColumn(Cursor cursor);

Gibt die Spalte zurück, die keine Leerraumzeichen enthält. Die Suche beginnt an der angegebenen Cursor-Position und erfolgt dabei vorwärts. 

int document.prevNonEmptyLine(int zeile);

Gibt die nächste nicht leere Zeile zurück, die keine Leerraumzeichen enthält. Die Suche erfolgt dabei rückwärts. 

int document.nextNonEmptyLine(int zeile);

Gibt die nächste nicht leere Zeile zurück, die keine Leerraumzeichen enthält. Die Suche erfolgt dabei vorwärts. 

bool document.isInWord(String zeichen, int attribut);

Gibt true zurück, wenn das angegebene zeichen mit den angegebenen attribut Teil eines Wortes sein kann, sonst false. 

bool document.canBreakAt(String zeichen, int attribut);

Gibt true zurück, wenn die Zeile an dem angegebenen zeichen mit den angegebenen attribut umgebrochen werden kann, sonst false. 

bool document.canComment(int startAttribut, int endAttribut);

Gibt true zurück, wenn ein mit dem angegebenen Attribut beginnender und endender Bereich auskommentiert werden kann, sonst false. 

String document.commentMarker(int attribut);

Gibt das Kommentarzeichen für einzeilige Kommentare für ein angegebenes attribut zurück. 

String document.commentStart(int attribut);

Gibt das Kommentarzeichen für den Beginn von mehrzeiligen Kommentaren für ein angegebenes attribut zurück. 

String document.commentEnd(int attribut);

Gibt das Kommentarzeichen für das Ende von mehrzeiligen Kommentaren für ein angegebenes attribut zurück. 

Range document.documentRange();

Gibt einen Bereich zurück, der dass gesamte Dokument umfasst. 

Cursor documentEnd();

Gibt einen Cursor zurück, der an der letzten Spalte in der letzten Zeile des Dokuments positioniert ist. 

bool isValidTextPosition(int zeile, int spalte);
bool isValidTextPosition(Cursor cursor);

Gibt true zurück, wenn der Cursor an eine gültigen Position innerhalb eines Textes positioniert ist. Eine Textposition ist nur dann gültig, wenn der Cursor am Anfang, in der Mitte oder am Ende einer gültigen Zeile positioniert ist. Weiterhin ist eine Textposition ungültig, wenn diese in einem Unicode-Surrogat liegt.

Seit: KDE 5.0 

int document.attribute(int zeile, int spalte);
int document.attribute(Cursor cursor);

Gibt das Attribut an der aktuellen Cursor-Position zurück. 

bool document.isAttribute(int zeile, int spalte, int attribut);
bool document.isAttribute(Cursor cursor, int attribut);

Gibt true zurück, wenn das Attribut an der angegebenen Cursor-Position gleich attribut ist, sonst false. 

String document.attributeName(int zeile, int spalte);
String document.attributeName(Cursor cursor);

Gibt den Attributnamen als lesbaren Text zurück. Dies entspricht dem Namen itemData in den Syntaxhervorhebungs-Dateien. 

bool document.isAttributeName(int zeile, int spalte, String name);
bool document.isAttributeName(Cursor cursor, String name);

Gibt true zurück, wenn der Attributname an der angegebenen Cursor-Position gleich name ist, sonst false. 

String document.variable(String key);

Gibt den Wert der angefragten Dokumentvariablen key zurück. Existiert diese Variable nicht, wird eine leere Zeichenfolge zurückgegeben. 

void document.setVariable(String key, String value);

Setzt den Wert der angefragten Dokumentvariablen key.

Siehe auch: Kate-Dokumentvariable

Seit: KDE 4.8 

int document.firstVirtualColumn(int zeile);

Gibt in der angegebenen Zeile die virtuelle Spalte des ersten Zeichens zurück, das kein Leerraumzeichen ist, oder -1, wenn die Zeile leer ist oder nur Leerraumzeichen enthält. 

int document.lastVirtualColumn(int zeile);

Gibt in der angegebenen Zeile die virtuelle Spalte des letzten Zeichens zurück, das kein Leerraumzeichen ist, oder -1, wenn die Zeile leer ist oder nur Leerraumzeichen enthält. 

int document.toVirtualColumn(int zeile, int spalte);
int document.toVirtualColumn(Cursor cursor);
Cursor document.toVirtualCursor(Cursor cursor);

Wandelt die angegebene „reale“ Cursor-Position in eine virtuelle Cursor-Position um und gibt entweder einen „int“-Wert oder ein Cursor-Objekt zurück. 

int document.fromVirtualColumn(int zeile, int virtuelleSpalte);
int document.fromVirtualColumn(Cursor virtuellerCursor);
Cursor document.fromVirtualCursor(Cursor virtuellerCursor);

Wandelt die angegebene virtuelle Cursor-Position in eine „reale“ Cursor-Position um und gibt entweder einen „int“-Wert oder ein Cursor-Objekt zurück. 

Cursor document.anchor(int zeile, int spalte, Char zeichen);
Cursor document.anchor(Cursor cursor, Char zeichen);

Sucht rückwärts nach dem angegebenen Zeichen und beginnt dabei an dem angegebenen Cursor. Wenn zum Beispiel „(“ als Zeichen ist, gibt diese Funktion die Position der öffnenden Klammer „(“. Dabei wird das Vorkommen mitgezählt, d. h. andere Klammern „(...)“ werden ignoriert. 

Cursor document.rfind(int zeile, int spalte, String text, int attribut = -1);
Cursor document.rfind(Cursor cursor, String text, int attribut = -1);

Sucht rückwärts nach dem angegeben Text mit dem passenden attribut. Ein Attribut mit dem Wert -1wird dabei ignoriert. Es wird ein ungültiger Cursor zurückgegeben, wenn der Text nicht gefunden wurde. 

int document.defStyleNum(int zeile, int spalte);
int document.defStyleNum(Cursor cursor);

Gibt den Standardstil zurück, der an der angegebenen Cursor-Position benutzt wird. 

bool document.isCode(int zeile, int spalte);
bool document.isCode(Cursor cursor);

Gibt true zurück, wenn das Attribut an der angegeben Cursor-Position nicht den folgenden Stilen entspricht: dsComment, dsString, dsRegionMarker, dsChar, dsOthers. 

bool document.isComment(int zeile, int spalte);
bool document.isComment(Cursor cursor);

Gibt true zurück, wenn das Attribut des Zeichens an der Cursor-Position dsComment ist, sonst false. 

bool document.isString(int zeile, int spalte);
bool document.isString(Cursor cursor);

Gibt true zurück, wenn das Attribut des Zeichens an der Cursor-Position dsString ist, sonst false. 

bool document.isRegionMarker(int zeile, int spalte);
bool document.isRegionMarker(Cursor cursor);

Gibt true zurück, wenn das Attribut des Zeichens an der Cursor-Position dsRegionMarker ist, sonst false. 

bool document.isChar(int zeile, int spalte);
bool document.isChar(Cursor cursor);

Gibt true zurück, wenn das Attribut des Zeichens an der Cursor-Position dsChar ist, sonst false. 

bool document.isOthers(int zeile, int spalte);
bool document.isOthers(Cursor cursor);

Gibt true zurück, wenn das Attribut des Zeichens an der Cursor-Position dsOthers ist, sonst false.

Die Programmschnittstelle zum Editor

Zusätzlich zur Programmierschnittstelle für das Dokument und die Ansicht gibt es eine weitere Schnittstelle mit Funktionen für Skripte des Editors. 

String editor.clipboardText();

Gibt den aktuellen Text aus der globalen Zwischenablage zurück.

Seit KDE Frameworks™ 5.50

String editor.clipboardHistory();

Der Editor enthält den Verlauf der Zwischenablage mit bis zu 10 Eintragen. Diese Funktion gibt alle Einträge zurück, die aktuell im Verlauf der Zwischenablage vorhanden sind.

Seit KDE Frameworks™ 5.50

void editor.setClipboardText(String text);

Setzt den Inhalt der Zwischenablagen auf den Wert text, der auch zum Verlauf hinzugefügt wird.

Seit KDE Frameworks™ 5.50