# Skripte

## Skripte in &kile;

Die Skriptfunktion von &kile; ermöglicht die Ausführung von von ECMAScript-Quelltext, auch unter dem Namen &javascript; bekannt. Es gibt viele Anleitungen mit Informationen über Objekte (Variablen), Funktionen und Eigenschaften in &javascript;.

Skript-Unterstützung im Einrichtungsdialog von &kile; eingeschaltet werden: Einstellungen Kile einrichten ... Kile Skripte. Skript-Unterstützung aktivieren oder abschalten Skript-Unterstützung aktivieren oder abschalten

Sind Skripte aktiviert, wird ein zusätzliche Skriptfenster in der Seitenleiste angezeigt, in dem die Skripte verwaltet werden können. Skriptfenster in der Seitenleiste Skriptfenster in der Seitenleiste

Das Fenster enthält sechs Symbole für verschiedene Aktionen:

- Ausgewähltes Skript ausführen.

- Neues Skript erstellen.

- Ausgewähltes Skript im Editor öffnen.

- Tastenfolge für ein ausgewähltes Skript einrichten.

- Eine zugewiesene Tastenfolge entfernen.

- Liste aller verfügbaren und in `$`KDEDIR`/share/apps/kile/scripts/` gefundenen Skripte neu einlesen.

## Ein Skript ausführen

Ein Skript können Sie auf drei verschiedene Arten ausführen:

1. Wählen Sie das gewünschte Skript aus und klicken Sie auf das Symbol Ausführen oben links im Skriptfenster in der Seitenleiste.

   Skripte: Ausführungsknopf Skripte: Ausführungsknopf

2. Einen Kurzbefehl verwenden.

   Skripte: Tastatur-Kurzbefehl Skripte: Tastatur-Kurzbefehl

   Sie können einem Skript einen Tastatur-Kurzbefehl zuweisen, indem Sie auf das Symbol Einrichten im Skriptfenster in der Seitenleiste drücken.

   Skripte: Einrichtungsdialog für Tastenfolgen Skripte: Einrichtungsdialog für Tastenfolgen

3. Verwendung einer Editor-Tastenfolge. Das Skript wird ausgeführt, wenn die Tastenfolge im Editor eingegeben wird.

   Skripte: Editor-Tastenfolge Skripte: Editor-Tastenfolge

   Diese Methode kann für ziemlich raffinierte Arten von Quelltext-Vervollständigung benutzt werden. Angenommen Sie haben ein Skript, das den &latex;Befehl `\textbf{}` in das aktuelle Dokument einfügt.

       document.insertText("\\textbf{%C}");

   Geben Sie nun die zugewiesene Tastenfolge `bfx` in Ihrem Textdokument ein, wird diese Eingabe entfernt und das Skript wird ausgeführt. Es fügt `\textbf{}` ein und der Cursor steht zwischen den Klammern.

   Skripte: Eingabe einer Editor-Tastenfolge Skripte: Eingabe einer Editor-Tastenfolge

   Dies ist eine komfortable und leistungsfähige Methode zur Quelltextvervollständigung.

## Referenz der Programmierschnittstelle (API)

Die hier vorgestellte Skript-API kann in allen Skripten verwendet werden. Ehe der Inhalt eines Skripts geladen wird, fügt &kile; zuerst mehrere Prototypen und Funktionen in den Skript-Kontext ein. Diese API enthält Prototypen wie Text-Cursor und Textbereiche und wird im Ordner `KILE_APP_DIR/script-plugins/` gespeichert.

&kile;-Skripte unterscheiden sich geringfügig von &kate;-Skripten, die für einen anderen Anwendungsfall wie Ausführung auch auf der Befehlszeile entwickelt wurden. Es sind aber alle Funktionen der Skript-API für &kate; ebenfalls in der Skript-API für &kile; vorhanden. Das erleichtert die Portierung von Skripten von &kate; zu &kile;. Da &kile; jedoch ein leistungsfähiger &latex;-Editor mit vielen Funktionen ist, bietet die &kile;-API mehr Möglichkeiten.

Hinweis: die Beschreibung der Programmierschnittstelle (API), die auch für Skripte in &kate; genutzt wird, stammt aus dem Handbuch zu &kate;.

### Globale Funktionen

In diesem Abschnitt werden die globalen Funktionen vorgestellt.

    void debug(String text);

- Gibt den `text` auf der Standarausgabe `stdout` in der Konsole aus. Der Text wird farbig angezeigt, um ihn von anderen Fehlerausgaben zu unterscheiden.

### Der Cursor-Prototyp

Da &kile; ein Texteditor ist. sind soweit möglich Cursor und Bereiche die Grundlage der Programmierschnittstelle (API) für Skripte. Ein Cursor ist ein einfaches Tupel aus `(zeile, spalte)` für die Textposition im Dokument.

    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 anderer);

