# Weitentwickelte Editierwerkzeuge

## Kommentar/Kommentar entfernen

Die Befehle Kommentar und Kommentar entfernen im Menü Bearbeiten erlauben das Hinzufügen oder Entfernen von Kommentarzeichen zur Auswahl, oder der aktuellen Textzeile, wenn kein Text markiert wurde. Diese Funktionen stehen nur zur Verfügung, wenn das benutzte Textformat Kommentare unterstützt.

Die Regeln für Kommentare werden in den Definitionen für die Syntax festgelegt, wenn Hervorhebungen für Syntax nicht benutzt werden, ist die Nutzung der Befehle also nicht möglich.

Einige Formate nutzen Kommentarzeichen für einzelne Zeilen, manche nutzen Kommentarzeichen für mehrere Zeilen, manche beides. Wenn Kommentarzeichen für mehrere Zeilen nicht verfügbar sind, kann eine Auswahl nicht auskommentiert werden, deren letzte Zeile nicht vollständig in die Auswahl einbezogen ist.

Wenn Kommentarzeichen für einzelne Zeilen definiert sind, werden diese bevorzugt eingesetzt, dies hilft, Probleme mit eingebetteten Kommentaren zu vermeiden.

Wenn Sie Kommentarzeichen entfernen, sollte nur kommentierter Text ausgewählt sein. Wenn mehrzeilige Kommentare entfernt werden, werden Leerzeichen und Tabulatoren (whitespaces) außerhalb der Kommentarzeichen ignoriert.

Um Kommentarzeichen einzufügen, wählen Sie im Menü Extras Kommentar oder das Tastenkürzel, hier standardmäßig &Ctrl;D.

Zum Entfernen von Kommentarzeichen wählen Sie im Menü Bearbeiten Kommentar entfernen oder das Tastenkürzel, hier standardmäßig &Strg;&Umschalt;D.

## Die integrierte Befehlszeile im Editor

&kate;s Editor hat eine interne Befehlszeile, von der aus Sie verschiedene Aktionen ausführen können. Die Befehlszeile ist ein Texteingabefeld am unteren Rand des Editorbereichs. Sie können diese einblenden, indem Sie im Menü Ansicht Auf Befehlszeile umschalten wählen oder das Tastenkürzel verwenden (standardmäßig ist F7 eingestellt). Der Editor stellt einige Befehle bereit, die nachfolgend beschrieben werden. Außerdem können Erweiterungen (Plugins) weitere Befehle bereitstellen.

Um einen Befehl auszuführen, geben Sie diesen in die Befehlszeile ein und drücken Sie Eingabetaste. Der Befehl gibt aus, ob die Ausführung erfolgreich war, eventuell wird noch eine Mitteilung ausgegeben. Wenn Sie den Befehl durch Drücken des Tastenkürzels F7 eingegeben haben, wird die Befehlszeile nach einigen Sekunden ausgeblendet. Um die Mitteilung zu löschen und einen neuen Befehl einzugeben, drücken Sie das Tastenkürzel F7 noch einmal.

Die Befehlszeile hat ein eingebautes Hilfesystem, das durch den Befehl `help` aufgerufen wird. Der Befehl `help list` zeigt eine Liste aller verfügbaren Befehle an, Hilfe zu einem speziellen Befehl erhalten Sie durch Eingabe von `help `befehl``.

Die Befehlszeile hat eine eingebauten Verlaufsspeicher, so dass Sie bereits eingegebene Befehle wiederverwenden können. Um aus den bisherigen Befehlen auszuwählen, benutzen Sie die Tasten Nach oben und Nach unten. Wenn bisherige Befehle angezeigt werden, dann ist automatisch der Teil des Befehls, der die Argumente enthält, markiert, so dass Sie die Argumente sofort überschreiben können.

### Standardbefehle der Befehlszeile

#### Befehle zum Einrichten des Editors

Diese Befehle werden von der Editorkomponente bereitgestellt und gestatten das Einrichten des Editors für die aktuelle Ansicht des aktuellen Dokuments. Dies ist hilfreich, wenn Sie von den Standardeinstellungen abweichende Einstellungen, &zb; für Einrückungen benutzen wollen.

#### Typen der Argumente

BOOLEAN

- Dieser Typ wird mit Befehlen benutzt, die Dinge ein- und ausschalten. Zulässige Werte sind `on`, `off`, `true`, `false`, `1` oder `0`.

INTEGER

- Eine ganze Zahl

STRING

- Eine Zeichenkette

    set-tab-widthINTEGER Weite

- Setzt die Tabulatorweite auf `Weite`

    set-indent-widthINTEGER Weite

- Setzt die Einrückungsweite auf `Weite`. Dieser Wert wird nur benutzt, wenn Sie Leerzeichen zum Einrücken verwenden.

    set-word-wrap-columnINTEGER Weite

