<!-- auto-generate scripting documentation (kwrite-devel@kde.org Re: [kate] doc/kate: document most of the new scripts in 4.10) -->
<chapter id="dev">
<chapterinfo>
<authorgroup>
<author
>&TC.Hollingsworth; &TC.Hollingsworth.mail;</author>
<othercredit role="translator"
> <firstname
>Thomas</firstname
> <surname
>Diehl</surname
> <affiliation
> <address
><email
>thd@kde.org</email
></address
> </affiliation
> <contrib
>GUI-Übersetzung</contrib
></othercredit
> <othercredit role="translator"
> <firstname
>Matthias</firstname
><surname
>Schulz</surname
> <affiliation
> <address
><email
>matthias.schulz@kdemail.net</email
></address
> </affiliation
> <contrib
>Deutsche Übersetzung</contrib
></othercredit
>
</authorgroup>
</chapterinfo>
<title
>&katepart; erweitern</title>
<sect1 id="dev-intro">
<title
>Einführung</title>
<para
>Wie jeder gute Texteditor bietet auch &katepart; verschiedene Möglichkeiten für Erweiterungen. Sie können Skripte in <link linkend="dev-scripting"
>&javascript;</link
> schreiben, um Funktionen zu erweitern. Wenn Sie dann &katepart; erweitert haben, <ulink url="https://kate-editor.org/join-us/"
>laden wir Sie ein</ulink
>, Ihre Verbesserungen mit der ganzen Welt zu teilen.</para>
</sect1>
<sect1 id="highlight">
<title
>Arbeiten mit Syntaxhervorhebungen</title>
<sect2 id="highlight-overview">
<title
>Überblick</title>
<para
>Syntaxhervorhebungen bewirken, dass der Editor den Text automatisch in verschiedenen Farben und Schriftstilen anzeigt, abhängig von der Funktion der Zeichenfolge in Beziehung zum Zweck des Dokuments. Zum Beispiel können in Quelltext Kontrollbefehle fett dargestellt werden, während Daten und Kommentare andere Farben als der Rest des Textes bekommen. Dies verbessert die Lesbarkeit des Textes erheblich und verhilft damit dem Autor zu mehr Effizienz und Produktivität.</para>
<mediaobject>
<imageobject
><imagedata format="PNG" fileref="highlighted.png"/></imageobject>
<textobject
><phrase
>Eine C++-Funktion, mit Hervorhebungen angezeigt.</phrase
></textobject>
<caption
><para
>Eine C++-Funktion, mit Hervorhebungen angezeigt.</para>
</caption>
</mediaobject>
<mediaobject>
<imageobject
><imagedata format="PNG" fileref="unhighlighted.png"/></imageobject>
<textobject
><phrase
>Dieselbe C++-Funktion, ohne Hervorhebungen.</phrase
></textobject>
<caption
><para
>Dieselbe C++-Funktion, ohne Hervorhebungen.</para
></caption>
</mediaobject>
<para
>Welche der beiden ist einfacher zu lesen?</para>
<para
>&kappname; enthält ein flexibles, konfigurierbares und leistungsfähiges System für Syntaxhervorhebungen, und die Standarddistribution enthält bereits Definitionen für eine Anzahl von Programmiersprachen, Markup- und Skriptsprachen sowie andere Textformaten. Außerdem können Sie eigene Definitionen in einfachen &XML;-Dateien erstellen.</para>
<para
>&kappname; erkennt auf Basis des &MIME;-Typs, der Dateiendung oder des Inhalts des Dokuments bereits beim Öffnen des Dokuments automatisch die richtigen Regeln für die Syntaxhervorhebungen. Wenn die automatische Auswahl nicht die richtigen Regeln ausgewählt hat, können Sie dies manuell korrigieren (<menuchoice
><guimenu
>Extras</guimenu
> <guisubmenu
>Hervorhebung</guisubmenu
></menuchoice
>).</para>
<para
>Die Schriftstile und Farben, die von jeder Syntaxhervorhebungsdefinition benutzt werden, können auf der Seite <link linkend="prefcolors-highlighting-text-styles"
>Hervorhebungs-Schriftarten</link
> des <link linkend="config-dialog"
>Einrichtungsdialogs</link
> festgelegt werden, die Einrichtung der &MIME;-Typen und Dateierweiterung, auf die diese angewendet werden, ist auf der Seite <link linkend="pref-open-save-modes-filetypes"
>Dateitypen</link
> möglich.</para>
<note>
<para
>Syntaxhervorhebungen sind dazu gedacht die Lesbarkeit von Text zu verbessern, aber nicht dazu geeignet die Richtigkeit des Quelltextes zu überprüfen. Die Erstellung der Regeln für die Hervorhebungen ist kompliziert, abhängig davon, welches Format Sie benutzen. In manchen Fällen sind die Autoren der Regeln stolz, wenn 98 % des Textes korrekt hervorgehoben werden, meistens jedoch sehen Sie die nicht korrekten 2 % nur bei seltenen Konstruktionen.</para>
</note>
</sect2>
<sect2 id="katehighlight-system">
<title
>Das &kappname; Syntaxhervorhebungssystem</title>
<para
>Dieser Abschnitt behandelt die Mechanismen des &kappname; Syntax-Hervorhebungssystems genauer. Wenn Sie selbst Definitionen erstellen oder verändern möchten, sollten Sie diesen genau lesen.</para>
<sect3 id="katehighlight-howitworks">
<title
>Wie es funktioniert</title>
<para
>Immer, wenn Sie ein Dokument öffnen, ist eines der ersten Dinge, die &kappname; macht, festzustellen, welche Syntaxdefinition für dieses Dokument benutzt werden soll. Während Sie den Text lesen und neuen Text eingeben, analysiert das Syntaxhervorhebungssystem den Text anhand der Regeln in der Syntaxdefinition und markiert ihn dementsprechend. </para>
<para
>Wenn Sie Text eingeben, wird der neue Text sofort analysiert und markiert.</para>
<para
>Die Syntaxdefinitionen, die in &XML; benutzt werden, sind &XML;-Dateien, die Folgendes enthalten <itemizedlist>
<listitem
><para
>Regeln für das Erkennen von Text, organisiert in Kontextblöcken</para
></listitem>
<listitem
><para
>Listen mit Schlüsselworten</para
></listitem>
<listitem
><para
>Stildefinitionen</para
></listitem>
</itemizedlist>
</para>
<para
>Beim Analysieren von Text werden die Erkennungsregeln in der Reihenfolge, in der sie definiert wurden, überprüft und wenn der Anfang des aktuellen Textes mit einer Definition übereinstimmt, wird der zugehörige Kontext benutzt. Der nächste Startpunkt wird nach dem Ende des erkannten Bereichs gesetzt und von dort aus wird eine neue Schleife für die Regeln mit dem Kontext der gerade gefundenen Regel gestartet.</para>
</sect3>
<sect3 id="highlight-system-rules">
<title
>Regeln</title>
<para
>Die Erkennungsregeln sind das Herzstück des Syntaxhervorhebungssystems. Eine Regel besteht aus einer Zeichenfolge, einem Zeichen oder einem <link linkend="regular-expressions"
>regulären Ausdruck</link
>. Mit diesen wird der zu analysierende Text verglichen. Sie enthalten Informationen, welche Darstellung für das erkannte Stück Text verwendet werden soll und ob entweder zu einem explizit angegebenem Kontext oder zum vorher vom Text benutzten Kontext gewechselt werden soll.</para>
<para
>Die Regeln sind in Kontextgruppen organisiert. Eine Kontextgruppe wird für die grundlegenden Textkonzepte innerhalb des Formates benutzt, ⪚ für Textteile in Anführungszeichen oder Kommentarblöcke in Programmquelltext. Dadurch wird sichergestellt, dass sich das Syntaxhervorhebungssystem nicht unnötig durch alle Regeln hindurch arbeiten muss und dass einige Zeichenfolgen im Text abhängig vom aktuellen Kontext unterschiedlich behandelt werden können. </para>
<para
>Kontexte können dynamisch generiert werden, um das Benutzen von Daten in Regeln zu erlauben, die nur auf diese Instanz zutreffen.</para>
</sect3>
<sect3 id="highlight-context-styles-keywords">
<title
>Kontextstile und Schlüsselwörter</title>
<para
>In einigen Programmiersprachen werden Ganze Zahlen durch den Compiler (das Programm, das den Quelltext in ein ausführbares Programm übersetzt) anders behandelt als Gleitkommazahlen, und es gibt Zeichen, die eine spezielle Bedeutung innerhalb einer in Anführungszeichen eingeschlossenen Zeichenfolge haben. In solchen Fällen ist es sinnvoll, diese unterschiedlich darzustellen, sodass sie beim Lesen einfach vom umgebenden Text zu unterscheiden sind. Auch wenn diese keine speziellen Kontexte repräsentieren, können sie durch das Syntaxhervorhebungssystem erkannt und anders dargestellt werden.</para>
<para
>Eine Syntaxdefinition kann so viele verschiedene Stile beinhalten, wie für das Format notwendig sind.</para>
<para
>In vielen Formaten gibt es Listen mit Wörtern, die einem speziellen Konzept zugehörig sind. In Programmiersprachen sind ⪚ die Kontrollanweisungen ein Konzept, die Datentypen ein anderes und die eingebauten Funktionen ein drittes. Das Syntaxhervorhebungssystem von &kappname; kann benutzt werden, um solche Wörter anhand der Listen zu finden und zur Hervorhebung der Konzepte im Text zu markieren.</para>
</sect3>
<sect3 id="kate-highlight-system-default-styles">
<title
>Standardstile</title>
<para
>Wenn Sie eine C++-Quelltextdatei, eine &Java;-Quelltextdatei und eine &HTML;-Datei in &kappname; öffnen, sehen Sie dass auch in unterschiedlichen Formaten und damit unterschiedlichen Worten, die spezielle Behandlung bekommen, die benutzten Farben dieselben sind. Der Grund dafür ist, dass &kappname; vordefinierte Standardstile benutzt, die von den individuellen Syntaxdefinitionen verwendet werden.</para>
<para
>Dadurch wird die Erkennung von ähnlichen Konzepten in verschiedenen Textformaten einfach. Kommentare ⪚ gibt es in fast allen Programmiersprachen, Skripten und Markup-Sprachen; diese werden in allen Sprachen gleich dargestellt, sodass Sie sich auf die Arbeit konzentrieren können und nicht über den Zweck einzelner Einträge nachdenken müssen.</para>
<tip>
<para
>Alle Stile in einer Syntaxdefinition nutzen einen der Standardstile. Einige wenige Syntaxdefinitionen nutzen mehr Stile als Standardstile vorhanden sind. Wenn Sie ein Format sehr oft benutzen, kann es die Arbeit wert sein, den Einrichtungsdialog zu starten und nachzusehen, ob mehrere Konzepte dieselben Stile benutzen. In der Programmiersprache Perl ⪚ gibt es zwei Typen von Zeichenfolgen, sodass Sie die Hervorhebung durch eine etwas andere Darstellung des zweiten Typs verbessern können. Alle <link linkend="kate-highlight-default-styles"
>verfügbaren Standardstile</link
>, werden weiter unten erklärt.</para>
</tip>
</sect3>
</sect2>
<sect2 id="katehighlight-xml-format">
<title
>Die Hervorhebungsdefinition für das &XML; Format</title>
<sect3>
<title
>Überblick</title>
<para
>&kappname; verwendet die Syntaxhervorhebungs-Bibliothek von &kde-frameworks;. Die in &kappname; enthaltenen Standard-&XML;-Hervorhebungsdateien werden in die Syntaxhervorhebungs-Bibliothek einkompiliert. </para>
<para
>Dieser Abschnitt ist ein Überblick über die Hervorhebungsdefinition für das &XML;-Format.. Es beschreibt die Hauptbestandteile, deren Bedeutung und Verwendung. Im nächsten Kapitel werden die Erkennungsregeln detailliert beschrieben.</para>
<para
>Die formale Definition <acronym
>XSD</acronym
> finden Sie im <ulink url="https://commits.kde.org/syntax-highlighting?path=data/schema"
>Syntax-Highlighting-Repository</ulink
> in der Datei <filename
>language.xsd</filename
>. </para>
<para
>Eigene <filename class="extension"
>.xml</filename
>-Dateien mit Definitionen zur Syntaxhervorhebung sind im Ordner <filename class="directory"
>org.kde.syntax-highlighting/syntax/</filename
> in Ihrem persönlichen Ordner. Den Pfad zu diesem Ordner finden Sie mit <userinput
><command
>qtpaths</command
><option
>--paths GenericDataLocation</option
></userinput
>. Normalerweise sind dies <filename class="directory"
><envar
>$HOME</envar
>/.local/share/</filename
> und <filename class="directory"
>/usr/share/</filename
>. </para>
<para
>Bei Flatpak- und Snap-Paketen funktioniert der obige Ordner nicht, da der Speicherort der Daten für jede Anwendung unterschiedlich ist. In einer Flatpak-Anwendung ist der Speicherort der benutzerdefinierten &XML;-Dateien normalerweise <filename class="directory"
><envar
>$HOME</envar
>/.var/app/<replaceable
>flatpak-package-name</replaceable
>/data/org.kde.syntax-highlighting/syntax/</filename
> und in einer Snap-Anwendung ist dieser Ort <filename class="directory"
><envar
>$HOME</envar
>/snap/<replaceable
>snap-package-name</replaceable
>/current/.local/share/org.kde.syntax-highlighting/syntax/</filename
>. </para>
<para
>Auf &Windows;-Systemen finden Sie diese Dateien unter <filename
>%USERPROFILE%\AppData\Local\org.kde.syntax-highlighting\syntax</filename
>. Dabei ist <replaceable
>%USERPROFILE%</replaceable
> normalerweise <filename
>C:\Users\<replaceable
>user</replaceable
></filename
>.</para>
<para
>Zusammenfassend lässt sich sagen, dass bei den meisten Einrichtungen der Ordner der benutzerdefinierten &XML;-Dateien wie folgt aussieht </para>
<informaltable>
<tgroup cols="2">
<tbody>
<row>
<entry
>Für lokale Benutzer</entry>
<entry
><filename class="directory"
><envar
>$HOME</envar
>/.local/share/org.kde.syntax-highlighting/syntax/</filename
></entry>
</row>
<row>
<entry
>Für alle Benutzer</entry>
<entry
><filename class="directory"
>/usr/share/org.kde.syntax-highlighting/syntax/</filename
></entry>
</row>
<row>
<entry
>Für Flatpak-Pakete</entry>
<entry
><filename class="directory"
><envar
>$HOME</envar
>/.var/app/<replaceable
>flatpak-package-name</replaceable
>/data/org.kde.syntax-highlighting/syntax/</filename
></entry>
</row>
<row>
<entry
>Für Snap-Pakete</entry>
<entry
><filename class="directory"
><envar
>$HOME</envar
>/snap/<replaceable
>snap-package-name</replaceable
>/current/.local/share/org.kde.syntax-highlighting/syntax/</filename
></entry>
</row>
<row>
<entry
>Unter &Windows;</entry>
<entry
><filename
>%USERPROFILE%\AppData\Local\org.kde.syntax-highlighting\syntax</filename
></entry>
</row>
</tbody>
</tgroup>
</informaltable>
<para
>Wenn mehrere Dateien für dieselbe Sprache existieren, wird die Datei mit der höchsten <userinput
>version</userinput
>-Attribut im <userinput
>language</userinput
>-Element geladen.</para>
<variablelist>
<title
>Hauptbestandteile der &kappname;-Hervorhebungsdefinitionen</title>
<varlistentry>
<term
>Eine Hervorhebungsdefinitionsdatei enthält einen Kopf mit der &XML;-Version:</term>
<listitem>
<programlisting
><?xml version="1.0" encoding="UTF-8"?>
</programlisting>
</listitem>
</varlistentry>
<varlistentry>
<term
>Die Wurzel der Definitionsdatei ist das Element <userinput
>language</userinput
>. Verfügbare Eigenschaften sind:</term>
<listitem>
<para
>Notwendige Eigenschaften:</para>
<para
><userinput
>name</userinput
> setzt den Namen der Sprache. Dieser erscheint nachher in Menüs und in Dialogen.</para>
<para
>Die Eigenschaft <userinput
>section</userinput
> definiert die Kategorie.</para>
<para
><userinput
>extensions</userinput
> definiert die Erweiterungen für Dateinamen wie ⪚ "*.cpp;*.h".</para>
<para
><userinput
>version</userinput
> gibt die aktuelle Revision der Definitionsdatei als ganze Zahl an. Bei jeder Änderung einer Hervorhebungs-Datei sollte diese Zahl vergrößert werden.</para>
<para
><userinput
>kateversion</userinput
> definiert die letzte unterstützte Version von &kappname;.</para>
<para
>Optionale Eigenschaften: </para>
<para
><userinput
>mimetype</userinput
> ordnet Dateien basierend auf deren &MIME;-Type zu.</para>
<para
><userinput
>casesensitive</userinput
> definiert, ob bei den Schlüsselwörtern Groß-/Kleinschreibung unterschieden wird oder nicht.</para>
<para
><userinput
>priority</userinput
> ist notwendig, wenn eine andere Hervorhebungsdefinitionsdatei die gleichen Dateinamenerweiterung benutzt. Die Definitionsdatei mit der höheren Priorität wird dann benutzt.</para>
<para
><userinput
>author</userinput
> enthält den Namen des Autors und dessen E-Mail-Adresse.</para>
<para
><userinput
>license</userinput
> enthält die Lizenz der Datei, normalerweise wird hier die MIT-Lizenz für neue Dateien benutzt.</para>
<para
><userinput
>style</userinput
> enthält die Programmiersprache, die mit der Definition zur Verfügung gestellt wird und wird durch das Einrückungsskript für die Eigenschaft <literal
>required-syntax-style</literal
> benutzt.</para>
<para
><userinput
>indenter</userinput
> definiert die als Standard verwendetet Einrückung. Verfügbare Einrückungen sind: <emphasis
>ada, normal, cstyle, cmake, haskell, latex, lilypond, lisp, lua, pascal, python, replicode, ruby</emphasis
> und <emphasis
>xml</emphasis
>.</para>
<para
><userinput
>hidden</userinput
> definiert, ob der Name in Menüs von &kappname; erscheinen soll.</para>
<para
>Die nächste Zeile könnte wie folgt aussehen:</para>
<programlisting
><language name="C++" version="1" kateversion="2.4" section="Sources" extensions="*.cpp;*.h" />
</programlisting>
</listitem>
</varlistentry>
<varlistentry>
<term
>Als nächstes kommt das Element <userinput
>highlighting</userinput
>, das das optionale Element <userinput
>list</userinput
> und die notwendigen Elemente <userinput
>contexts</userinput
> und <userinput
>itemDatas</userinput
> enthält.</term>
<listitem>
<para
><userinput
>list</userinput
>-Elemente enthalten eine Liste von Schlüsselwörtern. In diesem Fall sind die Schlüsselwörter <emphasis
>class</emphasis
> und <emphasis
>const</emphasis
>. Sie können so viele hinzufügen, wie Sie brauchen.</para>
<para
>Seit &kde-frameworks; 5.53 kann eine Liste Schlüsselwörter aus anderen Listen oder Sprachen bzw. Dateien enthalten. Dazu benutzen Sie das Element <userinput
>include</userinput
>. <userinput
>##</userinput
> wird auf die gleiche Art wie die Regel <userinput
>IncludeRules</userinput
> verwendet, um den Namen der Liste und der Sprachdefinition zu trennen. Dies ist nützlich, um doppelte Listen von Schlüsselwörtern zu vermeiden, wenn Sie Schlüsselwörter aus anderen Sprachen oder Dateien einschließen müssen. Die Liste <emphasis
>othername</emphasis
> zum Beispiel enthält das Schlüsselwort <emphasis
>str</emphasis
> und alle Schlüsselwörter der Liste <emphasis
>types</emphasis
> aus der Sprache <emphasis
>ISO C++</emphasis
>.</para>
<para
>Das Element <userinput
>contexts</userinput
> enthält alle Kontexte. Der erste Kontext ist Standard bei Start der Hervorhebungen. Es gibt zwei Regeln im Kontext <emphasis
>Normal Text</emphasis
>, die auf die Liste mit Schlüsselwörtern mit dem Namen <emphasis
>somename</emphasis
> und eine Regel, die Anführungszeichen entdeckt und zum Kontext <emphasis
>string</emphasis
> umschaltet. Weitere Informationen zu Regeln finden Sie im nächsten Kapitel.</para>
<para
>Der dritte Teil ist das Element <userinput
>itemDatas</userinput
>. Es enthält alle Farb- und Schriftartstile, die durch die Kontexte und Regeln benötigt werden. In diesem Beispiel werden <userinput
>itemData</userinput
>, <emphasis
>Normal Text</emphasis
>, <emphasis
>String</emphasis
> und <emphasis
>Keyword</emphasis
> benutzt. </para>
<programlisting
><highlighting>
<list name="somename">
<item>class</item>
<item>const</item>
</list>
<list name="othername">
<item>str</item>
<include>types##ISO C++</include>
</list>
<contexts>
<context attribute="Normal Text" lineEndContext="#pop" name="Normal Text" >
<keyword attribute="Keyword" context="#stay" String="somename" />
<keyword attribute="Keyword" context="#stay" String="othername" />
<DetectChar attribute="String" context="string" char="&quot;" />
</context>
<context attribute="String" lineEndContext="#stay" name="string" >
<DetectChar attribute="String" context="#pop" char="&quot;" />
</context>
</contexts>
<itemDatas>
<itemData name="Normal Text" defStyleNum="dsNormal" />
<itemData name="Keyword" defStyleNum="dsKeyword" />
<itemData name="String" defStyleNum="dsString" />
</itemDatas>
</highlighting>
</programlisting>
</listitem>
</varlistentry>
<varlistentry>
<term
>Der letzte Teil der Hervorhebungsdefinition ist der optionale Abschnitt <userinput
>general</userinput
>. Dieser kann Informationen über Schlüsselwörter, Quelltextausblendungen, Leerzeilen und Rechtschreibprüfung enthalten.</term>
<listitem>
<para
>Der Abschnitt <userinput
>comment</userinput
> definiert, mit welcher Zeichenfolge eine einzelne Kommentarzeile beginnt. Sie können außerdem mehrzeilige Kommentare definieren, indem Sie <emphasis
>multiLine</emphasis
> mit der zusätzlichen Eigenschaft <emphasis
>end</emphasis
> benutzen. Diese werden benutzt, wenn Sie das Tastaturkürzel für <emphasis
>Kommentar / Kommentar entfernen</emphasis
> drücken.</para>
<para
>Der Abschnitt <userinput
>keywords</userinput
> definiert, ob in den Schlüsselwortlisten nach Groß- und Kleinschreibung unterschieden wird oder nicht. Andere Eigenschaften werden später erläutert.</para>
<para
>Die anderen Abschnitte <userinput
>Quelltextausblendung</userinput
>, <userinput
>Leerzeilen</userinput
> und <userinput
>Rechtschreibprüfung</userinput
> sind normalerweise nicht nötig und werden später erklärt.</para>
<programlisting
><general>
<comments>
<comment name="singleLine" start="#"/>
<comment name="multiLine" start="###" end="###" region="CommentFolding"/>
</comments>
<keywords casesensitive="1"/>
<folding indentationsensitive="0"/>
<emptyLines>
<emptyLine regexpr="\s+"/>
<emptyLine regexpr="\s*#.*"/>
</emptyLines>
<spellchecking>
<encoding char="á" string="\'a"/>
<encoding char="à" string="\`a"/>
</spellchecking>
</general>
</language>
</programlisting>
</listitem>
</varlistentry>
</variablelist>
</sect3>
<sect3 id="kate-highlight-sections">
<title
>Die Abschnitte im Einzelnen</title>
<para
>Dieser Teil beschreibt alle verfügbaren Eigenschaften für Kontexte, itemDatas, Schlüsselwörter, Kommentare, Quelltextausblendungen und Einrückungen. </para>
<variablelist>
<varlistentry>
<term
>Das Element <userinput
>context</userinput
> gehört in die Gruppe <userinput
>contexts</userinput
>. Ein Kontext selbst definiert spezielle Regeln, wie zum Beispiel, was geschehen soll, wenn das Hervorhebungssystem ein Zeilenende erreicht. Die verfügbaren Eigenschaften sind:</term>
<listitem>
<para
>Der Kontextname <userinput
>name</userinput
>. Regeln benutzen diesen Namen, um festzulegen, zu welchem Kontext umgeschaltet wird, wenn die Regel zutrifft.</para>
<para
>Der Kontext <userinput
>lineEndContext</userinput
> definiert den Kontext, zu dem das Hervorhebungssystem umschaltet, wenn es ein Zeilenende erreicht. Das kann entweder der Name eines anderen Kontextes sein, <userinput
>#stay</userinput
> um den Kontext nicht umzuschalten, (⪚ tue nichts) oder <userinput
>#pop</userinput
> das bewirkt, dass der Kontext verlassen wird. Es ist möglich, zum Beispiel <userinput
>#pop#pop#pop</userinput
> zu verwenden, um drei Kontextebenen zu verlassen oder mit <userinput
>#pop#pop!OtherContext</userinput
> zwei Kontextebenen zu verlassen und in einen neuen Kontext zu springen. Es ist auch möglich zu einem Kontext zu wechseln, der zu einer anderen Sprachdefinition gehört, genauso wie in den <userinput
>IncludeRules</userinput
>-Regeln, ⪚ <userinput
>SomeContext##JavaScript</userinput
>. Beachten Sie, dass es nicht möglich ist, diesen Kontextwechsel in Kombination mit <userinput
>#pop</userinput
> zu verwenden, zum Beispiel ist <userinput
>#pop!SomeContext##JavaScript</userinput
> nicht gültig. Kontextwechsel werden auch in <xref linkend="kate-highlight-rules-detailled"/> beschrieben.</para>
<para
><userinput
>lineEmptyContext</userinput
> definiert den Kontext, der in einer leeren Zeile verwendet wird. Die Bezeichnung der Kontextwechsel ist die gleiche wie zuvor in <emphasis
>lineEndContext</emphasis
> beschrieben. Standard hierfür ist: #stay.</para>
<para
><userinput
>fallthroughContext</userinput
> legt den nächsten Kontext fest, zu dem gewechselt wird, wenn keine Regel passt. Die Bezeichnung der Kontextwechsel ist die gleiche wie zuvor in <emphasis
>lineEndContext</emphasis
> beschrieben. Voreinstellung: #stay.</para>
<para
><userinput
>fallthrough</userinput
> definiert, ob das Hervorhebungssystem zu dem in <userinput
>fallthroughContext</userinput
> angegebenen Kontext wechselt, wenn keine Regel passt. Beachten Sie, dass seit &kde; &frameworks; 5.62 dieses Attribut zugunsten von <userinput
>fallthroughContext</userinput
> veraltet ist. Denn wenn das Attribut <userinput
>fallthroughContext</userinput
> vorhanden ist, wird stillschweigend angenommen, dass der Wert von <userinput
>fallthrough</userinput
> <emphasis
>true</emphasis
> ist. Voreinstellung: <emphasis
>false</emphasis
>.</para>
<para
><userinput
>noIndentationBasedFolding</userinput
> deaktiviert das auf der Einrückung basierte Ausblenden von Text im Kontext. Wenn das Ausblenden nicht aktiviert ist, ist dieses Attribut nutzlos. Es wird im Element <emphasis
>folding</emphasis
> der Gruppe <emphasis
>general</emphasis
> definiert. Voreinstellung: <emphasis
>false</emphasis
>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term
>Das Element <userinput
>itemData</userinput
> ist in der Gruppe <userinput
>itemDatas</userinput
>. Es definiert die Schriftarten und Schriftfarben. So ist es möglich, Ihre eigenen Schriftarten und -farben festzulegen. Wir empfehlen jedoch, bei den vordefinierten Einstellungen zu bleiben, sodass in unterschiedlichen Sprachen trotzdem die gleichen Farben angezeigt werden. Manchmal ist es doch nötig, die Farben und Schriftarten zu ändern. Der Name der Eigenschaft und defStyleNum müssen angeben werden, alle anderen können verwendet werden, sind aber nicht unbedingt nötig. Die verfügbaren Eigenschaften sind:</term>
<listitem>
<para
><userinput
>name</userinput
> setzt den Namen von itemData. Kontexte und Regel benutzen diesen Namen in ihrer Eigenschaft <emphasis
>attribute</emphasis
>, um den Bezug zum itemData herzustellen.</para>
<para
><userinput
>defStyleNum</userinput
> definiert, welcher Stil standardmäßig benutzt wird. Die verfügbaren Stile werden später näher erläutert.</para>
<para
><userinput
>color</userinput
> definiert eine Farbe. Erlaubte Formate hierfür sind: ‚#rrggbb‘ oder ‚#rgb‘.</para>
<para
><userinput
>selColor</userinput
> definiert die Farbe für die Hervorhebung.</para>
<para
><userinput
>italic</userinput
> Wenn <emphasis
>true</emphasis
>, dann wird der Text in Kursivschrift dargestellt.</para>
<para
><userinput
>bold</userinput
> Wenn <emphasis
>true</emphasis
>, dann wird der Text in Fettschrift dargestellt.</para>
<para
><userinput
>underline</userinput
> Wenn <emphasis
>true</emphasis
>, dann wird der Text unterstrichen dargestellt.</para>
<para
><userinput
>strikeout</userinput
> Wenn <emphasis
>true</emphasis
>, dann wird der Text durchgestrichen dargestellt.</para>
<para
><userinput
>spellChecking</userinput
> Wenn <emphasis
>true</emphasis
>, dann wird die Rechtschreibprüfung für den Text aktiviert.</para>
</listitem>
</varlistentry>
<varlistentry>
<term
>Das Element <userinput
>keywords</userinput
> in der Gruppe <userinput
>general</userinput
> definiert Eigenschaften von Schlüsselwörtern. Verfügbare Eigenschaften sind:</term>
<listitem>
<para
><userinput
>casesensitive</userinput
> kann <emphasis
>true</emphasis
> oder <emphasis
>false</emphasis
> sein. Wenn es <emphasis
>true</emphasis
> ist, dann wird bei allen Schlüsselwörtern die Groß- und Kleinschreibung beachtet.</para>
<para
><userinput
>weakDeliminator</userinput
> ist eine Liste von Zeichen, die nicht als Wortbegrenzung wirken. Der Punkt <userinput
>'.'</userinput
> ist zum Beispiel eine Wortbegrenzung. Nehmen Sie an, ein Schlüsselwort in einer <userinput
>list</userinput
> enthält einen Punkt, diese Schlüsselwort kann nur dann erkannt werden, wenn Sie den Punkt als <userinput
>weakDeliminator</userinput
> festlegen.</para>
<para
><userinput
>additionalDeliminator</userinput
> definiert zusätzliche Wortbegrenzungen.</para>
<para
><userinput
>wordWrapDeliminator</userinput
> definiert Zeichen, nach denen ein Zeilenumbruch erfolgen kann.</para>
<para
>Standard für Wortbegrenzer und Zeilenumbruchbegrenzer sind die Zeichen <userinput
>.():!+,-<=>%&*/;?[]^{|}~\</userinput
>, Leerzeichen (<userinput
>' '</userinput
>) und der Tabulator (<userinput
>'\t'</userinput
>).</para>
</listitem>
</varlistentry>
<varlistentry>
<term
>Das Element <userinput
>comment</userinput
> in der Gruppe <userinput
>comments</userinput
> definiert Eigenschaften für Kommentare, die für <menuchoice
> <guimenu
>Extras</guimenu
><guimenuitem
>Kommentar</guimenuitem
> </menuchoice
>, <menuchoice
> <guimenu
>Extras</guimenu
><guimenuitem
>Kommentar entfernen</guimenuitem
></menuchoice
> und <menuchoice
><guimenu
>Tools</guimenu
><guimenuitem
>Kommentar ein-/ausschalten</guimenuitem
></menuchoice
> benutzt werden. Verfügbare Eigenschaften hierfür sind:</term>
<listitem>
<para
><userinput
>name</userinput
> ist entweder <emphasis
>singleLine</emphasis
> oder <emphasis
>multiLine</emphasis
>. Wenn Sie <emphasis
>multiLine</emphasis
> auswählen, müssen auch die Eigenschaften <emphasis
>end</emphasis
> und <emphasis
>region</emphasis
> benutzt werden. Bei <emphasis
>singleLine</emphasis
> können Sie das optionale Attribut <emphasis
>position</emphasis
> hinzufügen.</para>
<para
><userinput
>start</userinput
> definiert die Zeichenfolge, die einen Kommentar beginnt. In C++ ist dies zum Beispiel "/*" in mehrzeiligen Kommentaren. Dieses Attribut ist für <emphasis
>multiLine</emphasis
> und <emphasis
>singleLine</emphasis
> nötig.</para>
<para
><userinput
>end</userinput
> definiert die Zeichenfolge, die einen Kommentar beendet. In C++ ist dies zum Beispiel "*/". Diese Attribut ist nur für den Typ <emphasis
>multiLine</emphasis
> verfügbar und erforderlich.</para>
<para
><userinput
>region</userinput
> sollte der Name von ausblendbaren Mehrzeilenkommentaren sein. Nehmen Sie an, Sie haben <emphasis
>beginRegion=<quote
>Comment</quote
></emphasis
> ... <emphasis
>endRegion=<quote
>Comment</quote
></emphasis
> in Ihren Regeln, dann sollten Sie <emphasis
>region=<quote
>Comment</quote
></emphasis
> benutzen. Auf diesem Wege funktioniert das automatische Entfernen von Kommentaren auch dann, wenn Sie nicht den gesamten Text des mehrzeiligen Kommentars auswählen. Es muss nur der Cursor innerhalb des mehrzeiligen Kommentars stehen. diese Attribut ist nur für den Typ <emphasis
>multiLine</emphasis
> verfügbar.</para>
<para
><userinput
>position</userinput
> definiert, wo der einzeilige Kommentar eingefügt wird. Standardmäßig wird der einzeilige Kommentar am Anfang der der Zeile bei Spalte 0 platziert, aber wenn Sie <emphasis
>position="afterwhitespace"</emphasis
> verwenden, wird der Kommentar nach führenden Leerraumzeichen rechts eingefügt, vor dem ersten Nicht-Leerraumzeichen. Dies ist nützlich für das korrekte Einfügen von Kommentaren in Sprachen, in denen die Einrückung wichtig ist, wie z. B. in Python oder YAML. Dieses Attribut ist optional und der einzig mögliche Wert ist <emphasis
>afterwhitespace</emphasis
>. Dies ist nur verfügbar für den Typ <emphasis
>singleLine</emphasis
>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term
>Das Element <userinput
>folding</userinput
> in der Gruppe <userinput
>general</userinput
> definiert Eigenschaften für ausblendbaren Quelltext. Verfügbare Eigenschaften sind:</term>
<listitem>
<para
><userinput
>indentationsensitive</userinput
> Wenn <emphasis
>true</emphasis
>, werden die Markierungen für Quelltextausblendungen basiert auf Einrückungen gesetzt, wie zum Beispiel in der Skriptsprache Python. Normalerweise brauchen Sie dies nicht zu setzen, Standard ist <emphasis
>false</emphasis
>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term
>Das Element <userinput
>emptyLine</userinput
> in der Gruppe <userinput
>emptyLines</userinput
> definiert, welche Zeilen als Leerzeilen behandelt werden sollen. Damit lässt sich das Verhalten des Attributs <emphasis
>lineEmptyContext</emphasis
> in den Elementen <userinput
>Kontext</userinput
> ändern. Verfügbare Attribute sind:</term>
<listitem>
<para
><userinput
>regexpr</userinput
> definiert einen regulären Ausdruck, der als eine leere Zeile behandelt wird. Standardmäßig enthalten leere Zeilen keine Zeichen, daher werden hier zusätzliche Leerzeilen hinzugefügt, z. B. wenn Zeilen mit Leerzeichen als Leerzeilen betrachtet werden sollen. In den meisten Syntaxdefinitionen brauchen Sie dieses Attribut jedoch nicht zu setzen.</para>
</listitem>
</varlistentry>
<varlistentry>
<term
>Das Element <userinput
>encoding</userinput
> in der Gruppe <userinput
>spellchecking</userinput
> definiert eine Zeichenkodierung für die Rechtschreibprüfung. Verfügbare Eigenschaften sind:</term>
<listitem>
<para
><userinput
>char</userinput
> ist ein kodiertes Zeichen.</para>
<para
><userinput
>string</userinput
> ist eine Folge von Zeichen, die in der Rechtschreibprüfung als das Zeichen <emphasis
>char</emphasis
> kodiert wird. In der Sprache LaTeX repräsentiert beispielsweise die Zeichenfolge <userinput
>\"{A}</userinput
> das Zeichen <userinput
>Ä</userinput
>.</para>
</listitem>
</varlistentry>
</variablelist>
</sect3>
<sect3 id="kate-highlight-default-styles">
<title
>Verfügbare Standardstile</title>
<para
>Standardstile wurden als <link linkend="kate-highlight-system-default-styles"
> kurze Zusammenfassung</link
> bereits erklärt. Standardstile sind vordefinierte Schriftarten und -farben.</para>
<variablelist>
<varlistentry>
<term
>Allgemeine Standardstile:</term>
<listitem>
<para
><userinput
>dsNormal</userinput
>, wenn keine spezielle Hervorhebung benötigt wird</para>
<para
><userinput
>dsKeyword</userinput
>, benutzt für eingebaute Sprach-Schlüsselwörter.</para>
<para
><userinput
>dsFunction</userinput
>, benutzt für Funktionsaufrufe und -definitionen.</para>
<para
><userinput
>dsVariable</userinput
>, falls zutreffend Variablennamen ⪚ $someVar in PHP/Perl.</para>
<para
><userinput
>dsControlFlow</userinput
>, Kontrollfluss-Schlüsselwörter wie if, else, switch, break, return, yield, ...</para>
<para
><userinput
>dsOperator</userinput
>, Operatoren wie + - * / :: < ></para>
<para
><userinput
>dsBuiltIn</userinput
>, eingebaute Funktionen, Klassen und Objekte.</para>
<para
><userinput
>dsExtension</userinput
>, allgemeine Erweiterungen wie zum Beispiel &Qt;-Klassen und Funktionen/Makros in C++ und Python.</para>
<para
><userinput
>dsPreprocessor</userinput
>, Präprozessor-Anweisungen oder Makro-Definitionen.</para>
<para
><userinput
>dsAttribute</userinput
>, Anmerkungen wie @override und __declspec(...).</para>
</listitem>
</varlistentry>
<varlistentry>
<term
>Standardstile für Zeichenfolgen:</term>
<listitem>
<para
><userinput
>dsChar</userinput
>, benutzt für einzelne Buchstaben wie „X“.</para>
<para
><userinput
>dsSpecialChar</userinput
>, Zeichen mit besonderer Bedeutung in Zeichenfolgen wie Escape-Sequenzen, Ersetzungen oder Operatoren für reguläre Ausdrücke.</para>
<para
><userinput
>dsString</userinput
>, benutzt für Zeichenfolgen wie „Hallo Welt“.</para>
<para
><userinput
>dsVerbatimString</userinput
>, wörtliche oder unveränderte Zeichenfolgen wie „raw \backlash“ in Perl, CoffeeScript und Shells wie auch r'\raw' in Python.</para>
<para
><userinput
>dsSpecialString</userinput
>, SQL, Reguläre Ausdrücke, HERE-Dokumente, &latex;-Mathematikmodus, ...</para>
<para
><userinput
>dsImport</userinput
>, import, include, erforderliche Module.</para>
</listitem>
</varlistentry>
<varlistentry>
<term
>Standardstile für Zahlen:</term>
<listitem>
<para
><userinput
>dsDataType</userinput
>, benutzt für eingebaute Datentypen wie int, void, u64.</para>
<para
><userinput
>dsDecVal</userinput
>, benutzt für Dezimalwerte.</para>
<para
><userinput
>dsBaseN</userinput
>, benutzt für Werte mit einer anderen Zahlenbasis als 10.</para>
<para
><userinput
>dsFloat</userinput
>, benutzt für Gleitkommawerte.</para>
<para
><userinput
>dsConstant</userinput
>, eingebaute und benutzerdefinierte Konsonanten wie Pi.PI.</para>
</listitem>
</varlistentry>
<varlistentry>
<term
>Standardstile für Kommentare und Dokumentation:</term>
<listitem>
<para
><userinput
>dsComment</userinput
>, benutzt für Kommentare.</para>
<para
><userinput
>dsDocumentation</userinput
>, /** Dokumentation-Kommentare */ oder """docstrings""".</para>
<para
><userinput
>dsAnnotation</userinput
>, Dokumentations--Befehle wie @param, @brief.</para>
<para
><userinput
>dsCommentVar</userinput
>, die in den vorher genannten Befehlen verwendeten Variablennamen wie „foobar“ in @param foobar.</para>
<para
><userinput
>dsRegionMarker</userinput
>, benutzt für Markierungen von Bereichen wie //BEGIN, //END in Kommentaren.</para>
</listitem>
</varlistentry>
<varlistentry>
<term
>Andere Standardstile:</term>
<listitem>
<para
><userinput
>dsInformation</userinput
>, Notizen und Hinweise wie @note in doxygen.</para>
<para
><userinput
>dsWarning</userinput
>, Warnungen wie @warning in doxygen.</para>
<para
><userinput
>dsAlert</userinput
>, besondere Wörter wie TODO, FIXME, XXXX.</para>
<para
><userinput
>dsError</userinput
>, benutzt für Hervorhebungen von Fehlern und für fehlerhafter Syntax.</para>
<para
><userinput
>dsOthers</userinput
>, wenn nichts anderes passt.</para>
</listitem>
</varlistentry>
</variablelist>
</sect3>
</sect2>
<sect2 id="kate-highlight-rules-detailled">
<title
>Hervorhebungs-Erkennungsregeln</title>
<para
>Dieser Abschnitt beschreibt die Hervorhebungs-Erkennungsregeln</para>
<para
>Jede Regel kann auf Null oder mehrere Zeichen am Anfang der untersuchten Zeichenfolge zutreffen. Wenn eine Übereinstimmung gefunden wird, wird den erkannten Zeichen der Stil oder die <emphasis
>Eigenschaft</emphasis
>, die durch die Regel festgelegt wurde, zugeordnet, Außerdem kann die Regel ein Umschalten des aktuellen Kontexts anfordern.</para>
<para
>Eine Regel sieht wie folgt aus:</para>
<programlisting
><RuleName attribute="(identifier)" context="(identifier)" [rule specific attributes] /></programlisting>
<para
>Die <emphasis
>attribute</emphasis
> (Eigenschaft) legt den Namen des Stils fest, der für die erkannten Zeichen benutzt werden soll und der <emphasis
>context</emphasis
> (Kontext) legt den Kontext fest, der ab hier benutzt werden soll.</para>
<para
>Der <emphasis
>context</emphasis
> (Kontext) kann durch Folgendes identifiziert werden:</para>
<itemizedlist>
<listitem>
<para
>Einen <emphasis
>identifier</emphasis
>, der der Name eines anderen Kontextes ist.</para>
</listitem>
<listitem>
<para
>Eine Anweisung, die vorgibt, im aktuellen Kontext zu bleiben (<userinput
>#stay</userinput
>), oder zu einem vorher in der Zeichenfolge benutzten Kontext zurückzuspringen (<userinput
>#pop</userinput
>).</para>
<para
>Zum Zurückgehen über mehrere Schritte kann das Schlüsselwort #pop wiederholt werden: <userinput
>#pop#pop#pop</userinput
></para>
</listitem>
<listitem>
<para
>Eine Anweisung <emphasis
>order</emphasis
>, die von einem Ausrufezeichen (<emphasis
>!</emphasis
>) und einem <emphasis
>identifier</emphasis
> gefolgt wird, veranlasst &kate; erst die Anweisung <emphasis
>order</emphasis
> auszuführen und dann in den anderen Kontext umzuschalten, ⪚ <userinput
>#pop#pop!OtherContext</userinput
>.</para>
</listitem>
<listitem>
<para
>Ein <emphasis
>identifier</emphasis
> ist ein Kontextname gefolgt von zwei Doppelkreuzen (<userinput
>##</userinput
>) und einem weiteren <emphasis
>identifier</emphasis
> für den Name einer Sprachdefinition. Diese Namensgebung ist ähnlich wie bei den Regeln <userinput
>IncludeRules</userinput
> und ermöglicht den Wechsel zu einem Kontext, der zu einer anderen Syntaxhervorhebungsdefinition gehört, z. B. <userinput
>SomeContext##JavaScript</userinput
>. Beachten Sie, dass es nicht möglich ist, diesen Kontextwechsel in Kombination mit <userinput
>#pop</userinput
> zu verwenden, z. B. <userinput
>#pop!SomeContext##JavaScript</userinput
> ist nicht gültig.</para>
</listitem>
</itemizedlist>
<para
>Regelspezifische Eigenschaften sind unterschiedlich und werden im Folgenden beschrieben.</para>
<itemizedlist>
<title
>Gemeinsame Eigenschaften</title>
<para
>Alle Regeln haben die folgenden Eigenschaften gemeinsam und sind immer verfügbar, wenn <userinput
>(common attributes)</userinput
> erscheint. <emphasis
>attribute</emphasis
> und <emphasis
>context</emphasis
> sind notwendige Eigenschaften, alle anderen sind optional, müssen also nicht benutzt werden. </para>
<listitem>
<para
><emphasis
>attribute</emphasis
>: Eine Eigenschaft zeigt auf ein bestimmtes <emphasis
>itemData</emphasis
>-Element.</para>
</listitem>
<listitem>
<para
><emphasis
>context</emphasis
>: Legt den Kontext fest, zu dem das Hervorhebungssystem umschaltet, wenn die Regel als zutreffend erkannt wird.</para>
</listitem>
<listitem>
<para
><emphasis
>beginRegion</emphasis
>: Beginnt einen Quelltextausblendungsblock. Standard ist: unset.</para>
</listitem>
<listitem>
<para
><emphasis
>endRegion</emphasis
>: Beendet eine Quelltextausblendungsblock. Standard ist: unset.</para>
</listitem>
<listitem>
<para
><emphasis
>lookAhead</emphasis
>: Wenn <emphasis
>true</emphasis
>, dann wird das Hervorhebungssystem die Länge der Übereinstimmung nicht verarbeiten. Standard ist: <emphasis
>false</emphasis
>.</para>
</listitem>
<listitem>
<para
><emphasis
>firstNonSpace</emphasis
>: Trifft nur dann zu, wenn die Zeichenfolge als erstes nach Zwischenräumen in der Zeile erkannt wird. Standard ist: <emphasis
>false</emphasis
>.</para>
</listitem>
<listitem>
<para
><emphasis
>column</emphasis
>: Trifft nur dann zu, wenn die Spalte zutrifft. Standard ist: unset.</para>
</listitem>
</itemizedlist>
<itemizedlist>
<title
>Dynamische Regeln</title>
<para
>Einige Regeln erlauben die Benutzung der optionalen Eigenschaft <userinput
>dynamic</userinput
>, Standard ist hier <emphasis
>false</emphasis
>.Wenn diese Eigenschaft auf <emphasis
>true</emphasis
> gesetzt wird, kann eine Regel in ihren Eigenschaften <userinput
>string</userinput
> oder <userinput
>char</userinput
> Platzhalter verwenden, die den zutreffenden Text aus einer als <emphasis
>regulärem Ausdruck</emphasis
> formulierten Regel enthält. Diese Regel muss direkt in den gegenwärtigen Kontext umgeschaltet haben. In einem <userinput
>string</userinput
> wird der Platzhalter <replaceable
>%N</replaceable
> (wobei N eine Zahl sein muss) ersetzt durch das Ergebnis für <replaceable
>N</replaceable
> aus dem aufrufenden regulären Ausdruck, startend mit 1. In einem <userinput
>char</userinput
> muss der Platzhalter auch eine Zahl <replaceable
>N</replaceable
> sein und wird durch das erste Zeichen aus dem Ergebnis für <replaceable
>N</replaceable
> aus dem aufrufenden regulären Ausdruck ersetzt. Immer wenn eine Regel diese Eigenschaft erlaubt, dann enthält diese ein <emphasis
>(dynamic)</emphasis
>.</para>
<listitem>
<para
><emphasis
>dynamic</emphasis
>: kann <emphasis
>(true oder false)</emphasis
> sein.</para>
</listitem>
</itemizedlist>
<para
><userinput
>Wie es funktioniert:</userinput
></para>
<para
>In den <link linkend="regular-expressions"
>regulären Ausdrücken</link
> der der <userinput
>RegExpr</userinput
>-Regeln wird der gesamte Text innerhalb einfacher runder Klammern <userinput
>(PATTERN)</userinput
> erfasst und behalten. Diese Erfassungen können in dem Kontext verwendet werden, in den gewechselt wird, in den Regeln mit dem Attribut <userinput
>dynamic</userinput
> <emphasis
>true</emphasis
>, durch <replaceable
>%N</replaceable
> (in <emphasis
>String</emphasis
>) oder <replaceable
>N</replaceable
> (in <emphasis
>char</emphasis
>).</para>
<para
>Ein Text, der in einer <userinput
>RegExpr</userinput
>-Regel erfasst wird, nur für den gewechselten Kontext behalten wird, der in seinem Attribut <userinput
>Kontext</userinput
> angegeben ist.</para>
<tip>
<itemizedlist>
<listitem>
<para
>Wenn die Erfassung nicht verwendet werden sollen, sowohl durch dynamische Regeln als auch im gleichen regulären Ausdruck, sollte <userinput
>nicht-erfassende Gruppen</userinput
> verwendet werden verwendet werden: <userinput
>(?:PATTERN)</userinput
></para>
<para
>Die Gruppen <emphasis
>Vorwärtsreferenz</emphasis
> oder <emphasis
>Rückwärtsreferenz</emphasis
> wie <userinput
>(?=PATTERN)</userinput
>, <userinput
>(?!PATTERN)</userinput
> oder <userinput
>(?<=PATTERN)</userinput
> werden nicht erfasst. Weitere Informationen fingen Sie im Abschnitt <link linkend="regular-expressions"
>Reguläre Ausdrücke</link
>.</para>
</listitem>
<listitem>
<para
>Die Erfassungs-Gruppen können innerhalb desselben regulären Ausdrucks verwendet werden, indem <replaceable
>\N</replaceable
> anstelle von <replaceable
>%N</replaceable
> verwendet wird. Für weitere Informationen siehe <link linkend="regex-capturing"
>Erfassen von passendem Text (Rückwärtsreferenz)</link
> in Abschnitt<link linkend="regular-expressions"
>Reguläre Ausdrücke</link
>.</para>
</listitem>
</itemizedlist>
</tip>
<para
>Beispiel 1:</para>
<para
>In diesem einfachen Beispiel wird der Text, der mit dem regulären Ausdruck <userinput
>=*</userinput
> übereinstimmt, erfasst und für <replaceable
>%1</replaceable
> in die dynamische Regel eingefügt. Dadurch kann der Kommentar mit der gleiche Zahl von Gleichheitszeichen <userinput
>=</userinput
> wie am Anfang beendet werden. Dies passt auf Text wie: <userinput
>[[ Kommentar ]]</userinput
>, <userinput
>[=[ Kommentar ]=]</userinput
> oder <userinput
>[=====[ Kommentar ]=====]</userinput
>.</para>
<para
>Außerdem sind die Erfassungen nur im gewechselten Kontext <emphasis
>mehrzeiligen Kommentaren</emphasis
> verfügbar.</para>
<programlisting
><context name="Normal" attribute="Normal Text" lineEndContext="#stay">
<RegExpr context="Multi-line Comment" attribute="Comment" String="\[(=*)\[" beginRegion="RegionComment"/>
</context>
<context name="Multi-line Comment" attribute="Comment" lineEndContext="#stay">
<StringDetect context="#pop" attribute="Comment" String="]%1]" dynamic="true" endRegion="RegionComment"/>
</context>
</programlisting>
<para
>Beispiel 2:</para>
<para
>In der dynamischen Regel entspricht <replaceable
>%1</replaceable
> der Erfassung, die auf <userinput
>#+</userinput
> passt und <replaceable
>%2</replaceable
> auf <userinput
>&quot;+</userinput
>. Dies trifft auf Text wie <userinput
>#label""""inside the context""""#</userinput
> zu.</para>
<para
>Diese Erfassungen sind in anderen Kontexten wie z. B. <emphasis
>OtherContext</emphasis
>, <emphasis
>FindEscapes</emphasis
> oder <emphasis
>SomeContext</emphasis
> nicht verfügbar.</para>
<programlisting
><context name="SomeContext" attribute="Normal Text" lineEndContext="#stay">
<RegExpr context="#pop!NamedString" attribute="String" String="(#+)(?:[\w-]|[^[:ascii:]])(&quot;+)"/>
</context>
<context name="NamedString" attribute="String" lineEndContext="#stay">
<RegExpr context="#pop!OtherContext" attribute="String" String="%2(?:%1)?" dynamic="true"/>
<DetectChar context="FindEscapes" attribute="Escape" char="\"/>
</context>
</programlisting>
<para
>Beispiel 3:</para>
<para
>Die passt auf Text wie: <userinput
>Class::function<T>( ... )</userinput
>.</para>
<programlisting
><context name="Normal" attribute="Normal Text" lineEndContext="#stay">
<RegExpr context="FunctionName" lookAhead="true"
String="\b([a-zA-Z_][\w-]*)(::)([a-zA-Z_][\w-]*)(?:&lt;[\w\-\s]*&gt;)?(\()"/>
</context>
<context name="FunctionName" attribute="Normal Text" lineEndContext="#pop">
<StringDetect context="#stay" attribute="Class" String="%1" dynamic="true"/>
<StringDetect context="#stay" attribute="Operator" String="%2" dynamic="true"/>
<StringDetect context="#stay" attribute="Function" String="%3" dynamic="true"/>
<DetectChar context="#pop" attribute="Normal Text" char="4" dynamic="true"/>
</context>
</programlisting>
<itemizedlist>
<title
>Lokale Begrenzungszeichen</title>
<para
>Einige Regeln erlauben die optionalen Attribute <userinput
>weakDeliminator</userinput
> und <userinput
>additionalDeliminator</userinput
>, die mit gleichnamigen Attributen des <userinput
>Schlüsselworts</userinput
> kombiniert werden. Wenn zum Beispiel <userinput
>'%'</userinput
> ein schwacher Wortbegrenzer des <userinput
>Schlüsselworts</userinput
> ist, kann es in einer Regel nur zum Wortbegrenzer werden, indem man es dem Attribut <userinput
>additionalDeliminator</userinput
> hinzufügt. Wann immer eine Regel diese Attribute zulässt, enthält sie <emphasis
>lokale Begrenzungszeichen</emphasis
>.</para>
<listitem>
<para
><emphasis
>weakDeliminator</emphasis
>: Liste der Zeichen, die nicht als Wortbegrenzungen fungieren.</para>
</listitem>
<listitem>
<para
><emphasis
>additionalDeliminator</emphasis
> definiert zusätzliche Wortbegrenzungen.</para>
</listitem>
</itemizedlist>
<sect3 id="highlighting-rules-in-detail">
<title
>Die Regeln im Einzelnen:</title>
<variablelist>
<varlistentry>
<term
>DetectChar</term>
<listitem>
<para
>Findet ein einzelnes bestimmtes Zeichen. Häufig zum Finden des Endes von Zeichenfolgen in Anführungszeichen benutzt.</para>
<programlisting
><DetectChar char="(character)" (common attributes) (dynamic) /></programlisting>
<para
>Die Eigenschaft <userinput
>char</userinput
> definiert das zu erkennende Zeichen.</para>
</listitem>
</varlistentry>
<varlistentry>
<term
>Detect2Chars</term>
<listitem>
<para
>Findet zwei bestimmte Zeichen in einer bestimmten Reihenfolge.</para>
<programlisting
><Detect2Chars char="(character)" char1="(character)" (common attributes) /></programlisting>
<para
>Die Eigenschaft <userinput
>char</userinput
> definiert das erste zu erkennende Zeichen, <userinput
>char1</userinput
> das zweite.</para>
</listitem>
</varlistentry>
<varlistentry>
<term
>AnyChar</term>
<listitem>
<para
>Findet ein Zeichen aus einem bestimmten Satz von Zeichen.</para>
<programlisting
><AnyChar String="(string)" (common attributes) /></programlisting>
<para
>Die Eigenschaft <userinput
>String</userinput
> definiert den Satz der Zeichen.</para>
</listitem>
</varlistentry>
<varlistentry>
<term
>StringDetect</term>
<listitem>
<para
>Findet eine bestimmte Zeichenfolge.</para>
<programlisting
><StringDetect String="(string)" [insensitive="true|false"] (common attributes) (dynamic) /></programlisting>
<para
>Die Eigenschaft <userinput
>String</userinput
> definiert die zu erkennende Zeichenfolge. Die Eigenschaft <userinput
>insensitive</userinput
> ist standardmäßig auf <emphasis
>false</emphasis
> gesetzt und wird an die Zeichenfolgen-Vergleichsfunktion übergeben. Wenn der Wert auf <emphasis
>true</emphasis
> gesetzt wird, wird Groß- und Kleinschreibung ignoriert.</para>
</listitem>
</varlistentry>
<varlistentry>
<term
>WordDetect</term>
<listitem>
<para
>Findet eine Zeichenfolge, aber zusätzlich werden die Wortgrenzen wie ein Punkt <userinput
>'.'</userinput
> oder ein Leerzeichen am Anfang und Ende des Wortes beachtet. Dies funktioniert wie der reguläre Ausdruck <userinput
>\b<string>\b</userinput
>, ist aber schneller als die Regel <userinput
>RegExpr</userinput
>.</para>
<programlisting
><WordDetect String="(string)" [insensitive="true|false"] (common attributes) (local deliminators) /></programlisting>
<para
>Die Eigenschaft <userinput
>String</userinput
> definiert die zu erkennende Zeichenfolge. Die Eigenschaft <userinput
>insensitive</userinput
> ist standardmäßig auf <emphasis
>false</emphasis
> gesetzt und wird an die Zeichenfolgen-Vergleichsfunktion übergeben. Wenn der Wert auf <emphasis
>true</emphasis
> gesetzt wird, wird Groß- und Kleinschreibung ignoriert.</para>
<para
>Ab Version: &kate; 3.5 (&kde; 4.5)</para>
</listitem>
</varlistentry>
<varlistentry>
<term
>RegExpr</term>
<listitem>
<para
>Prüft die Übereinstimmung mit einem regulären Ausdruck.</para>
<programlisting
><RegExpr String="(string)" [insensitive="true|false"] [minimal="true|false"] (common attributes) (dynamic) /></programlisting>
<para
>Die Eigenschaft <userinput
>String</userinput
> definiert den regulären Ausdruck.</para>
<para
>Die Eigenschaft <userinput
>insensitive</userinput
> ist standardmäßig auf <emphasis
>false</emphasis
> gesetzt und wird an die Funktion zur Auswertung des regulären Ausdrucks übergeben.</para>
<para
>Die Eigenschaft <userinput
>minimal</userinput
> ist standardmäßig auf <emphasis
>false</emphasis
> gesetzt und wird an die Funktion zur Auswertung des regulären Ausdrucks übergeben.</para>
<para
>Weil die Regeleinhaltung immer am Anfang der aktuellen Zeichenfolge geprüft wird, kann mit dem Hochzeichen (<literal
>^</literal
>) angegeben werden, dass die Regeleinhaltung nur am Anfang der Zeile untersucht werden soll.</para>
<para
>Sehen Sie unter <link linkend="regular-expressions"
>Reguläre Ausdrücke</link
> für weitere Informationen zu diesen nach.</para>
</listitem>
</varlistentry>
<varlistentry>
<term
>keyword</term>
<listitem>
<para
>Erkennt ein Schlüsselwort aus einer angegebenen Liste.</para>
<programlisting
><keyword String="(list name)" (common attributes) (local deliminators) /></programlisting>
<para
>Die Eigenschaft <userinput
>String</userinput
> definiert die Schlüsselwortliste durch deren Name. Eine Liste mit diesem Namen muss vorhanden sein.</para>
<para
>Das Hervorhebungssystem verarbeitet die Regeln mit sehr stark optimierten Methoden. Deswegen ist es absolut notwendig, dass alle Schlüsselworte, die gefunden werden sollen, durch definierte Begrenzer eingeschlossen werden. Das können entweder die Standardbegrenzer sein oder Begrenzer, die mit der Eigenschaft <emphasis
>additionalDeliminator</emphasis
> des Tags <emphasis
>keywords</emphasis
> festgelegt wurden.</para>
<para
>Wenn ein Schlüsselwort ein Begrenzerzeichen enthalten soll, dann muss dieses Zeichen zur Eigenschaft <emphasis
>weakDeliminator</emphasis
> des Tags <emphasis
>keywords</emphasis
> hinzugefügt werden. Dieses Zeichen verliert damit seine Funktion als Begrenzer in allen <emphasis
>keyword</emphasis
>-Regeln. Es ist auch möglich, das <emphasis
>weakDeliminator</emphasis
> Attribut vom <emphasis
>keyword</emphasis
> zu verwenden, so dass diese Änderung nur für diese Regel gilt.</para>
</listitem>
</varlistentry>
<varlistentry>
<term
>Int</term>
<listitem>
<para
>Erkennt eine ganze Zahl wie im regulären Ausdruck <userinput
>\b[0-9]+</userinput
>).</para>
<para
><programlisting
><Int (common attributes) (local deliminators) /></programlisting
></para>
<para
>Diese Regel hat keine speziellen Eigenschaften.</para>
</listitem>
</varlistentry>
<varlistentry>
<term
>Float</term>
<listitem>
<para
>Erkennt eine Dezimalzahl wie im regulären Ausdruck <userinput
>\b[0-9]+)\.[0-9]*|\.][-+]?[0-9]+)?</userinput
>).</para>
<para
><programlisting
><Float (common attributes) (local deliminators) /></programlisting
></para>
<para
>Diese Regel hat keine speziellen Eigenschaften.</para>
</listitem>
</varlistentry>
<varlistentry>
<term
>HlCOct</term>
<listitem>
<para
>Erkennt eine Oktalzahl wie im regulären Ausdruck <userinput
>\b0[0-7]+</userinput
>.</para>
<para
><programlisting
><HlCOct (common attributes) (local deliminators) /></programlisting
></para>
<para
>Diese Regel hat keine speziellen Eigenschaften.</para>
</listitem>
</varlistentry>
<varlistentry>
<term
>HlCHex</term>
<listitem>
<para
>Erkennt eine hexadezimale Zahl wie im regulären Ausdruck <userinput
>\b0[xX][0-9a-fA-F]+</userinput
>.</para>
<para
><programlisting
><HlCHex (common attributes) (local deliminators) /></programlisting
></para>
<para
>Diese Regel hat keine speziellen Eigenschaften.</para>
</listitem>
</varlistentry>
<varlistentry>
<term
>HlCStringChar</term>
<listitem>
<para
>Findet ein Steuerzeichen.</para>
<para
><programlisting
><HlCStringChar (common attributes) /></programlisting
></para>
<para
>Diese Regel hat keine speziellen Eigenschaften.</para>
<para
>Solche Zeichen sind durch druckbare Zeichen dargestellte nicht druckbare Zeichen, die in Programmquelltexten häufig benutzt werden. ⪚: <userinput
>\n</userinput
> (Zeilenvorschub) oder <userinput
>\t</userinput
> (TAB)</para>
<para
>Die folgenden Zeichen werden erkannt, wenn sie einem Linksschrägstrich <literal
>\</literal
> folgen: <userinput
>abefnrtv"'?</userinput
>. Zusätzlich werden auch hexadezimale (<userinput
>\xff</userinput
>) oder oktale (<userinput
>\033</userinput
>) Zahlen nach einem <literal
>\</literal
> erkannt.</para>
</listitem>
</varlistentry>
<varlistentry>
<term
>HlCChar</term>
<listitem>
<para
>Findet ein C Zeichen.</para>
<para
><programlisting
><HlCChar (common attributes) /></programlisting
></para>
<para
>Diese Regel hat keine speziellen Eigenschaften.</para>
<para
>Trifft zu, wenn C Zeichen in einfachen Anführungszeichen (Beispiel: <userinput
>'c'</userinput
>) vorkommen. In den Anführungszeichen kann ein einfaches Zeichen oder Sonderzeichen (Beispiel: <userinput
>'
'</userinput
>) stehen. Für Zeichenfolgen von Sonderzeichen sehen Sie unter HlCStringChar nach.</para>
</listitem>
</varlistentry>
<varlistentry>
<term
>RangeDetect</term>
<listitem>
<para
>Findet eine Zeichenfolge mit definierten Anfangs- und Endzeichen.</para>
<programlisting
><RangeDetect char="(character)" char1="(character)" (common attributes) /></programlisting>
<para
><userinput
>char</userinput
> definiert das Zeichen am Anfang des Bereichs, <userinput
>char1</userinput
> das Zeichen am Ende des Bereichs.</para>
<para
>Diese Regel ist für das Finden von kleinen Zeichenfolgen in Anführungszeichen nützlich, kann aber wegen der verwendeten Funktion keine über mehrere Zeilen gehenden Zeichenfolgen finden.</para>
</listitem>
</varlistentry>
<varlistentry>
<term
>LineContinue</term>
<listitem>
<para
>Trifft auf ein angegebenes Zeichen an einem Zeilenende zu.</para>
<programlisting
><LineContinue (common attributes) [char="\"] /></programlisting>
<para
>Die Eigenschaft <userinput
>char</userinput
> definiert das optionale zu erkennende Zeichen, Standard ist der Rückstrich <userinput
>'\'</userinput
>. Neu seit &kde; 4.13.</para>
<para
>Diese Regel wird zum Umschalten des Kontextes am Ende einer Zeile benutzt. Dies wird in C/C++ zum Fortsetzen von Makros oder Zeichenfolgen gebraucht.</para>
</listitem>
</varlistentry>
<varlistentry>
<term
>IncludeRules</term>
<listitem>
<para
>Schließt Regeln aus einem anderen Kontext, einer anderen Sprache oder einer anderen Datei ein.</para>
<programlisting
><IncludeRules context="contextlink" [includeAttrib="true|false"] /></programlisting>
<para
>Die Eigenschaft <userinput
>context</userinput
> definiert, welcher Kontext eingeschlossen werden soll.</para>
<para
>Wenn dies eine einfache Zeichenfolge ist, dann werden alle definierten Regeln in den gegenwärtigen Kontext eingeschlossen. Beispiel: <programlisting
><IncludeRules context="anotherContext" /></programlisting
></para>
<para
>Wenn die Zeichenfolge eine <userinput
>##</userinput
>-Nutzereingabe enthät, dann wird das Hervorhebungssystem einen Kontext aus einer anderen Sprachdefinition mit dem angegebenen Namen suchen, zum Beispiel: <programlisting
><IncludeRules context="String##C++" /></programlisting
> schliesst den Kontext <emphasis
>String</emphasis
> aus der Sprachdefinition für <emphasis
>C++</emphasis
> ein.</para>
<para
>Wenn die Eigenschaft <userinput
>includeAttrib</userinput
> <emphasis
>true</emphasis
> ist, dann wird die Zieleigenschaft zu der aus der Quelle geändert. Dies wird zum Beispiel für Kommentare gebraucht, wenn der Text, der durch den eingeschlossenen Kontext anders hervorgehoben wird, als im gegenwärtigen Kontext. </para>
</listitem>
</varlistentry>
<varlistentry>
<term
>DetectSpaces</term>
<listitem>
<para
>Finde Zwischenräume.</para>
<programlisting
><DetectSpaces (common attributes) /></programlisting>
<para
>Diese Regel hat keine speziellen Eigenschaften.</para>
<para
>Benutzen Sie diese Regel, wenn Sie wissen, dass jetzt mehrere Zwischenräume folgen, zum Beispiel am Anfang von eingerückten Zeilen. Diese Regel überspringt mehrere Zwischenräume mit einem Mal, ohne diese einzeln auf die Einhaltung von anderen Regeln zu testen und dann nach Nichtzutreffen einzeln zu überspringen.</para>
</listitem>
</varlistentry>
<varlistentry>
<term
>DetectIdentifier</term>
<listitem>
<para
>Finde Zeichenfolgen als Bezeichner (als regulärer Ausdruck: <userinput
>[a-zA-Z_][a-zA-Z0-9_]*</userinput
>).</para>
<programlisting
><DetectIdentifier (common attributes) /></programlisting>
<para
>Diese Regel hat keine speziellen Eigenschaften.</para>
<para
>Benutzen Sie diese Regel zum Überspringen von Wörtern mit einem Mal, ohne die Zeichen im Wort einzeln auf die Einhaltung von anderen Regeln zu testen und dann nach Nichtzutreffen zu überspringen.</para>
</listitem>
</varlistentry>
</variablelist>
</sect3>
<sect3>
<title
>Tipps & Tricks</title>
<itemizedlist>
<para
>Wenn Sie einmal verstanden haben, wie das Umschalten zwischen Kontexten funktioniert, dann ist es einfach Hervorhebungsdefinitionen zu schreiben. Sie sollten jedoch sorgfältig entscheiden, welche Regel in welcher Situation Sie verwenden. Reguläre Ausdrücke sind sehr leistungsfähig, aber verglichen mit einfachen Regeln langsam. Sie sollten daher die folgenden Tipps beachten. </para>
<listitem>
<para
>Wenn Sie nur zwei Zeichen vergleichen, dann benutzen Sie <userinput
>Detect2Chars</userinput
> an Stelle von <userinput
>StringDetect</userinput
>. Das Gleiche gilt für <userinput
>DetectChar</userinput
>.</para>
</listitem>
<listitem>
<para
>Reguläre Ausdrücke sind einfach zu benutzen, aber oft gibt es einen anderen viel schnelleren Weg, um das gleiche Ergebnis zu erreichen. Nehmen Sie an, Sie wollen feststellen, ob das Zeichen <userinput
>'#'</userinput
> das erste Zeichen einer Zeile ist. Ein regulärer Ausdruck dafür wäre: <programlisting
><RegExpr attribute="Macro" context="macro" String="^\s*#" /> </programlisting
> Sie können aber auch die wesentlich schnellere Lösung: <programlisting
><DetectChar attribute="Macro" context="macro" char="#" firstNonSpace="true" /></programlisting
> benutzen. An Stelle des regulären Ausdrucks <userinput
>'^#'</userinput
> können Sie <userinput
>DetectChar</userinput
> mit der Eigenschaft <userinput
>column="0"</userinput
> benutzen. Die Eigenschaft <userinput
>column</userinput
> zählt Zeichenbasiert, sodass auch ein Tabulator nur ein Zeichen ist. </para>
</listitem>
<listitem>
<para
>Verwenden Sie in <userinput
>RegExpr</userinput
>-Regeln das Attribut <userinput
>column="0"</userinput
>, wenn mit dem Muster <userinput
>^PATTERN</userinput
> Text am Anfang einer Zeile gefunden werden soll. Dies ist schneller, da nicht mehr in den restlichen Spalten der Zeile nach Übereinstimmungen gesucht wird.</para>
</listitem>
<listitem>
<para
>Verwenden Sie in regulären Ausdrücken nicht-erfassende Gruppen <userinput
>(?:PATTERN)</userinput
> anstelle von erfassenden Gruppen <userinput
>(PATTERN)</userinput
>, wenn die Erfassungen nicht in demselben regulären Ausdruck oder in dynamischen Regeln verwendet werden. Dadurch wird das unnötige Speichern von Erfassungen vermieden.</para>
</listitem>
<listitem>
<para
>Sie können zwischen Kontexten umschalten, ohne Zeichen zu verarbeiten. Angenommen, Sie wollen den Kontext umschalten, wenn Sie die Zeichenfolge <userinput
>*/</userinput
> finden, aber Sie müssen diese Zeichenfolge im nächsten Kontext verarbeiten. Die folgende Regel trifft zu und die Eigenschaft <userinput
>lookAhead</userinput
> sorgt dafür, dass die zutreffende Zeichenfolge für den folgenden Kontext bereitgehalten wird. <programlisting
><Detect2Chars attribute="Comment" context="#pop" char="*" char1="/" lookAhead="true" /></programlisting>
</para>
</listitem>
<listitem>
<para
>Benutzen Sie <userinput
>DetectSpaces</userinput
>, wenn Sie wissen, dass mehrere Zwischenräume vorkommen.</para>
</listitem>
<listitem>
<para
>Benutzen Sie <userinput
>DetectIdentifier</userinput
> an Stelle des regulären Ausdrucks <userinput
>'[a-zA-Z_]\w*'</userinput
>.</para>
</listitem>
<listitem>
<para
>Benutzen Sie Standardstile wann immer das möglich ist. Die Benutzer finden dadurch eine vertraute Umgebung vor.</para>
</listitem>
<listitem>
<para
>Sehen Sie in anderen &XML;-Dateien nach, wie andere Benutzer komplizierte Regeln geschrieben haben.</para>
</listitem>
<listitem>
<para
>Sie können die Gültigkeit jeder &XML;-Datei mit dem Befehl <command
>validatehl.sh language.xsd mySyntax.xml</command
> überprüfen. Die Dateien <filename
>validatehl.sh</filename
> und <filename
>language.xsd</filename
> finden Sie im <ulink url="https://commits.kde.org/syntax-highlighting?path=data/schema"
>Syntax-Highlighting-Repository</ulink
>. </para>
</listitem>
<listitem>
<para
>Wenn Sie komplexe reguläre Ausdrücke oft wiederholen, können Sie <emphasis
>ENTITIES</emphasis
> benutzen. Beispiel:</para>
<programlisting
><?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE language SYSTEM "language.dtd"
[
<!ENTITY myref "[A-Za-z_:][\w.:_-]*">
]>
</programlisting>
<para
>Nun können Sie <emphasis
>&myref;</emphasis
> an Stelle des regulären Ausdrucks benutzen.</para>
</listitem>
</itemizedlist>
</sect3>
</sect2>
</sect1>
<sect1 id="color-themes">
<title
>Arbeiten mit Farbschemata</title>
<sect2 id="color-themes-overview">
<title
>Überblick</title>
<para
>Farbschemata definieren die Farben des <link linkend="kate-part"
>Text-Editierbereichs</link
> und der <link linkend="highlight"
>Syntaxhervorhebung</link
>. Ein Farbschema umfasst die folgenden Punkte: <itemizedlist>
<listitem
><para
>Der Textstil für die Syntaxhervorhebung durch die <emphasis
>Standard-Stilattribute</emphasis
>. Zum Beispiel die Textfarbe und die ausgewählte Textfarbe.</para
></listitem>
<listitem
><para
>Der Hintergrund des Textbearbeitungsbereichs, einschließlich der Textauswahl und der aktuellen Zeile.</para
></listitem>
<listitem
><para
>Die Symbolumrandung des Textbereichs, deren Hintergrund, die Trennlinie, die Zeilennummern, die Zeilenumbruchmarkierungen, die geänderten Zeilenmarkierungen und die Quelltextausblendung.</para
></listitem>
<listitem
><para
>Textmarkierungen wie die Suchmarkierungen, die Einrückung und die Zeilenmarkierungen für Tabulator-/Leerzeichen, zusammengehörende Klammern und die Rechtschreibprüfung.</para
></listitem>
<listitem
><para
>Lesezeichen und Textbausteine.</para
></listitem>
</itemizedlist>
</para>
<para
>Um Verwechslungen zu vermeiden, liegt das Folgende außerhalb des Anwendungsbereichs: <itemizedlist>
<listitem
><para
>Die Schriftart und Schriftgröße.</para
></listitem>
<listitem
><para
>Die Farben der Textbearbeitung, wie z. B. die Textgrafik auf der Bildlaufleiste, die Menüs, die Unterfensterleiste, die Fensterfarbe usw. In &kde; Anwendungen, wie &kate; oder &kdevelop;, werden diese Farben durch das <userinput
>globale &kde; &plasma;,Farbschema</userinput
> definiert, die im Modul <ulink url="help:/kcontrol/colors/"
><quote
>Farben</quote
> in den &systemsettings;</ulink
> oder von der Anwendung selbst im Menü <menuchoice
><guimenu
>Einstellungen</guimenu
><guisubmenu
>Farbschema</guisubmenu
></menuchoice
> festgelegt werden. </para
></listitem>
</itemizedlist>
</para>
<mediaobject>
<imageobject
><imagedata format="PNG" fileref="breeze-color-theme-preview.png"/></imageobject>
<textobject
><phrase
>Die Farbschemata <quote
>Breeze-Hell</quote
> und <quote
>Breeze-Dunkel</quote
> mit der Syntaxhervorhebung für <quote
>C++</quote
>.</phrase>
</textobject>
<caption
><para
>Die Farbschemata <quote
>Breeze-Hell</quote
> und <quote
>Breeze-Dunkel</quote
> mit der Syntaxhervorhebung für <quote
>C++</quote
>.</para>
</caption>
</mediaobject>
</sect2>
<sect2 id="color-themes-ksyntaxhighlighting">
<title
>Farbschemata für KSyntaxHighlighting</title>
<para
>Das Framework <ulink url="https://api.kde.org/frameworks/syntax-highlighting/html/"
>KSyntaxHighlighting</ulink
> enthält die <link linkend="highlight"
>Syntax-Highlighting</link
>-Engine und ist eine Bibliothek, die <userinput
>die Farbschemata bereitstellt und verwaltet</userinput
>. Die Bibliothek ist Teil von von &kde;-&frameworks; und wird in &kde;-Texteditoren wie <ulink url="https://apps.kde.org/en/kate"
>&kate;</ulink
>, <ulink url="https://apps.kde.org/de/kwrite"
>&kwrite;</ulink
>, <ulink url="https://apps.kde.org/en/.kile"
>&kile;</ulink
> und <ulink url="https://apps.kde.org/en/kdevelop"
>&kdevelop;</ulink
> verwendet. Diese Abhängigkeit sieht wie folgt aus:</para>
<mediaobject>
<imageobject
><imagedata format="PNG" fileref="kf5-ksyntaxhighlighting.png"/></imageobject>
<textobject
><phrase
>Abhängigkeit von &kde;-&frameworks; 5 Bibliotheken von Texteditoren.</phrase
></textobject>
<caption
><para
>Abhängigkeit von &kde;-&frameworks;-Bibliotheken von Texteditoren.</para>
</caption>
</mediaobject>
<para
>KSyntaxHighlighting enthält eine Vielzahl von eingebauten Schemata, die auf der Seite <ulink url="https://kate-editor.org/themes/"
><quote
>Farbschemata</quote
> der Webseite des Kate-Editors zu finden sind</ulink
>.</para>
<para
>Das Framework <ulink url="https://api.kde.org/frameworks/ktexteditor/html/"
>KTextEditor</ulink
> enthält eine Benutzeroberfläche zum Erstellen und Bearbeiten von Farbschemata und ermöglicht das Importieren und Exportieren von Schemata. Sie können diesen Dialog in den <link linkend="config-dialog"
><quote
>Einstellungen</quote
></link
> des Texteditors öffnen. Weitere Informationen finden Sie im Abschnitt <xref linkend="color-themes-gui"/>.</para>
<mediaobject>
<imageobject
><imagedata format="PNG" fileref="color-themes-gui-breeze-dark-default-text-styles.png"/></imageobject>
<textobject
><phrase
>Die &GUI; zur Bearbeitung von Farbschemata in den Einstellungen von &kate;.</phrase
></textobject>
<caption
><para
>Die &GUI; zur Bearbeitung von Farbschemata in den Einstellungen von &kate;.</para>
</caption>
</mediaobject>
<para
>In den &kde;-Texteditoren wie &kate; oder &kdevelop; werden die Farbschemata von KSyntaxHighlighting seit <ulink url="https://kate-editor.org/post/2020/2020-09-13-kate-color-themes-5.75/"
>&kde; &frameworks; 5.75</ulink
> vom 10. Oktober 2020 verwendet. Zuvor wurden die Farbschemata von &kate; (KConfig-basierte Schema-Einstellungen) verwendet und die sind nun veraltet. Es ist jedoch möglich, die alten &kate;-Schemata in die KSyntaxHighlighting-Farbschemata umzuwandeln. Das <ulink url="https://invent.kde.org/frameworks/syntax-highlighting"
>KSyntaxHighlighting-Quelltextarchiv</ulink
> enthält das Skript <userinput
>utils/kateschema_to_theme_converter.py</userinput
> und den Ordner <userinput
>utils/schema-converter/</userinput
> mit weiteren Hilfsprogrammen für diesen Zweck. </para>
</sect2>
<sect2 id="color-themes-json">
<title
>Das &JSON;-Format der Farbschemata</title>
<sect3 id="color-themes-json-overview">
<title
>Überblick</title>
<para
>Farbschemata werden in Dateien im &JSON;-Format mit der Dateierweiterung <userinput
>.theme</userinput
> gespeichert.</para>
<para
>Im <ulink url="https://invent.kde.org/frameworks/syntax-highlighting"
> KSyntaxHighlighting-Quelltext</ulink
> befinden sich die &JSON;-Dateien der eingebauten Schemata im Ordner <userinput
>data/themes/</userinput
>. Die eingebauten Schemata werden in die Bibliothek KSyntaxHighlighting kompiliert, daher ist der Zugriff auf sie über den Quelltext oder durch <link linkend="color-themes-gui-import-export"
>Exportieren aus der &GUI; zur Verwaltung der Schemata von KTextEditor</link
> möglich.</para>
<para
>Sie können auch auf einfache Weise zusätzliche oder benutzerdefinierte Schemata hinzuzufügen, die aus dem Dateisystem geladen werden. Benutzerdefinierte Schemadateien befinden sich im Ordner <filename class="directory"
>org.kde.syntax-highlighting/themes/</filename
> in Ihrem persönlichen Ordner, den Sie mit dem Befehl <userinput
><command
>qtpaths</command
><option
> --paths GenericDataLocation</option
></userinput
> finden können, üblicherweise <filename class="directory"
><envar
>$HOME</envar
>/.local/share/</filename
> und <filename class="directory"
>/usr/share/</filename
>. </para>
<para
>Bei Flatpak- und Snap-Paketen funktioniert der obige Ordner nicht, da der Speicherort der Daten für jede Anwendung unterschiedlich ist. In einer Flatpak-Anwendung ist der Speicherort der benutzerdefinierten Schemadateien normalerweise <filename class="directory"
><envar
>$HOME</envar
>/.var/app/<replaceable
>flatpak-package-name</replaceable
>/data/org.kde.syntax-highlighting/themes/</filename
> und in einer Snap-Anwendung ist dieser Ort <filename class="directory"
><envar
>$HOME</envar
>/snap/<replaceable
>snap-package-name</replaceable
>/current/.local/share/org.kde.syntax-highlighting/themes/</filename
>. </para>
<para
>Auf &Windows;-Systemen finden Sie diese Dateien unter <filename
>%USERPROFILE%\AppData\Local\org.kde.syntax-highlighting\themes</filename
>. <replaceable
>%USERPROFILE%</replaceable
>. Dabei ist <replaceable
>%USERPROFILE%</replaceable
> normalerweise <filename
>C:\Users\<replaceable
>user-name</replaceable
></filename
>.</para>
<para
>Zusammenfassend lässt sich sagen, dass der Ordner für benutzerdefinierte Schemata bei den meisten Einrichtungen wie folgt aussieht:</para>
<informaltable>
<tgroup cols="2">
<tbody>
<row>
<entry
>Für lokale Benutzer</entry>
<entry
><filename class="directory"
><envar
>$HOME</envar
>/.local/share/org.kde.syntax-highlighting/themes/</filename
></entry>
</row>
<row>
<entry
>Für alle Benutzer</entry>
<entry
><filename class="directory"
>/usr/share/org.kde.syntax-highlighting/themes/</filename
></entry>
</row>
<row>
<entry
>Für Flatpak-Pakete</entry>
<entry
><filename class="directory"
><envar
>$HOME</envar
>/.var/app/<replaceable
>flatpak-package-name</replaceable
>/data/org.kde.syntax-highlighting/themes/</filename
></entry>
</row>
<row>
<entry
>Für Snap-Pakete</entry>
<entry
><filename class="directory"
><envar
>$HOME</envar
>/snap/<replaceable
>snap-package-name</replaceable
>/current/.local/share/org.kde.syntax-highlighting/themes/</filename
></entry>
</row>
<row>
<entry
>Unter &Windows;</entry>
<entry
><filename
>%USERPROFILE%\AppData\Local\org.kde.syntax-highlighting\themes</filename
></entry>
</row>
</tbody>
</tgroup>
</informaltable>
<para
>Wenn mehrere Schemadateien mit demselben Namen existieren, wird die Datei mit der höchsten <userinput
>Revision</userinput
> geladen. </para>
</sect3>
<sect3 id="color-themes-json-basic">
<title
>Dit &JSON;-Struktur</title>
<para
>Der Aufbau einer &JSON;-Datei wird auf <ulink url="https://www.json.org"
>dieser Webseite</ulink
> erläutert. Grundsätzlich besteht eine Datei im &JSON;-Format aus: <itemizedlist>
<listitem
><para
>Sammlungen von Schlüssel/Wert-Paaren, getrennt durch Kommas und gruppiert in <userinput
>{ }</userinput
>, auch <quote
>Objekte</quote
> genannt.</para
></listitem>
<listitem
><para
>Sortierte Listen von Werten, getrennt durch Kommas und gruppiert in <userinput
>[ ]</userinput
>, auch <quote
>Feld</quote
> genannt.</para
></listitem
></itemizedlist>
</para>
<para
>Die Bezeichnungen <quote
>Schlüssel</quote
>, <quote
>Wert</quote
>, <quote
>Objekt</quote
> und <quote
>Feld</quote
> werden hier verwendet. Falls Sie zum ersten Mal mit &JSON;-Dateien arbeiten, helfen die folgenden Beispiele beim Verständnis. </para>
</sect3>
<sect3 id="color-themes-json-root">
<title
>Hauptabschnitte der &JSON;-Farbschemadateien</title>
<para
>Das Basisobjekt der Farbschemadateien im &JSON;-Format enthält die folgenden Schema-Schlüssel:</para>
<itemizedlist>
<listitem
><para
><userinput
>metadata</userinput
>: Dies ist obligatorisch. Der Wert ist ein Objekt mit den Metadaten des Schemas wie Name, Revision und Lizenz.</para>
<para
>Ausführliche Informationen dazu unter <xref linkend="color-themes-json-metadata"/>.</para>
</listitem>
<listitem
><para
><userinput
>Editor-Farben</userinput
>: Dies ist obligatorisch. Der Wert ist ein Objekt mit den Farben des Textbearbeitungsbereichs wie dem Hintergrund, dem Symbolrand und der Textdekoration.</para>
<para
>Ausführliche Informationen dazu unter <xref linkend="color-themes-editor-colors"/>.</para>
</listitem>
<listitem
><para
><userinput
>Textstile</userinput
>: Dies ist obligatorisch. Der Wert ist ein Objekt mit dem Attribut<emphasis
>Standard-Textstil</emphasis
> der Syntaxhervorhebung. Jedes Attribut definiert seine <emphasis
>Textfarbe</emphasis
>, seine <emphasis
>gewählte Textfarbe</emphasis
>, oder ob es zum Beispiel <emphasis
>fett</emphasis
> oder <emphasis
>kursiv</emphasis
> sein soll. Die Textstile können aus den <link linkend="kate-highlight-default-styles"
>Attributen der Syntaxdefinitionsdateien referenziert werden</link
>.</para>
<para
>Ausführliche Informationen dazu unter <xref linkend="color-themes-text-styles"/>.</para>
</listitem>
<listitem
><para
><userinput
>custom-styles</userinput
>: Ist optional. Definiert Textstile für die Attribute bestimmter Definitionen von Syntaxhervorhebungen. In einer Hervorhebungsdefinition wie <userinput
>Python</userinput
> oder <userinput
>Markdown</userinput
> können Sie einen anderen Textstil angeben, der den in <userinput
>text-styles</userinput
> definierten Standard überschreibt.</para>
<para
>Ausführliche Informationen dazu unter <xref linkend="color-themes-custom-styles"/>.</para>
</listitem>
</itemizedlist>
<para
>Die Sprache &JSON; unterstützt keine Kommentare. Sie können jedoch mit dem optionalen Schlüssel <userinput
>_comments</userinput
> im Basisobjekt Kommentare schreiben. Wenn sie zum Beispiel ein bestehendes Schema anpassen, können Sie die URL des ursprünglichen Archivs angeben. Der praktischste Weg ist die Verwendung eines Felds mit Zeichenfolgen. </para>
<para
>Nachfolgend finden Sie eine Beispieldatei für das Schema <quote
>Breeze-Hell</quote
>-. Um das Beispiel nicht zu lang werden zu lassen, enthalten die Objekte <userinput
>editor-colors</userinput
> und <userinput
>text-styles</userinput
> nicht alle alle erforderlichen Schlüssel. Sie können die vollständige Datei des <ulink url="https://invent.kde.org/frameworks/syntax-highlighting/-/blob/master/data/themes/breeze-light.theme"
>Schemas <quote
>Breeze-Hell</quote
> aus dem KSyntaxHighlighting-Quelltextarchiv</ulink
> herunterladen. </para>
<programlisting
>{
"_comments": [
"This is a comment.",
"If this theme is an adaptation of another, put the link to the original repository."
],
"metadata": {
"name" : "Breeze Light",
"revision" : 5,
"copyright": [
"SPDX-FileCopyrightText: 2016 Volker Krause <vkrause@kde.org>",
"SPDX-FileCopyrightText: 2016 Dominik Haumann <dhaumann@kde.org>"
],
"license": "SPDX-License-Identifier: MIT"
},
"editor-colors": {
"BackgroundColor" : "#ffffff",
"CodeFolding" : "#94caef",
"BracketMatching" : "#ffff00",
"CurrentLine" : "#f8f7f6",
"IconBorder" : "#f0f0f0",
"IndentationLine" : "#d2d2d2",
"LineNumbers" : "#a0a0a0",
"CurrentLineNumber" : "#1e1e1e",
<replaceable
>The other editor color keys...</replaceable>
},
"text-styles": {
"Normal" : {
"text-color" : "#1f1c1b",
"selected-text-color" : "#ffffff",
"bold" : false,
"italic" : false,
"underline" : false,
"strike-through" : false
},
"Keyword" : {
"text-color" : "#1f1c1b",
"selected-text-color" : "#ffffff",
"bold" : true
},
"Function" : {
"text-color" : "#644a9b",
"selected-text-color" : "#452886"
},
"Variable" : {
"text-color" : "#0057ae",
"selected-text-color" : "#00316e"
},
<replaceable
>The other text style keys...</replaceable>
},
"custom-styles": {
"ISO C++": {
"Data Type": {
"bold": true,
"selected-text-color": "#009183",
"text-color": "#00b5cf"
},
"Keyword": {
"text-color": "#6431b3"
}
},
"YAML": {
"Attribute": {
"selected-text-color": "#00b5cf",
"text-color": "#00b5cf"
}
}
}
}
</programlisting>
</sect3>
<sect3 id="color-themes-json-metadata">
<title
>Metadaten</title>
<para
>Das &JSON; Objekt des Schlüssels <userinput
>metadata</userinput
> enthält die wichtigsten Informationen über das Schema. Dieses Objekt hat die folgenden Schlüssel: <itemizedlist>
<listitem
><para
><userinput
>Name</userinput
>: Dies ist eine <emphasis
>Zeichenfolge</emphasis
> mit dem Name der Sprache. Dies wird in den Menüs und Dialogen angezeigt und ist verpflichtend.</para
></listitem>
<listitem
><para
><userinput
>revision</userinput
>: Es ist eine <emphasis
>ganze Zahl</emphasis
>. die die aktuelle Revision der Schemadatei angibt. Wann immer Sie eine Farbschemadatei aktualisieren, müssen Sie diese Zahl vergrößern. Diese Wert ist erforderlich.</para
></listitem>
<listitem
><para
><userinput
>Lizenz</userinput
>: Eine <emphasis
>Zeichenfolge</emphasis
>, die die Lizenz des Schemas definiert, unter Verwendung des Lizenzbezeichner <userinput
>SPDX-License-Identifier</userinput
> aus dem Standard <ulink url="https://spdx.dev/"
>SPDX-Lizenzkommunikationsformat</ulink
>. Dies ist optional.</para>
<para
>Die vollständige Liste der SPDX-Lizenzbezeichner können Sie <ulink url="https://spdx.org/licenses/"
>hier</ulink
> einsehen.</para
></listitem>
<listitem
><para
><userinput
>copyright</userinput
>: Ein <emphasis
>Feld</emphasis
> mit <emphasis
>Zeichenfolgen</emphasis
>, das die Autoren des Schemas angibt, mit <userinput
>SPDX-FileCopyrightText</userinput
> aus dem Standard <ulink url="https://spdx.dev/"
>SPDX-Lizenzkommunikationsformat</ulink
>. Dies ist optional.</para
></listitem>
</itemizedlist>
</para>
<programlisting
>"metadata": {
"name" : "Breeze Light",
"revision" : 5,
"copyright": [
"SPDX-FileCopyrightText: 2016 Volker Krause <vkrause@kde.org>",
"SPDX-FileCopyrightText: 2016 Dominik Haumann <dhaumann@kde.org>"
],
"license": "SPDX-License-Identifier: MIT"
}
</programlisting>
</sect3>
</sect2>
<sect2 id="color-themes-editing">
<title
>Farben im Detail:</title>
<para
>In diesem Abschnitt werden all verfügbaren Attribute und Einstellungen für Farben aufgeführt:</para>
<sect3 id="color-themes-editor-colors">
<title
>Editor-Farben</title>
<para
>Entspricht den Farben im <link linkend="kate-part"
>Editorbereichs</link
>.</para>
<para
>In der <link linkend="color-themes-json"
>&JSON;-Schemadatei</link
> ist der Wert des entsprechenden Schlüssels <userinput
>editor-colors</userinput
> ein <emphasis
>object</emphasis
> wobei jeder Schlüssel auf eine Attribut-Farbe des des Texteditors verweist. Hier sind <userinput
>alle verfügbaren Schlüssel notwendig</userinput
>, ihre Werte sind <userinput
>Zeichenfolgen</userinput
> mit hexadezimalen Farbcodes wie <quote
>#00B5CF</quote
>. </para>
<para
>In der <link linkend="color-themes-gui"
>&GUI; zum Verwalten von Schemata für KTextEditor</link
> können diese Attribute auf der Karteikarte <userinput
><guilabel
>Farben</guilabel
></userinput
> ändern. </para>
<para
>Folgende Schlüssel sind verfügbar: Die Schlüssel aus der <link linkend="color-themes-json"
>&JSON;-Datei</link
> sind <emphasis
>fett</emphasis
>, die Namen in der <link linkend="color-themes-gui"
>&GUI;</link
> sind in Klammern angegeben. </para>
<variablelist>
<varlistentry id="variable-prefcolors-colors-text-background">
<term
><guilabel
>Hintergrundfarben des Editors</guilabel
></term>
<listitem>
<variablelist>
<varlistentry id="variable-pref-colors-normal-text">
<term
><userinput
>BackgroundColor</userinput
> (<guilabel
>Textbereich</guilabel
>)</term>
<listitem
><para
>Dies ist die Standardhintergrundfarbe für den Editorbereich, die vorherrschende Farbe im Editorbereich.</para>
<mediaobject>
<imageobject
><imagedata format="PNG" fileref="editor-colors-BackgroundColor.png"/></imageobject>
<caption
><para
></para
></caption>
</mediaobject>
</listitem>
</varlistentry>
<varlistentry id="variable-pref-colors-selected-text">
<term
><userinput
>TextSelection</userinput
> (<guilabel
>Ausgewählter Text</guilabel
>)</term>
<listitem
><para
>Dies ist die Hintergrundfarbe für ausgewählten Text. </para>
<mediaobject>
<imageobject
><imagedata format="PNG" fileref="editor-colors-TextSelection.png"/></imageobject>
<caption
><para
></para
></caption>
</mediaobject>
</listitem>
</varlistentry>
<varlistentry id="variable-pref-colors-current-line">
<term
><userinput
>CurrentLine</userinput
> (<guilabel
>Aktuelle Zeile</guilabel
>)</term>
<listitem
><para
>Setzt die Farbe für die aktuelle Zeile. Die Farbe ist ein klein wenig anders als die normale Hintergrundfarbe, sodass Sie die aktuelle Zeile schnell wiederfinden. </para>
<mediaobject>
<imageobject
><imagedata format="PNG" fileref="editor-colors-CurrentLine.png"/></imageobject>
<caption
><para
></para
></caption>
</mediaobject>
</listitem>
</varlistentry>
<varlistentry id="variable-pref-colors-search-highlight">
<term
><userinput
>SearchHighlight</userinput
> (<guilabel
>Suchen-Hervorhebung</guilabel
>)</term>
<listitem
><para
>Die Farbe für den Text, der bei der letzten Suche gefunden wurde. </para>
<mediaobject>
<imageobject
><imagedata format="PNG" fileref="editor-colors-SearchHighlight.png"/></imageobject>
<caption
><para
></para
></caption>
</mediaobject>
</listitem>
</varlistentry>
<varlistentry id="variable-pref-colors-replace-highlight">
<term
><userinput
>ReplaceHighlight</userinput
> (<guilabel
>Ersetzen-Hervorhebung</guilabel
>)</term>
<listitem
><para
>Die Farbe für den Text, der bei der letzten Suche gefunden wurde.</para>
<mediaobject>
<imageobject
><imagedata format="PNG" fileref="editor-colors-ReplaceHighlight.png"/></imageobject>
<caption
><para
></para
></caption>
</mediaobject>
</listitem>
</varlistentry>
</variablelist>
</listitem>
</varlistentry>
<varlistentry id="variable-prefcolors-colors-icon-border">
<term
><guilabel
>Symbolrand</guilabel
></term>
<listitem>
<variablelist>
<varlistentry>
<term
><userinput
>IconBorder</userinput
> (<guilabel
>Hintergrundbereich</guilabel
>)</term>
<listitem
><para
>Diese Farbe wird für den Hintergrund des Symbolrandes und des Zeilennummerrandes an der linken Seite des Editorfensters verwendet. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><userinput
>LineNumbers</userinput
> (<guilabel
>Zeilennummern</guilabel
>)</term>
<listitem
><para
>Diese Farbe wird für die Zeilennummern am linken Rand des Editorbereiches verwendet.</para
></listitem>
</varlistentry>
<varlistentry>
<term
><userinput
>CurrentLineNumber</userinput
> (<guilabel
>Aktuelle Zeilennummer</guilabel
>)</term>
<listitem
><para
>Diese Farbe wird verwendet, um die Zeilennummer der aktuellen Zeile darzustellen und wird auf der linken Seite der Ansicht eingeblendet. Wenn Sie dies etwas anders als für<quote
>LineNumbers</quote
> einstellen, erleichtert das die aktuellen Zeile im Blick zu behalten. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><userinput
>Separator</userinput
> (<guilabel
>Trennlinie</guilabel
>)</term>
<listitem
><para
>Diese Farbe wird verwendet, um die senkrechte Linie zu zeichnen, die den Symbolrand vom Hintergrund des Textbereichs trennt.</para>
<mediaobject>
<imageobject
><imagedata format="PNG" fileref="editor-colors-IconBorder.png"/></imageobject>
<caption
><para
></para
></caption>
</mediaobject>
</listitem>
</varlistentry>
<varlistentry>
<term
><userinput
>WordWrapMarker</userinput
> (<guilabel
>Markierungen für Zeilenumbrüche</guilabel
>)</term>
<listitem
><para
>Diese Farbe wird benutzt, wenn am linken Rand angezeigt wird, dass Zeilen dynamisch umgebrochen und eingerückt sind, sowie auch für die Markierung von festen Zeilenumbrüchen.</para>
<mediaobject>
<imageobject
><imagedata format="PNG" fileref="editor-colors-WordWrapMarker.png"/></imageobject>
<caption
><para
></para
></caption>
</mediaobject>
</listitem>
</varlistentry>
<varlistentry>
<term
><userinput
>CodeFolding</userinput
> (<guilabel
>Quelltextausblendung</guilabel
>)</term>
<listitem
><para
>Mit dieser Farbe wird der Abschnitt des Quelltextes hervorgehoben, der beim Klicken auf den Pfeil zur Quelltextausblendung am linken Rand des Dokuments ausgeblendet wird Weitere Informationen finden Sie im Abschnitt <link linkend="advanced-editing-tools-code-folding"
>Quelltextausblendung</link
>.</para>
<mediaobject>
<imageobject
><imagedata format="PNG" fileref="editor-colors-CodeFolding.png"/></imageobject>
<caption
><para
></para
></caption>
</mediaobject>
</listitem>
</varlistentry>
<varlistentry>
<term
><userinput
>ModifiedLines</userinput
> (<guilabel
>Geänderte Zeilen</guilabel
>)</term>
<listitem
><para
>Mit dieser Farbe werden links neben dem Dokument Zeilen hervorgehoben, die in dieser Sitzung geändert wurden aber noch nicht gespeichert sind. Weitere Informationen finden Sie unter <xref linkend="kate-part-line-modification"/>.</para
></listitem>
</varlistentry>
<varlistentry>
<term
><userinput
>SavedLines</userinput
> (<guilabel
>Gespeicherte Zeilen</guilabel
>)</term>
<listitem
><para
>Mit dieser Farbe werden links neben dem Dokument Zeilen hervorgehoben, die in dieser Sitzung geändert wurden und bereits gespeichert sind. Weitere Informationen finden Sie unter <xref linkend="kate-part-line-modification"/>.</para>
<mediaobject>
<imageobject
><imagedata format="PNG" fileref="editor-colors-ModifiedLines.png"/></imageobject>
<caption
><para
></para
></caption>
</mediaobject>
</listitem>
</varlistentry>
</variablelist>
</listitem>
</varlistentry>
<varlistentry id="variable-prefcolors-colors-text-decorations">
<term
><guilabel
>Textdekorationen</guilabel
></term>
<listitem>
<variablelist>
<varlistentry>
<term
><userinput
>SpellChecking</userinput
> (<guilabel
>Linie für Rechtschreibfehler</guilabel
>)</term>
<listitem
><para
>Dies legt die Farbe der Linie fest, die zum Markieren von Rechtschreibfehlern verwendet wird.</para>
<mediaobject>
<imageobject
><imagedata format="PNG" fileref="editor-colors-SpellChecking.png"/></imageobject>
<caption
><para
></para
></caption>
</mediaobject>
</listitem>
</varlistentry>
<varlistentry>
<term
><userinput
>TabMarker</userinput
> (<guilabel
>Markierungen für Tabulatoren und Leerzeichen</guilabel
>)</term>
<listitem
><para
>Diese Farbe wird für dir Markierung von Tabulatoren und Leerzeichen verwendet, wenn Symbole für Wortzwischenräume angezeigt werden.</para>
<mediaobject>
<imageobject
><imagedata format="PNG" fileref="editor-colors-TabMarker.png"/></imageobject>
<caption
><para
></para
></caption>
</mediaobject>
</listitem>
</varlistentry>
<varlistentry>
<term
><userinput
>IndentationLine</userinput
> (<guilabel
>Einrückungslinie</guilabel
>)</term>
<listitem
><para
>Diese Farbe wird verwendet,um eine Linie links von eingerückten Textblöcken anzuzeigen, wenn <link linkend="appearance-general"
>diese Funktion aktiviert ist</link
>.</para>
<mediaobject>
<imageobject
><imagedata format="PNG" fileref="editor-colors-IndentationLine.png"/></imageobject>
<caption
><para
></para
></caption>
</mediaobject>
</listitem>
</varlistentry>
<varlistentry>
<term
><userinput
>BracketMatching</userinput
> (<guilabel
>Hervorhebung für Klammern</guilabel
>)</term>
<listitem
><para
>Diese Farbe wird für den Hintergrund von zusammengehörenden Klammern verwendet. </para>
<mediaobject>
<imageobject
><imagedata format="PNG" fileref="editor-colors-BracketMatching.png"/></imageobject>
<caption
><para
></para
></caption>
</mediaobject>
</listitem>
</varlistentry>
</variablelist>
</listitem>
</varlistentry>
<varlistentry id="variable-prefcolors-colors-marker-colors">
<term
><guilabel
>Markierungsfarben</guilabel
></term>
<listitem>
<variablelist>
<varlistentry>
<term
><userinput
>MarkBookmark</userinput
> (<guilabel
>Lesezeichen</guilabel
>)</term>
<listitem
><para
>Mit dieser Farbe werden Lesezeichen angezeigt. Beachten Sie, dass diese Farbe eine Deckkraft von 22 % (und 33 % für die aktuelle Zeile) in Bezug auf den Hintergrund hat. Weitere Informationen finden Sie unter <xref linkend="kate-part-bookmarks"/>.</para>
<mediaobject>
<imageobject
><imagedata format="PNG" fileref="editor-colors-MarkBookmark.png"/></imageobject>
<caption
><para
></para
></caption>
</mediaobject>
</listitem>
</varlistentry>
<varlistentry>
<term
><userinput
>MarkBreakpointActive</userinput
> (<guilabel
>Aktiver Haltepunkt</guilabel
>)</term>
<listitem
><para
>In dieser Farbe wird vom GDB-Modul ein aktiver Haltepunkt angezeigt, Beachten Sie, dass diese Farbe eine Deckkraft gegenüber dem Hintergrund hat. Weitere Informationen finden Sie in der Dokumentation zum <ulink url="help:/kate/kate-application-plugin-gdb.html"
>GDB-Modul</ulink
>.</para
></listitem>
</varlistentry>
<varlistentry>
<term
><userinput
>MarkBreakpointReached</userinput
> (<guilabel
>Erreichter Haltepunkt</guilabel
>)</term>
<listitem
><para
>In dieser Farbe wird vom GDB-Modul ein Haltepunkt angezeigt, der bei der Fehlersuche erreicht wurde. Beachten Sie, dass diese Farbe eine Deckkraft gegenüber dem Hintergrund hat. Weitere Informationen finden Sie in der Dokumentation zum <ulink url="help:/kate/kate-application-plugin-gdb.html"
>GDB-Modul</ulink
>.</para
></listitem>
</varlistentry>
<varlistentry>
<term
><userinput
>MarkBreakpointDisabled</userinput
> (<guilabel
>Nicht aktiver Haltepunkt</guilabel
>)</term>
<listitem
><para
>In dieser Farbe wird vom GDB-Modul ein nicht aktiver Haltepunkt angezeigt, Beachten Sie, dass diese Farbe eine Deckkraft gegenüber dem Hintergrund hat. Weitere Informationen finden Sie in der Dokumentation zum <ulink url="help:/kate/kate-application-plugin-gdb.html"
>GDB-Modul</ulink
>.</para
></listitem>
</varlistentry>
<varlistentry>
<term
><userinput
>MarkExecution</userinput
> (<guilabel
>Ausführung</guilabel
>)</term>
<listitem
><para
>In dieser Farbe wird vom GDB-Modul die zur Zeit ausgeführte Zeile angezeigt, Beachten Sie, dass diese Farbe eine Deckkraft gegenüber dem Hintergrund hat Weitere Informationen finden Sie in der Dokumentation zum <ulink url="help:/kate/kate-application-plugin-gdb.html"
>GDB-Modul</ulink
>.</para
></listitem>
</varlistentry>
<varlistentry>
<term
><userinput
>MarkWarning</userinput
> (<guilabel
>Warnung</guilabel
>)</term>
<listitem
><para
>Mit dieser Farbe wird vom Erstellen-Modul eine Zeile eingefärbt, für die Compiler eine Warnung ausgegeben hat. Beachten Sie, dass diese Farbe eine Deckkraft gegenüber dem Hintergrund hat. Weitere Informationen finden Sie in der Dokumentation zum <ulink url="help:/kate/kate-application-plugin-build.html"
>Erstellen-Modul</ulink
>.</para
></listitem>
</varlistentry>
<varlistentry>
<term
><userinput
>MarkError</userinput
> (<guilabel
>Fehler</guilabel
>)</term>
<listitem
><para
>Mit dieser Farbe wird vom Erstellen-Modul eine Zeile eingefärbt, für die Compiler einen Fehler ausgegeben hat Beachten Sie, dass diese Farbe eine Deckkraft gegenüber dem Hintergrund hat. Weitere Informationen finden Sie in der Dokumentation zum <ulink url="help:/kate/kate-application-plugin-build.html"
>Erstellen-Modul</ulink
>.</para
></listitem>
</varlistentry>
</variablelist>
</listitem>
</varlistentry>
<varlistentry id="variable-prefcolors-colors-text-templates-snippets">
<term
><guilabel
>Textvorlagen & Textbausteine</guilabel
></term>
<listitem>
<variablelist>
<varlistentry>
<term
><userinput
>TemplateBackground</userinput
> (<guilabel
>Hintergrund</guilabel
>)</term>
<listitem
><para
>In dieser Farbe wird der Hintergrund eines Textbausteins in &kate; angezeigt. Weitere Informationen dazu finden Sie in der <ulink url="help:/kate/kate-application-plugin-snippets.html"
>Dokumentation zu &kate;-Textbausteinen</ulink
>.</para
></listitem>
</varlistentry>
<varlistentry>
<term
><userinput
>TemplatePlaceholder</userinput
> (<guilabel
>Editierbarer Platzhalter</guilabel
>)</term>
<listitem
><para
>In dieser Farbe wird ein Platzhalter eines Textbausteins in &kate; angezeigt, den Sie zur manuellen Bearbeitung anklicken können. Weitere Informationen dazu finden Sie in der <ulink url="help:/kate/kate-application-plugin-snippetshtml"
>Dokumentation zu &kate;-Textbausteinen</ulink
>.</para
></listitem>
</varlistentry>
<varlistentry>
<term
><userinput
>TemplateFocusedPlaceholder</userinput
> (<guilabel
>Editierbarer Platzhalter mit Fokus</guilabel
>)</term>
<listitem
><para
>In dieser Farbe wird der gerade bearbeitete Platzhalter eines Textbausteins in &kate; angezeigt Weitere Informationen dazu finden Sie in der <ulink url="help:/kate/kate-application-plugin-snippets.html"
>Dokumentation zu &kate;-Textbausteinen</ulink
>.</para>
<mediaobject>
<imageobject
><imagedata format="PNG" fileref="editor-colors-Template.png"/></imageobject>
<caption
><para
></para
></caption>
</mediaobject>
</listitem>
</varlistentry>
<varlistentry>
<term
><userinput
>TemplateReadOnlyPlaceholder</userinput
> (<guilabel
>Nicht editierbarer Platzhalter</guilabel
>)</term>
<listitem
><para
>Diese Farbe wird im Textbausteinmodul von &kate; verwendet, um Platzhalter zu kennzeichnen, der nicht manuell editiert werden kann und zum Beispiel automatisch ausgefüllt wird. Weitere Informationen finden Sie in der Dokumentation zu <ulink url="help:/kate/kate-application-plugin-snippets.html"
>&kate;-Textbausteinen</ulink
>.</para>
<mediaobject>
<imageobject
><imagedata format="PNG" fileref="editor-colors-TemplateReadOnlyPlaceholder.png"/></imageobject>
<caption
><para
></para
></caption>
</mediaobject>
</listitem>
</varlistentry>
</variablelist>
</listitem>
</varlistentry>
</variablelist>
</sect3>
<sect3 id="color-themes-text-styles">
<title
>Standardtextstile</title>
<para
>Die Stile für Standardtext sind von den Stilen für Hervorhebungen abgeleitet, sodass der Editor Texte immer in der gleichen Form anzeigen kann. So sind zum Beispiel Kommentare unabhängig vom Textformat oder der Programmiersprache des Quelltextdokuments immer in der gleichen Farbe gekennzeichnet. </para>
<note>
<para
>Diese Textstile können von den <userinput
>Standardstilen</userinput
> in den Definitionen der &XML;-Dateien zur <link linkend="highlight"
>Syntaxhervorhebung</link
> referenziert werden. Zum Beispiel entspricht das Attribut <quote
>Normal</quote
> dem Attribut <quote
>dsNormal</quote
> in den &XML;-Dateien, und <quote
>DataType</quote
> entspricht <quote
>dsDataType</quote
>. Weitere Informationen finden Sie in der <xref linkend="kate-highlight-default-styles"/>Dokumentation zur Syntaxhervorhebung. </para>
</note>
<tip>
<para
>Achten Sie darauf, lesbare Farben mit gutem Kontrast zu wählen, besonders in Kombination mit dem <userinput
><link linkend="color-themes-editor-colors"
>Editor-Farben</link
></userinput
>. Siehe auch <xref linkend="color-themes-contrast"/>. </para>
</tip>
<para
>In der <link linkend="color-themes-json"
>&JSON;-Datei</link
>, hat der jeweilige Schlüssel <userinput
>text-styles</userinput
> als Wert ein <emphasis
>Objekt</emphasis
>, wobei jeder Schlüssel dem Namen eines <emphasis
>Standard-Textstils</emphasis
> in den in den Definitionen für die Syntaxhervorhebung entspricht. Hier sind <userinput
>alle verfügbaren Stil-Schlüsselwörter für Text obligatorisch </userinput
>, diese sind unten aufgeführt. </para>
<programlisting
>"text-styles": {
"Normal" : {
"text-color" : "#1f1c1b",
"selected-text-color" : "#ffffff",
"bold" : false,
"italic" : false,
"underline" : false,
"strike-through" : false
},
"Keyword" : {
"text-color" : "#1f1c1b",
"selected-text-color" : "#ffffff",
"bold" : true
},
"Function" : {
"text-color" : "#644a9b",
"selected-text-color" : "#452886"
},
<replaceable
>The other text style keys...</replaceable>
}
</programlisting>
<variablelist>
<varlistentry>
<term
>Jeder Schlüssel des <emphasis
>Standardtextstils</emphasis
> enthält ein &JSON;-Objekt als Wert, in dem Werte wie <emphasis
>color</emphasis
>, <emphasis
>bold</emphasis
>, <emphasis
>italic</emphasis
>, usw. angegeben werden. Es gibt folgende Schlüssel: </term>
<listitem>
<para
><userinput
>text-color</userinput
>: Eine <emphasis
>Zeichenfolge</emphasis
> mit der Textfarbe im hexadezimalen Farbcode. Dieser Schlüssel/Wert ist erforderlich.</para>
<para
><userinput
>selected-text-color</userinput
>: Die Textfarbe für ausgewählten Text hat in der Regel den gleichen Wert wie <quote
>text-color</quote
>. Wenn der Text ausgewählt ist, wird der Hintergrund durch den Wert von <link linkend="variable-pref-colors-selected-text"
>TextSelection</link
> in der <link linkend="color-themes-editor-colors"
>Editor-Farben</link
> definiert, daher sollte der Text einen guten Kontrast haben und mit diesem Hintergrund gut lesbar ist. Der Wert ist eine <emphasis
>Zeichenfolge</emphasis
> mit einem hexadezimalen Farbcode. Dieser Schlüssel/Wert muss angegeben werden.</para>
<para
><userinput
>bold</userinput
>: Ein <emphasis
>Boolescher Wert</emphasis
>, der festlegt, ob der Text in Fettschrift angezeigt wird. Dieser Schlüssel ist optional, der Standardwert ist <userinput
>false</userinput
>.</para>
<para
><userinput
>italic</userinput
>: Ein <emphasis
>Boolescher Wert</emphasis
>, der festlegt, ob der Text kursiv angezeigt wird. Dieser Schlüssel ist optional, der Standardwert ist <userinput
>false</userinput
>.</para>
<para
><userinput
>underline</userinput
>: Ein <emphasis
>Boolescher Wert</emphasis
>, der festlegt, ob der Text in unterstrichen angezeigt wird. Dieser Schlüssel ist optional, der Standardwert ist <userinput
>false</userinput
>.</para>
<para
><userinput
>strike-through</userinput
>: Ein <emphasis
>Boolescher Wert</emphasis
>, der festlegt, ob der Text in durchgestrichen angezeigt wird. Dieser Schlüssel ist optional, der Standardwert ist <userinput
>false</userinput
>.</para>
<para
><userinput
>background-color</userinput
>: Bestimmt die Hintergrundfarbe von Text und wird zum Beispiel in Warnungen (Alerts) in Kommentaren verwendet. Der Wert ist eine <emphasis
>Zeichenfolge</emphasis
> mit einem hexadezimalen Farbcode. Dieser Schlüssel ist optional, als Voreinstellung gibt es keine Hintergrundfarbe.</para>
<para
><userinput
>selected-background-color</userinput
>: Bestimmt die Hintergrundfarbe von ausgewähltem Text. Der Wert ist eine <emphasis
>Zeichenfolge</emphasis
> mit einem hexadezimalen Farbcode. Dieser Schlüssel ist optional, als Voreinstellung gibt es keine Hintergrundfarbe.</para>
</listitem>
</varlistentry>
</variablelist>
<para
>In <link linkend="color-themes-gui"
>der &GUI; zur Verwaltung der Farbthemen von KTextEditor</link
> können diese Attribute auf der Karteikarte <userinput
><guilabel
>Standardtextstile</guilabel
></userinput
> geändert werden. Der Name in der Liste der Stile verwendet den für das Element eingerichteten Stil, so dass Sie beim Ändern eines Stils sofort eine Vorschau erhalten. Jeder Stil ermöglicht die Auswahl gemeinsamer Attribute sowie von Vorder- und Hintergrundfarben. Um eine Hintergrundfarbe zu deaktivieren, klicken Sie mit der rechten Maustaste, um das Kontextmenü zu verwenden.</para>
<para
>Folgende Schlüssel für Textstile sind verfügbar: Die Schlüssel aus der <link linkend="color-themes-json"
>&JSON;-Datei</link
> sind <emphasis
>fett</emphasis
> geschrieben, die Namen in der <link linkend="color-themes-gui"
>&GUI;</link
> sind in Klammern angegeben, falls sie anders sind.</para>
<variablelist>
<varlistentry>
<term
><guilabel
>Normaltext & Quelltext</guilabel
></term>
<listitem>
<para
><userinput
>Normal</userinput
>: Standard-Textstil für normalen Text und Quelltext ohne besondere Hervorhebung.</para>
<para
><userinput
>Keyword</userinput
>: Textstil für eingebaute Sprach-Schlüsselwörter.</para>
<para
><userinput
>Function</userinput
>: Textstil für Funktionsaufrufe und -definitionen.</para>
<para
><userinput
>Variable</userinput
>: Textstil für Variablen, falls zutreffend. Zum Beispiel beginnen Variablen in PHP/Perl typischerweise mit einem <userinput
>$</userinput
>, also werden alle Bezeichner mit dem Muster <userinput
>$foo</userinput
> als Variable hervorgehoben.</para>
<para
><userinput
>ControlFlow</userinput
> (<guilabel
>Kontrollfluss</guilabel
>): Textstile für Schlüsselwörter den Programmablauf wie zum Beispiel <emphasis
>if</emphasis
>, <emphasis
>then</emphasis
>, <emphasis
>else</emphasis
>, <emphasis
>return</emphasis
>, <emphasis
>switch</emphasis
>, <emphasis
>break</emphasis
>, <emphasis
>yield</emphasis
>, <emphasis
>continue</emphasis
>, usw.</para>
<para
><userinput
>Operator</userinput
>: Textstil für Operatoren wie <userinput
>+</userinput
>, <userinput
>-</userinput
>, <userinput
>*</userinput
>, <userinput
>/</userinput
>, <userinput
>%</userinput
> usw.</para>
<para
><userinput
>BuiltIn</userinput
>
> (<guilabel
>Built-in</guilabel
>): Textstil eingebaute Funktionen, Klassen und Objekte.</para>
<para
><userinput
>Extension</userinput
>: Textstil für bekannte Erweiterungen wie zum Beispiel &Qt;-Klassen und Funktionen/Makros in C++ und Python oder Boost.</para>
<para
><userinput
>Preprocessor</userinput
>Textstil für Präprozessor-Anweisungen oder Makro-Definitionen.</para>
<para
><userinput
>Attribute</userinput
>: Textstil für Anmerkungen oder Attribute von Funktionen oder Objekten wie zum Beispiel <userinput
>@override</userinput
> in Java oder <userinput
>__declspec(...)</userinput
> und <userinput
>__attribute__((...))</userinput
> in C++.</para>
</listitem>
</varlistentry>
<varlistentry>
<term
><guilabel
>Zahlen, Typen & Konstanten</guilabel
></term>
<listitem>
<para
><userinput
>DataType</userinput
> (<guilabel
>Datentyp</guilabel
>): Textstil für eingebaute Datentypen wie <emphasis
>int</emphasis
>, <emphasis
>char</emphasis
>, <emphasis
>float</emphasis
>, <emphasis
>void</emphasis
>, <emphasis
>u64</emphasis
> usw.</para>
<para
><userinput
>DecVal</userinput
> (<guilabel
>Dezimal/Wert</guilabel
>): Textstil für Dezimalwerte.</para>
<para
><userinput
>BaseN</userinput
> (<guilabel
>Base-N Integer</guilabel
>): Textstil für Werte mit einer anderen Zahlenbasis als 10.</para>
<para
><userinput
>Float</userinput
> (<guilabel
>Fließkommazahl</guilabel
>): Textstil für Gleitkommawerte.</para>
<para
><userinput
>Constant</userinput
>: Textstile für Konstanten in Sprachen oder für benutzerdefinierte Konstanten wie zum Beispiel <emphasis
>True</emphasis
>, <emphasis
>False</emphasis
>, <emphasis
>None</emphasis
> in Python oder <emphasis
>nullptr</emphasis
> in C/C++; oder mathematische Konstanten wie <emphasis
>PI</emphasis
>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term
><guilabel
>Zeichenfolgen & Zeichen </guilabel
></term>
<listitem>
<para
><userinput
>Char</userinput
> (<guilabel
> Zeichen</guilabel
>): Textstil für einzelne Zeichen wie <userinput
>'x'</userinput
>.</para>
<para
><userinput
>SpecialChar</userinput
> (<guilabel
>Sonderzeichen</guilabel
>): Textstil für maskierte Zeichen in Zeichenfolgen, z.B. <quote
><userinput
>hello
</userinput
></quote
>, und andere Zeichen mit besonderer Bedeutung in Zeichenfolgen, z. B. Ersetzungen oder Regex-Operatoren.</para>
<para
><userinput
>String</userinput
>:Textstil für Zeichenfolgen wie <quote
><userinput
>Hallo Welt</userinput
></quote
>.</para>
<para
><userinput
>VerbatimString</userinput
> (<guilabel
>Wörtliche Zeichenfolge</guilabel
>): Textstile für wörtliche oder unveränderte Zeichenfolgen wie <userinput
>raw \backlash</userinput
> in Perl, CoffeeScript und Shells wie auch <userinput
>r'\raw'</userinput
> in Python oder wie in HERE-Dokumenten.</para>
<para
><userinput
>SpecialString</userinput
> (<guilabel
>Besondere Zeichenfolge</guilabel
>): Textstil für besondere Zeichenfolgen wie reguläre Ausdrücke in ECMAScript, im &latex;-Mathematikmodus, SQL, usw.</para>
<para
><userinput
>Import</userinput
> (<guilabel
>Importe, Module, Includes</guilabel
>): Textstil für Includes, Importe, Module oder &latex;-Pakete.</para>
</listitem>
</varlistentry>
<varlistentry>
<term
><guilabel
>Kommentare & Dokumentation</guilabel
></term>
<listitem>
<para
><userinput
>Comment</userinput
>: Textstile für normale Kommentare.</para>
<para
><userinput
>Documentation</userinput
>: Textstil für Kommentare zur API-Dokumentation wie z. B. <userinput
>/** doxygen comments */</userinput
> oder <userinput
>"""docstrings"""</userinput
>.</para>
<para
><userinput
>Annotation</userinput
>: Textstil für Anmerkungen in Kommentaren oder Dokumentationsbefehle wie <userinput
>@param</userinput
> in Doxygen oder JavaDoc.</para>
<para
><userinput
>KommentarVar</userinput
> (<guilabel
>Kommentar-Variable</guilabel
>): Textstil, der auf Variablennamen verweist, die in obigen Befehlen in einem Kommentar verwendet werden, wie z. B. <userinput
>foobar</userinput
> in <quote
><userinput
>@param foobar</userinput
></quote
> in Doxygen oder JavaDoc.</para>
<para
><userinput
>RegionMarker</userinput
> (<guilabel
>Bereichsmarkierungr</guilabel
>): Textstil für das Markieren von Bereichen, typischerweise definiert durch<userinput
>//BEGIN</userinput
> und <userinput
>//END</userinput
> in Kommentaren.</para>
<para
><userinput
>Information</userinput
>:Textstil für Notizen und Hinweise wie zum Beispiel Schlüsselwörter wie <userinput
>@note</userinput
> in Doxygen.</para>
<para
><userinput
>Warning</userinput
>: Textstil für Warnungen wie das Schlüsselwort <userinput
>@warning</userinput
> in Doxygen.</para>
<para
><userinput
>Alert</userinput
>: Textstil für spezielle Wörter in Kommentaren wie <userinput
>TODO</userinput
>, <userinput
>FIXME</userinput
>, <userinput
>XXXX</userinput
> und <userinput
>WARNING</userinput
>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term
><guilabel
>Verschiedenes</guilabel
></term>
<listitem>
<para
><userinput
>Error</userinput
>: Textstil für Hervorhebungen von Fehlern und für fehlerhafter Syntax.</para>
<para
><userinput
>Others</userinput
>: Textstile für Attribute, die nicht für einen der anderen Standardstile zutreffen.</para>
</listitem>
</varlistentry>
</variablelist>
</sect3>
<sect3 id="color-themes-custom-styles">
<title
>Benutzerdefinierte Textstile für Hervorhebungen</title>
<para
>Hier können Sie Textstile für eine bestimmte Syntaxhervorhebung festlegen Definition festlegen und damit den <userinput
>Standard-Textstil</userinput
> überschreiben wie in <link linkend="color-themes-text-styles"
>dem vorherigen Abschnitt</link
> beschrieben. </para>
<para
>In der <link linkend="color-themes-json"
>&JSON;-Schemadatei</link
> entspricht dies dem Schlüssel <userinput
>custom-styles</userinput
>, dessen Wert ein ein <emphasis
>Objekt</emphasis
> ist, wobei jeder Unterschema-Schlüssel mit dem <userinput
>Name einer Syntaxhervorhebungsdefinition</userinput
> korrespondiert. Sein Wert ist ein <emphasis
>Objekt</emphasis
>, bei dem jeder Schlüssel auf den <userinput
>Name des Stilattributs</userinput
> verweist, der in <link linkend="kate-highlight-sections"
>den <userinput
>itemData</userinput
>-Elementen</link
> der der Syntaxhervorhebung-s&XML;-Datei definiert ist. Der jeweilige Wert ist ein Unterobjekt mit den Schlüsseln <emphasis
>text-color</emphasis
>, <emphasis
>selected-text-color</emphasis
>, <emphasis
>bold</emphasis
>, <emphasis
>italic</emphasis
>, <emphasis
>underline</emphasis
>, <emphasis
>strike-through</emphasis
>, <emphasis
>background-color</emphasis
> und <emphasis
>selected-background-color</emphasis
>, definiert im <link linkend="color-themes-text-styles"
>vorherigen Abschnitt</link
>. Jeder dieser Werte ist optional, denn wenn sie nicht vorhanden sind, wird der in <userinput
>text-styles</userinput
> eingestellte Stil berücksichtigt. </para>
<para
>Zum Beispiel hat die Syntaxhervorhebungsdefinition für <quote
>ISO C++</quote
> in diesem Quelltext einen speziellen Textstil für die Attribute <quote
>Type Modifiers</quote
> und <quote
>Standard Classes</quote
>. In der zugehörigen &XML;-Datei <quote
>isocpp.xml</quote
> verwendet das definierte Attribut <quote
>Standard Classes</quote
> den Standardstil <userinput
>BuiltIn</userinput
> (oder dsBuiltIn). In diesem Attribut wird nur der Wert von <userinput
>text-color</userinput
> durch die neue Farbe <quote
>#6431b3</quote
> überschrieben . </para>
<programlisting
>"custom-styles": {
"ISO C++": {
"Standard Classes": {
"text-color": "#6431b3"
},
"Type Modifiers": {
"bold": true,
"selected-text-color": "#009183",
"text-color": "#00b5cf"
}
}
}
</programlisting>
<note>
<itemizedlist>
<listitem>
<para
>Sie sollten beachten, dass diese Textstile den Attributnamen zugeordnet sind, die in den &XML; -Syntaxhervorhebungsdateien definiert sind. Wenn eine XML-Datei aktualisiert und einige Attribute umbenannt oder entfernt werden, ist der im eigenen Schema definierte Stil nicht mehr gültig.</para>
</listitem>
<listitem>
<para
>Definitionen für Syntaxhervorhebung enthalten oft andere Definitionen. Die Syntaxhervorhebung für <quote
>QML</quote
> zum Beispiel enthält die Syntaxhervorhebung für <quote
>JavaScript</quote
>, da beide die gleichen Funktionen für die Hervorhebung verwenden.</para>
</listitem>
</itemizedlist>
</note>
<para
>In der <link linkend="color-themes-gui"
>&GUI; zum Verwalten von Schemata von KTextEditor</link
> können Sie diese Attribute auf der Karteikarte <userinput
><guilabel
>Textstile für Hervorhebungen</guilabel
></userinput
> verwalten. Als Voreinstellung wird die Hervorhebung des aktuellen Dokuments vom Editor eingestellt. Sie werden feststellen, dass viele Hervorhebungen andere Hervorhebungen enthalten, die durch Gruppen in der Stilliste repräsentiert werden. Zum Beispiel importieren die meisten Hervorhebungen die Hervorhebung <quote
>Alert</quote
> und viele Quelltextformate importieren die Hervorhebung <quote
>Doxygen</quote
>. </para>
</sect3>
</sect2>
<sect2 id="color-themes-gui">
<title
>Die &GUI; der Farbschemata</title>
<para
>Farbschemata lassen sich am einfachsten über die &GUI; im <link linkend="config-dialog"
><quote
>Einrichtungs</quote
>-Dialog</link
> von <ulink url="https://api.kde.org/frameworks/ktexteditor/html/"
>KTextEditor</ulink
>erstellen und bearbeiten. .Um diesen Dialog zu öffnen, wählen Sie <menuchoice
><guimenu
>Einstellungen</guimenu
> <guimenuitem
><replaceable
>Anwendung</replaceable
> einrichten ...</guimenuitem
></menuchoice
> aus der Menüleiste in Ihrer Textverarbeitung. Wählen Sie dann <guilabel
>Farbschema</guilabel
> in der Seitenleiste. </para>
<mediaobject>
<imageobject
><imagedata format="PNG" fileref="color-themes-gui-default-text-styles.png"/></imageobject>
<textobject
><phrase
>&kate;s Einrichtungsdialog mit der Bearbeitung von Farbschemata.</phrase
></textobject>
<caption
><para
>&kate;s Einrichtungsdialog mit der Bearbeitung von Farbschemata.</para>
</caption>
</mediaobject>
<para
>In diesem <link linkend="config-dialog"
>Dialog</link
> können Sie alle alle Farben in einem beliebigen Schema einstellen, neue Schemata erstellen/kopieren, löschen, sie in eine <userinput
>.theme</userinput
>-Datei im <link linkend="color-themes-json"
>&JSON; Format</link
> exportieren oder aus externen <userinput
>.theme</userinput
>-Dateien importieren. Jedes Schema hat Einstellungen für Textfarben und Stile. </para>
<para
>Die eingebauten Schemata können als Voreinstellung nicht geändert werden. Dazu müssen Sie sie unter einem neuen Namen kopieren.</para>
<para
>Um ein Farbschema dauerhaft in im Texteditor zu verwenden, müssen Sie es im Kombinationsfeld mit der Bezeichnung <guilabel
>Standardschema für <replaceable
>Anwendung</replaceable
></guilabel
> am unteren Rand des Dialogs auswählen und dann <guibutton
>Anwenden</guibutton
> oder <guibutton
>OK</guibutton
> drücken. Standardmäßig wird die <userinput
><guilabel
>Automatische Auswahl</guilabel
></userinput
> aktiviert. Damit wird ein geeigneteres Farbschema passend zum <emphasis
>&kde; &plasma;-Farbschema</emphasis
> für die Textbearbeitung gewählt. Normalerweise wird zwischen <quote
>Breeze-Hellt</quote
> und <quote
>Breeze-Dunkel</quote
> gewählt. </para>
<tip>
<para
>Sie können das globale Farbschema für &kde; im Modul <ulink url="help:/kcontrol/colors/"
><quote
>Farben</quote
> in den &systemsettings;</ulink
> anpassen. Für einzelne Anwendungen wie &kate; und &kdevelop; können Sie ein Schema auch mit <menuchoice
><guimenu
>Einstellungen</guimenu
><guisubmenu
>Farbschema</guisubmenu
></menuchoice
> ändern. </para>
</tip>
<sect3 id="color-themes-gui-new-theme">
<title
>Ein neues Schema erstellen</title>
<para
>Um ein neues Farbschema zu erstellen, müssen Sie zuerst ein vorhandenes Schema kopieren, Wählen Sie ein vorhandenes Schema aus, das Sie als Grundlage verwenden möchten wie <quote
>Breeze-Hell</quote
> oder <quote
>Breeze-Dunkel</quote
>. Klicken Sie dann auf <guibutton
>Kopieren</guibutton
> und geben den Namen für das neue Schema ein. </para>
<para
>Möchten Sie ein eingebautes oder nur lesbares Schema verändern, müssen Sie es zuerst unter einem anderen Namen kopieren.</para>
</sect3>
<sect3 id="color-themes-gui-import-export">
<title
>&JSON;-Schemadateien importieren oder exportieren</title>
<para
>Mit <guibutton
>Exportieren</guibutton
> können Sie ein ausgewähltes Schema einschließlich der eingebauten Schemata in eine <link linkend="color-themes-json"
>&JSON;-Datei</link
> mit der Dateierweiterung <userinput
>.theme</userinput
> exportieren. Damit öffnen Sie einen Dialog zum Speichern der Datei. Um eine Farbschema aus einer externen <link linkend="color-themes-json"
>&JSON;-Datei</link
> hinzuzufügen, drücken Sie den Knopf <guibutton
>Importieren</guibutton
> und wählen dann die <userinput
>.theme</userinput
>-Datei im Dialog. </para>
<tip>
<itemizedlist>
<listitem>
<para
>Wie <link linkend="color-themes-json-overview"
>oben erwähnt</link
>, werden benutzerdefinierte Farbschema-Dateien im Ordner <filename class="directory"
>org.kde.syntax-highlighting/themes/</filename
> abgelegt. Wenn Sie ein Farbschema kopieren oder neu erstellen, wird es automatisch dort gespeichert. Auch das Importieren oder Hinzufügen eines Farbschemas entspricht dem Kopieren einer externen <userinput
>.theme</userinput
>-Datei in diesen Ordner. KSyntaxHighlighting holt sich automatisch Schemadateien aus diesem Ordner.</para>
</listitem>
<listitem>
<para
>Wenn Sie ein von Ihnen erstelltes Schema veröffentlichen wollen, ist es unbedingt erforderlich, das <link linkend="color-themes-json-metadata"
>Metadaten</link
>-Objekt der <link linkend="color-themes-json"
>&JSON; Datei</link
> zu prüfen, eine passende Lizenz hinzuzufügen und die Revisionsnummer zu überprüfen.</para>
</listitem>
</itemizedlist>
</tip>
</sect3>
<sect3 id="color-themes-gui-editing">
<title
>Bearbeitung von Farbschemata</title>
<sect4 id="prefcolors-colors">
<title
>Farben</title>
<para
>Hier können die Farben des Editorbereichs angepasst werden. Mehr Informationen dazu finden Sie in <xref linkend="color-themes-editor-colors"/>.</para>
</sect4>
<sect4 id="prefcolors-normal-text-styles">
<title
>Standardtextstile</title>
<para
>Die Stile für Standardtext sind von den Stilen für Hervorhebungen abgeleitet, sodass der Editor Texte immer in der gleichen Form anzeigen kann. So sind zum Beispiel Kommentare unabhängig vom Textformat oder der Programmiersprache des Quelltextdokuments immer in der gleichen Farbe gekennzeichnet.</para>
<para
>Der Name in der Liste der Stile wird so wie Elemente im Dokument mit diesem Kontext angezeigt. So erhalten Sie sofort eine Vorschau beim Bearbeiten. </para>
<para
>Zu jedem Stil können Sie Eigenschaften sowie Vordergrund- und Hintergrundfarbe einstellen. Um eine Hintergrundfarbe zu löschen, benutzen Sie die &RMB;, um das Kontextmenü aufzurufen.</para>
<para
>Die Attribute in diesem Bereich werden in <xref linkend="color-themes-text-styles"/> erläutert.</para>
</sect4>
<sect4 id="prefcolors-highlighting-text-styles">
<title
>Textstile für Hervorhebungen</title>
<para
>Hier können Sie die Textstile für bestimmte Hervorhebungsdefinitionen einstellen. Der Editor startet diese Seite mit der Hervorhebung für das aktuelle Dokument. Wenn Sie an einer anderen Hervorhebungsdefinition Veränderungen vornehmen wollen, dann wählen Sie diese mit dem Auswahlfeld <guilabel
>Hervorhebung</guilabel
> aus. </para>
<para
>Der Name in der Liste der Stile wird so wie Elemente im Dokument mit diesem Kontext angezeigt. So erhalten Sie sofort eine Vorschau beim Bearbeiten. </para>
<para
>Zu jedem Stil können Sie Eigenschaften sowie Vordergrund- und Hintergrundfarbe einstellen. Um eine Hintergrundfarbe zu löschen, benutzen Sie die &RMB;, um das Kontextmenü aufzurufen. Zusätzlich gibt es noch ein Feld, das anzeigt, ob der eingestellte Stil der Standarddefinition entspricht - wenn nicht klicken Sie einfach auf dieses Feld, um die Standardeinstellungen herzustellen.</para>
<para
>Sie werden feststellen, dass viele Hervorhebungen andere Hervorhebungen enthalten, die in Untergruppen geordnet sind. So werden zum Beispiel die Hervorhebungen für Warnungen (Alerts) in die meisten Hervorhebungen importiert, viele Quelltexte importieren außerdem die Hervorhebungen für Doxygen. Wenn Sie Änderungen an den importierten Hervorhebungen vornehmen, dann werden nur die Stile im bearbeiteten Format beeinflusst. Andere Formate, die die gleichen Hervorhebungen importiert haben, werden nicht beeinflusst. </para>
</sect4>
</sect3>
</sect2>
<sect2 id="color-themes-tips-and-tricks">
<title
>Tipps & Tricks</title>
<sect3 id="color-themes-contrast">
<title
>Kontrast von Textfarben</title>
<para
>Ein wichtiger Aspekt bei der Arbeit mit Farbschemata ist die Wahl eines Textkontrasts, der die Lesbarkeit des Textes erleichtert, insbesondere in Kombination mit dem Hintergrund.</para>
<para
><userinput
>Kontrast</userinput
> ist eine Anwendung zur Überprüfung von Farbkontrasten. Damit erkennen Sie, ob die Kombinationen aus Textfarbe und Hintergrundfarbe lesbar und zugänglich sind, daher ist dies ein ausgezeichnetes Werkzeug für die Erstellung von Farbschemata.</para>
<para
>Sie können <userinput
>Kontrast</userinput
> von der <ulink url="https://apps.kde.org/de/kontrast"
>&kde;-Webseite mit Anwendungen</ulink
> oder als <ulink url="https://flathub.org/apps/details/org.kde.kontrast"
>Flatpak-Paket auf Flathub</ulink
> herunterladen (nur für GNU/Linux).</para>
<para
>Die GNOME-Anwendung <userinput
>Contrast</userinput
> funktioniert ähnlich. Sie können sie als <ulink url="https://flathub.org/apps/details/org.kde.kontrast"
>Flatpak-Paket auf Flathub</ulink
> herunterladen (nur für GNU/Linux).</para>
</sect3>
<sect3 id="color-themes-tips-and-tricks-consistency">
<title
>Vorschläge zur Konsistenz bei der Syntaxhervorhebung</title>
<para
>KSyntaxHighlighting enthält <ulink url="https://kate-editor.org/syntax/"
>mehr als 300 Definitionen für Syntaxhervorhebung</ulink
>, daher sollten Sie dafür sorgen, dass Ihr neues Schema in allen Definitionen der Syntaxhervorhebung gut aussieht. Die eingebauten Farbschemata haben folgende Gemeinsamkeiten, die Sie beachten sollten, um eine eine korrekte Darstellung aller Definitionen der Syntaxhervorhebung zu erhalten:</para>
<itemizedlist>
<listitem
><para
>Verwenden Sie Fettschrift für <quote
>Keyword</quote
> und <quote
>ControlFlow</quote
> als <link linkend="color-themes-text-styles"
>Textstile</link
>.</para
></listitem>
<listitem
><para
>Benutzen Sie keine Hintergrundfarbe in einem <link linkend="color-themes-text-styles"
>Textstil</link
>, außer bei <quote
>Alert</quote
> und <quote
>RegionMarker</quote
>.</para
></listitem>
</itemizedlist>
<para
>Die meisten der Syntaxhervorhebungen sind für die Standarddesigns <quote
>Breeze-Hell</quote
> und <quote
>Breeze-Dunkel</quote
> optimiert.Daher sollten Sie für die Einheitlichkeit ähnlicher Farben verwenden wie in den <link linkend="color-themes-text-styles"
>Textstilen</link
>, wie <emphasis
>grün</emphasis
> für <quote
>Präprozessor</quote
> und <quote
>Andere</quote
>, <emphasis
>blau</emphasis
> für <quote
>Datentyp</quote
> und <quote
>Attribut</quote
> oder <emphasis
>purpur</emphasis
> für <quote
>Funktion</quote
>.</para>
<para
>Beachten Sie, dass diese Empfehlungen nicht zwingend für das Erstellen und Veröffentlichen eines Schemas sind.</para>
</sect3>
</sect2>
</sect1>
<sect1 id="dev-scripting">
<title
>Scripting mit &javascript;</title>
<para
>Die Editorkomponente von &kappname; kann durch Skripte erweitert werden. Als Skriptsprache wird ECMAScript verwendet, das auch unter dem Namen &javascript; bekannt ist. In &kappname; können zwei Arten von Skripten benutzt werden: Einrückungs- und Befehlszeilenskripte. </para>
<sect2 id="dev-scripting-indentation">
<title
>Einrückungsskripte</title>
<para
>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. </para>
<para
>Die folgenden Abschnitte beschreiben Schritt für Schritt, wie das Gerüst für ein einfaches Einrückungsskript entsteht. Zuerst wird eine neue <filename
>*.js</filename
>-Datei ⪚ mit dem Namen <filename
>$<envar
>XDG_DATA_HOME</envar
>/katepart5/script/indentation</filename
> erzeugt. Darin wird die Umgebungsvariable <envar
>XDG_DATA_HOME</envar
> normalerweise entweder zu <filename
>~/.local</filename
> oder <filename
>~/.local/share</filename
> erweitert. </para>
<para
>Auf &Windows;-Systemen finden Sie diese Dateien unter <filename
>%USERPROFILE%\AppData\Local\katepart5\indentation</filename
>. Dabei ist <replaceable
>%USER%</replaceable
> normalerweise <filename
>C:\\Users\\<replaceable
>user</replaceable
></filename
>.</para>
<sect3 id="dev-scripting-indentation-header">
<title
>Der Vorspann des Einrückungsskripts</title>
<para
>Der Vorspann der Datei <filename
>javascript.js</filename
> ist als &JSON; am Anfang des Dokumentes eingebettet und hat folgende Form: <programlisting>
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
</programlisting
> Jede Zeile wird jetzt im Detail erklärt: <itemizedlist>
<listitem
><para
><literal
>name</literal
> [erforderlich]: Dies ist der Name des Skripts, der im Menü <menuchoice
><guimenu
>Extras</guimenu
><guimenuitem
>Einrückung</guimenuitem
></menuchoice
> und im Einrichtungsdialog angezeigt wird. </para
></listitem>
<listitem
><para
><literal
>author</literal
> [optional]: Der Name des Autors und weitere Kontaktinformationen. </para
></listitem>
<listitem
><para
><literal
>license</literal
> [optional]: Kurzform der Lizenz, wie zum Beispiel BSD-Lizenz oder LGPLv3. </para
></listitem>
<listitem
><para
><literal
>revision</literal
> [erforderlich]: Die Version des Skripts, sie sollte bei jeder Änderung des Skripts erhöht werden. </para
></listitem>
<listitem
><para
><literal
>kate-version</literal
> [required]: Minimal erforderliche &kappname;-Version. </para
></listitem>
<listitem
><para
><literal
>required-syntax-style</literal
> [optional]: Der erforderliche Sytaxstil, der zum angebenen <literal
>style</literal
> 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 <quote
>nicht definiertes Verhalten</quote
> 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 <filename
>ruby.js</filename
> und <filename
>ruby.xml</filename
> benutzt. </para
></listitem>
<listitem
><para
><literal
>indent-languages</literal
> [optional]: &JSON;-Feld von Syntaxstilen, die das Skript richtig einrücken kann, ⪚: <literal
>["c++", "java"]</literal
>. </para
></listitem>
<listitem
><para
><literal
>priority</literal
> [optional]: Wenn es mehrere Einrückungsskripte für eine bestimmte hervorgehobene Datei gibt, bestimmt die Priorität, welches Skript als Standard verwendet wird. </para
></listitem>
</itemizedlist>
</para>
</sect3>
<sect3 id="dev-scripting-indentation-body">
<title
>Der Quelltext des Einrückungsskripts</title>
<para
>Nachdem der Vorspann beschrieben wurde, erklärt dieser Abschnitt wie das Einrückungsskript selbst funktioniert. Die Basisvorlage für den Quelltext sieht so aus:<programlisting>
// benötigt die Bibliothek „katepart js“ ⪚ 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 <menuchoice
><guimenu
>Extras</guimenu
><guimenuitem
>Ausrichten</guimenuitem
></menuchoice>
// gewählt wird, ist die Variable ch leer, d. h. ch == ''.
//
// siehe auch: Skript-API
return -2;
}
</programlisting
> Die Funktion <function
>indent()</function
> hat drei Argumente: <itemizedlist
> <listitem
><para
><literal
>line</literal
>: die Zeile die eingerückt werden soll</para
></listitem
> <listitem
><para
><literal
>indentWidth</literal
>: die Einrückungstiefe mit der Anzahl der Leerzeichen</para
></listitem
><listitem
><para
><literal
>ch</literal
>: entweder das Zeichen für Zeilenumbruch (<literal
>ch == '\n'</literal
>), ein in <literal
>triggerCharacters</literal
> festgelegtes Zeichen oder ein leeres Zeichen, wenn der Benutzer die Aktion <menuchoice
><guimenu
>Extras</guimenu
><guimenuitem
>Ausrichten</guimenuitem
></menuchoice
> aufgerufen hat.</para
></listitem
> </itemizedlist
> Der Rückgabewert der Funktion <function
>indent()</function
> bestimmt, wie die Zeile eingerückt wird. Ist dieser Wert eine Ganze Zahl, wird sie wie folgt interpretiert: <itemizedlist
> <listitem
><para
>Rückgabewert <literal
>-2</literal
>: keine Aktion</para
></listitem
> <listitem
><para
>Rückgabewert <literal
>-1</literal
>: Einrückung beibehalten (sucht nach vorherigen nicht leeren Zeilen)</para
></listitem
> <listitem
><para
>Rückgabewert <literal
> 0</literal
>: eine Zahl >= 0 gibt die Anzahl der Leerzeichen zum Einrücken an</para
></listitem
> </itemizedlist
> Alternativ kann ein Feld mit zwei Elementen zurückgegeben werden: <itemizedlist
> <listitem
><para
><literal
>Rückgabewert [ indent, align ];</literal
></para
></listitem
> </itemizedlist
> 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 <quote
>Ausrichtung</quote
>. 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 <quote
>Mischmodus</quote
> bezeichnet. </para>
<para
>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: <programlisting>
1: <tab><tab>foobar("hello",
2: <tab><tab>......."world");
</programlisting
> Beim Einrücken der Zeile 2 gibt die Funktion <function
>indent()</function
> [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. </para>
<para
>In der Standardinstallation von &kde; wird &kappname; mit einigen Einrückungsskripten installiert. Die entsprechenden &javascript;-Quelltexte finden Sie unter <filename
>$<envar
>XDG_DATA_DIRS</envar
>/katepart5/script/indentation</filename
>.</para>
<para
>Auf &Windows;-Systemen finden Sie diese Dateien unter <filename
>%USERPROFILE%\AppData\Local\katepart5\indentation</filename
>. Dabei ist <replaceable
>%USER%</replaceable
> normalerweise <filename
>C:\\Users\\<replaceable
>user</replaceable
></filename
>. </para>
<para
>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 <command
>reload-scripts</command
> ein. </para>
<para
>Wenn Sie nützliche Skripte entwickelt haben, sollten Sie darüber nachdenken, sie zum &kappname;-Projekt hinzufügen. Schreiben Sie dazu an die <ulink url="mailto:kwrite-devel@kde.org"
>Mailingliste</ulink
>. </para>
</sect3>
</sect2>
<sect2 id="dev-scripting-command-line">
<title
>Befehlszeilenskripte</title>
<para
>Da nicht alle gewünschten Funktionen in &kappname; eingebaut werden können, ist es möglich, kleine Hilfsskripte für die schnelle Änderung von Textes mit der <link linkend="advanced-editing-tools-commandline"
>eingebauten Befehlszeile</link
> auszuführen. Der Befehl <command
>sort</command
> ist zum Beispiel als Skript geschrieben. Dieser Abschnitt erklärt, wie <filename
>*.js</filename
>-Dateien erstellt werden, um die Fähigkeiten von &kappname; mit beliebigen Hilfsskripten zu erweitern. </para>
<para
>Befehlszeilenskripte werden im gleichen Ordner wie Einrückungsskripte gespeichert. Zuerst erstellen Sie eine neue <filename
>*.js</filename
>-Datei namens <filename
>myutils.js</filename
> im lokalen persönlichen Ordner <filename
>$<envar
>XDG_DATA_HOME</envar
>/katepart5/script/commands</filename
>. Darin wird die Umgebungsvariable <envar
>XDG_DATA_HOME</envar
> normalerweise entweder zu <filename
>~/.local</filename
> oder <filename
>~/.local/share</filename
> erweitert.</para>
<para
>Auf &Windows;-Systemen finden Sie diese Dateien unter <filename
>%USERPROFILE%\AppData\Local\katepart5\commands</filename
>. Dabei ist <replaceable
>%USERPROFILE%</replaceable
> normalerweise <filename
>C:\\Users\\<replaceable
>user</replaceable
></filename
>. </para>
<sect3 id="dev-scripting-command-line-header">
<title
>Der Vorspann des Befehlszeilenskripts</title>
<para
>Der Vorspann jedes Befehlszeilen-Skripts ist in der &JSON;-Datei am Anfang des Skripts so eingebettet: <programlisting>
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
</programlisting
> Jede Zeile wird jetzt im Detail erklärt: <itemizedlist>
<listitem
><para
><literal
>author</literal
> [optional]: Der Name des Autors und weitere Kontaktinformationen.</para
></listitem>
<listitem
><para
><literal
>license</literal
> [optional]: Kurzform der Lizenz, wie zum Beispiel BSD-Lizenz oder LGPLv2.</para
></listitem>
<listitem
><para
><literal
>revision</literal
> [erforderlich]: Die Version des Skripts, sie sollte bei jeder Änderung des Skripts erhöht werden.</para
></listitem>
<listitem
><para
><literal
>kate-version</literal
> [required]: Minimal erforderliche &kappname;-Version.</para
></listitem>
<listitem
><para
><literal
>functions</literal
> [erforderlich]: &JSON;-Feld der Befehle im Skript.</para
></listitem>
<listitem
><para
><literal
>actions</literal
> [optional]: &JSON;-Feld mit &JSON;-Objekten, das die Aktionen festlegt, die im Anwendungsmenü erscheinen sollen. Weitergehende Informationen finden Sie im Abschnitt <link linkend="advanced-editing-tools-commandline"
>Kurzbefehle festlegen</link
>.</para
></listitem>
</itemizedlist>
</para>
<para
>Da der Inhalt von <literal
>functions</literal
> ein &JSON;-Feld ist, kann ein einzelnes Skript eine beliebige Anzahl von Befehlen für die Befehlszeile enthalten. Jede Funktion ist durch die <link linkend="advanced-editing-tools-commandline"
>eingebaute Befehlszeile</link
> in &kappname; verfügbar. </para>
</sect3>
<sect3 id="dev-scripting-command-line-body">
<title
>Der Quelltext des Skripts</title>
<para
>Alle im Vorspann aufgeführten Funktionen müssen im Skript implementiert werden. Im oben gezeigten Skript müssen zum Beispiel die beiden Funktionen <command
>sort</command
> und <command
>moveLinesDown</command
> implementiert werden. Alle Funktionen haben folgende Syntax: <programlisting
>// benötigt die Bibliothek „katepart js“ ⪚ range.js wenn Range benutzt wird
require ("range.js");
function <name>(arg1, arg2, ...)
{
// ... Implementierung, siehe auch: Skript-API
}
</programlisting>
</para>
<para
>Argumente in der Befehlszeile werden der Funktion als <parameter
>arg1</parameter
>, <parameter
>arg2</parameter
> &etc; übergeben. Um für jeden Befehl eine Dokumentation zu Verfügung zu stellen, verwenden Sie die Funktion „<function
>help</function
>“ wie im folgenden Beispiel: <programlisting>
function help(cmd)
{
if (cmd == "sort") {
return i18n("Sortiert den ausgewählten Text.");
} else if (cmd == "...") {
// ...
}
}
</programlisting
> Durch den Aufruf von <command
>help sort</command
> auf der Befehlszeile wird dann diese Hilfefunktion mit dem Argument <parameter
>cmd</parameter
> für den verwendeten Befehl benutzt, &ie; mit <parameter
>cmd == "sort"</parameter
>. zeigt &kate; den zurückgegebenen Text als Hilfe für den Benutzer an. Denken Sie daran, die Texte zu <link linkend="dev-scripting-api-i18n"
>übersetzen </link
>. </para>
<para
>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 <command
>reload-scripts</command
> ein. </para>
<sect4 id="dev-scripting-command-line-shortcuts">
<title
>Kurzbefehle festlegen</title>
<para
>Das Skript braucht einen passenden Skript-Header, der die Skripte über das Anwendungsmenü verfügbar macht. Im Beispiel erscheinen die Funktionen <literal
>sort</literal
> und <literal
>moveLinesDown</literal
> im Menü. Das wird durch den folgenden Skript-Header erreicht: <programlisting>
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"
}
]
};
</programlisting
> Die Felder für eine Aktion lauten wie folgt: <itemizedlist>
<listitem
><para
><literal
>function</literal
> [erforderlich]: Die Funktion, die im Menü <menuchoice
><guimenu
>Extras</guimenu
> <guisubmenu
>Skripte</guisubmenu
></menuchoice
> erscheint.</para
></listitem>
<listitem
><para
><literal
>name</literal
> [erforderlich]: Der Text, der im Menü Skript angezeigt wird.</para
></listitem>
<listitem
><para
><literal
>icon</literal
> [optional]: Dieses Symbol erscheint neben dem Text im Menü. Alle &kde;-Symbolnamen können hier benutzt werden.</para
></listitem>
<listitem
><para
><literal
>category</literal
> [optional]: Wenn eine Kategorie angegeben ist, dann erscheint das Skript in einem Untermenü.</para
></listitem>
<listitem
><para
><literal
>shortcut</literal
> [optional]: Der hier angegebene Kurzbefehl ist der Standard. Beispiel: <literal
>Ctrl+Alt+T</literal
>. Sehen Sie in der <ulink url="https://doc.qt.io/qt-5/qt.html#Key-enum"
>&Qt;-Dokumentation</ulink
> für weitere Einzelheiten nach.</para
></listitem>
<listitem
><para
><literal
>interactive</literal
> [optional]: Wenn das Skript Benutzereingaben auf der Befehlszeile braucht, dann setzen Sie diesen Parameter auf <literal
>true</literal
>.</para
></listitem>
</itemizedlist>
</para>
<para
>Wenn Sie nützliche Skripte entwickelt haben, sollten Sie darüber nachdenken, sie zum &kappname;-Projekt hinzufügen. Schreiben Sie dazu an die <ulink url="mailto:kwrite-devel@kde.org"
>Mailingliste</ulink
>. </para>
</sect4>
</sect3>
</sect2>
<sect2 id="dev-scripting-api">
<title
>Skript-API</title>
<para
>Die hier vorgestellte Programmierschnittstelle (API) ist in allen Skripten verfügbar, &ie; in Einrückungs- und Befehlszeilenskripten. Die Klassen <classname
>Cursor</classname
> und <classname
>Range</classname
> werden durch die Bibliotheksdateien in <filename
>$<envar
>XDG_DATA_DIRS</envar
>/katepart5/libraries</filename
> bereit gestellt. Wenn Sie sie in Ihren Skripten verwenden möchten, was für einige der Funktionen <classname
>Document</classname
> oder <classname
>View</classname
> erforderlich ist, fügen Sie bitte die benötigte Bibliothek wie folgt ein: <programlisting
>// benötigt die Bibliothek „katepart js“ ⪚ range.js wenn Range benutzt wird
require ("range.js");
</programlisting>
</para>
<para
>Um die Standard-Skript-API mit eigenen Funktionen und Prototypen zu erweitern, erzeugen Sie eine neue Datei im lokalen Einrichtungsordner für &kde; <filename
>$<envar
>XDG_DATA_HOME</envar
>/katepart5/libraries</filename
> und schließen Sie sie in Ihr Skript mit folgendem Befehl ein: <programlisting
>require ("myscriptnamehere.js");
</programlisting>
</para>
<para
>Auf &Windows;-Systemen finden Sie diese Dateien unter <filename
>%USERPROFILE%\AppData\Local\katepart5\libraries</filename
>. Dabei ist <replaceable
>%USERPROFILE%</replaceable
> normalerweise <filename
>C:\\Users\\<replaceable
>user</replaceable
></filename
>.</para>
<para
>Um vorhandene Prototypen wie <classname
>Cursor</classname
> oder <classname
>Range</classname
> zu erweitern, wird empfohlen, <emphasis
>nicht</emphasis
> die globalen <filename
>*.js</filename
>-Dateien zu ändern. Ändern Sie stattdessen den <classname
>Cursor</classname
>-Prototyp in &javascript;, nachdem <filename
>cursor.js</filename
> in Ihrem Skript mit <literal
>require</literal
> eingefügt ist. </para>
<sect3 id="dev-scripting-api-prototypes">
<title
>Cursor und Bereiche</title>
<para
>Da &kappname; ein Texteditor ist, basiert die Skript-API soweit möglich auf Cursor und Bereichen. Ein Cursor ist ein einfaches Tupel <literal
>(Zeile, Spalte)</literal
> 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. </para>
<sect4 id="dev-scripting-api-cursors">
<title
>Der Cursor-Prototyp</title>
<variablelist
><varlistentry>
<term
><synopsis
>Cursor();
</synopsis
></term>
<listitem
><para
>Konstruktor. Gibt einen Cursor an der Position <literal
>(0, 0)</literal
> zurück.</para>
<para
>Beispiel: <function
>var cursor = new Cursor();</function
> </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>Cursor(<parameter
>int <replaceable
>zeile</replaceable
></parameter
>, <parameter
>int <replaceable
>spalte</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Konstruktor. Gibt einen Cursor an der Position <literal
>(zeile, spalte)</literal
> zurück. </para>
<para
>Beispiel: <function
>var cursor = new Cursor(3, 42);</function
> </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>Cursor(<parameter
>Cursor <replaceable
>other</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Kopierkonstruktor. Gibt die Kopie des Cursors <replaceable
>other</replaceable
> zurück. </para>
<para
>Beispiel: <function
>var copy = new Cursor(cursor);</function
> </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>Cursor Cursor.clone();
</synopsis
></term>
<listitem
><para
>Gibt einen Klon des Cursors zurück.</para>
<para
>Beispiel: <function
>var clone = cursor.clone();</function
> </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>Cursor.setPosition(<parameter
>int <replaceable
>zeile</replaceable
></parameter
>, <parameter
>int <replaceable
>spalte</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Setzt die Cursor-Position auf <replaceable
>zeile</replaceable
> und <replaceable
>spalte</replaceable
>.</para>
<para
>Since: &kde; 4.11 </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>bool Cursor.isValid();
</synopsis
></term>
<listitem
><para
>Überprüft, ob der Cursor gültig ist. Ein Cursor ist ungültig, wenn die Zeile und oder die Spalte den Wert <literal
>-1</literal
> haben. </para>
<para
>Beispiel: <function
>var valid = cursor.isValid();</function
> </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>Cursor Cursor.invalid();
</synopsis
></term>
<listitem
><para
>Gibt einen neuen ungültigen Cursor an der Position <literal
>(-1, -1)</literal
> zurück. </para>
<para
>Beispiel: <function
>var invalidCursor = cursor.invalid();</function
> </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>int Cursor.compareTo(<parameter
>Cursor <replaceable
>other</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Vergleicht diesen Cursor mit dem Cursor <replaceable
>other</replaceable
>. Gibt folgende Werte zurück: <itemizedlist>
<listitem
><para
><literal
>-1</literal
>, wenn dieser Cursor sich vor dem Cursor <replaceable
>other</replaceable
> befindet,</para
></listitem>
<listitem
><para
><literal
>0</literal
>, wenn beide Cursor an der gleichen Stelle stehen und </para
></listitem>
<listitem
><para
><literal
>+1</literal
>, wenn dieser Cursor sich hinter dem Cursor <replaceable
>other</replaceable
> befindet.</para
></listitem>
</itemizedlist>
</para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>bool Cursor.equals(<parameter
>Cursor <replaceable
>other</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Gibt <literal
>true</literal
> zurück, wenn dieser Cursor und der Cursor <replaceable
>other</replaceable
> gleich sind, sonst <literal
>false</literal
>. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>String Cursor.toString();
</synopsis
></term>
<listitem
><para
>Gibt den Cursor als Zeichenfolge in der Form <quote
><literal
>Cursor(zeile, spalte)</literal
></quote
> zurück. </para
></listitem>
</varlistentry
></variablelist>
</sect4>
<sect4 id="dev-scripting-api-ranges">
<title
>Der Bereich-Prototyp</title>
<variablelist
><varlistentry>
<term
><synopsis
>Range();
</synopsis
></term>
<listitem
><para
>Konstruktor. Der Aufruf <literal
>new Range()</literal
> gibt einen Bereich von (0, 0) - (0, 0) zurück. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>Range(<parameter
>Cursor <replaceable
>start</replaceable
></parameter
>, <parameter
>Cursor <replaceable
>ende</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Konstruktor. Der Aufruf <literal
>new Range(<replaceable
>start</replaceable
>, <replaceable
>end</replaceable
>)</literal
> gibt einen Bereich von (<replaceable
>start</replaceable
>, <replaceable
>ende</replaceable
>) zurück. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>Range(<parameter
>int <replaceable
>startZeile</replaceable
></parameter
>, <parameter
>int <replaceable
>startspalte</replaceable
></parameter
>, <parameter
>int <replaceable
>endZeile</replaceable
></parameter
>, <parameter
>int <replaceable
>endSpalte</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Konstruktor. Der Aufruf von <literal
>new Range(<replaceable
>startZeile</replaceable
>, <replaceable
>startSpalte</replaceable
>, <replaceable
>endZeile</replaceable
>, <replaceable
>endSpalte</replaceable
>)</literal
>. Gibt den Bereich von (<replaceable
>startZeile</replaceable
>, <replaceable
>startSpalte</replaceable
>) bis (<replaceable
>endZeile</replaceable
>, <replaceable
>endSpalte</replaceable
>) zurück. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>Range(<parameter
>Range <replaceable
>other</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Kopierkonstruktor. Gibt eine Kopie von Range <replaceable
>other</replaceable
> zurück. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>Range Range.clone();
</synopsis
></term>
<listitem
><para
>Gibt einen Klon des Bereichs zurück. </para>
<para
>Beispiel: <function
>var clone = range.clone();</function
> </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>bool Range.isEmpty();
</synopsis
></term>
<listitem
><para
>Gibt <literal
>true</literal
> zurück, wenn der Start- und der End-Cursor gleich sind. </para>
<para
>Beispiel: <function
>var empty = range.isEmpty();</function
> </para>
<para
>Since: &kde; 4.11 </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>bool Range.isValid();
</synopsis
></term>
<listitem
><para
>Gibt <literal
>true</literal
> zurück, wenn sowohl Start- als auch End-Cursor gültig sind, sonst <literal
>false</literal
>. </para>
<para
>Beispiel: <function
>var valid = range.isValid();</function
> </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>Range Range.invalid();
</synopsis
></term>
<listitem
><para
>Gibt den Bereich von (-1, -1) bis (-1, -1) zurück. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>bool Range.contains(<parameter
>Cursor <replaceable
>cursor</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Gibt <literal
>true</literal
> zurück, wenn dieser Bereich die Cursor-Position enthält, sonst <literal
>false</literal
>. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>bool Range.contains(<parameter
>Range <replaceable
>other</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Gibt <literal
>true</literal
> zurück, wenn dieser Bereich den Bereich <replaceable
>other</replaceable
> enthält, sonst <literal
>false</literal
>. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>bool Range.containsColumn(<parameter
>int <replaceable
>spalte</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Gibt <literal
>true</literal
> zurück, wenn <replaceable
>spalte</replaceable
> in dem halboffenen Intervall <literal
>[start.spalte, end.spalte)</literal
> liegt, sonst <literal
>false</literal
>. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>bool Range.containsLine(<parameter
>int <replaceable
>zeile</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Gibt <literal
>true</literal
> zurück, wenn <replaceable
>zeile</replaceable
> in dem halboffenen Intervall <literal
>[start.zeile, end.zeile)</literal
> liegt, sonst <literal
>false</literal
>. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>bool Range.overlaps(<parameter
>Range <replaceable
>other</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Gibt <literal
>true</literal
> zurück, wenn dieser Bereich und der Bereich <replaceable
>other</replaceable
> sich überlappen, sonst <literal
>false</literal
>. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>bool Range.overlapsLine(<parameter
>int <replaceable
>zeile</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Gibt <literal
>true</literal
> zurück, wenn <replaceable
>zeile</replaceable
> in dem Intervall <literal
>[start.zeile, end.zeile]</literal
> liegt, sonst <literal
>false</literal
>. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>bool Range.overlapsColumn(<parameter
>int <replaceable
>spalte</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Gibt <literal
>true</literal
> zurück, wenn <replaceable
>spalte</replaceable
> in dem Intervall <literal
>[start.spalte, end.spalte]</literal
> liegt, sonst <literal
>false</literal
>. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>bool Range.onSingleLine();
</synopsis
></term>
<listitem
><para
>Gibt <literal
>true</literal
> zurück, wenn der Bereich in der gleichen Zeile beginnt und endet, &ie; wenn <replaceable
>Range.start.line == Range.end.line</replaceable
> ist. </para>
<para
>Seit: &kde; 4.9 </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>bool Range.equals(<parameter
>Range <replaceable
>other</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Gibt <literal
>true</literal
> zurück, wenn dieser Bereich und der Bereich <replaceable
>other</replaceable
> gleich sind, sonst <literal
>false</literal
>. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>String Range.toString();
</synopsis
></term>
<listitem
><para
>Gibt den Bereich als Zeichenfolge in der Form <quote
><literal
>Range(Cursor(zeile, spalte), Cursor(zeile, spalte))</literal
></quote
> zurück. </para
></listitem>
</varlistentry
></variablelist>
</sect4>
</sect3>
<sect3 id="dev-scripting-api-global">
<title
>Globale Funktionen</title>
<para
>Dieser Abschnitt listet alle globalen Funktionen auf.</para>
<sect4 id="dev-scripting-api-includes">
<title
>Lesen & Einfügen von Dateien</title>
<variablelist
><varlistentry>
<term
><synopsis
>String read(<parameter
>String <replaceable
>datei</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Sucht nach der angegebenen <replaceable
>datei</replaceable
> relativ zum Ordner <literal
>katepart/script/files</literal
> und gibt den Inhalt der Datei als String zurück. </para
></listitem>
</varlistentry
></variablelist>
<variablelist
><varlistentry>
<term
><synopsis
>void require(<parameter
>String <replaceable
>datei</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Sucht die angegebene <replaceable
>datei</replaceable
> relativ zum Ordner <literal
>katepart/script/libraries</literal
> und wertet sie aus. <literal
>require</literal
> verhindert intern, dass die gleiche <replaceable
>datei</replaceable
> mehrfach eingeschlossen wird. </para>
<para
>Seit: &kde; 4.10 </para>
</listitem>
</varlistentry
></variablelist>
</sect4>
<sect4 id="dev-scripting-api-debug">
<title
>Fehlersuche</title>
<variablelist
><varlistentry>
<term
><synopsis
>void debug(<parameter
>String <replaceable
>text</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Gibt den <replaceable
>text</replaceable
> auf der Standardausgabe <literal
>stdout</literal
> in der Konsole aus, von der das Programm gestartet wurde. </para
></listitem>
</varlistentry
></variablelist>
</sect4>
<sect4 id="dev-scripting-api-i18n">
<title
>Übersetzung</title>
<para
>Die Lokalisierung wird durch einige Funktionen zum Übersetzen von Zeichenfolgen in Skripten unterstützt, so durch <literal
>i18n</literal
>, <literal
>i18nc</literal
>, <literal
>i18np</literal
> und <literal
>i18ncp</literal
>. Diese Funktionen arbeiten genau wie auf der Seite <ulink url="https://techbase.kde.org/Development/Tutorials/Localization/i18n"
> &kde;'s Übersetzungsfunktionen</ulink
> beschrieben. </para>
<para
>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 &kappname;-Quellen entwickelt werden, werden automatisch extrahiert und sind übersetzbar. Anders gesagt, müssen Sie sich als Entwickler von &kappname; 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. </para>
<variablelist
><varlistentry>
<term
><synopsis
>void i18n(<parameter
>String <replaceable
>text</replaceable
></parameter
>, <replaceable
>arg1</replaceable
>, ...);
</synopsis
></term>
<listitem
><para
>Übersetzt <replaceable
>text</replaceable
> in die von der Anwendung benutzte Sprache. Die Argumente <replaceable
>arg1</replaceable
>, ..., sind optional und werden benutzt, um die Platzhalter <literal
>%1</literal
>, <literal
>%2</literal
> &etc; zu ersetzen.</para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>void i18nc(<parameter
>String <replaceable
>context</replaceable
></parameter
>, <parameter
>String <replaceable
>text</replaceable
></parameter
>, <replaceable
>arg1</replaceable
>, ...);
</synopsis
></term>
<listitem
><para
>Übersetzt <replaceable
>text</replaceable
> in die von der Anwendung benutzte Sprache. Zusätzlich ist die Zeichenfolge <replaceable
>context</replaceable
> sichtbar, so dass Übersetzer bessere Übersetzungen anfertigen können. Die Argumente <replaceable
>arg1</replaceable
>, ..., sind optional und werden benutzt, um die Platzhalter <literal
>%1</literal
>, <literal
>%2</literal
> &etc;. zu ersetzen.</para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>void i18np(<parameter
>String <replaceable
>singular</replaceable
></parameter
>, <parameter
>String <replaceable
>plural</replaceable
></parameter
>, <parameter
>int <replaceable
>number</replaceable
></parameter
>, <replaceable
>arg1</replaceable
>, ...);
</synopsis
></term>
<listitem
><para
>Übersetzt entweder <replaceable
>singular</replaceable
> oder <replaceable
>plural</replaceable
> in die von der Anwendung benutzte Sprache. Dies ist abhängig von der angegebenen <replaceable
>number</replaceable
>. Die Argumente <replaceable
>arg1</replaceable
>, ..., sind optional und werden benutzt, um die Platzhalter <literal
>%1</literal
>, <literal
>%2</literal
> &etc;. zu ersetzen.</para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>void i18ncp(<parameter
>String <replaceable
>context</replaceable
></parameter
>, <parameter
>String <replaceable
>singular</replaceable
></parameter
>, <parameter
>String <replaceable
>plural</replaceable
></parameter
>, <parameter
>int <replaceable
>number</replaceable
></parameter
>, <replaceable
>arg1</replaceable
>, ...);
</synopsis
></term>
<listitem
><para
>Übersetzt entweder <replaceable
>singular</replaceable
> oder <replaceable
>plural</replaceable
> in die von der Anwendung benutzte Sprache. Dies ist abhängig von der angegebenen <replaceable
>number</replaceable
>. Zusätzlich ist die Zeichenfolge <replaceable
>context</replaceable
> sichtbar, so dass Übersetzer bessere Übersetzungen anfertigen können. Die Argumente <replaceable
>arg1</replaceable
>, ..., sind optional und werden benutzt, um die Platzhalter <literal
>%1</literal
>, <literal
>%2</literal
> &etc;. zu ersetzen.</para
></listitem>
</varlistentry
></variablelist>
</sect4>
</sect3>
<sect3 id="dev-scripting-api-view">
<title
>Die Programmschnittstelle zur Ansicht</title>
<para
>Für jedes ausgeführte Skript gibt es eine globale Variable <quote
><literal
>view</literal
></quote
>, für die aktuelle Editoransicht. Im Folgenden finden Sie eine Liste aller verfügbaren Funktionen für eine Ansicht. <variablelist>
<varlistentry>
<term
><synopsis
><function
>void view.copy()</function
>
</synopsis
></term>
<listitem>
<para
>Kopiert eine vorhandene Auswahl, ansonsten die aktuelle Zeile, wenn die Einstellung <userinput
>[ ] Die aktuelle Zeile kopieren/ausschneiden, wenn keine Markierung vorliegt</userinput
> aktiviert ist.</para>
<para
>Seit &kde-frameworks; 5.79</para>
</listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
><function
>void view.cut()</function
>
</synopsis
></term>
<listitem>
<para
>Schneidet eine vorhandene Auswahl, ansonsten die aktuelle Zeile aus, wenn die Einstellung <userinput
>[ ] Die aktuelle Zeile kopieren/ausschneiden, wenn keine Markierung vorliegt</userinput
> aktiviert ist.</para>
<para
>Seit &kde-frameworks; 5.79</para>
</listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
><function
>void view.paste()</function
>
</synopsis
></term>
<listitem>
<para
>Inhalt der Zwischenablage einfügen.</para>
<para
>Seit &kde-frameworks; 5.79</para>
</listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
><function
>Cursor view.cursorPosition()</function
>
</synopsis
></term>
<listitem
><para
>Gibt die aktuelle Position des Cursors in der Ansicht zurück.</para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>void view.setCursorPosition(<parameter
>int <replaceable
>zeile</replaceable
></parameter
>, <parameter
>int <replaceable
>spalte</replaceable
></parameter
>);
void view.setCursorPosition(<parameter
>Cursor <replaceable
>cursor</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Setzt die aktuelle Position des Cursors entweder auf (zeile, spalte) oder auf den angegebenen Cursor. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>Cursor view.virtualCursorPosition();
</synopsis
></term>
<listitem
><para
>Gibt die virtuelle Cursor-Position zurück, dabei wird jeder Tabulator mit der Anzahl der Leerzeichen entsprechend der aktuellen Tabulatorweite berechnet. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>void view.setVirtualCursorPosition(<parameter
>int <replaceable
>zeile</replaceable
></parameter
>, <parameter
>int <replaceable
>spalte</replaceable
></parameter
>);
void view.setVirtualCursorPosition(<parameter
>Cursor <replaceable
>cursor</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Setzt die aktuelle Position des virtuellen Cursors entweder auf (zeile, spalte) oder auf den angegebenen Cursor. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>String view.selectedText();
</synopsis
></term>
<listitem
><para
>Gibt den ausgewählten Text zurück. Ist kein Text ausgewählt, wird eine leere Zeichenfolge zurückgegeben. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>bool view.hasSelection();
</synopsis
></term>
<listitem
><para
>Gibt <literal
>true</literal
> zurück, wenn die Ansicht ausgewählten Text enthält, sonst <literal
>false</literal
>. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>Range view.selection();
</synopsis
></term>
<listitem
><para
>Gibt den ausgewählten Textbereich zurück. Der zurückgegebene Bereich ist ungültig, wenn kein Text ausgewählt ist. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>void view.setSelection(<parameter
>Range <replaceable
>range</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Setzt den ausgewählten Text zum angegebenen Bereich. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>void view.removeSelectedText();
</synopsis
></term>
<listitem
><para
>Entfernt den ausgewählten Text. Wenn in der Ansicht kein Text ausgewählt ist, passiert nichts. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>void view.selectAll();
</synopsis
></term>
<listitem
><para
>Wählt den gesamten Text im Dokument aus. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>void view.clearSelection();
</synopsis
></term>
<listitem
><para
>Löscht die Textauswahl, aber nicht den Text selbst. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>object view.executeCommand(<parameter
>String <replaceable
>command</replaceable
></parameter
>,
<parameter
>String <replaceable
>args</replaceable
></parameter
>,
<parameter
>Range <replaceable
>range</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Führt den <link linkend="advanced-editing-tools-commandline"
>Befehl</link
> <replaceable
>command</replaceable
> mit den optionalen Argumenten <replaceable
>args</replaceable
> und <replaceable
>range</replaceable
> aus. Das zurückgegebene <replaceable
>object</replaceable
>hat die boolesche Eigenschaft <replaceable
>object.ok</replaceable
>, mit der angegeben wird, ob der Befehl <replaceable
>command</replaceable
> erfolgreich ausgeführt wurde. Bei einem Fehler enthält <replaceable
>object.status</replaceable
> die Fehlermeldung. </para>
<para
>Seit &kde-frameworks; 5.50</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</sect3>
<sect3 id="dev-scripting-api-document">
<title
>Die Programmschnittstelle zum Dokument</title>
<para
>Für jedes ausgeführte Skript gibt es eine globale Variable <quote
><literal
>document</literal
></quote
>, die das aktuelle Dokument verweist. Im Folgenden finden Sie eine Liste aller verfügbaren Funktionen für ein Dokument. <variablelist>
<varlistentry>
<term
><synopsis
>String document.fileName();
</synopsis
></term>
<listitem
><para
>Gibt den Dateinamen des Dokuments zurück oder eine leere Zeichenfolge für nicht gespeicherte Textpuffer. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>String document.url();
</synopsis
></term>
<listitem
><para
>Gibt die vollständige &URL; des Dokuments zurück oder eine leere Zeichenfolge für nicht gespeicherte Textpuffer. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>String document.mimeType();
</synopsis
></term>
<listitem
><para
>Gibt den &MIME;-Typ des Dokuments zurück oder <literal
>application/octet-stream</literal
>, wenn kein passender &MIME;-Typ gefunden wurde. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>String document.encoding();
</synopsis
></term>
<listitem
><para
>Gibt die aktuell verwendete Kodierung zum Speichern der Datei zurück. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>String document.highlightingMode();
</synopsis
></term>
<listitem
><para
>Gibt den globalen Hervorhebungsmodus für das gesamte Dokument zurück. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>String document.highlightingModeAt(<parameter
>Cursor <replaceable
>pos</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Gibt den Hervorhebungsmodus an der angegebenen Cursor-Position im Dokument zurück. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>Array document.embeddedHighlightingModes();
</synopsis
></term>
<listitem
><para
>Gibt ein Feld von Hervorhebungsmodi zurück, die in diesem Dokument eingebettet sind.. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>bool document.isModified();
</synopsis
></term>
<listitem
><para
>Gibt <literal
>true</literal
> zurück, wenn das Dokument ungespeicherte Änderungen enthält, sonst <literal
>false</literal
>. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>String document.text();
</synopsis
></term>
<listitem
><para
>Gibt den gesamten Inhalt des Dokuments in einer einzigen Zeichenfolge zurück. Zeilenumbrüche werden mit dem zugehörigen Zeichen <quote
><literal
>\n</literal
></quote
> markiert. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>String document.text(<parameter
>int <replaceable
>vonZeile</replaceable
></parameter
>, <parameter
>int <replaceable
>vonSpalte</replaceable
></parameter
>, <parameter
>int <replaceable
>bisZeile</replaceable
></parameter
>, <parameter
>int <replaceable
>bisSpalte</replaceable
></parameter
>);
String document.text(<parameter
>Cursor <replaceable
>von</replaceable
></parameter
>, <parameter
>Cursor <replaceable
>bis</replaceable
></parameter
>);
String document.text(<parameter
>Range <replaceable
>range</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Gibt den Text im angegebenen Bereich zurück. Es wird empfohlen, die Cursor- und Bereichsbasierte Version zu benutzen, dadurch ist der Quelltext besser lesbar. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>String document.line(<parameter
>int <replaceable
>zeile</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Gibt die angegebene Textzeile als Zeichenfolge zurück. Die Zeichenfolge ist leer, wenn die angeforderte Zeile außerhalb des Bereichs liegt. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>String document.wordAt(<parameter
>int <replaceable
>zeile</replaceable
></parameter
>, <parameter
>int <replaceable
>spalte</replaceable
></parameter
>);
String document.wordAt(<parameter
>Cursor <replaceable
>cursor</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Gibt das Wort an der angegebenen Cursor-Position zurück. </para
></listitem>
</varlistentry>
<varlistentry>
<term>
<synopsis
>Range document.wordRangeAt(<parameter
>int <replaceable
>zeile</replaceable
></parameter
>, <parameter
>int <replaceable
>spalte</replaceable
></parameter
>);
Range document.wordRangeAt(<parameter
>Cursor <replaceable
>cursor</replaceable
></parameter
>);
</synopsis>
</term>
<listitem
><para
>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. </para>
<para
>Seit: &kde; 4.9 </para>
</listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>String document.charAt(<parameter
>int <replaceable
>zeile</replaceable
></parameter
>, <parameter
>int <replaceable
>spalte</replaceable
></parameter
>);
String document.charAt(<parameter
>Cursor <replaceable
>cursor</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Gibt das Zeichen an der aktuellen Cursor-Position zurück. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>String document.firstChar(<parameter
>int <replaceable
>zeile</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Gibt in der angegebenen <replaceable
>zeile</replaceable
> 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. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>String document.lastChar(<parameter
>int <replaceable
>zeile</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Gibt in der angegebenen <replaceable
>zeile</replaceable
> 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. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>bool document.isSpace(<parameter
>int <replaceable
>zeile</replaceable
></parameter
>, <parameter
>int <replaceable
>spalte</replaceable
></parameter
>);
bool document.isSpace(<parameter
>Cursor <replaceable
>cursor</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Gibt <literal
>true</literal
> zurück, wenn das Zeichen an der angegebenen Cursor-Position ein Leerraumzeichen ist, sonst <literal
>false</literal
>. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>bool document.matchesAt(<parameter
>int <replaceable
>line</replaceable
></parameter
>, <parameter
>int <replaceable
>column</replaceable
></parameter
>, <parameter
>String <replaceable
>text</replaceable
></parameter
>);
bool document.matchesAt(<parameter
>Cursor <replaceable
>cursor</replaceable
></parameter
>, <parameter
>String <replaceable
>text</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Gibt <literal
>true</literal
> zurück, wenn der angegebene <replaceable
>text</replaceable
> mit der zugehörigen Cursor-Position übereinstimmt, sonst <literal
>false</literal
>. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>bool document.startsWith(<parameter
>int <replaceable
>zeile</replaceable
></parameter
>, <parameter
>String <replaceable
>text</replaceable
></parameter
>, <parameter
>bool <replaceable
>skipWhiteSpaces</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Gibt <literal
>true</literal
> zurück, wenn die Zeile mit <replaceable
>text</replaceable
> beginnt, sonst <literal
>false</literal
>. Das Argument <replaceable
>skipWhiteSpaces</replaceable
> bestimmt, ob führende Leerraumzeichen ignoriert werden. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>bool document.endsWith(<parameter
>int <replaceable
>zeile</replaceable
></parameter
>, <parameter
>String <replaceable
>text</replaceable
></parameter
>, <parameter
>bool <replaceable
>skipWhiteSpaces</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Gibt <literal
>true</literal
> zurück, wenn die Zeile mit <replaceable
>text</replaceable
> endet, sonst <literal
>false</literal
>. Das Argument <replaceable
>skipWhiteSpaces</replaceable
> bestimmt, ob angehängte Leerraumzeichen ignoriert werden. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>bool document.setText(<parameter
>String <replaceable
>text</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Setzt den Text für das gesamte Dokument. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>bool document.clear();
</synopsis
></term>
<listitem
><para
>Löscht den gesamten Text im Dokument. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>bool document.truncate(<parameter
>int <replaceable
>zeile</replaceable
></parameter
>, <parameter
>int <replaceable
>spalte</replaceable
></parameter
>);
bool document.truncate(<parameter
>Cursor <replaceable
>cursor</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Schneidet die angegebene Zeile an der Spalte oder an der Cursor-Position ab. War das erfolgreich, wird <literal
>true</literal
> zurückgegeben, oder <literal
>false</literal
>, wenn die angegeben Zeile nicht im Bereich des Dokuments liegt. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>bool document.insertText(<parameter
>int <replaceable
>zeile</replaceable
></parameter
>, <parameter
>int <replaceable
>spalte</replaceable
></parameter
>, <parameter
>String <replaceable
>text</replaceable
></parameter
>);
bool document.insertText(<parameter
>Cursor <replaceable
>cursor</replaceable
></parameter
>, <parameter
>String <replaceable
>text</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Fügt den <replaceable
>text</replaceable
> an der angegebenen Cursor-Position ein. War das erfolgreich, wird <literal
>true</literal
> zurückgegeben, oder <literal
>false</literal
>, wenn das Dokument im Nur-Lesen-Modus geöffnet wurde. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>bool document.removeText(<parameter
>int <replaceable
>vonZeile</replaceable
></parameter
>, <parameter
>int <replaceable
>vonSpalte</replaceable
></parameter
>, <parameter
>int <replaceable
>bisZeile</replaceable
></parameter
>, <parameter
>int <replaceable
>bisSpalte</replaceable
></parameter
>);
bool document.removeText(<parameter
>Cursor <replaceable
>von</replaceable
></parameter
>, <parameter
>Cursor <replaceable
>bis</replaceable
></parameter
>);
bool document.removeText(<parameter
>Range <replaceable
>bereich</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Löscht den Text im angegebenen Bereich. War das erfolgreich, wird <literal
>true</literal
> zurückgegeben, oder <literal
>false</literal
>, wenn das Dokument im Nur-Lesen-Modus geöffnet wurde. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>bool document.insertLine(<parameter
>int <replaceable
>zeile</replaceable
></parameter
>, <parameter
>String <replaceable
>text</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Fügt Text in einer angegebenen Zeile ein. War das erfolgreich, wird <literal
>true</literal
> zurückgegeben, oder <literal
>false</literal
>, wenn das Dokument im Nur-Lesen-Modus geöffnet wurde oder die Zeile nicht mehr im Bereich des Dokuments liegt. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>bool document.removeLine(<parameter
>int <replaceable
>zeile</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Löscht die angegebene Textzeile. War das erfolgreich, wird <literal
>true</literal
> zurückgegeben, oder <literal
>false</literal
>, wenn das Dokument im Nur-Lesen-Modus geöffnet wurde oder die Zeile nicht mehr im Bereich des Dokuments liegt. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>bool document.wrapLine(<parameter
>int <replaceable
>zeile</replaceable
></parameter
>, <parameter
>int <replaceable
>spalte</replaceable
></parameter
>);
bool document.wrapLine(<parameter
>Cursor <replaceable
>cursor</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Bricht die Zeile an der angegebenen Cursor-Position um. War das erfolgreich, wird <literal
>true</literal
> zurückgegeben, ansonsten <literal
>false</literal
>, ⪚ wenn die angegeben Zeilennummer < 0 ist. </para>
<para
>Seit: &kde; 4.9 </para>
</listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>void document.joinLines(<parameter
>int <replaceable
>startZeile</replaceable
></parameter
>, <parameter
>int <replaceable
>endZeile</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Verbindet die Zeilen von <replaceable
>startZeile</replaceable
> bis <replaceable
>endZeile</replaceable
>. Zwei aufeinanderfolgende Textzeilen werden immer mit einem einzelnen Leerzeichen getrennt. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>int document.lines();
</synopsis
></term>
<listitem
><para
>Gibt die Zeilenanzahl des Dokuments zurück. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>bool document.isLineModified(<parameter
>int <replaceable
>zeile</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Gibt <literal
>true</literal
> zurück, wenn die <replaceable
>zeile</replaceable
> noch nicht gespeicherte Daten enthält. </para>
<para
>Seit: &kde; 5.0 </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>bool document.isLineSaved(<parameter
>int <replaceable
>zeile</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Gibt <literal
>true</literal
> zurück, wenn <replaceable
>zeile</replaceable
> geändert und das Dokument gespeichert wurde. Folglich enthält die aktuelle Zeile keine ungesicherten Daten. </para>
<para
>Seit: &kde; 5.0 </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>bool document.isLineTouched(<parameter
>int <replaceable
>zeile</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Gibt <literal
>true</literal
> zurück, wenn <replaceable
>zeile</replaceable
> ungesicherte Daten enthält oder geändert wurde. </para>
<para
>Seit: &kde; 5.0 </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>void document.findTouchedLine(<parameter
>int <replaceable
>startZeile</replaceable
></parameter
>, <parameter
>bool <replaceable
>nach unten</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Suche nach der nächsten Zeile, die ungesicherte Daten enthält oder geändert wurde. Die Suche wird in der <replaceable
>startZeile</replaceable
> begonnen und in der Richtung durchgeführt, die in <replaceable
>nach unten</replaceable
> angegeben ist. </para>
<para
>Seit: &kde; 5.0 </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>int document.length();
</synopsis
></term>
<listitem
><para
>Gibt die Anzahl der Zeichen des Dokuments zurück. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>int document.lineLength(<parameter
>int <replaceable
>zeile</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Gibt die Länge der <replaceable
>zeile</replaceable
> zurück. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>void document.editBegin();
</synopsis
></term>
<listitem
><para
>Beginnt eine Bearbeitungsgruppe für die Gruppierung von Rückgängig/Wiederherstellen. Achten Sie darauf, <function
>editEnd()</function
> immer genauso oft wie <function
>editBegin()</function
> zu benutzen. Der Aufruf von <function
>editBegin()</function
> verwendet intern einen Referenzzähler, &ie; diese Aufrufe können geschachtelt werden. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>void document.editEnd();
</synopsis
></term>
<listitem
><para
>Beendet eine Bearbeitungsgruppe. Der letzte Aufruf von <function
>editEnd()</function
> (&ie; der Aufruf zum ersten Aufruf von <function
>editBegin()</function
>) beendet den Bearbeitungsschritt. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>int document.firstColumn(<parameter
>int <replaceable
>zeile</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Gibt die erste Spalte in der angegebenen <replaceable
>zeile</replaceable
> zurück, die kein Leerraumzeichen enthält. Besteht die Zeile nur aus Leerraumzeichen, wird <literal
>-1</literal
> zurückgegeben. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>int document.lastColumn(<parameter
>int <replaceable
>zeile</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Gibt die letzte Spalte in der angegebenen <replaceable
>zeile</replaceable
> zurück, die kein Leerraumzeichen enthält. Besteht die Zeile nur aus Leerraumzeichen, wird <literal
>-1</literal
> zurückgegeben. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>int document.prevNonSpaceColumn(<parameter
>int <replaceable
>zeile</replaceable
></parameter
>, <parameter
>int <replaceable
>spalte</replaceable
></parameter
>);
int document.prevNonSpaceColumn(<parameter
>Cursor <replaceable
>cursor</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Gibt die Spalte zurück, die keine Leerraumzeichen enthält. Die Suche beginnt an der angegebenen Cursor-Position und erfolgt dabei rückwärts. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>int document.nextNonSpaceColumn(<parameter
>int <replaceable
>zeile</replaceable
></parameter
>, <parameter
>int <replaceable
>spalte</replaceable
></parameter
>);
int document.nextNonSpaceColumn(<parameter
>Cursor <replaceable
>cursor</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Gibt die Spalte zurück, die keine Leerraumzeichen enthält. Die Suche beginnt an der angegebenen Cursor-Position und erfolgt dabei vorwärts. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>int document.prevNonEmptyLine(<parameter
>int <replaceable
>zeile</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Gibt die nächste nicht leere Zeile zurück, die keine Leerraumzeichen enthält. Die Suche erfolgt dabei rückwärts. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>int document.nextNonEmptyLine(<parameter
>int <replaceable
>zeile</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Gibt die nächste nicht leere Zeile zurück, die keine Leerraumzeichen enthält. Die Suche erfolgt dabei vorwärts. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>bool document.isInWord(<parameter
>String <replaceable
>zeichen</replaceable
></parameter
>, <parameter
>int <replaceable
>attribut</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Gibt <literal
>true</literal
> zurück, wenn das angegebene <replaceable
>zeichen</replaceable
> mit den angegebenen <replaceable
>attribut</replaceable
> Teil eines Wortes sein kann, sonst <literal
>false</literal
>. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>bool document.canBreakAt(<parameter
>String <replaceable
>zeichen</replaceable
></parameter
>, <parameter
>int <replaceable
>attribut</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Gibt <literal
>true</literal
> zurück, wenn die Zeile an dem angegebenen <replaceable
>zeichen</replaceable
> mit den angegebenen <replaceable
>attribut</replaceable
> umgebrochen werden kann, sonst <literal
>false</literal
>. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>bool document.canComment(<parameter
>int <replaceable
>startAttribut</replaceable
></parameter
>, <parameter
>int <replaceable
>endAttribut</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Gibt <literal
>true</literal
> zurück, wenn ein mit dem angegebenen Attribut beginnender und endender Bereich auskommentiert werden kann, sonst <literal
>false</literal
>. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>String document.commentMarker(<parameter
>int <replaceable
>attribut</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Gibt das Kommentarzeichen für einzeilige Kommentare für ein angegebenes <replaceable
>attribut</replaceable
> zurück. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>String document.commentStart(<parameter
>int <replaceable
>attribut</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Gibt das Kommentarzeichen für den Beginn von mehrzeiligen Kommentaren für ein angegebenes <replaceable
>attribut</replaceable
> zurück. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>String document.commentEnd(<parameter
>int <replaceable
>attribut</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Gibt das Kommentarzeichen für das Ende von mehrzeiligen Kommentaren für ein angegebenes <replaceable
>attribut</replaceable
> zurück. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>Range document.documentRange();
</synopsis
></term>
<listitem
><para
>Gibt einen Bereich zurück, der dass gesamte Dokument umfasst. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>Cursor documentEnd();
</synopsis
></term>
<listitem
><para
>Gibt einen Cursor zurück, der an der letzten Spalte in der letzten Zeile des Dokuments positioniert ist. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>bool isValidTextPosition(<parameter
>int <replaceable
>zeile</replaceable
></parameter
>, <parameter
>int <replaceable
>spalte</replaceable
></parameter
>);
bool isValidTextPosition(<parameter
>Cursor <replaceable
>cursor</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Gibt <literal
>true</literal
> 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. </para
><para
>Seit: &kde; 5.0 </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>int document.attribute(<parameter
>int <replaceable
>zeile</replaceable
></parameter
>, <parameter
>int <replaceable
>spalte</replaceable
></parameter
>);
int document.attribute(<parameter
>Cursor <replaceable
>cursor</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Gibt das Attribut an der aktuellen Cursor-Position zurück. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>bool document.isAttribute(<parameter
>int <replaceable
>zeile</replaceable
></parameter
>, <parameter
>int <replaceable
>spalte</replaceable
></parameter
>, <parameter
>int <replaceable
>attribut</replaceable
></parameter
>);
bool document.isAttribute(<parameter
>Cursor <replaceable
>cursor</replaceable
></parameter
>, <parameter
>int <replaceable
>attribut</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Gibt <literal
>true</literal
> zurück, wenn das Attribut an der angegebenen Cursor-Position gleich <replaceable
>attribut</replaceable
> ist, sonst <literal
>false</literal
>. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>String document.attributeName(<parameter
>int <replaceable
>zeile</replaceable
></parameter
>, <parameter
>int <replaceable
>spalte</replaceable
></parameter
>);
String document.attributeName(<parameter
>Cursor <replaceable
>cursor</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Gibt den Attributnamen als lesbaren Text zurück. Dies entspricht dem Namen <literal
>itemData</literal
> in den Syntaxhervorhebungs-Dateien. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>bool document.isAttributeName(<parameter
>int <replaceable
>zeile</replaceable
></parameter
>, <parameter
>int <replaceable
>spalte</replaceable
></parameter
>, <parameter
>String <replaceable
>name</replaceable
></parameter
>);
bool document.isAttributeName(<parameter
>Cursor <replaceable
>cursor</replaceable
></parameter
>, <parameter
>String <replaceable
>name</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Gibt <literal
>true</literal
> zurück, wenn der Attributname an der angegebenen Cursor-Position gleich <replaceable
>name</replaceable
> ist, sonst <literal
>false</literal
>. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>String document.variable(<parameter
>String <replaceable
>key</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Gibt den Wert der angefragten Dokumentvariablen <replaceable
>key</replaceable
> zurück. Existiert diese Variable nicht, wird eine leere Zeichenfolge zurückgegeben. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>void document.setVariable(<parameter
>String <replaceable
>key</replaceable
></parameter
>, <parameter
>String <replaceable
>value</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Setzt den Wert der angefragten Dokumentvariablen <replaceable
>key</replaceable
>. </para>
<para
>Siehe auch: <link linkend="config-variables"
>Kate-Dokumentvariable</link
> </para>
<para
>Seit: &kde; 4.8 </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>int document.firstVirtualColumn(<parameter
>int <replaceable
>zeile</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Gibt in der angegebenen Zeile die virtuelle Spalte des ersten Zeichens zurück, das kein Leerraumzeichen ist, oder <literal
>-1</literal
>, wenn die Zeile leer ist oder nur Leerraumzeichen enthält. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>int document.lastVirtualColumn(<parameter
>int <replaceable
>zeile</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Gibt in der angegebenen Zeile die virtuelle Spalte des letzten Zeichens zurück, das kein Leerraumzeichen ist, oder <literal
>-1</literal
>, wenn die Zeile leer ist oder nur Leerraumzeichen enthält. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>int document.toVirtualColumn(<parameter
>int <replaceable
>zeile</replaceable
></parameter
>, <parameter
>int <replaceable
>spalte</replaceable
></parameter
>);
int document.toVirtualColumn(<parameter
>Cursor <replaceable
>cursor</replaceable
></parameter
>);
Cursor document.toVirtualCursor(<parameter
>Cursor <replaceable
>cursor</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Wandelt die angegebene <quote
>reale</quote
> Cursor-Position in eine virtuelle Cursor-Position um und gibt entweder einen „int“-Wert oder ein Cursor-Objekt zurück. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>int document.fromVirtualColumn(<parameter
>int <replaceable
>zeile</replaceable
></parameter
>, <parameter
>int <replaceable
>virtuelleSpalte</replaceable
></parameter
>);
int document.fromVirtualColumn(<parameter
>Cursor <replaceable
>virtuellerCursor</replaceable
></parameter
>);
Cursor document.fromVirtualCursor(<parameter
>Cursor <replaceable
>virtuellerCursor</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Wandelt die angegebene virtuelle Cursor-Position in eine <quote
>reale</quote
> Cursor-Position um und gibt entweder einen „int“-Wert oder ein Cursor-Objekt zurück. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>Cursor document.anchor(<parameter
>int <replaceable
>zeile</replaceable
></parameter
>, <parameter
>int <replaceable
>spalte</replaceable
></parameter
>, <parameter
>Char <replaceable
>zeichen</replaceable
></parameter
>);
Cursor document.anchor(<parameter
>Cursor <replaceable
>cursor</replaceable
></parameter
>, <parameter
>Char <replaceable
>zeichen</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>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, &ie; andere Klammern „(...)“ werden ignoriert. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>Cursor document.rfind(<parameter
>int <replaceable
>zeile</replaceable
></parameter
>, <parameter
>int <replaceable
>spalte</replaceable
></parameter
>, <parameter
>String <replaceable
>text</replaceable
></parameter
>, <parameter
>int <replaceable
>attribut</replaceable
> = -1</parameter
>);
Cursor document.rfind(<parameter
>Cursor <replaceable
>cursor</replaceable
></parameter
>, <parameter
>String <replaceable
>text</replaceable
></parameter
>, <parameter
>int <replaceable
>attribut</replaceable
> = -1</parameter
>);
</synopsis
></term>
<listitem
><para
>Sucht rückwärts nach dem angegeben Text mit dem passenden <replaceable
>attribut</replaceable
>. Ein Attribut mit dem Wert <literal
>-1</literal
>wird dabei ignoriert. Es wird ein ungültiger Cursor zurückgegeben, wenn der Text nicht gefunden wurde. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>int document.defStyleNum(<parameter
>int <replaceable
>zeile</replaceable
></parameter
>, <parameter
>int <replaceable
>spalte</replaceable
></parameter
>);
int document.defStyleNum(<parameter
>Cursor <replaceable
>cursor</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Gibt den Standardstil zurück, der an der angegebenen Cursor-Position benutzt wird. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>bool document.isCode(<parameter
>int <replaceable
>zeile</replaceable
></parameter
>, <parameter
>int <replaceable
>spalte</replaceable
></parameter
>);
bool document.isCode(<parameter
>Cursor <replaceable
>cursor</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Gibt <literal
>true</literal
> zurück, wenn das Attribut an der angegeben Cursor-Position nicht den folgenden Stilen entspricht: <literal
>dsComment</literal
>, <literal
>dsString</literal
>, <literal
>dsRegionMarker</literal
>, <literal
>dsChar</literal
>, <literal
>dsOthers</literal
>. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>bool document.isComment(<parameter
>int <replaceable
>zeile</replaceable
></parameter
>, <parameter
>int <replaceable
>spalte</replaceable
></parameter
>);
bool document.isComment(<parameter
>Cursor <replaceable
>cursor</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Gibt <literal
>true</literal
> zurück, wenn das Attribut des Zeichens an der Cursor-Position <literal
>dsComment</literal
> ist, sonst <literal
>false</literal
>. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>bool document.isString(<parameter
>int <replaceable
>zeile</replaceable
></parameter
>, <parameter
>int <replaceable
>spalte</replaceable
></parameter
>);
bool document.isString(<parameter
>Cursor <replaceable
>cursor</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Gibt <literal
>true</literal
> zurück, wenn das Attribut des Zeichens an der Cursor-Position <literal
>dsString</literal
> ist, sonst <literal
>false</literal
>. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>bool document.isRegionMarker(<parameter
>int <replaceable
>zeile</replaceable
></parameter
>, <parameter
>int <replaceable
>spalte</replaceable
></parameter
>);
bool document.isRegionMarker(<parameter
>Cursor <replaceable
>cursor</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Gibt <literal
>true</literal
> zurück, wenn das Attribut des Zeichens an der Cursor-Position <literal
>dsRegionMarker</literal
> ist, sonst <literal
>false</literal
>. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>bool document.isChar(<parameter
>int <replaceable
>zeile</replaceable
></parameter
>, <parameter
>int <replaceable
>spalte</replaceable
></parameter
>);
bool document.isChar(<parameter
>Cursor <replaceable
>cursor</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Gibt <literal
>true</literal
> zurück, wenn das Attribut des Zeichens an der Cursor-Position <literal
>dsChar</literal
> ist, sonst <literal
>false</literal
>. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>bool document.isOthers(<parameter
>int <replaceable
>zeile</replaceable
></parameter
>, <parameter
>int <replaceable
>spalte</replaceable
></parameter
>);
bool document.isOthers(<parameter
>Cursor <replaceable
>cursor</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Gibt <literal
>true</literal
> zurück, wenn das Attribut des Zeichens an der Cursor-Position <literal
>dsOthers</literal
> ist, sonst <literal
>false</literal
>. </para
></listitem>
</varlistentry>
</variablelist>
</para>
</sect3>
<sect3 id="dev-scripting-api-editor">
<title
>Die Programmschnittstelle zum Editor</title>
<para
>Zusätzlich zur Programmierschnittstelle für das Dokument und die Ansicht gibt es eine weitere Schnittstelle mit Funktionen für Skripte des Editors. <variablelist>
<varlistentry>
<term
><synopsis
>String editor.clipboardText();
</synopsis
></term>
<listitem
><para
>Gibt den aktuellen Text aus der globalen Zwischenablage zurück. </para>
<para
>Seit &kde-frameworks; 5.50</para>
</listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>String editor.clipboardHistory();
</synopsis
></term>
<listitem
><para
>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. </para>
<para
>Seit &kde-frameworks; 5.50</para>
</listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>void editor.setClipboardText(<parameter
>String <replaceable
>text</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Setzt den Inhalt der Zwischenablagen auf den Wert <replaceable
>text</replaceable
>, der auch zum Verlauf hinzugefügt wird. </para>
<para
>Seit &kde-frameworks; 5.50</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</sect3>
</sect2>
</sect1>
</chapter>
Generated by dwww version 1.15 on Thu Jun 27 09:20:41 CEST 2024.