- Kopierkonstruktor: Gibt die Kopie des Cursors `anderer` zurück.

  Beispiel: `var copy = new Cursor(cursor);`

    Cursor Cursor.clone();

- Gibt einen Klon des Cursors zurück.

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

    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 anderer);

- Vergleicht diesen Cursor mit dem Cursor `anderer` . Gibt folgende Werte zurück:

  - `-1`, wenn dieser Cursor sich vor dem Cursor `anderer` befindet,

  - `0`, wenn beide Cursor an der gleichen Stelle stehen und

  - `+1`, wenn dieser Cursor sich hinter dem Cursor `anderer` befindet.

    bool Cursor.equals(Cursor anderer);

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

    String Cursor.toString();

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

### Der Bereich-Prototyp

Da &kile; 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 m Dokument. Ein Bereich umfasst Text von Start bis zum Ende der Cursorposition.

    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`, `ende`)` 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 anderer);

- Kopierkonstruktor: Gibt eine Kopie von Range `anderer` zurück.

    Range Range.clone();

- Gibt einen Klon des Bereichs zurück.

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

    bool Range.isValid();

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

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

    bool 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 Cursorposition enthält, sonst `false`.

    bool Range.contains(Range anderer);

- Gibt `true` zurück, wenn dieser Bereich den Bereich `anderer` 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 anderer);

- Gibt `true` zurück, wenn dieser Bereich und der Bereich `anderer` 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.equals(Range anderer);

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

    String Range.toString();

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

### Die Programmierschnittstelle zur Ansicht

Für jedes ausgeführte Skript gibt es eine globales Objekt oder Variable `view` für die aktuelle Editoransicht. Alle Funktionen von `view` arbeiten mit Cursor-Positionen oder Textauswahl. Es folgt eine Liste aller vorhandenen Funktionen für `view`.

    void view.backspace();

- Führt im Programm die gleiche Funktion wie das Drücken der Rücktaste aus.

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

    void view.cursorLeft();

- Bewegt den Cursor zum vorherigen Zeichen im Text.

    void view.cursorRight();

- Bewegt den Cursor zum nächsten Zeichen im Text.

    void view.cursorUp();

- Bewegt den Cursor zur vorherigen Zeile im Dokument.

    void view.cursorDown();

- Bewegt den Cursor zur nächsten Zeile im Dokument.

    int view.cursorLine();

- Gibt die Zeile zurück, in der sich der Cursor gerade befindet.

    int view.cursorColumn();

- Gibt die Spalte zurück, in der sich der Cursor gerade befindet.

    void view.setCursorLine(int zeile);

- Setzt die Cursor-Zeile auf die angegebene `zeile`.

    void view.setCursorColumn(int spalte);

- Setzt die Cursor-Spalte auf die angegebene `spalte`.

    Cursor view.virtualCursorPosition();

- Gibt die aktuelle virtuelle Cursor-Position zurück. Virtuell bedeutet, dass Tabulatoren als mehrere Zeichen entsprechend der eingestellten Werte gezählt werden, zum Beispiel ein Tabulator als 8 Leerzeichen. Die virtuelle Cursor-Position ermöglicht den Zugriff auf die für den Benutzer sichtbaren Werte der aktuellen Cursor-Position.

    bool view.hasSelection();

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

    String view.selectedText();

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

    Range view.selectionRange();

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

    void view.setSelection(Range bereich);

- Setzt den ausgewählten Text zum angegebenen `bereich`.

    void view.selectAll();

- Wählt den gesamten Text im Dokument aus.

    void view.clearSelection();

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

    void view.removeSelectedText();

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

    void view.selectLine();

- Wählt den Text in der aktuellen Zeile aus.

    void view.selectLine(int zeile);

- Wählt den Text in der angegebenen `zeile` aus.

    void view.selectLines(int von, int bis);

- Wählt den gesamten Text von Zeile `von` bis Zeile `bis` aus.

    void view.selectWord();

- Wählt das aktuelle Wort aus. Wurde an der aktuellen Cursor-Position kein Wort gefunden, passiert nichts.

    void view.selectLatexCommand();

- Wählt den aktuellen &latex;-Befehls aus. Wurde an der aktuellen Cursor-Position kein Befehl gefunden, passiert nichts.

    void view.selectEnvironment(bool inside = false);

- Wählt den gesamten Text der aktuellen &latex;-Umgebung aus. Wenn der Parameter `inside` den Wert `False` hat, wird der Text der Umgebung einschließlich der umgebenden &latex;-Tags `\begin{...}...\end{...}` ausgewählt, ansonsten ohne diese Tags. Ist kein Parameter angegeben, wird `inside` auf `false` gesetzt.

    void view.selectTexgroup(bool inside = true);