- Setzt die Zeilenlänge für den harten Zeilenumbruch auf `Weite`. Dieser Wert wird nur benutzt, wenn Sie den automatischen Zeilenumbruch benutzen.

    set-icon-borderBOOLEAN enable

- Schaltet die Anzeige des Symbolrandes ein und aus.

    set-folding-markersBOOLEAN enable

- Schaltet die Markierungen für die Code-Ausblendung ein und aus.

    set-line-numbersBOOLEAN enable

- Schaltet die Zeilennummerierung ein und aus.

    set-replace-tabsBOOLEAN enable

- Wenn eingeschaltet, werden Tab's durch Leerzeichen ersetzt.

    set-remove-trailing-spaceBOOLEAN enable

- Wenn eingeschaltet, werden Leerzeichen und andere Zwischenräume am Zeilenanfang entfernt, wenn der Cursor eine Zeile verlässt.

    set-show-tabsBOOLEAN enable

- Wenn eingeschaltet, werden Tab's und vorangestellte Leerzeichen durch kleine Punkte dargestellt.

    set-indent-spacesBOOLEAN enable

- Wenn eingeschaltet, werden Leerzeichen in der mit `indent-width` eingestellten Anzahl für jedes Einrückungsniveau benutzt und nicht Tab's.

    set-mixed-indentBOOLEAN enable

- Kate benutzt eine Mischung aus Tab's und Leerzeichen zum Einrücken wenn diese OPtion eingeschaltet ist. Jedes Einrückungsniveau ist `indent-width` breit, es werden möglichst viele Leerzeichen durch Tab's ersetzt.

  Wenn dieser Befehl ausgeführt wird, wird außerdem das Einrücken mit Leerzeichen eingeschaltet und wenn die Einrückungsbreite noch nicht festgelegt ist, dann wird diese auf die Hälfte von `tab-width` für dieses Dokument zum Ausführungszeitpunkt gesetzt.

    set-word-wrapBOOLEAN enable

- Schaltet dynamischen Zeilenumbruch ein oder aus.

    set-replace-tabs-saveBOOLEAN enable

- Wenn eingeschaltet, werden Tab's durch Leerzeichen ersetzt, wenn das Dokument gespeichert wird.

    set-remove-trailing-space-saveBOOLEAN enable

- Wenn eingeschaltet, werden am Anfang der Zeile stehende Leerzeichen oder Tab's entfernt, wenn das Dokument gespeichert wird.

    set-indent-modename

- Setzt den Einrückungsmodus auf `name`. Wenn `name` nicht angegeben ist oder ein ungültiger Name verwendet wurde, wird der Modus 'Kein(none)' gesetzt. Verfügbare Modes sind: 'cstyle', 'csands', 'xml', 'python', 'varindent' und 'none'.

    set-highlighthighlight

- Setzt den Hervorhebungsmodus für das aktuelle Dokument. Das Argument muss ein gültiger Name für einen Hervorhebungsmodus sein. Die gültigen Modi findet man unter Extras Hervorhebungen.Dieser Befehl zeigt eine Liste der möglichen Argumente an, wenn die ersten Zeichen des Argumentes eingegeben wurden.

#### Befehle zum Bearbeiten

Diese Befehle bearbeiten und verändern das aktuelle Dokument.

    indent

- Rückt markierten Text oder die aktuelle Zeile ein.

    unindent

- Hebt die Einrückung für die markierten Zeilen oder die aktuelle Zeile auf.

    cleanindent

- Setzt die Einrückungen in den markierten Zeilen oder in der aktuellen Zeile in den Grundzustand zurück. Hierzu werden die Einstellungen für das aktuelle Dokument verwendet.

    comment

- Setzt Kommentarzeichen um die markierten Zeilen oder die aktuelle Zeile zu Kommentaren zu machen. Es wird das Kommentarzeichen aus der Hervorhebungsdefinition für das aktuelle Textformat benutzt.

    uncomment

- Entfernt Kommentarzeichen von den markierten Zeilen oder der aktuellen Zeile. Es wird das Kommentarzeichen aus der Hervorhebungsdefinition für das aktuelle Textformat benutzt.

    kill-line

- Löscht die aktuelle Zeile

    replacesuchtextreplacement

- Ersetzt den mit `suchtext` übereinstimmenden Text durch `replacement`. Wenn Sie Leerzeichen oder Tabulatoren im `suchtext` verwenden wollen, dann müssen Sie sowohl `suchtext` als auch `replacement` in einfache oder doppelte Anführungszeichen einschließen. Wenn Worte nicht in Anführungszeichen eingeschlossen sind, wird das erste Wort als `suchtext` und der Rest als `replacement` benutzt. Wenn `replacement` nicht angegeben ist, dann wird jedes Auftreten von `suchtext` gelöscht.

  Sie können bestimmte Einstellungen für die Suche vornehmen, indem Sie einen Doppelpunkt, gefolgt von einem oder mehreren Buchstaben - die die Einstellungen enthalten - anfügen. Die Form der Eingabe ist dann: `replace:options suchtext replacement`. Folgende Einstellungen sind verfügbar:

  `b`

- Rückwärts suchen.

`c`

- Suchen ab Cursorposition.

`e`

- Suchen nur in markiertem Text.

`r`

- Suche nach einem regulären Ausdruck. Wenn diese Einstellung verwendet wird, können Sie `\N` im replacement string verwenden, die Anzahl, wie oft der Suchtext gefunden wurde, wird dann in den replacement string eingefügt.

`s`

- Suche unter Berücksichtigung von Groß- und Kleinschreibung.

`p`

- Nachfragen vor Ersetzen des nächsten Auftretens.

`w`

- Nur ganze Wörter erfüllen die Suchbedingung.

    dateformat

- Setzt das aktuelle Datum und die aktuelle Uhrzeit im durch `format` eingestellten Format ein. Wenn kein Format eingestellt wurde, wird das Format yyyy-MM-dd hh:mm:ss als Standard benutzt. Die folgenden Übersetzungen werden vorgenommen, wenn `format` ausgewertet wird:

  `d` | Tag als Ziffer ohne führende Null (1-31).
  `dd` | Tag als Ziffer mit führender Null (01-31).
  `ddd` | Tag als abgekürzter Name in Landessprache (&zb; 'Mon'..'Son').
  `dddd` | Tag als langer Name in Landessprache (&zb; 'Montag'..'Sonntag').
  `M` | Monat als Ziffer ohne führende Null (1-12).
  `MM` | Monat als Ziffer mit führender Null (01-12).
  `MMM` | Monat als abgekürzter Name in Landessprache (&zb;'Jan'..'Dez').
  `yy` | Das Jahr als zweistellige Ziffer (00-99).
  `yyyy` | Das Jahr als vierstellige Ziffer (1752-8000).
  `h` | Stunde ohne führende Null (0..23 oder 1..12 wenn AM/PM verwendet wird).
  `hh` | Stunde mit führender Null (00..23 oder 00..12 wenn AM/PM verwendet wird).
  `m` | Minute ohne führende Null (0.59).
  `mm` | Minute mit führender Null (00..59).
  `s` | Sekunde ohne führende Null (0.59).
  `ss` | Sekunde mit führender Null (00.59).
  `z` | Millisekunden ohne führende Null (0..999).
  `zzz` | Millisekunden mit führender Null (000..999).
  `AP` | Benutze die Anzeige mit AM/PM AP wird entweder von "AM" oder "PM" ersetzt.
  `ap` | Benutze die Anzeige mit am/pm ap wird durch "am" oder "pm" ersetzt.

    charidentifier

- Dieser Befehl erlaubt das Einsetzen von Zeichen in Text durch die Eingabe Ihrer Kodierung in dezimaler, oktaler oder hexadezimaler Form. Rufen Sie die Befehlszeile auf, schreiben Sie in das Eingabefeld das Wort `char:[nummer]` und klicken Sie auf OK.

  ##### Beispiele zu `char`

  Eingabe: `char:234`

  Ausgabe: `ê`

  Eingabe: `char:0x1234`

  Ausgabe: `ሴ`

`s///[ig]` `%s///[ig]`