- Wählt den Text der aktuellen &latex;-Gruppe aus. Wenn der Parameter `inside` den Wert `true` hat, wird nur die TeX-Gruppe ohne umgebende Klammern ausgewählt. Ist kein Parameter angegeben, wird `inside` auf `true` gesetzt.

    void view.selectMathgroup();

- Wählt den Text in der aktuellen Mathematikgruppe aus.

    void view.selectParagraph(bool wholeLines = true);

- Wählt den Text des aktuellen &latex;-Paragraphen aus. Wenn der Parameter `wholeLines` den Wert `true` hat, wird die erste und letzte Zeilen vollständig einschließlich dem Zeilenendezeichen in der Auswahl enthalten. Andernfalls sind nur Nicht-Leerraumzeichen in der Auswahl.

### Die Programmierschnittstelle 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 `document`.

    void document.insertText(String text);

- Fügt den `text` an der aktuellen Cursor-Position ein.

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

- Fügt den `text` an der angegebenen Cursor-Position ein.

    bool document.removeText(int fromLine, int fromColumn, int toLine, int toColumn);
    bool document.removeText(Cursor from, Cursor to);
    bool document.removeText(Range range);

- 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.replaceText(Range range, String text);

- Ersetzt den Text des angegebenen Bereichs mit dem vorgegebenen Text.

    int document.lines();

- Gibt die Zeilenanzahl des Dokuments zurück.

    int document.length();

- Gibt die Anzahl der Zeichen des Dokuments zurück.

    Range document.documentRange();

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

    Cursor document.documentEnd();

- Gibt die aktuelle Cursor-Position des Dokumentenendes zurück.

    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 fromLine, int fromColumn, int toLine, int toColumn);
    String document.text(Cursor from, Cursor to);
    String document.text(Range range);

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

    bool document.setText(String text);

- Setzt den Text für das gesamte Dokument.

    bool document.clear();

- Löscht den gesamten Text im Dokument.

    String document.line();

- Gibt den Text der aktuellen Zeile als String zurück.

    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.

    int document.lineLength();

- Gibt die Länge der aktuellen Zeile zurück.

    int document.lineLength(int zeile);

- Gibt die Länge der `zeile` zurück.

    bool document.insertLine(String s);

- Fügt Text in die aktuelle 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.insertLine(int zeile, String s);

- 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();

- Löscht die aktuelle Textzeile. War das erfolgreich, wird `true` zurückgegeben, oder `false`, wenn das Dokument im Nur-Lesen-Modus geöffnet wurde.

    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.replaceLine(String text);

- Ersetzt den Text der aktuellen Zeile mit dem vorgegebenen Text.

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

- Ersetzt den Text der angegebenen Zeile mit dem vorgegebenen Text.

    bool document.truncateLine();

- Schneidet die aktuelle 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.truncate(int zeile, int spalte);
    bool document.truncate(Cursor cursor);

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

    String document.word();

- Gibt das Wort an der aktuellen Cursor-Position zurück. Wurde an dieser Position kein Wort gefunden, wird eine leere Zeichenfolge zurückgegeben.

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

- Gibt das Wort an der angegebenen Cursor-Position zurück. Wurde an dieser Position kein Wort gefunden, wird eine leere Zeichenfolge zurückgegeben.

    Range document.wordRange();

- Gibt den Bereich des Wortes an der angegebenen Cursor-Position zurück. Wurde kein Wort gefunden, wird `Range.invalid()` zurückgegeben. Dies kann mit der Funktion `Range.isValid()` überprüft werden.

    String document.latexCommand();

- Gibt den &latex;-Befehl an der aktuellen Cursor-Position zurück. Wurde an dieser Position kein Befehl gefunden, wird eine leere Zeichenfolge zurückgegeben.

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

- Gibt den &latex;-Befehl an der angegebenen Cursor-Position zurück. Wurde an dieser Position kein Befehl gefunden, wird eine leere Zeichenfolge zurückgegeben.

    Range document.latexCommandRange();

- Gibt den Bereich des &latex;-Befehls an der angegebenen Cursor-Position zurück. Wurde kein &latex;-Befehl gefunden, wird `Range.invalid()` zurückgegeben. Dies kann mit der Funktion `Range.isValid()` überprüft werden.

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