- Dieser Befehl führt Suchen/Ersetzen auf der aktuellen Zeile oder in der gesamten Datei aus (`%s///`).

  Kurz gesagt, der Text wird nach dem Suchtext, dem regulären Ausdruck zwischen dem ersten und dem zweiten Schrägstrich, durchsucht und wenn der Suchtext gefunden wurde, wird der übereinstimmende Teil des Textes durch den Ausdruck zwischen dem mittleren und dem hinterem Schrägstrich ersetzt. Runde Klammern im Suchtext erzeugen Referenzen, die dann später dazu benutzt werden, die Zeichenketten wiederzuverwenden. Diese Referenzen werden wie folgt aufgerufen: `\1` für die erste Referenz, `\2` für die zweite und so weiter.

  Um nach einem Sonderzeichen, `(` oder `)`, zu suchen, müssen Sie dieses durch einen Rückwärtsschrägstrich kenntlich machen. `\(\)`

  Wenn Sie ein `i` an das Ende des Ausdruckes anhängen, wird beim Suchen nicht nach Groß- und Kleinbuchstaben unterschieden. Das Anhängen eines `g` legt fest, dass alle Vorkommen des Suchtextes ersetzt werden, normalerweise wird nur das erste Vorkommen ersetzt.

  ##### Ersetzen von Text in der aktuellen Zeile

  Ihr lieber Computer verweigerte gerade die Ausführung eines Programms, mit der Bemerkung, dass die Klasse `myClass`, die in der Zeile 3902 im Quelltext verwendet wird, nicht definiert ist.

  "Natürlich!", denken Sie, das muss `MyClass` heißen. Sie gehen zur Zeile 3092, rufen den Bearbeitungsbefehl auf, geben `s/myclass/MyClass/i` ein und klicken auf OK, Speichern die Datei und kompilieren – ohne Fehlermeldungen.

  ##### Ersetzen von Text in der gesamten Datei

  Stellen Sie sich vor, Sie hätten eine Datei, in der eine Miss Jensen einige Male erwähnt wird. Jemand kommt zur Tür herein und erzählt Ihnen, dass sie gerade Mr Jones geheiratet hat. Sie stehen nun vor der Aufgabe, jedes Miss Jensen durch Ms Jones zu ersetzen.

  Rufen Sie die Befehlszeile auf, geben Sie `%s/Miss Jensen/Ms Jones/` ein drücken Sie die Eingabetaste - fertig.

  ##### Ein etwas komplizierteres Beispiel

  Dieses Beispiel benutzt Referenzen und auch eine Wortklasse (wenn Sie nicht wissen, was das bedeutet, sehen Sie bitte in der unten angegebenen Dokumentation nach).

  Stellen Sie sich vor, Sie hätten folgende Zeile:

      void MyClass::DoStringOps( String      &foo, String &bar String *p, int  &a, int &b )

  Sie erkennen, dass dies nicht gut lesbar ist und entscheiden, das Schlüsselwort `const` für alle address of-Argumente zu verwenden (diese sind durch den vorangestellten Operator & gekennzeichnet). Außerdem wollen Sie die Zwischenräume vereinfachen, so dass nur noch ein Leerzeichen zwischen den Wörtern steht.

  Rufen Sie den Bearbeitungsbefehl auf, geben Sie `s/\s+(\w+)\s+(&)/ const \1 \2/g` und klicken Sie auf OK. Das `g` am Ende des regulären Ausdrucks bewirkt, dass der reguläre Ausdruck jedesmal neu kompiliert wird, um die Referenz zu sichern.

  Ausgabe: `void MyClass::DoStringOps( const String &foo, const String &bar String *p, const int &a, const int &b )`

  Erledigt! Was passierte hier? Es wurde nach Leerzeichen (`\s+`) gefolgt von einem oder mehreren alphanumerischen Zeichen (`\w+`) gefolgt von einem oder mehreren Leerzeichen (`\s+`) gefolgt von einem Ampersand (&) gesucht und dabei der alphanumerische Abschnitt und das Ampersand (&) gesichert, um diese beim Ersetzen wiederzuverwenden. Dann haben wir den übereinstimmenden Teil der Zeile ersetzt durch ein Leerzeichen gefolgt von const gefolgt von einem Leerzeichen gefolgt vom gesicherten Abschnitt (`\1`) gefolgt von einem Leerzeichen gefolgt vom gesicherten Ampersand (&) (`\2`).

  In einigen Fällen war war der gesicherte Abschnitt String, in einigen int, so dass das Benutzen der Wortklasse `\w` und des `+`-Zeichens zum Angeben von ein oder mehrere sich als wertvoll erwies.

#### Befehle zur Bewegung im Dokument

    gotoINT line

- Dieser Befehl setzt den Cursor auf die angegebene Zeile.

    findSuchtext

- Dieser Befehl setzt den Cursor auf das erste Auftreten des `Suchtext` entsprechend der Einstellungen. Weitere Fundstellen werden durch Bearbeiten Weitersuchen oder Drücken des Tastenkürzels (Standard ist F3) gefunden.

  Der Befehl `find` kann durch das Anhängen eines Doppelpunktes und eines oder mehrerer Buchstaben in der Form `find:options pattern` ergänzt werden. Die folgenden Einstellungen sind verfügbar:

  `b`

- Rückwärts suchen.

`c`

- Suchen ab Cursorposition.

`e`

- Suchen nur in markiertem Text.

`r`

- Suche nach einem regulären Ausdruck. Wenn diese Einstellung verwendet wird, können Sie `\N` im replacement string verwenden, die Anzahl, wie oft der Suchtext gefunden wurde, wird dann in den replacement string eingefügt.

`s`

- Suche unter Berücksichtigung von Groß- und Kleinschreibung.

`w`

- Nur ganze Wörter erfüllen die Suchbedingung.

    ifindsuchtext

- Dieser Befehl sucht schon beim Eingeben nach dem Suchtext. Sie können auch hier die Suche durch Anhängen eines Doppelpunktes und eines oder mehrerer Buchstaben in ihrem Verhalten anpassen. Die Eingabe muss dann in der Form: `ifind:options suchtext` erfolgen. Die folgenden Einstellungen stehen zur Verfügung:

  `b`

- Rückwärts suchen.

`r`

- Suche nach einem regulären Ausdruck.

`s`

- Suche unter Berücksichtigung von Groß- und Kleinschreibung.

`c`

- Suchen ab Cursorposition.

## Benutzen von Code-Ausblendung

Code-Ausblendung dient zum Verstecken von Teilen des Dokuments im Editor, so dass große Dokumente einfacher zu lesen sind. In &kate; werden die ausblendbaren Abschnitte unter Zugrundelegung der Hervorhebungsregeln ermittelt und demzufolge sind Code-Ausblendungen nur in manchen Formaten verfügbar. Dies sind besonders Quelltexte in Programmiersprachen, XML und Ähnliches. Die meisten Hervorhebungsregeln, die Code-Ausblendungen bereitstellen, lassen auch die manuelle Festlegung von ausblendbaren Abschnitten zu, üblicherweise werden dazu die Schlüsselwörter `BEGIN` und `END` benutzt.

Um die Funktion Code-Ausblendung zu benutzen, wählen Sie im Menü Ansicht Markierungen für Code-Ausblendungen anzeigen. Es wird dann am linken Rand des Editorfensters ein grauer Rand eingeblendet, der eine grafische Darstellung der ausblendbaren Abschnitte enthält. In diesen Markierungen sind Symbole enthalten, die die möglichen Operationen anzeigen. Wenn zum Beispiel ein - angezeigt wird, kann dieser Abschnitt ausgeblendet werden, ein + dagegen heisst, dass hier ein Abschnitt ausgeblendet wurde. Dieser kann durch Klicken auf das +-Zeichen eingeblendet werden.

Vier Befehle sind im Menü enthalten, die die Code-Ausblendung beeinflussen, sehen Sie in der Menü-Dokumentation für weitere Einzelheiten nach.

Wenn Sie keine Code-Ausblendung benutzen wollen, dann können Sie die Funktion Markierung für Code-Ausblendungen anzeigen, falls vorhanden auf der Seite Erscheinungsbild in den Einstellungen von &kate; komplett ausschalten.

## Scripting mit Javascript in der Editorkomponente

### Einführung

Beginnend mit Version 2.5 unterstützt der Editor von &kate; das Scripting mit ECMA-Scripten, auch als JavaScript bekannt.

Scripts können nur durch die eingebaute Befehlszeile benutzt werden. Folgende Voraussetzungen müssen erfüllt sein: das Script muss sich in einem Ordner befinden, in dem &kate; es finden kann, zusammen mit der eventuell vorhandenen .desktop-Datei, die die Eigenschaften definiert. Die gültigen Ordner sind mit `katepart/scripts` in den &kde; Datenordnern bezeichnet. Sie können herausfinden, welche Ordner dies sind, indem Sie den Befehl `kde-config `--path` `data`` eingeben. Normalerweise existiert mindestens ein Systemordner und ein persönlicher Datenordner. Scripts, die sich im Systemordner befinden, sind für alle Nutzer verfügbar, die im Persönlichen Ordner nur für den Eigentümer des Ordners.

Diese Funktionen sind noch im experimentellen Stadium und werden sich sicher während der Weiterentwicklung in der Zukunft noch ändern.

Wir wissen, dass es Sie stört, dass Sie Ihre Scripts nicht zum Menü hinzufügen können und dass Sie den Scripts keine Kurzbefehle zuordnen können. Dies wird sicher in der Zukunft möglich sein.

Es ist außerdem noch nicht möglich, den Scripten Argumente zu übergeben. Auch diese Funktion wird sicher in der Zukunft hinzugefügt werden.

### Die Kate JavaScript API

Hier wird der gesamte Befehlssatz von Funktionen und Eigenschaften aufgelistet, die in den `document` und `view`-Objekten verfügbar sind. Zusätzlich können Sie natürlich alle Standardobjekte wie `Math`, `String` `Regex` und so weiter benutzen.

Wenn ein Script läuft, ist das Objekt `document` das aktuelle Dokument und das Objekt `view` ist die aktuelle Ansicht.

Die Argumenttypen sind derzeit in JavaScript nicht benutzt, diese dienen nur dazu, deutlich zu machen, welche Art Wert die Funktionen erwarten.

### Globale Funktionen

`debug( ``string``) [function]`

- ### Parameter

  - `string` Die auszugebende Zeichenkette

  Gibt die Zeichenkette auf die Standardausgabe STDERR unter Benutzung der Funktion `kdDebug()` aus. Es wird ein besonderer Bereich für die Ausgabe benutzt, die den Vorspann `Kate (KJS Scripts):` erhält.