- Gibt das Zeichen an der aktuellen Cursorposition 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`.

    void document.insertBullet();

- Fügt eine &kile;-Sprungmarke ein.Denken Sie daran, dass Sie einfach zur nächsten oder vorherigen Sprungmarke gehen können. Diese Funktion wählt außerdem diese Sprungmarke aus, so dass sie automatisch gelöscht wird, wenn Sie die ersten Zeichen eingeben.

    void document.nextBullet();

- Springt zur nächsten Sprungmarke im Text (sofern vorhanden).

    void document.previousBullet();

- Springt zur vorherigen Sprungmarke im Text (sofern vorhanden).

    bool document.hasEnvironment();

- Gibt `true` zurück, wenn eine umgebende &latex;-Umgebung gefunden wurde, sonst `false`.

    String document.environment(bool inside = false);

- Gibt den gesamten Text der umgebenden &latex;-Umgebung zurück. Wenn der Parameter `inside` den Wert `false` hat, wird der Text der Umgebung einschließlich der umgebenden &latex;-Tags `\begin{...}...\end{...}` ausgewählt, ansonsten ohne diese Tags. Ist kein Parameter angegeben, wird `inside` auf `false` gesetzt. Wurde keine Umgebung gefunden. wird eine leere Zeichenfolge zurückgegeben.

    Range document.environmentRange(bool inside = false);

- Gibt den Bereich der umgebenden &latex;-Umgebung zurück. Wenn der Parameter `inside` den Wert `false` hat, wird der Bereich der Umgebung einschließlich der umgebenden &latex;-Tags `\begin{...}...\end{...}` zurückgegeben, ansonsten ohne diese Tags. Ist kein Parameter angegeben, wird `inside` auf `false` gesetzt. Wurde keine Umgebung gefunden. wird `Range.invalid()` zurückgegeben. Dies kann mit der Funktion `Range.isValid()` überprüft werden.

    String document.environmentName();

- Gibt den Namen der umgebenden &latex;-Umgebung oder eine leere Zeichenfolge zurück.

    void document.removeEnvironment(bool inside = false);

- Entfernt den gesamten Text der aktuellen &latex;-Umgebung. Wenn der Parameter `inside` den Wert `false` hat, wird der Text der Umgebung einschließlich der umgebenden &latex;-Tags `\begin{...}...\end{...}` entfernt, ansonsten ohne diese Tags. Ist kein Parameter angegeben, wird `inside` auf `false` gesetzt.

    void document.closeEnvironment();

- Fügt ein schließendes Umgebungs-Tag ein, wenn eine offene &latex;-Umgebungen an der aktuellen Cursor-Position gefunden wurde.

    void document.closeAllEnvironments();

- Fügt das schließende Umgebungs-Tag für alle offenen &latex;-Umgebungen ein, die an der aktuellen Cursor-Position gefunden wurden.

    bool document.hasTexgroup();

- Gibt `true` zurück, wenn eine umgebende &latex;-Gruppe an der aktuellen Cursor-Position gefunden wurde, sonst `false`.

    String document.texgroup(bool inside = true);

- Gibt den Text der umgebenden &latex;-Gruppe zurück. Wenn der Parameter `inside` den Wert `false` hat, wird der Text dieser &latex;-Gruppe einschließlich der umgebenden Klammern `{...}` zurückgegeben, ansonsten ohne diese Klammern. Ist kein Parameter angegeben, wird `inside` auf `false` gesetzt. Wurde keine umgebenden &latex;-Gruppe gefunden. wird eine leere Zeichenfolge zurückgegeben.

    Range document.texgroupRange(bool inside = true);

- Gibt den Bereich der umgebenden &latex;-Gruppe zurück. Wenn der Parameter `inside` den Wert `false` hat, wird der Bereich einschließlich der umgebenden Klammern `{...}` zurückgegeben, ansonsten ohne diese Klammern. Ist kein Parameter angegeben, wird `inside` auf `false` gesetzt. Wurde keine Gruppe gefunden. wird `Range.invalid()` zurückgegeben. Dies kann mit der Funktion `Range.isValid()` überprüft werden.

    void document.removeTexgroup(bool inside = true);

- Entfernt den Text der umgebenden &latex;-Gruppe. Wenn der Parameter `inside` den Wert `false` hat, wird der Text der &latex;-Gruppe einschließlich der umgebenden Klammern `{...}` entfernt, ansonsten ohne diese Klammern. Ist kein Parameter angegeben, wird `inside` auf `false` gesetzt.

    bool document.hasMathgroup();

- Gibt `true` zurück, wenn eine umgebende &latex;-Mathematikgruppe an der aktuellen Cursor-Position gefunden wurde, sonst `false`.

    String document.mathgroup();

- Gibt den Text der umgebenden &latex;-Mathematikgruppe zurück. Der Rückgabewert ist eine leere Zeichenfolge, wenn keine umgebende &latex;-Mathematikgruppe an der aktuellen Cursor-Position gefunden wurde.

    Range document.mathgroupRange();

- Gibt den Bereich der umgebenden &latex;-Mathematikgruppe zurück Wurde keine Mathematikgruppe gefunden, wird `Range.invalid()` zurückgegeben. Dies kann mit der Funktion `Range.isValid()` überprüft werden.

    void document.removeMathgroup();

- Entfernt den Text der umgebenden &latex;-Mathematikgruppe.

    String document.paragraph();

- Gibt den Text des aktuellen &latex;-Paragraphen zurück.

    Range document.paragraphRange();

- Gibt den Bereich des umgebenden &latex;-Paragraphen zurück.

    void document.removeParagraph();

- Entfernt den Text des aktuellen &latex;-Paragraphen.

    bool document.matchesAt(int zeile, int spalte, 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 muster, bool skipWhiteSpaces = true);

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

    bool document.endsWith(int zeile, String muster, bool skipWhiteSpaces = true);

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

    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 kein Leerraumzeichen enthält. Die Suche beginnt an der angegebenen Cursorposition und erfolgt dabei rückwärts.

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

- Gibt die Spalte zurück, die kein Leerraumzeichen enthält. Die Suche beginnt an der angegebenen Cursorposition 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.

    void document.gotoBeginEnv();

- Geht zum Beginn der umgebenden &latex;-Umgebung.

    void document.gotoEndEnv();

- Geht zum Ende der umgebenden &latex;-Umgebung.

    void document.gotoBeginTexgroup();

- Geht zum Beginn der umgebenden &latex;-Gruppe.

    void document.gotoEndTexgroup();

- Geht zum Ende der umgebenden &latex;-Gruppe.

    void document.gotoNextParagraph();

- Geht zum nächsten &latex;-Paragraphen.

    void document.gotoPrevParagraph();

- Geht zum vorherigen &latex;-Paragraphen.

    void document.gotoNextSectioning();

- Geht zum nächsten &latex;-Abschnitt.

    void document.gotoPrevSectioning();

- Geht zum vorherigen &latex;-Abschnitt.

    void document.gotoLine(int zeile);

- Geht zur angegebenen `zeile`.

    void document.insertChapter();

- Fügt einen Befehl `\chapter` ein (Siehe auch `document.insertSection()`).

    void document.insertSection();

- Fügt einen Befehl `\section` ein. Wie mit dem Menüeintrag LaTeX Gliederung section wird ein Dialog geöffnet, in dem ein Titel des Abschnitts und ein optionales Label für diesen Befehl eingegeben werden kann. Dialog: Einen Kapitelbefehl einfügen Dialog: Einen Kapitelbefehl einfügen

    void document.insertSubsection();

- Fügt einen Befehl `\subsection` ein, siehe auch `document.insertSection()`.

    void document.insertSubsubsection();

- Fügt einen Befehl `\subsubsection` ein, siehe auch `document.insertSection()`.

    void document.insertParagraph();

- Fügt einen Befehl `\paragraph` ein. siehe auch `document.insertSection()`.

    void document.insertSubparagraph();

- Fügt einen Befehl `\subparagraph` ein, siehe auch `document.insertSection()`.

    void document.insertLabel();

- Fügt einen Befehl `\label` ein.

    void document.insertReference();

- Fügt einen Befehl `\ref` ein. Wie mit dem Menüeintrag &latex;Referenzen ref wird ein Dialog geöffnet, in dem aus vorhandenen Labeln aus einem Kombinationsfeld ausgewählt werden kann. Dialog: Einen Referenzbefehl einfügen Dialog: Einen Referenzbefehl einfügen

    void document.insertPageref();

- Fügt einen Befehl `\pageref` ein, siehe auch `document.insertReference()`.

    void document.insertCitation();

- Fügt einen Befehl `\cite` ein.

    void document.insertIndex();

- Fügt einen Befehl `\index` ein.

    void document.insertFootnote();

- Fügt einen Befehl `\footnote` ein.

    void document.comment();

- Setzt Kommentarzeichen, um die Auswahl oder die aktuelle Zeile zu Kommentaren zu machen.

    void document.uncomment();

- Entfernt Kommentarzeichen von der Auswahl oder der aktuellen Zeile.

    void document.uppercase();

- Der ausgewählte Text oder der Buchstabe nach dem Cursor wird in Großschreibung gesetzt.

    void document.lowercase();

- Der ausgewählte Text oder der Buchstabe nach dem Cursor wird in Kleinschreibung gesetzt.

    void document.capitalize();

- Setzt den ausgewählten Text oder das aktuelle Wort in Großbuchstaben.

    void document.joinLines();

- Verbindet die Zeilen der aktuellen Auswahl. Zwei aufeinander folgende Textzeilen werden immer durch ein Leerzeichen getrennt.

    void document.insertIntelligentNewline();

- Fügt einen Zeilenumbruch ein, siehe editing_smartnewline.

    void document.insertIntelligentTabulator();

- Fügt einen „Intelligenten Tabulator“ ein, siehe editing_tabulator.

    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, &ie; diese Aufrufe können geschachtelt werden.

    void document.editEnd();

- Beendet eine Bearbeitungsgruppe. Der letzte Aufruf von `editEnd()` (&ie; der Aufruf zum ersten Aufruf von `editBegin()`) beendet den Bearbeitungsschritt.

    StringList document.labelList();

- Gibt alle definierten Label als eine `StringList` zurück, die in &javascript; als Feld von Zeichenfolgen benutzt werden kann.

    StringList document.bibitemList();

- Gibt alle definierten Einträge im Literaturverzeichnis als eine `StringList` zurück, die in &javascript; als Feld von Zeichenfolgen benutzt werden kann.

    void document.refreshStructure();

- Lädt die Strukturansicht wieder neu (siehe navigating).

### Die &kile;-API

Das globale Objekt (Variable) `kile` wird zur Interaktion mit Eingabenachrichten, und Dialogschnittstellen benutzt. Die API-Aufrufe sind zur Strukturierung dieses Teils der Skript-API in Unterobjekte aufgeteilt. Konzeptionell ist `kile` etwa mit den Objekt `window` in einem Browser vergleichbar.

- `kile.alert`: Nachrichtenfenster

- `kile.input`: Benutzereingaben abfragen

- `kile.wizard`: Aufruf eines &kile;-Assistenten

- `kile.script`: Informationen über ein laufendes Skript abfragen

- `kile.file`: Dateioperationen wie Lesen und Schreiben.

#### Alert (Dialoge)

    void kile.alert.information(String text, String caption);

- Zeigt einen Informations-Dialog. Der Parameter `text` wird als Nachricht und `caption` als Titel des Dialogs verwendet. Standardtitel ist der Name des Skripts.

    void kile.alert.sorry(String text, String caption);

- Zeigt einen Dialog Entschuldigung. Der Parameter `text` wird als Nachricht und `caption` als Titel des Dialogs verwendet. Standardtitel ist der Name des Skripts.

    void kile.alert.error(String text, String caption);

- Zeigt einen Fehler-Dialog. Der Parameter `text` wird als Nachricht und `caption` als Titel des Dialogs verwendet. Standardtitel ist der Name des Skripts.

    String kile.alert.question(String text, String caption);

- Zeigt einen einfachen Frage-Dialog. Der Parameter `text` wird als Nachricht und `caption` als Titel des Dialogs verwendet. Standardtitel ist der Name des Skripts. Als Zeichenfolge wird entweder `yes` oder `no` zurückgegeben.

    String kile.alert.warning(String text, String caption);

- Zeigt einen einfachen Warnung-Dialog. Der Parameter `text` wird als Nachricht und `caption` als Titel des Dialogs verwendet. Standardtitel ist der Name des Skripts. Als Zeichenfolge wird entweder `continue` oder `cancel` zurückgegeben.

#### Input (Eingaben)

    String kile.input.getListboxItem(String caption, String label, StringList list);

- Funktion, mit dem der Benutzer einen Eintrag aus einer Liste in einem Listenfeld auswählen kann. `caption` wird in der Titelleiste angezeigt, `label` als Beschriftung des Listenfelds und `list` ist die Zeichenfolge, die als als Liste in das Listenfeld eingefügt wird.

    String kile.input.getComboboxItem(String caption, String label, StringList list);

- Funktion, mit dem der Benutzer einen Eintrag aus einer Liste in einem Kombinationsfeld auswählen kann. `caption` wird in der Titelleiste angezeigt, `label` als Beschriftung des Kombinationsfelds und `list` ist die Zeichenfolge, die als als Liste in das Kombinationsfeld eingefügt wird.

    String kile.input.getText(String caption, String label);

- Funktion, mit dem der Benutzer einen Text eingeben kann. `caption` wird in der Titelleiste angezeigt und `label` als Beschriftung des Eingabefelds benutzt.

    String kile.input.getLatexCommand(String caption, String label);

- Funktion, mit dem der Benutzer einen &latex;-Befehl eingeben kann, für den nur groß- oder kleingeschriebene Zeichen zuläsig sind. `caption` wird in der Titelleiste angezeigt und `label` als Beschriftung des Eingabefelds benutzt.

    int kile.input.getInteger(String caption, String label, int min = INT_MIN, int max = INT_MAX);

- Funktion, um den Benutzer eine Glanzzahl eingeben zu lassen. `caption` ist der im Dialog angezeigte Titel. `label` ist die Beschriftung für das Drehfeld. `min` und `max` sind die minimalen und maximalen Werte die hier eingegeben werden können.Die Standardwerte sind `INT_MIN` und `INT_MAX`.

    int kile.input.getPosInteger(String caption, String label, int min = 1, int max = INT_MAX);

- Funktion, um den Benutzer eine positive Glanzzahl eingeben zu lassen. `caption` ist der im Dialog angezeigte Titel. `label` ist die Beschriftung für das Drehfeld. `min` und `max` sind die minimalen und maximalen Werte die hier eingegeben werden können.Die Standardwerte sind `1` und `INT_MAX`.

#### Wizard (Assistenten)

    void kile.wizard.tabular();

- Ruft den Tabellen-Assistenten auf, der Sie beim Schreiben von Tabellen-Umgebungen unterstützt, siehe wizard_array.

    void kile.wizard.array();

- Ruft den Feld-Assistenten auf, der Sie beim Schreiben von Feld-Umgebungen unterstützt, siehe wizard_array.

    void kile.wizard.tabbing();

- Ruft den Tabulatoren-Assistenten auf, der Sie beim Schreiben von Tabulatoren-Umgebungen unterstützt, siehe wizard_array.

    void kile.wizard.floatEnvironment();

- Ruft den Gleitobjekt-Assistenten auf, der Sie beim Einfügen von Gleitobjekt-Umgebungen unterstützt, siehe wizard_float.

    void kile.wizard.mathEnvironment();

- Ruft den Mathematik-Assistenten auf, der Sie beim Einfügen von Mathematik-Umgebungen unterstützt (siehe wizard_math).

    void kile.wizard.postscript();

- Öffnet den Assistenten Postscript-Werkzeuge, der die Bearbeitung oder das Umordnen von Postscript-Dokumenten unterstützt, siehe auch wizard_postscript).

#### Skript

    String kile.script.name();

- Gibt den Dateinamen eines ausgeführten Skripts ohne Pfad und Erweiterung zurück.

    String kile.script.caption();

- Gibt eine Zeichenfolge zurück, die als Titel eines Benachrichtigungsdialogs benutzt werden kann. Der Wert hat die Form `Skript: scriptname.js`.

#### Datei

    Objekt kile.file.read(String filename);

- Liest den Inhalt einer Textdatei, wie im folgenden gezeigt wird.

  Beispiel: `var res = kile.file.read("pfad/zu/datei.txt");`

  Der Rückgabewert `res` ist ein Objekt (genauer eine „Map“) mit drei Eigenschaften:

  - status: Gibt den Status-Code der Operation zurück. Möglicher Werte sind: 0 (kein Fehler), 1 (Zugriff fehlgeschlagen) oder 2 (Zugriff verweigert). Wenn kein Fehler aufgetreten ist, hat `res.status` oder `res["status"]` den Wert 0.

  - result: Enthält den Text der angegebenen Datei.

  - message: Enthält eine Fehlermeldung, wenn ein Fehler aufgetreten ist.

    Objekt kile.file.read();

- Wie `read(filename)`, aber es wird kein Dateiname angegeben. Es wird ein Dialog zur Auswahl eines Dateinamens angezeigt.

    Objekt kile.file.write(String filename, String text);

- Schreibt den angegebenen Text in eine Datei, wie im folgenden gezeigt wird.

  Beispiel: `var res = kile.file.write("pfad/zu/datei.txt","Ein Text ...");`

  Der Rückgabewert `res` ist ein Objekt (genauer eine „Map“) mit zwei Eigenschaften: `status` und `message`.Weitere Informationen finden Sie bei der Funktion `read())`.

    Objekt kile.file.write(String text);

- Wie `write(filename,text)`, aber es wird kein Dateiname angegeben. Es wird ein Dialog zur Auswahl eines Dateinamens angezeigt.

    String kile.file.getOpenFileName(String startDir, String filter);

- Öffnet einen modalen Dateidialog und gibt den gewählten Dateinamen oder eine leere Zeichenfolge zurück, wenn keine Datei ausgewählt wurde. Beachten Sie, dass der Benutzer mit dieser Funktion nur einen bereits vorhandenen Dateinamen auswählen kann.

  Parameter:

  - startDir: Startordner des Dialogs „Datei öffnen“.

  - filter: Ein Shell-Muster oder ein MIME-Typ-Filter, der die anzuzeigenden Dateien bestimmt. In der Dokumentation zu KFileDialog finden Sie weitere Informationen zu diesen Parametern.

  Beide Parameter sind optional. Fehlt `filter`, dann werden alle Dateien angezeigt. Wenn auch `startDir` nicht angegeben ist, wird der Ordner des aktuellen Dokuments als Startordner verwendet.

    String kile.file.getSaveFileName(String startDir, String filter);

- Öffnet einen modalen Dateidialog und gibt den gewählten Dateinamen oder eine leere Zeichenfolge zurück, wenn keine Datei ausgewählt wurde. Beachten Sie, dass der Benutzer mit dieser Funktion nicht nur einen bereits vorhandenen Dateinamen auswählen kann. Siehe auch `getOpenFileName()` zur Erläuterung der Parameter.

## Beispiele

Einige Beispiele können die Anwendung der Skript-API erläutern. Diese und weitere Beispiele finden Sie Im Skript-Ordner von &kile;: `KILE_APP_DIR/scripts/`. Jedes Skript in diesem Ordner enthält eine kurze Beschreibung.

### Beispiel 1: Einen Umgebungsnamen ersetzen

Ersetzen einer umgebenden &latex;-Umgebung durch eine Andere, dabei wird die relative Cursor-Position nicht geändert. `\begin{abc}...\end{abc}` zum Beispiel kann zu `\begin{xyz}...\end{xyz}` geändert werden.

    var range = document.environmentRange(false);
    if ( range.isValid() ) {
            var envname = kile.input.getLatexCommand("Umgebung eingeben","Neuer Name der Umgebung:");
            if ( envname != '' ) {
                    replaceEnvCommand(envname,range);
            }
    }
    else {
            kile.alert.sorry("Keine umgebende LaTeX-Umgebung gefunden.");
    }

    function replaceEnvCommand(newEnv,r)
    {
            var c = view.cursorPosition();

            var envname = document.environmentName();

            if ( envname != "" ) {
                    var beginRange = new Range(r.start,new Cursor(r.start.line,r.start.column+8+envname.length));
                    var endRange = new Range(new Cursor(r.end.line,r.end.column-6-envname.length),r.end);

                    document.editBegin();
                    document.replaceText(endRange,"\\end{"+newEnv+"}");
                    document.replaceText(beginRange,"\\begin{"+newEnv+"}");
                    document.editEnd();
            }
    }

### Beispiel 2: Einen &latex;-Schriftbefehl ersetzen

Ersetzen eines umgebenden &latex;-Schriftbefehls durch einen anderen Schriftbefehl, wenn der Cursor innerhalb einer TeX-Gruppe steht. Die relative Cursor-Position wird nicht geändert. `\textbf{abc}` zum Beispiel kann zu `\textit{abc}` geändert werden.

    var fontCommands = new Array("\\textbf","\\textit","\\textsl","\\texttt",
                                 "\\textsc","\\textrm","\\textsf","\\emph");

    var range = document.texgroupRange(false);
    if ( range.isValid() ) {
            replaceFontCommand(range);
    }
    else {
            kile.alert.sorry("Keine umgebende TeX-Gruppe gefunden.");
    }

    function replaceFontCommand(r)
    {
            var c = view.cursorPosition();

            document.editBegin();
            view.setCursorPosition(r.start);
            var cmd = document.latexCommand();
            var index = fontCommands.indexOf(cmd);
            if ( index
    >= 0 ) {
                    var cmdRange = document.latexCommandRange();
                    if ( cmdRange.isValid() ) {
                            var newcommand = kile.input.getListboxItem("Auswahl",
                                                        "Wählen Sie einen Schriftbefehl:",buildCmdList(cmd));
                            if ( newcommand != "" ) {
                                    document.replaceText(cmdRange,newcommand);
                                    c.column = c.column - (cmd.length - newcommand.length);
                            }
                    }
    /                view.setCursorPosition(c);
            }
            else {
                    kile.alert.sorry("Kein umgebender Schriftbefehl gefunden.");
            }
            document.editEnd();
    }

    function buildCmdList(current)
    {
            var result = new Array();
            for ( i=0; i<fontCommands.length; ++i ) {
                    if ( fontCommands[i] != current ) {
                            result.push(fontCommands[i]);
                    }
            }
            return result;
    }

### Beispiel 3: Umgebung für ausgewählten Text

Umgebung eines ausgewählten Textes mit einem TeX-Befehl, dabei wird die relative Cursor-Position nicht verändert. `abc` zum Beispiel kann zu `\texcommand{abc}` geändert werden.

    var range = view.selectionRange();

    if ( range.isValid() ) {
            var cmd = kile.input.getLatexCommand("Auswahl","Wählen Sie den umgebenden LaTeX-Befehl:");
            if ( cmd != "" ) {
                    surroundTexCommand("\\"+cmd,range);
            }
    }
    else {
            kile.alert.sorry("Keine Auswahl gefunden.");
    }

    function surroundTexCommand(cmd,r)
    {
            var c = view.cursorPosition();

            document.editBegin();
            view.clearSelection();
            document.insertText(r.end,"}");
            document.insertText(r.start,cmd+"{");

            c.column = c.column + cmd.length + 2;
            view.setCursorPosition(c);
            document.editEnd();
    }