### Die `document`-API

`document.attribute( ``line`` , ``column`` ); [function]`

- ### Parameter

  - `uint line` Die Zeilennummer der Position, deren Eigenschaften gefunden werden sollen.

  - `uint column` Die Spaltennummer der Position, deren Eigenschaften gefunden werden sollen.

  Gibt die numerische ID der Eigenschaft des Textes an der Position [`line`,`column`] zurück. Die Eigenschaft enthält das Erscheinungsbild oder den Stil des Textes und wird auch dazu benutzt, die Hervorhebungssyntax für einen bestimmten Teil des Textes in gemischten Formaten wie HTML oder PHP zu berechnen.

`document.canBreakAt( `Char c`, `uint attribute` ); [function]`

- ### Parameter

  - `c` Das zu testende Zeichen

  - `attribute` Die Eigenschaften an der Position des `c`.

  Gibt zurück, ob die Zeile am Zeichen c mit der Eigenschaft `attribute` umgebrochen werden darf. Das Ergebnis ergibt sich aus der Abfrage, für welche Zeichen die Hervorhebungseigenschaft das Umbrechen zuläßt.

`document.canComment( `uint start_attribute`, `uint end_attribute` ); [function]`

- ### Parameter

  - `start_attribute` Die Eigenschaft am Beginn eines Bereiches, die diesen als Kommentar kennzeichnet.

  - `end_attribute` Die Eigenschaft am Ende eines Bereiches, die diesen als Kommentar kennzeichnet.

  Gibt zurück, ob die Anfangseigenschaft (start_attribute) und die Endeigenschaft (end_attribute) zum gleichen Hervorhebungssystem gehören. Wenn das der Fall ist, dann ist das in Ordnung.

  #### Benutzen von canComment

      if ( document.canComment( document.attribute(1,0), document.attribute(5,0) ) ) {
          // 1,0 and 5,0 belongs to the same syntax highlighting system
      }

`document.clear(); [function]`

- Löscht den Inhalt des aktuellen Dokuments.

`document.commentStart( `uint attribute` ); [function]`

- ### Parameter

  - `attribute` Die Eigenschaft des Textes, für den die Zeichenkette für commentStart abgefragt werden soll.

  Gibt die Zeichenkette zurück, die den Anfang eines mehrzeiligen Kommentars kennzeichnet, oder eine leere Zeichenkette, falls mehrzeilige Kommentare im Format für diesen Text nicht unterstützt werden.

`document.commentMarker( `uint attribute` ); [function]`

- ### Parameter

  - `attribute` Die Eigenschaft des Textes, für den die Zeichenkette für commentMarker abgefragt werden soll.

  Gibt die Zeichenkette zurück, die den Rest einer Zeile als Kommentar kennzeichnet, oder eine leere Zeichenkette, falls einzeilige Kommentare im Format für diesen Text nicht unterstützt werden.

`document.commentEnd( `uint attribute` ); [function]`

- ### Parameter

  - `attribute` Die Eigenschaft des Textes, für den die Zeichenkette für commentEnd abgefragt werden soll.

  Gibt die Zeichenkette zurück, die das Ende eines mehrzeiligen Kommentars kennzeichnet, oder eine leere Zeichenkette, falls mehrzeilige Kommentare im Format für diesen Text nicht unterstützt werden.

`document.editBegin(); [function]`

- Beginnt eine Editiergruppe. Alle Aktionen, die bis zum Aufruf von editEnd() werden zu einer Rückgängig-Aktion zusammengefasst.

`document.editEnd(); [function]`

- Beendet eine Editiergruppe.

`document.highlightMode; [property:read only]`

- Der Name des für das Dokument benutzten Hervorhebungsmodus, wie zum Beispiel JavaScript oder C++. Wenn kein Hervorhebungsmodus gesetzt ist, wird `None` zurückgegeben. Beachten Sie, dass Sie den englischen Namen, benutzen müssen, wenn der übersetzte Name anders als der englische ist.

`document.indentMode; [property:read only]`

- Der Name des Einrückungsmodus, wie zum Beispiel `normal` oder `cstyle`. Beachten Sie, dass der Wert `none` ist, wenn kein Einrückungsmodus gesetzt wurde.

`document.indentWidth; [property:read only]`

- Setzt die Einrückungsweite auf für das Dokument. Dieser Wert wird nur benutzt, wenn Sie Leerzeichen zum Einrücken verwenden.

`document.insertLine( `uint line`, `string text` ); [function]`

- ### Parameter

  - `line` Zeilennummer des Dokuments

  - `text` einzusetzender Text

  Fügt eine neue Zeile mit dem Text `text` in die Zeile `line` ein.

`document.insertText( `uint line`, `uint column`, `string text` ); [function]`

- ### Parameter

  - `line` Zeilennummer

  - `column` Spaltennummer

  - `text` einzusetzender Text

  Fügt den Text `text` in die Zeile `line` und Spalte `column` ein.

document.length(); [function]

- Gibt die Größe des Dokumentes in Bytes zurück.

`document.lines(); [function]`

- Gibt die Zeilenanzahl des Dokumentes zurück.

document.mixedIndent; [property:read only]

- Eine Boolescher Wert, der angibt, ob für das Dokument der gemischte Modus im Emacs-Stil bei der Einrückung mit Leerzeichen benutzt wird. Wenn ja, dann werden Leerzeichen und Tabulatoren optimal verteilt, wie diese auch der Editor Emacs benutzt.

document.removeLine( `uint line` ); [function]

- ### Parameter

  - `line` Zeilennummer

  Löscht die Zeile `line`

`document.removeText( `uint startLine`, `uint startColumn`, `uint endLine`, `uint endColumn` ); [function]`

- ### Parameter

  - `startLine` gibt die Zeilennummer an, an der begonnen werden soll

  - `startColumn` gibt die Spaltennummer an, an der begonnen werden soll

  - `endLine` gibt die Zeilennummer an, an der die Funktion beendet werden soll

  - `endColumn` gibt die Spaltennummer an, an der die Funktion beendet werden soll

  Entfernt den Text im Bereich von Zeile `startLine` und Spalte `startColumn` bis zur Zeile `endLine` und Spalte `endColumn`.

`document.setText( `string text` ); [function]`

- ### Parameter

  - `text` Dokumententext

  Setzt den Inhalt des gesamten Dokumentes `text`.

`document.spaceIndent; [property:read only]`

- Eine Boolescher Wert, der angibt, ob für das Dokument Leerzeichen als Einrückung benutzt werden. Wenn ja, dann werden indentWidth Leerzeichen je Ebene benutzt, wenn nicht, dann wird ein Tabulatorzeichen je Ebene benutzt.

`document.textFull(); [function]`

- Gibt den gesamten Text des Dokumentes zurück. Wenn der Text mehrere Zeilen enthält, ist das Zeilenendezeichen `\n`.

`document.textLine( uint line ); [function]`

- ### Parameter

  - `line` Zeile

  Gibt den Text der Zeile `line` zurück.

`document.textRange( `uint startLine`, `uint startColumn`, `uint endLine`, `uint endColumn` ); [function]`

- ### Parameter

  - `startLine` gibt die Zeilennummer an, an der begonnen werden soll

  - `startColumn` gibt die Spaltennummer an, an der begonnen werden soll

  - `endLine` gibt die Zeilennummer an, an der die Funktion beendet werden soll

  - `endColumn` gibt die Spaltennummer an, an der die Funktion beendet werden soll

  Gibt den Text des angegebenen Bereiches zurück. Wenn der Text mehrere Zeilen enthält, ist das Zeilenendezeichen `\n`.

### Die `view` API

`view.clearSelection(); [function]`

- Hebt die Auswahl für den gesamten Text auf.

`view.cursorColumn(); [function]`

- Gibt die aktuelle Spalte des Cursors zurück. (Tabulatoren werden in einzelne Spalten umgerechnet)

`view.cursorColumnReal(); [function]`

- Gibt die reale aktuelle Spalte des Cursors zurück. (Tabulatoren als je eine Spalte gerechnet)

`view.cursorLine(); [function]`

- Gibt die aktuelle Zeile des Cursors zurück.

`view.hasSelection(); [function]`

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

`view.removeSelectedText(); [function]`

- Entfernt den ausgewählten Text, wenn die Ansicht eine Auswahl hat.

`view.selectAll(); [function]`

- Wählt den gesamten Text aus.

`view.selection(); [function]`

- Gibt den ausgewählten Text zurück. Wenn die Auswahl mehrere Zeilen enthält, ist das Zeilenendezeichen `\n`.

`view.selectionEndColumn; [property:read only]`

- Gibt die Spalte des Endes der Auswahl zurück.

`view.selectionEndLine; [property:read only]`

- Gibt die Zeilennummer der Zeile zurück in der die Auswahl endet.

`view.selectionStartColumn; [property:read only]`

- Gibt die Spaltennummer der Spalte zurück in der die Auswahl beginnt.

`view.selectionStartLine; [property:read only]`

- Gibt die Zeilennummer der Zeile zurück in der die Auswahl beginnt.

`view.setCursorPosition( `uint line`, `uint column` ); [function]`

- ### Parameter

  - `line` Gibt die Zeile für den Cursor an.

  - `column` Gibt die Spalte für den Cursor an.

  Setzt den Eingabecursor auf die Position [`line`, `col`] in der aktuellen Ansicht. Die Cursorposition wird nach der Ansicht gesetzt, das heisst, das das Tabulatorzeichen bis zu `tabwidth` Spalten zählt, abhängig von dessen Position innerhalb der Zeile. Die Cursorposition wird sichtbar gemacht. Beide die Zeilen und die Spaltenposition zählen von 0 beginnend.

`view.setCursorPositionReal( `uint line`, `uint column` ); [function]`

- ### Parameter

  - `line` Gibt die Zeile für den Cursor an.

  - `column` Gibt die Spalte für den Cursor an.

  Setzt den Eingabecursor auf die Position [`line`, `col`] in der aktuellen Ansicht. Die Cursorposition wird nach der Zeicheanzahl gesetzt, das heisst, das das Tabulatorzeichen ein Zeichen zählt, unabhängig von dessen Position innerhalb der Zeile. Die Cursorposition wird sichtbar gemacht. Beide die Zeilen und die Spaltenposition zählen von 0 beginnend.

`view.setSelection( `uint startLine`, `uint startColumn`, `uint endLine`, `uint endColumn` ); [function]`

- ### Parameter

  - `startLine` gibt die Zeilennummer an, an der begonnen werden soll

  - `startColumn` gibt die Spaltennummer an, an der begonnen werden soll

  - `endLine` gibt die Zeilennummer an, an der die Funktion beendet werden soll

  - `endColumn` gibt die Spaltennummer an, an der die Funktion beendet werden soll

  Setzt eine Auswahl beginnend an Zeile `startLine` und Spalte `startColumn` bis zur Zeile `endLine` und Spalte `endColumn`.

#### Ein Beispielscript

Als Beispiel soll hier ein kleines Script erstellt werden, das die Auswahl in Großbuchstaben umwandelt. Es ist einleuchtend, dass zuerst geprüft werden muss, ob eine Auswahl existiert. Wenn dies der Fall ist, dann wird der Text geholt, in Großbuchstaben umgewandelt und die Auswahl mit dem Ergebnis ersetzt. Eine Umsetzung könnte wie folgt aussehen:

    if ( view.hasSelection() )
    {
      // uppercase selection
      column = view.selectionStartColumn;
      line = view.selectionStartLine;

      selection = view.selection().toUpperCase();

      document.editBegin();
      view.removeSelectedText();
      document.insertText( line, column, selection );
      document.editEnd();
    }

Um alle Aktionen zu einer Editiergruppe zusammenzufassen, so dass diese mit einem einzelnen Rückgängig aufgehoben werden können, werden die Zeilen

    view.removeSelectedText()

und

    document.insertText()

mit

    document.editBegin()

und

    document.editEnd()

eingeschlossen.

#### Eine Beispiel für eine `.desktop`-Datei

Hier ist ein Beispiel für eine .desktop-Datei, die zu diesem Script gehört.

    # Example of a .desktop file
    [Desktop Entry]
    Encoding=UTF-8
    Name=Kate Part JavaScript Uppercase
    Comment=Script to uppercase the selection
    X-Kate-Command=uppercase-selection
    X-Kate-Help=<p>Usage: <code>uppercase-selection</code></p>

Wie sie sehen, können Sie hier die Kodierung, den Namen, einen Kommentar, einen Hilfetext unter Benutzung von X-Kate-Help und den Befehlszeilennamen unter Benutzung von X-Kate-Command festlegen. Die Einträge unter Name, Kommentar und X-Kate-Help werden automatisch von den KDE-Übersetzerteams in andere Sprachen übersetzt, wenn die Dateien im SVN-Repository KDE sind.

#### Zusammensetzen

&kate; durchsucht die Scriptordner (sehen Sie oben für weitere Informationen nach) nach Dateien mit der Endung `.js`. Für jede gefundene Datei wird geprüft, ob es eine dazugehörige Datei mit der Endung `.desktop` gibt, &zb; für uppercase.js die Datei uppercase.desktop.

Wenn die zugehörige `.desktop`-Datei nicht gefunden wird, dann wird das Script in der Befehlszeile von Katepart ohne die Endung .js registriert, in unserem besispiel wäre das `uppercase`. Wenn Ihnen der Befehlsname ausreicht und Sie die zusätzlichen Möglichkeiten, die eine `.desktop`-Datei bietet, nicht brauchen, dann brauchen Sie keine `.desktop`-Datei.

Wenn eine `.desktop`-Datei existiert, dann liest Katepart den Namen, unter dem das Script vom Eintrag X-Kate-Command in der .desktop-Datei registriert wird, zum Beispiel X-Kate-Command=uppercase-selection.