<!-- 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>
&traductor.Antoni.Bella;
</authorgroup>
</chapterinfo>
<title
>Estendre la &katepart;</title>
<sect1 id="dev-intro">
<title
>Introducció</title>
<para
>Igual que qualsevol editor de text avançat, la &katepart; ofereix una varietat de maneres d'estendre la seva funcionalitat. Podeu <link linkend="dev-scripting"
>escriure scripts senzills per a afegir funcionalitat amb &javascript;</link
>. Finalment, un cop esteneu la &katepart;, us donarem la benvinguda per <ulink url="https://kate-editor.org/join-us/"
>unir-vos</ulink
> amb nosaltres i compartir les vostres millores amb el món!</para>
</sect1>
<sect1 id="highlight">
<title
>Treballar amb el ressaltat de la sintaxi</title>
<sect2 id="highlight-overview">
<title
>Vista general</title>
<para
>El ressaltat de la sintaxi és el que fa que l'editor mostri automàticament text en diferents estils/colors, depenent de la funció de la cadena en relació amb la finalitat del fitxer. En el codi font d'un programa, per exemple, les sentències de control es poden presentar en negreta, mentre que els tipus de dades i els comentaris poden tenir diferents colors que la resta del text. Això millora considerablement la llegibilitat del text, i ajuda a l'autor a ser més eficient i productiu.</para>
<mediaobject>
<imageobject
><imagedata format="PNG" fileref="highlighted.png"/></imageobject>
<textobject
><phrase
>Una funció de C++, presentada amb ressaltat de la sintaxi.</phrase
></textobject>
<caption
><para
>Una funció de C++, presentada amb ressaltat de la sintaxi.</para>
</caption>
</mediaobject>
<mediaobject>
<imageobject
><imagedata format="PNG" fileref="unhighlighted.png"/></imageobject>
<textobject
><phrase
>La mateixa funció de C++, sense ressaltat.</phrase
></textobject>
<caption
><para
>La mateixa funció de C++, sense ressaltat.</para
></caption>
</mediaobject>
<para
>Dels dos exemples, quin resulta més fàcil de llegir?</para>
<para
>La &kappname; compta amb un sistema de ressaltat de sintaxi flexible, configurable i capaç, la distribució estàndard proveeix definicions per a una gran varietat de llenguatges de programació, creació de scripts i de marques. A més podeu proveir les vostres pròpies definicions en simples fitxers &XML;.</para>
<para
>La &kappname; detectarà automàticament les regles de la sintaxi correctes quan obriu un fitxer, basant-se en el tipus &MIME; del fitxer, determinat per la seva extensió, o, si no en té, pel seu contingut. Si l'elecció no és la correcta, podreu establir-la manualment des del menú <menuchoice
><guimenu
>Eines</guimenu
><guisubmenu
>Ressaltat</guisubmenu
></menuchoice
>.</para>
<para
>Els estils i colors emprats per a cada definició de ressaltat de sintaxi es poden configurar utilitzant la pestanya <link linkend="prefcolors-highlighting-text-styles"
>Estils del text ressaltat</link
> del <link linkend="config-dialog"
>Diàleg de configuració</link
>, mentre que els tipus &MIME; i extensions de fitxer per als que s'hauran d'utilitzar, es poden gestionar utilitzant la pàgina <link linkend="pref-open-save-modes-filetypes"
>Modes i tipus de fitxer</link
>.</para>
<note>
<para
>El ressaltat de la sintaxi té el seu ús en la millora de la llegibilitat del text, però no podeu confiar-hi per a validar que el text és correcte. Marcar el text en funció de la seva sintaxi pot ser difícil, depenent del format que s'estigui emprant, i en alguns casos els autors de les regles de la sintaxi poden estar orgullosos si es processa correctament el 98% del text, si bé caldrà un estil molt rar per a veure el 2% incorrecte.</para>
</note>
</sect2>
<sect2 id="katehighlight-system">
<title
>El sistema de ressaltat de la sintaxi de la &kappname;</title>
<para
>Aquesta secció tractarà sobre el mecanisme de ressaltat de la sintaxi de la &kappname; amb més detall. Recomanem la seva lectura si voleu aprendre sobre seu, o si voleu crear o canviar les definicions de la sintaxi.</para>
<sect3 id="katehighlight-howitworks">
<title
>Com funciona</title>
<para
>Sempre que obriu un fitxer, una de les primeres coses que fa l'editor de la &kappname; és detectar quina definició de la sintaxi s'emprarà per al fitxer. Mentre va llegint el text del fitxer, i mentre hi va escrivint, el sistema de ressaltat de la sintaxi analitza el text utilitzant les regles establertes per la definició de la sintaxi i marcant a on comencen i acaben els diferents contexts i estils.</para>
<para
>Quan escriviu en el document, el text nou és analitzat i marcat al vol, de manera que si suprimiu un caràcter que marca el començament o el final d'un context, l'estil del text adjacent canviarà en conseqüència.</para>
<para
>Les definicions de la sintaxi utilitzades per al sistema de ressaltat de la sintaxi de la &kappname; són fitxers &XML;, que contenen <itemizedlist>
<listitem
><para
>Regles per a detectar el paper del text, organitzades en blocs segons el context</para
></listitem>
<listitem
><para
>Llistes de paraules clau</para
></listitem>
<listitem
><para
>Definicions dels elements d'estil</para
></listitem>
</itemizedlist>
</para>
<para
>Quan s'analitza el text, les regles de detecció són avaluades en l'ordre en el qual estan definides, i si el començament de la cadena actual coincideix amb la regla, s'utilitzarà el context relacionat. El punt d'inici del text es mou al punt final en el qual la regla coincideix i comença un nou cicle de regles, començant en el context establert per la regla coincident.</para>
</sect3>
<sect3 id="highlight-system-rules">
<title
>Regles</title>
<para
>Les regles de la detecció són el nucli del sistema de detecció del ressaltat. Una regla és una cadena, un caràcter o una <link linkend="regular-expressions"
>expressió regular</link
> contra què haurà de coincidir el text que s'està analitzant. Conté informació sobre l'estil a emprar per a la part coincident del text. Es pot canviar el context de treball del sistema, ja sigui cap a un context mencionat explícitament o cap a l'anterior context emprat pel text.</para>
<para
>Les regles s'organitzen en grups de context. Un grup de context s'utilitza per als conceptes del text principal dins del format, per exemple, les cadenes de text entre cometes o els blocs de comentaris en el codi font d'un programa. Això garanteix que el sistema de ressaltat no necessita realitzar un cicle per a totes les regles quan no és necessari, i que algunes seqüències de caràcters del text es poden tractar de forma diferent depenent del context actual. </para>
<para
>En les regles és possible generar contexts dinàmicament per a permetre l'ús de dades específiques d'una instància.</para>
</sect3>
<sect3 id="highlight-context-styles-keywords">
<title
>Estils i paraules clau del context</title>
<para
>En alguns llenguatges de programació, els nombres enters són tractats pel compilador (el programa que converteix el codi font en un executable binari) d'una forma diferent dels de coma flotant, i poden haver-hi caràcters que tinguin un significat especial dins d'una cadena entre cometes. En aquests casos, té sentit processar-los de diferent manera que el text adjacent, perquè resultin fàcils d'identificar. De manera que si no representen contexts especials, poden ser vistos com a tals pel sistema de ressaltat de la sintaxi, així que són marcats per a un processat diferent.</para>
<para
>Una definició de la sintaxi pot contenir tants estils com siguin requerits per a cobrir tots els conceptes del format per què s'utilitza.</para>
<para
>En molts formats hi ha llistes de paraules que representen un concepte específic. Per exemple, en els llenguatges de programació, les sentències de control són un concepte, els noms de tipus de dades un altre, i les funcions incloses en el llenguatge són un tercer. El sistema de ressaltat de la sintaxi de la &kappname; pot utilitzar aquestes llistes per a detectar i marcar paraules en el text per a emfatitzar conceptes dels formats del text.</para>
</sect3>
<sect3 id="kate-highlight-system-default-styles">
<title
>Estils per omissió</title>
<para
>Si obriu un fitxer de codi font en C++, un fitxer de codi font en &Java; i un document en &HTML; a la &kappname;, podreu comprovar que tot i que els formats són diferents, i per tant les paraules que reben un tractament especial també són diferents, els colors emprats són els mateixos. Això és perquè la &kappname; té una llista predefinida d'estils predeterminats, els quals s'empren en les definicions individuals de la sintaxi.</para>
<para
>Això facilita reconèixer conceptes similars en diferents formats de text. Per exemple, els comentaris estan presents en pràcticament qualsevol llenguatge de programació, creació de scripts o de marques, i si es presenten utilitzant el mateix estil en tots els llenguatges, no haureu de parar-vos a pensar i identificar la seva posició en el text.</para>
<tip>
<para
>Tots els estils de definició de la sintaxi utilitzen un dels estils predeterminats. Hi ha poques definicions de la sintaxi que utilitzin més estils dels que hi ha de manera predeterminada, així que, si empreu un format molt sovint, potser val la pena obrir el diàleg de configuració per a veure si alguns conceptes estan emprant el mateix estil. Per exemple, tan sols hi ha un estil predeterminat per a les cadenes, però com el llenguatge de programació Perl utilitza dos tipus de cadena, podeu millorar el ressaltat configurant ambdues de forma lleugerament diferent. Més endavant s'explicaran tots els <link linkend="kate-highlight-default-styles"
>estils predeterminats disponibles</link
>.</para>
</tip>
</sect3>
</sect2>
<sect2 id="katehighlight-xml-format">
<title
>El format &XML; per a la definició del ressaltat</title>
<sect3>
<title
>Vista general</title>
<para
>El &kappname; utilitza l'entorn de treball per al ressaltat de la sintaxi dels &kde-frameworks;. Els fitxers en &XML; predeterminats del ressaltat distribuïts amb el &kappname; són compilats dintre de la biblioteca de ressaltat de la sintaxi. </para>
<para
>Aquesta secció és una introducció al format &XML; per a la definició del ressaltat. Descriu els components principals, el seu significat i utilització. La següent secció entra en detalls amb les regles de la detecció.</para>
<para
>La definició formal, també coneguda com la <acronym
>XSD</acronym
> es troba al <ulink url="https://commits.kde.org/syntax-highlighting?path=data/schema"
>repositori del ressaltat de la sintaxi</ulink
> al fitxer <filename
>language.xsd</filename
> </para>
<para
>Els fitxers <filename class="extension"
>.xml</filename
> personalitzats per a la definició del ressaltat es troben a <filename class="directory"
>org.kde.syntax-highlighting/syntax/</filename
> a la carpeta d'usuari que trobareu amb <userinput
><command
>qtpaths</command
><option
>--paths GenericDataLocation</option
></userinput
> que normalment és <filename class="directory"
><envar
>$HOME</envar
>/.local/share/</filename
> i <filename class="directory"
>/usr/share/</filename
>. </para>
<para
>En els paquets Flatpak i Snap, la carpeta anterior no funcionarà, ja que la ubicació de les dades és diferent per a cada aplicació. En una aplicació de Flatpak, la ubicació dels fitxers &XML; generalment és <filename class="directory"
><envar
>$HOME</envar
>/.var/app/<replaceable
>nom_paquet_flatpak</replaceable
>/data/org.kde.syntax-highlighting/syntax/</filename
> i en una aplicació de Snap aquesta ubicació és <filename class="directory"
><envar
>$HOME</envar
>/snap/<replaceable
>nom_paquet_snap</replaceable
>/current/.local/share/org.kde.syntax-highlighting/syntax/</filename
>. </para>
<para
>Al &Windows; aquests fitxers es troben a <filename
>%USERPROFILE%\AppData\Local\org.kde.syntax-highlighting\syntax</filename
>. <replaceable
>%USERPROFILE%</replaceable
> que generalment s'expandeix a <filename
>C:\Users\<replaceable
>usuari</replaceable
></filename
>.</para>
<para
>En resum, per a la majoria de les configuracions, la carpeta dels fitxers &XML; personalitzats és la següent:</para>
<informaltable>
<tgroup cols="2">
<tbody>
<row>
<entry
>Per a l'usuari local</entry>
<entry
><filename class="directory"
><envar
>$HOME</envar
>/.local/share/org.kde.syntax-highlighting/syntax/</filename
></entry>
</row>
<row>
<entry
>Per a tots els usuaris</entry>
<entry
><filename class="directory"
>/usr/share/org.kde.syntax-highlighting/syntax/</filename
></entry>
</row>
<row>
<entry
>Per als paquets Flatpak</entry>
<entry
><filename class="directory"
><envar
>$HOME</envar
>/.var/app/<replaceable
>nom_paquet_flatpak</replaceable
>/data/org.kde.syntax-highlighting/syntax/</filename
></entry>
</row>
<row>
<entry
>Per als paquets Snap</entry>
<entry
><filename class="directory"
><envar
>$HOME</envar
>/snap/<replaceable
>nom_paquet_snap</replaceable
>/current/.local/share/org.kde.syntax-highlighting/syntax/</filename
></entry>
</row>
<row>
<entry
>A &Windows;</entry>
<entry
><filename
>%USERPROFILE%\AppData\Local\org.kde.syntax-highlighting\syntax</filename
></entry>
</row>
</tbody>
</tgroup>
</informaltable>
<para
>Si hi ha múltiples fitxers per al mateix llenguatge, es carregarà el fitxer amb l'atribut <userinput
>version</userinput
> més alt en l'element <userinput
>language</userinput
>.</para>
<variablelist>
<title
>Principals seccions dels fitxers de definició del ressaltat de la &kappname;</title>
<varlistentry>
<term
>Tots els fitxers de ressaltat contenen una capçalera que estableix la versió &XML;:</term>
<listitem>
<programlisting
><?xml version="1.0" encoding="UTF-8"?>
</programlisting>
</listitem>
</varlistentry>
<varlistentry>
<term
>La part principal del fitxer de la definició és l'element <userinput
>language</userinput
>. Els atributs disponibles són:</term>
<listitem>
<para
>Atributs requerits:</para>
<para
><userinput
>name</userinput
> estableix el nom del llenguatge. Després apareixerà als menús i als diàlegs.</para>
<para
><userinput
>section</userinput
> especifica la categoria.</para>
<para
><userinput
>extensions</userinput
> defineix les extensions dels fitxers, com "*.cpp;*.h"</para>
<para
><userinput
>version</userinput
> especifica la versió actual del fitxer de definició en termes d'un nombre enter. Sempre que es canvia un fitxer de definició del ressaltat, assegureu-vos d'augmentar aquest número.</para>
<para
><userinput
>kateversion</userinput
> especifica l'última versió implementada de la &kappname;.</para>
<para
>Atributs opcionals:</para>
<para
><userinput
>mimetype</userinput
> fitxers associats amb el tipus &MIME;.</para>
<para
><userinput
>casesensitive</userinput
> defineix quan les paraules clau distingeixen o no les majúscules i minúscules.</para>
<para
><userinput
>priority</userinput
> és necessària si una altra definició de ressaltat utilitza les mateixes extensions. S'emprarà la de major prioritat.</para>
<para
><userinput
>author</userinput
> conté el nom de l'autor i la seva adreça de correu electrònic.</para>
<para
><userinput
>license</userinput
> conté la llicència, normalment la llicència del MIT per a fitxers nous de ressaltat de la sintaxi.</para>
<para
><userinput
>style</userinput
> conté el llenguatge proporcionat i és utilitzat pels sagnadors per a l'atribut <literal
>required-syntax-style</literal
>.</para>
<para
><userinput
>indenter</userinput
> defineix quin sagnat emprar de manera predeterminada. Els atributs disponibles són: <emphasis
>ada, normal, cstyle, cmake, haskell, latex, lilypond, lisp, lua, pascal, python, replicode, ruby</emphasis
> i <emphasis
>xml</emphasis
>.</para>
<para
><userinput
>hidden</userinput
> defineix quan hauria d'aparèixer el nom en els menús de la &kappname;.</para>
<para
>De manera que la línia següent pot tenir un aspecte similar a:</para>
<programlisting
><language name="C++" version="1" kateversion="2.4" section="Sources" extensions="*.cpp;*.h" />
</programlisting>
</listitem>
</varlistentry>
<varlistentry>
<term
>A continuació estaria l'element <userinput
>highlighting</userinput
>, el qual conté l'element opcional <userinput
>list</userinput
> i els elements requerits <userinput
>contexts</userinput
> i <userinput
>itemDatas</userinput
>.</term>
<listitem>
<para
>Els elements <userinput
>list</userinput
> contenen una llista de paraules clau. En aquest cas les paraules clau són <emphasis
>class</emphasis
> i <emphasis
>const</emphasis
>. Podeu afegir tantes llistes com us calguin.</para>
<para
>Des del &kde-frameworks; 5.53, una llista pot incloure paraules clau d'una altra llista o llenguatge/fitxer, utilitzant l'element <userinput
>include</userinput
>. Els caràcters <userinput
>##</userinput
> s'utilitzen per a separar el nom de la llista i el nom de la definició del llenguatge, de la mateixa manera que a la regla <userinput
>IncludeRules</userinput
>. Això és útil per a evitar la duplicació de llistes de paraules clau, si necessiteu incloure les paraules clau d'un altre llenguatge/fitxer. Per exemple, la llista <emphasis
>altre_nom</emphasis
> conté la paraula clau <emphasis
>str</emphasis
> i totes les paraules clau de la llista <emphasis
>types</emphasis
>, la qual pertany al llenguatge <emphasis
>C++ de l'ISO</emphasis
>.</para>
<para
>L'element <userinput
>contexts</userinput
> conté tots els contexts. El primer és l'emprat de manera predeterminada i amb aquest s'iniciarà el ressaltat. Hi ha dues regles en el context <emphasis
>text_normal</emphasis
>, el qual farà coincidir la llista de paraules clau amb el nom <emphasis
>algun_nom</emphasis
> i una regla que detecta una cometa i canvia el context a <emphasis
>cadena</emphasis
>. Per a aprendre més sobre les regles llegiu el següent capítol.</para>
<para
>La tercera part és l'element <userinput
>itemDatas</userinput
>. Conté tots els colors i tipus de lletra que necessiten els contexts i les regles. En aquest exemple, s'utilitzen <userinput
>itemData</userinput
> <emphasis
>text_normal</emphasis
>, <emphasis
>cadena</emphasis
> i <emphasis
>paraula_clau</emphasis
>. </para>
<programlisting
><highlighting>
<list name="algun_nom">
<item>class</item>
<item>const</item>
</list>
<list name="altre_nom">
<item>str</item>
<include>types##ISO C++</include>
</list>
<contexts>
<context attribute="text_normal" lineEndContext="#pop" name="text_normal" >
<keyword attribute="paraula_clau" context="#stay" String="algun_nom" />
<keyword attribute="paraula_clau" context="#stay" String="altre_nom" />
<DetectChar attribute="cadena" context="cadena" char="&quot;" />
</context>
<context attribute="cadena" lineEndContext="#stay" name="cadena" >
<DetectChar attribute="cadena" context="#pop" char="&quot;" />
</context>
</contexts>
<itemDatas>
<itemData name="text_normal" defStyleNum="dsNormal" />
<itemData name="paraula_clau" defStyleNum="dsKeyword" />
<itemData name="cadena" defStyleNum="dsString" />
</itemDatas>
</highlighting>
</programlisting>
</listitem>
</varlistentry>
<varlistentry>
<term
>L'última part de la definició del ressaltat és la secció opcional <userinput
>general</userinput
>. Pot contenir informació sobre paraules clau, plegat del codi, comentaris, sagnat, línies buides i verificació de l'ortografia.</term>
<listitem>
<para
>La secció <userinput
>comment</userinput
> defineix amb quina cadena s'introdueix un comentari en una línia senzilla. També podeu definir un comentari en múltiples línies utilitzant <emphasis
>multiLine</emphasis
> amb l'atribut addicional <emphasis
>end</emphasis
>. Això s'empra si l'usuari prem la drecera corresponent per a <emphasis
>comenta/descomenta</emphasis
>.</para>
<para
>La secció <userinput
>keywords</userinput
> defineix si les llistes de paraules clau distingeixen les majúscules i minúscules o no. Més endavant s'explicaran altres atributs.</para>
<para
>Les altres seccions, <userinput
>folding</userinput
>, <userinput
>emptyLines</userinput
> i <userinput
>spellchecking</userinput
>, normalment no són necessàries i s'expliquen més endavant.</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
>Les seccions en detall</title>
<para
>Aquesta part descriu tots els atributs disponibles per als contexts, llistes de dades, paraules clau, comentaris, plegat del codi i sagnat.</para>
<variablelist>
<varlistentry>
<term
>L'element <userinput
>context</userinput
> pertany al grup <userinput
>contexts</userinput
>. Un context defineix les regles específiques de context que s'han de seguir quan el sistema de ressaltat abasta el final d'una línia. Els atributs disponibles són:</term>
<listitem>
<para
><userinput
>name</userinput
> estableix el nom del context. Les regles utilitzaran el nom per a especificar el context al qual canviar si les regles coincideixen.</para>
<para
><userinput
>lineEndContext</userinput
> defineix el context al qual canviarà el sistema de ressaltat si abasta el final de la línia. Pot ser un nom o un altre context, <userinput
>#stay</userinput
> permetrà que no es canviï el context (&pex;, no fer res) o <userinput
>#pop</userinput
> farà que deixi aquest context. És possible utilitzar, per exemple <userinput
>#pop#pop#pop</userinput
> per a sortir tres vegades, o fins i tot <userinput
>#pop#pop!AltreContext</userinput
> perquè aparegui dues vegades i canviar a un context anomenat <userinput
>AltreContext</userinput
>. També és possible canviar a un context que pertanyi a una altra definició de llenguatge, de la mateixa manera que en les regles <userinput
>IncludeRules</userinput
>, &pex;, <userinput
>AlgunContext##JavaScript</userinput
>. Cal tenir en compte que no és possible utilitzar aquest canvi de context en combinació amb <userinput
>#pop</userinput
>, &pex;, <userinput
>#pop!AlgunContext##JavaScript</userinput
> no és vàlid. Els canvis de context també es descriuen a <xref linkend="kate-highlight-rules-detailled"/>.</para>
<para
><userinput
>lineEmptyContext</userinput
> defineix el context si es troba una línia buida. La nomenclatura dels commutadors de context és la mateixa que s'ha descrit anteriorment a <emphasis
>lineEndContext</emphasis
>. De manera predeterminada: #stay.</para>
<para
><userinput
>fallthroughContext</userinput
> especifica el context següent al que canviar si no coincideix cap regla. La nomenclatura dels commutadors de context és la mateixa que s'ha descrit anteriorment a <emphasis
>lineEndContext</emphasis
>. De manera predeterminada: #stay.</para>
<para
><userinput
>fallthrough</userinput
> defineix si el sistema de ressaltat canviarà al context especificat a <userinput
>fallthroughContext</userinput
> si no coincideix cap regla. Cal tenir en compte que, des dels &frameworks; 5.62 del &kde;, aquest atribut està en desús a favor de <userinput
>fallthroughContext</userinput
>, ja que si està present aquest atribut, s'entendrà implícitament que el valor de <userinput
>fallthrough</userinput
> és <emphasis
>true</emphasis
> (cert). De manera predeterminada: <emphasis
>false</emphasis
> (fals).</para>
<para
><userinput
>noIndentationBasedFolding</userinput
> inhabilita el plegat basat en el sagnat dintre del context. Si el plegat basat en el sagnat no està activat, aquest atribut és inútil. Això es defineix en l'element <emphasis
>folding</emphasis
> del grup <emphasis
>general</emphasis
>. De manera predeterminada a: <emphasis
>false</emphasis
>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term
>L'element <userinput
>itemData</userinput
> es troba en el grup <userinput
>itemDatas</userinput
>. Defineix l'estil i els colors dels tipus de lletra. Per tant és possible definir els vostres propis estils i colors. Encara que recomanem utilitzar els estils predeterminats, atès que així l'usuari veurà colors homogenis per als diferents llenguatges. Si bé, algunes vegades no hi ha altres possibilitats i és necessari canviar el color i els atributs dels tipus de lletra. Els atributs «name» i «defStyleNum» són necessaris, els altres són opcionals. Els atributs disponibles són:</term>
<listitem>
<para
><userinput
>name</userinput
> estableix el nom del «itemData». Els contexts i les regles utilitzaran aquest nom en els seus atributs <emphasis
>attribute</emphasis
> per a fer referència a un «itemData».</para>
<para
><userinput
>defStyleNum</userinput
> defineix quin estil s'emprarà de manera predeterminada. Més endavant s'explicaran els estils predeterminats disponibles.</para>
<para
><userinput
>color</userinput
> defineix un color. Els formats vàlids són «#rrggbb» o «#rgb».</para>
<para
><userinput
>selColor</userinput
> defineix el color de la selecció.</para>
<para
><userinput
>italic</userinput
> si està a <emphasis
>true</emphasis
>, el text es mostrarà en cursiva.</para>
<para
><userinput
>bold</userinput
> si està a <emphasis
>true</emphasis
>, el text es mostrarà en negreta.</para>
<para
><userinput
>underline</userinput
> si està a <emphasis
>true</emphasis
>, el text es mostrarà subratllat.</para>
<para
><userinput
>strikeout</userinput
> si està a <emphasis
>true</emphasis
>, el text es mostrarà taxat.</para>
<para
><userinput
>spellChecking</userinput
> si està a <emphasis
>true</emphasis
>, el text es mostrarà amb la verificació ortogràfica.</para>
</listitem>
</varlistentry>
<varlistentry>
<term
>L'element <userinput
>keywords</userinput
> en el grup <userinput
>general</userinput
> defineix les propietats «keyword». Els atributs disponibles són:</term>
<listitem>
<para
><userinput
>casesensitive</userinput
> pot ser <emphasis
>true</emphasis
> o <emphasis
>false</emphasis
>. Si està a <emphasis
>true</emphasis
>, totes les paraules clau distingiran les majúscules i minúscules.</para>
<para
><userinput
>weakDeliminator</userinput
> és una llista de caràcters que no actuen com a delimitadors de paraules (delimitador feble). Per exemple, el punt <userinput
>«.»</userinput
> és un delimitador de paraula. Si tenim una paraula clau en una <userinput
>list</userinput
> que conté un punt, tan sols la trobareu si especifiqueu el punt com a delimitador feble.</para>
<para
><userinput
>additionalDeliminator</userinput
> defineix delimitadors addicionals.</para>
<para
><userinput
>wordWrapDeliminator</userinput
> defineix els caràcters al darrere dels quals pot ocórrer un ajust de la línia.</para>
<para
>Els delimitadors predeterminats i els d'ajust de la línia són els caràcters <userinput
>.():!+,-<=>%&*/;?[]^{|}~\</userinput
>, espai (<userinput
>« »</userinput
>) i tabulació (<userinput
>«\t»</userinput
>).</para>
</listitem>
</varlistentry>
<varlistentry>
<term
>L'element <userinput
>comment</userinput
> en el grup <userinput
>comments</userinput
> defineix les propietats dels comentaris emprats per a <menuchoice
><guimenu
>Eines</guimenu
><guimenuitem
>Comenta</guimenuitem
></menuchoice
>, <menuchoice
><guimenu
>Eines</guimenu
> <guimenuitem
>Descomenta</guimenuitem
></menuchoice
> i <menuchoice
><guimenu
>Eines</guimenu
><guimenuitem
>Commuta els comentaris</guimenuitem
></menuchoice
>. Els atributs disponibles són:</term>
<listitem>
<para
><userinput
>name</userinput
> pot ser <emphasis
>singleLine</emphasis
> o <emphasis
>multiLine</emphasis
>. Si escolliu <emphasis
>multiLine</emphasis
> es necessiten els atributs <emphasis
>end</emphasis
> i <emphasis
>region</emphasis
>. Si escolliu <emphasis
>singleLine</emphasis
> podreu afegir l'atribut opcional <emphasis
>position</emphasis
>.</para>
<para
><userinput
>start</userinput
> defineix la cadena que s'utilitza per a iniciar un comentari. En C++ seria "/*" en comentaris multilínia. Aquest atribut és requerit per als tipus <emphasis
>multiLine</emphasis
> i <emphasis
>singleLine</emphasis
>.</para>
<para
><userinput
>end</userinput
> defineix la cadena utilitzada per a tancar un comentari. En C++ seria "*/". Només està disponible aquest atribut i es necessita per als comentaris del tipus <emphasis
>multiLine</emphasis
>.</para>
<para
><userinput
>region</userinput
> serà el nom amb el qual es desarà el comentari multilínia. Si assumim que tenim una regió <emphasis
>beginRegion="Comentari"</emphasis
> ... <emphasis
>endRegion="Comentari"</emphasis
> en les regles, haureu d'emprar <emphasis
>region="Comentari"</emphasis
>. D'aquesta manera es descomentarà fins i tot si no heu seleccionat tot el text en un comentari multilínia. El cursor només haurà d'estar dins del comentari multilínia. Només està disponible aquest atribut i es necessita per als comentaris del tipus <emphasis
>multiLine</emphasis
>.</para>
<para
><userinput
>position</userinput
> defineix on s'insereix el comentari d'una sola línia. De manera predeterminada, el comentari d'una sola línia es col·loca al començament de la línia a la columna 0, però si utilitzeu <emphasis
>position="afterwhitespace"</emphasis
>, el comentari s'insereix a la dreta després dels espais en blanc inicials, abans del primer caràcter que no sigui un espai en blanc. Això és útil per a posar comentaris correctament en llenguatges on la sagnia és important, com el Python o YAML. Aquest atribut és opcional i l'únic valor possible és <emphasis
>afterwhitespace</emphasis
>. Només està disponible per als tipus <emphasis
>singleLine</emphasis
>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term
>L'element <userinput
>folding</userinput
> en el grup <userinput
>general</userinput
> defineix les propietats de plegat del codi. Els atributs disponibles són:</term>
<listitem>
<para
><userinput
>indentationsensitive</userinput
> si està a <emphasis
>true</emphasis
>, els marcadors de plegat del codi seran afegits al sagnat, com en el llenguatge per a la creació de scripts en Python. Normalment no caldrà establir-lo, ja que de manera predeterminada és <emphasis
>false</emphasis
>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term
>L'element <userinput
>emptyLine</userinput
> pertany al grup <userinput
>emptyLines</userinput
> defineix quines línies s'hauran de tractar com a línies buides. Això permet modificar el comportament de l'atribut <emphasis
>lineEmptyContext</emphasis
> en els elements <userinput
>context</userinput
>. Els atributs disponibles són:</term>
<listitem>
<para
><userinput
>regexpr</userinput
> defineix una expressió regular que es tractarà com una línia buida. De manera predeterminada, les línies buides no contenen cap caràcter, per tant, això afegirà línies buides addicionals, per exemple, si voleu que les línies amb espais també es consideren com a línies buides. No obstant això, en la majoria de les definicions de la sintaxi no caldrà establir aquest atribut.</para>
</listitem>
</varlistentry>
<varlistentry>
<term
>L'element <userinput
>encoding</userinput
> en el grup <userinput
>spellchecking</userinput
> defineix una codificació de caràcters per a la verificació ortogràfica. Els atributs disponibles són:</term>
<listitem>
<para
><userinput
>char</userinput
>, és un caràcter codificat.</para>
<para
><userinput
>string</userinput
> és una seqüència de caràcters que es codificaran com el caràcter <emphasis
>char</emphasis
> a la verificació ortogràfica. Per exemple, en el llenguatge LaTeX, la cadena <userinput
>\"{A}</userinput
> representa el caràcter <userinput
>Ä</userinput
>.</para>
</listitem>
</varlistentry>
</variablelist>
</sect3>
<sect3 id="kate-highlight-default-styles">
<title
>Estils predeterminats disponibles</title>
<para
>Els estils predeterminats <link linkend="kate-highlight-system-default-styles"
>ja s'han explicat</link
>, a manera de resum: Els estils predeterminats són tipus de lletra i estils de colors predefinits.</para>
<variablelist>
<varlistentry>
<term
>Estils predeterminats en general:</term>
<listitem>
<para
><userinput
>dsNormal</userinput
>, quan no es requereix un ressaltat especial.</para>
<para
><userinput
>dsKeyword</userinput
>, paraules clau incloses.</para>
<para
><userinput
>dsFunction</userinput
>, crides a funcions i definicions.</para>
<para
><userinput
>dsVariable</userinput
>, si és aplicable: noms de les variables (&pex;, $algunaVar als llenguatges PHP/Perl).</para>
<para
><userinput
>dsControlFlow</userinput
>, controla el flux de paraules clau com «if», «else», «switch», «break», «return», «yield»...</para>
<para
><userinput
>dsOperator</userinput
>, operadors com + - * / :: < ></para>
<para
><userinput
>dsBuiltIn</userinput
>, funcions, classes i objectes inclosos.</para>
<para
><userinput
>dsExtension</userinput
>, extensions comunes, com les classes de les &Qt; i les funcions/macros en els llenguatges C++ i Python.</para>
<para
><userinput
>dsPreprocessor</userinput
>, declaracions del preprocessador o de definicions de macros.</para>
<para
><userinput
>dsAttribute</userinput
>, anotacions com «@override» i «__declspec(...)».</para>
</listitem>
</varlistentry>
<varlistentry>
<term
>Estils predeterminats relacionats amb les cadenes:</term>
<listitem>
<para
><userinput
>dsChar</userinput
>, caràcters sols, com ara «x».</para>
<para
><userinput
>dsSpecialChar</userinput
>, caràcters amb un significat especial en cadenes com escapades, substitucions o els operadors d'expressions regulars.</para>
<para
><userinput
>dsString</userinput
>, cadenes com «hello world».</para>
<para
><userinput
>dsVerbatimString</userinput
>, cadenes literals o sense processar com «raw \backlash» en els llenguatges Perl, CoffeeScript i intèrprets d'ordres, així com «r'\raw'» en llenguatge Python.</para>
<para
><userinput
>dsSpecialString</userinput
>, SQL, expressions regulars, documentació HERE, mode matemàtic de &latex;...</para>
<para
><userinput
>dsImport</userinput
>, importar, incloure o requerir mòduls.</para>
</listitem>
</varlistentry>
<varlistentry>
<term
>Estils predeterminats relacionats amb números:</term>
<listitem>
<para
><userinput
>dsDataType</userinput
>, tipus de dades incloses com «int», «void», «u64».</para>
<para
><userinput
>dsDecVal</userinput
>, valors decimals.</para>
<para
><userinput
>dsBaseN</userinput
>, valors en una base diferent de 10.</para>
<para
><userinput
>dsFloat</userinput
>, valors de coma flotant.</para>
<para
><userinput
>dsConstant</userinput
>, definicions incloses i definides per l'usuari com PI.</para>
</listitem>
</varlistentry>
<varlistentry>
<term
>Estils predeterminats relacionats amb la documentació i els comentaris:</term>
<listitem>
<para
><userinput
>dsComment</userinput
>, comentaris.</para>
<para
><userinput
>dsDocumentation</userinput
>, «/** Comentaris de documentació */» o «"""cadenes_de_documentació"""».</para>
<para
><userinput
>dsAnnotation</userinput
>, ordres de la documentació com «@param», «@brief».</para>
<para
><userinput
>dsCommentVar</userinput
>, els noms de les variables utilitzades en les ordres anteriors, com «foobar» a «@param foobar».</para>
<para
><userinput
>dsRegionMarker</userinput
>, marcadors de regió com els comentaris «//BEGIN», «//END».</para>
</listitem>
</varlistentry>
<varlistentry>
<term
>Altres estils predeterminats:</term>
<listitem>
<para
><userinput
>dsInformation</userinput
>, notes i consells com «@note» al doxygen.</para>
<para
><userinput
>dsWarning</userinput
>, avisos com «@warning» al doxygen.</para>
<para
><userinput
>dsAlert</userinput
>, paraules especials com «Per fer», «TODO», «FIXME», «XXXX».</para>
<para
><userinput
>dsError</userinput
>, errors de ressaltat i sintaxi incorrecta.</para>
<para
><userinput
>dsOthers</userinput
>, quan res més s'hi ajusti.</para>
</listitem>
</varlistentry>
</variablelist>
</sect3>
</sect2>
<sect2 id="kate-highlight-rules-detailled">
<title
>Regles de detecció del ressaltat</title>
<para
>Aquesta secció descriu les regles de detecció del ressaltat.</para>
<para
>Cada regla pot coincidir en cap o amb diversos caràcters al començament de la cadena amb què es comparen. Si la regla coincideix, als caràcters coincidents se'ls assigna l'estil o <emphasis
>attribute</emphasis
> definit per la regla, tanmateix una regla pot demanar que es canviï el context actual.</para>
<para
>Una regla té aquest aspecte:</para>
<programlisting
><NomRegla attribute="(identificador)" context="(identificador)" [atributs específics de la regla] /></programlisting>
<para
>L'<emphasis
>attribute</emphasis
> identifica l'estil que utilitzaran els caràcters coincidents per nom, i el <emphasis
>context</emphasis
> identifica el context a utilitzar des d'aquí.</para>
<para
>El <emphasis
>context</emphasis
> es pot identificar per:</para>
<itemizedlist>
<listitem>
<para
>Un <emphasis
>identifier</emphasis
>, el qual és el nom de l'altre context.</para>
</listitem>
<listitem>
<para
>Una <emphasis
>order</emphasis
> us indica al motor que romandrà en el context actual (<userinput
>#stay</userinput
>), o que salti al context anterior (<userinput
>#pop</userinput
>).</para>
<para
>Per a retrocedir més passos, es pot repetir la paraula clau #pop: <userinput
>#pop#pop#pop</userinput
></para>
</listitem>
<listitem>
<para
>Una <emphasis
>ordre</emphasis
> seguida per un signe d'exclamació (<emphasis
>!</emphasis
>) i un <emphasis
>identificador</emphasis
>, el qual farà que el motor segueixi primer l'ordre i després passi a l'altre context, &pex;, <userinput
>#pop#pop!AltreContext</userinput
>.</para>
</listitem>
<listitem>
<para
>Un <emphasis
>identificador</emphasis
>, el qual és un nom de context, seguit de dos coixinets (<userinput
>##</userinput
>) i un altre <emphasis
>identificador</emphasis
>, el qual és el nom d'una definició de llenguatge. Aquest nom és similar al què s'utilitza en les regles <userinput
>IncludeRules</userinput
> i permet canviar a un context que pertany a una altra definició de ressaltat de la sintaxi, &pex;, <userinput
>AlgunContext##JavaScript</userinput
>. Cal tenir en compte que no és possible utilitzar aquest canvi de context en combinació amb <userinput
>#pop</userinput
>, &pex;, <userinput
>#pop!AlgunContext##JavaScript</userinput
> no és vàlid.</para>
</listitem>
</itemizedlist>
<para
>Els atributs específics de la regla varien, i es descriuen en les següents seccions.</para>
<itemizedlist>
<title
>Atributs comuns</title>
<para
>Totes les regles tenen els següents atributs comuns i estan disponibles sempre que apareixen <userinput
>(atributs comuns)</userinput
>. <emphasis
>attribute</emphasis
> i <emphasis
>context</emphasis
> són atributs requerits, els altres són opcionals. </para>
<listitem>
<para
><emphasis
>attribute</emphasis
>: Un mapa d'atributs d'un <emphasis
>itemData</emphasis
> definit.</para>
</listitem>
<listitem>
<para
><emphasis
>context</emphasis
>: Especifica el context al que canviarà el sistema de ressaltat si les regles coincideixen.</para>
</listitem>
<listitem>
<para
><emphasis
>beginRegion</emphasis
>: Inicia un bloc de plegat del codi. De manera predeterminada: unset.</para>
</listitem>
<listitem>
<para
><emphasis
>endRegion</emphasis
>: Tanca un bloc de plegat del codi. De manera predeterminada: unset.</para>
</listitem>
<listitem>
<para
><emphasis
>lookAhead</emphasis
>: Si està a <emphasis
>true</emphasis
>, el sistema de ressaltat no processarà les longituds coincidents. De manera predeterminada: <emphasis
>false</emphasis
>.</para>
</listitem>
<listitem>
<para
><emphasis
>firstNonSpace</emphasis
>: Només coincidiran si la cadena no conté un espai en blanc al començament de la línia. De manera predeterminada: <emphasis
>false</emphasis
>.</para>
</listitem>
<listitem>
<para
><emphasis
>column</emphasis
>: Només coincideix, si la columna coincideix. De manera predeterminada: unset.</para>
</listitem>
</itemizedlist>
<itemizedlist>
<title
>Regles dinàmiques</title>
<para
>Algunes regles permeten l'atribut opcional <userinput
>dynamic</userinput
> de tipus lògic que de manera predeterminada és <emphasis
>false</emphasis
>. Si dynamic està a <emphasis
>true</emphasis
>, la regla podrà utilitzar arguments que representin el text coincident amb una regla d'una <emphasis
>expressió regular</emphasis
> que canviï al context actual per al contingut en els atributs <userinput
>string</userinput
> o <userinput
>char</userinput
>. En un <userinput
>string</userinput
>, l'argument <replaceable
>%N</replaceable
> (a on N és un número) se substituirà amb el corresponent <replaceable
>N</replaceable
> capturat des de l'expressió regular cridada, començant per 1. En un <userinput
>char</userinput
> l'argument haurà de ser un número <replaceable
>N</replaceable
> i serà substituït amb el primer caràcter de la corresponent <replaceable
>N</replaceable
> capturada des de l'expressió regular cridada. Sempre que un regla permeti aquest atribut haurà de contenir un <emphasis
>(dynamic)</emphasis
>.</para>
<listitem>
<para
><emphasis
>dinàmic</emphasis
>: pot ser <emphasis
>(true|false)</emphasis
>.</para>
</listitem>
</itemizedlist>
<para
><userinput
>Com funciona:</userinput
></para>
<para
>A les <link linkend="regular-expressions"
>expressions regulars</link
> de la regla <userinput
>RegExpr</userinput
>, tot el text entre parèntesis <userinput
>(PATRÓ)</userinput
> serà capturat i recordat. Aquestes captures es podran utilitzar en el context al qual es canvia, en les regles amb l'atribut <userinput
>dynamic</userinput
> <emphasis
>true</emphasis
>, per <replaceable
>%N</replaceable
> (a <emphasis
>String</emphasis
>) o <replaceable
>N</replaceable
> (a <emphasis
>char</emphasis
>).</para>
<para
>És important esmentar que un text capturat en una regla <userinput
>RegExpr</userinput
> només s'emmagatzemarà per al context del canvi, especificat en el seu atribut <userinput
>context</userinput
>.</para>
<tip>
<itemizedlist>
<listitem>
<para
>Si no s'utilitzen les captures, tant per a les regles dinàmiques com en la mateixa expressió regular, s'han d'utilitzar grups sense captura: <userinput
>(?:PATRÓ)</userinput
></para>
<para
>Els grups <emphasis
>lookahead</emphasis
> (anticipada) o <emphasis
>lookbehind</emphasis
> (cerca cap enrere) com <userinput
>(?=PATRÓ)</userinput
>, <userinput
>(?!PATRÓ)</userinput
> <userinput
>(?<=PATRÓ)</userinput
> no seran capturats. Per a obtenir més informació, vegeu la secció sobre <link linkend="regular-expressions"
>expressions regulars</link
>.</para>
</listitem>
<listitem>
<para
>Els grups amb captura es poden utilitzar dins de la mateixa expressió regular, emprant <replaceable
>\N</replaceable
> en lloc de <replaceable
>%N</replaceable
> respectivament. Per a més informació, vegeu <link linkend="regex-capturing"
>Captura del text coincident (referències enrere)</link
> a les <link linkend="regular-expressions"
>Expressions regulars</link
>.</para>
</listitem>
</itemizedlist>
</tip>
<para
>Exemple 1:</para>
<para
>En aquest senzill exemple, el text que coincideix amb l'expressió regular <userinput
>=*</userinput
> serà capturat i inserit din de <replaceable
>%1</replaceable
> a la regla dinàmica. Això permet que el comentari acabi amb la mateixa quantitat de <userinput
>=</userinput
> que al començament. Això coincideix amb el text com: <userinput
>[[ comentari ]]</userinput
>, <userinput
>[=[ comentari ]=]</userinput
> o <userinput
>[=====[ comentari ]=====]</userinput
>.</para>
<para
>A més, les captures només estaran disponibles en el context del canvi <emphasis
>Comentari de múltiples línies</emphasis
>.</para>
<programlisting
><context name="Normal" attribute="Text normal" lineEndContext="#stay">
<RegExpr context="Comentari de múltiples línies" attribute="Comentari" String="\[(=*)\[" beginRegion="RegionComment"/>
</context>
<context name="Comentari de múltiples línies" attribute="Comentari" lineEndContext="#stay">
<StringDetect context="#pop" attribute="Comentari" String="]%1]" dynamic="true" endRegion="RegionComment"/>
</context>
</programlisting>
<para
>Exemple 2:</para>
<para
>A la regla dinàmica, <replaceable
>%1</replaceable
> es correspon amb la captura que coincideix <userinput
>#+</userinput
>, i <replaceable
>%2</replaceable
> amb <userinput
>&quot;+</userinput
>. Això coincidirà amb el text de: <userinput
>#label""""dins del context""""#</userinput
>.</para>
<para
>Aquestes captures no estaran disponibles en altres contextos, com <emphasis
>OtherContext</emphasis
>, <emphasis
>FindEscapes</emphasis
> o <emphasis
>AlgunContext</emphasis
>.</para>
<programlisting
><context name="AlgunContext" 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
>Exemple 3:</para>
<para
>Això coincidirà amb el text com: <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
>Delimitadors locals</title>
<para
>Algunes regles permeten els atributs opcionals <userinput
>weakDeliminator</userinput
> i <userinput
>additionalDeliminator</userinput
>, els quals es combinen amb atributs del mateix nom d'etiqueta de <userinput
>keywords</userinput
>. Per exemple, quan <userinput
>'%'</userinput
> és un delimitador feble de <userinput
>keywords</userinput
>, només podrà esdevenir un delimitador de paraula per a una regla posant-lo en el seu atribut <userinput
>additionalDeliminator</userinput
>. Sempre que una regla permeti aquests atributs, contindrà un <emphasis
>(delimitadors locals)</emphasis
>.</para>
<listitem>
<para
><emphasis
>weakDeliminator</emphasis
>: llista de caràcters que no actuen com a delimitadors de paraula.</para>
</listitem>
<listitem>
<para
><emphasis
>additionalDeliminator</emphasis
>: defineix delimitadors addicionals.</para>
</listitem>
</itemizedlist>
<sect3 id="highlighting-rules-in-detail">
<title
>Les regles en detall</title>
<variablelist>
<varlistentry>
<term
>DetectChar</term>
<listitem>
<para
>Detecta un únic caràcter específic. Normalment s'utilitza per a trobar el final de les cadenes entre cometes.</para>
<programlisting
><DetectChar char="(caràcter)" (atributs comuns) (dinàmic) /></programlisting>
<para
>L'atribut <userinput
>char</userinput
> defineix el caràcter a comparar.</para>
</listitem>
</varlistentry>
<varlistentry>
<term
>Detect2Chars</term>
<listitem>
<para
>Detecta dos caràcters especificats en l'ordre definit.</para>
<programlisting
><Detect2Chars char="(caràcter)" char1="(caràcter)" (atributs comuns) /></programlisting>
<para
>L'atribut <userinput
>char</userinput
> defineix el primer caràcter a comparar, <userinput
>char1</userinput
> el segon.</para>
</listitem>
</varlistentry>
<varlistentry>
<term
>AnyChar</term>
<listitem>
<para
>Detecta un caràcter d'un conjunt de caràcters especificats.</para>
<programlisting
><AnyChar String="(cadena)" (atributs comuns) /></programlisting>
<para
>L'atribut <userinput
>String</userinput
> defineix el conjunt de caràcters.</para>
</listitem>
</varlistentry>
<varlistentry>
<term
>StringDetect</term>
<listitem>
<para
>Detecta una cadena exacta.</para>
<programlisting
><StringDetect String="(cadena)" [insensitive="true|false"] (atributs comuns) (dinàmic) /></programlisting>
<para
>L'atribut <userinput
>String</userinput
> defineix la cadena a comparar. L'atribut <userinput
>insensitive</userinput
> predeterminat és <userinput
>false</userinput
> i es passa a la funció de comparació de la cadena. Si el valor és <userinput
>true</userinput
> la comparació no distingirà les majúscules i minúscules.</para>
</listitem>
</varlistentry>
<varlistentry>
<term
>WordDetect</term>
<listitem>
<para
>Detectar una cadena exacta requereix límits de paraula com un punt <userinput
>«.»</userinput
> o un espai en blanc al començament i al final de la paraula. Penseu en <userinput
>\b<cadena>\b</userinput
> en termes d'una expressió regular, però és més ràpid que la regla <userinput
>RegExpr</userinput
>.</para>
<programlisting
><WordDetect String="(cadena)" [insensitive="true|false"] (atributs comuns) (delimitadors locals) /></programlisting>
<para
>L'atribut <userinput
>String</userinput
> defineix la cadena a comparar. L'atribut <userinput
>insensitive</userinput
> predeterminat és <userinput
>false</userinput
> i es passa a la funció de comparació de la cadena. Si el valor és <userinput
>true</userinput
> la comparació no distingirà les majúscules i minúscules.</para>
<para
>Des del: &kate; 3.5 (&kde; 4.5)</para>
</listitem>
</varlistentry>
<varlistentry>
<term
>RegExpr</term>
<listitem>
<para
>Cerca la coincidència amb una expressió regular.</para>
<programlisting
><RegExpr String="(cadena)" [insensitive="true|false"] [minimal="true|false"] (atributs comuns) (dinàmic) /></programlisting>
<para
>L'atribut <userinput
>String</userinput
> defineix l'expressió regular.</para>
<para
><userinput
>insensitive</userinput
> de manera predeterminada és <userinput
>false</userinput
> i és passada al motor d'expressions regulars.</para>
<para
><userinput
>minimal</userinput
> de manera predeterminada és <userinput
>false</userinput
> i és passada al motor d'expressions regulars.</para>
<para
>Atès que les regles coincideixen amb el començament de la cadena actual, una expressió regular que comenci amb l'accent circumflex (<literal
>^</literal
>) indica que la regla tan sols s'haurà de comparar amb el començament d'una línia.</para>
<para
>Per a obtenir més informació, vegeu la secció sobre <link linkend="regular-expressions"
>expressions regulars</link
>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term
>keyword</term>
<listitem>
<para
>Detecta una paraula clau des d'una llista especificada.</para>
<programlisting
><keyword String="(nom de la llista)" (atributs comuns) (delimitadors locals) /></programlisting>
<para
>L'atribut <userinput
>String</userinput
> identifica la llista de paraules clau pel seu nom. Haurà d'existir una llista amb aquest nom.</para>
<para
>El sistema de ressaltat processa les regles de paraules clau d'una manera molt optimitzada. Això fa que sigui una necessitat absoluta que qualsevol paraula clau que coincideixi necessitarà estar envoltada pels delimitadors definits, ja sigui implícitament (els delimitadors predeterminats), o explícitament especificat dins la propietat <emphasis
>additionalDeliminator</emphasis
> de l'etiqueta <emphasis
>keywords</emphasis
>.</para>
<para
>Si una paraula clau coincideix haurà de contenir un caràcter de delimitador, aquest caràcter respectiu haurà d'afegir-se a la propietat <emphasis
>weakDeliminator</emphasis
> de l'etiqueta <emphasis
>keywords</emphasis
>. Aquest caràcter perdrà la seva propietat delimitadora en totes les regles keyword. També és possible utilitzar l'atribut <emphasis
>weakDeliminator</emphasis
> de la <emphasis
>keyword</emphasis
> perquè aquesta modificació només s'apliqui a aquesta regla.</para>
</listitem>
</varlistentry>
<varlistentry>
<term
>Int</term>
<listitem>
<para
>Detecta un nombre enter (com l'expressió regular: <userinput
>\b[0-9]+</userinput
>).</para>
<para
><programlisting
><Int (atributs comuns) (delimitadors locals) /></programlisting
></para>
<para
>Aquesta regla no té atributs específics.</para>
</listitem>
</varlistentry>
<varlistentry>
<term
>Decimals</term>
<listitem>
<para
>Detecta un nombre decimal (com l'expressió regular: <userinput
>(\b[0-9]+\.[0-9]*|\.[0-9]+)([eE][-+]?[0-9]+)?</userinput
>).</para>
<para
><programlisting
><Float (atributs comuns) (delimitadors locals) /></programlisting
></para>
<para
>Aquesta regla no té atributs específics.</para>
</listitem>
</varlistentry>
<varlistentry>
<term
>HlCOct</term>
<listitem>
<para
>Detecta una representació numèrica d'un nombre octal (com l'expressió regular: <userinput
>\b0[0-7]+</userinput
>).</para>
<para
><programlisting
><HlCOct (atributs comuns) (delimitadors locals) /></programlisting
></para>
<para
>Aquesta regla no té atributs específics.</para>
</listitem>
</varlistentry>
<varlistentry>
<term
>HlCHex</term>
<listitem>
<para
>Detecta una representació numèrica d'un nombre hexadecimal (com una expressió regular: <userinput
>\b0[xX][0-9a-fA-F]+</userinput
>).</para>
<para
><programlisting
><HlCHex (atributs comuns) (delimitadors locals) /></programlisting
></para>
<para
>Aquesta regla no té atributs específics.</para>
</listitem>
</varlistentry>
<varlistentry>
<term
>HlCStringChar</term>
<listitem>
<para
>Detecta un caràcter escapat.</para>
<para
><programlisting
><HlCStringChar (atributs comuns) /></programlisting
></para>
<para
>Aquesta regla no té atributs específics.</para>
<para
>Localitza representacions literals de caràcters que habitualment s'utilitzen en el codi de programació, per exemple <userinput
>\n</userinput
> (línia nova) o <userinput
>\t</userinput
> (tabulació).</para>
<para
>Els següents caràcters coincideixen amb la regla si segueixen a una barra inversa (<literal
>\</literal
>): <userinput
>abefnrtv"'?\</userinput
>. A més seran vàlids els nombres hexadecimals escapats com per exemple <userinput
>\xff</userinput
>, i els nombres octals escapats, per exemple <userinput
>\033</userinput
>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term
>HlCChar</term>
<listitem>
<para
>Detecta un caràcter C.</para>
<para
><programlisting
><HlCChar (atributs comuns) /></programlisting
></para>
<para
>Aquesta regla no té atributs específics.</para>
<para
>Localitza caràcters C tancats en una marca (Exemple: <userinput
>'c'</userinput
>). La marca pot ser un caràcter simple o un caràcter escapat. Vegeu «HICStringChar» per a localitzar seqüències de caràcters escapats.</para>
</listitem>
</varlistentry>
<varlistentry>
<term
>RangeDetect</term>
<listitem>
<para
>Detecta una cadena amb caràcters d'inici i de final definits.</para>
<programlisting
><RangeDetect char="(caràcter)" char1="(caràcter)" (atributs comuns) /></programlisting>
<para
><userinput
>char</userinput
> defineix el caràcter que inicia l'interval, <userinput
>char1</userinput
> el caràcter que finalitza l'interval.</para>
<para
>És molt útil per a detectar, per exemple, petites cadenes entre cometes i similars, però teniu en compte que el motor de ressaltat només pot treballar amb una línia a la vegada, de manera que no es detectaran les cadenes que estiguin dividides en dues línies o més.</para>
</listitem>
</varlistentry>
<varlistentry>
<term
>LineContinue</term>
<listitem>
<para
>Coincideix amb un caràcter específic al final d'una línia.</para>
<programlisting
><LineContinue (atributs comuns) [char="\"] /></programlisting>
<para
>L'atribut <userinput
>char</userinput
> defineix un caràcter opcional a comparar, de manera predeterminada és la barra inversa (<userinput
>'\'</userinput
>). Nou des del &kde; 4.13.</para>
<para
>Aquesta regla és pràctica per a canviar el context al final de la línia. Això és necessari per exemple en C/C++ per a continuar macros o cadenes.</para>
</listitem>
</varlistentry>
<varlistentry>
<term
>IncludeRules</term>
<listitem>
<para
>Inclou regles des d'un altre context o llenguatge/fitxer.</para>
<programlisting
><IncludeRules context="contextlink" [includeAttrib="true|false"] /></programlisting>
<para
>L'atribut <userinput
>context</userinput
> defineix el context a incloure.</para>
<para
>Si és una cadena simple, inclourà totes les regles definides en el context actual, exemple: <programlisting
><IncludeRules context="anotherContext" /></programlisting
></para>
<para
>Si la cadena conté un <userinput
>##</userinput
> el sistema de ressaltat cercarà un context d'una altra definició del llenguatge amb el nom indicat, per exemple, <programlisting
><IncludeRules context="String##C++" /></programlisting
> inclouria el context <emphasis
>String</emphasis
> des de la definició de ressaltat en <emphasis
>C++</emphasis
>.</para>
<para
>Si l'atribut <userinput
>includeAttrib</userinput
> està a <emphasis
>true</emphasis
>, canvia l'atribut de destinació per un altre de la font. Això és necessari, per exemple, per al treball de comentar, si el text coincideix amb el context inclòs s'utilitzarà un ressaltat diferent que amb el context amfitrió. </para>
</listitem>
</varlistentry>
<varlistentry>
<term
>DetectSpaces</term>
<listitem>
<para
>Detecta els espais en blanc.</para>
<programlisting
><DetectSpaces (atributs comuns) /></programlisting>
<para
>Aquesta regla no té atributs específics.</para>
<para
>Utilitzeu aquesta regla si sabeu que hi poden haver diversos espais en blanc al davant, per exemple, al començament de les línies sagnades. Aquesta regla ometrà tots els espais en blanc a la vegada, en comptes de comprovar múltiples regles i saltar coincidències.</para>
</listitem>
</varlistentry>
<varlistentry>
<term
>DetectIdentifier</term>
<listitem>
<para
>Detecta identificadors de cadenes (com l'expressió regular: <userinput
>[a-zA-Z_][a-zA-Z0-9_]*</userinput
>).</para>
<programlisting
><DetectIdentifier (atributs comuns) /></programlisting>
<para
>Aquesta regla no té atributs específics.</para>
<para
>Utilitzeu aquesta regla per a saltar d'una vegada una cadena de paraula de caràcters, en comptes de comprovar múltiples regles a la vegada i saltar coincidències.</para>
</listitem>
</varlistentry>
</variablelist>
</sect3>
<sect3>
<title
>Consells i trucs</title>
<itemizedlist>
<para
>Una vegada que hàgiu entès com funciona el canvi de context serà fàcil escriure definicions de ressaltat. Tot i que haureu de tenir cura de comprovar en quina situació s'hauria de seleccionar una regla. Les expressions regulars són molt potents, però són lentes en comparació amb altres regles. Per això haureu de tenir en compte els següents consells. </para>
<listitem>
<para
>Si només heu de localitzar dos caràcters, utilitzeu <userinput
>Detect2Chars</userinput
> en comptes de <userinput
>StringDetect</userinput
>. El mateix s'aplica a <userinput
>DetectChar</userinput
>.</para>
</listitem>
<listitem>
<para
>Les expressions regulars són fàcils d'emprar, però a vegades hi ha formes molt més ràpides d'obtenir el mateix resultat. Imagineu que només desitgeu localitzar el caràcter <userinput
>«#»</userinput
> si aquest és el primer caràcter de la línia. Una solució basada en una expressió regular seria quelcom semblant a això: <programlisting
><RegExpr attribute="Macro" context="macro" String="^\s*#" /></programlisting
>Podeu aconseguir el mateix molt més ràpid utilitzant: <programlisting
><DetectChar attribute="Macro" context="macro" char="#" firstNonSpace="true" /></programlisting
>Si voleu que l'expressió regular localitzi <userinput
>«^#»</userinput
> també podeu utilitzar <userinput
>DetectChar</userinput
> amb l'atribut <userinput
>column="0"</userinput
>. L'atribut <userinput
>column</userinput
> compta els caràcters, per tant el tabulador és només un caràcter. </para>
</listitem>
<listitem>
<para
>A les regles <userinput
>RegExpr</userinput
>, utilitzeu l'atribut <userinput
>column="0"</userinput
> si el patró <userinput
>^PATRÓ</userinput
> s'utilitza per a fer coincidir el text amb el començament d'una línia. Això millorarà el rendiment, ja que evitarà cercar coincidències en la resta de les columnes.</para>
</listitem>
<listitem>
<para
>En les expressions regulars, utilitzeu grups sense captura <userinput
>(?:PATRÓ)</userinput
> en lloc dels grups amb captura <userinput
>(PATRÓ)</userinput
>, si les captures no s'utilitzen per a la mateixa expressió regular o en regles dinàmiques. Això evita emmagatzemar innecessàriament les captures.</para>
</listitem>
<listitem>
<para
>Podeu canviar de context sense processar els caràcters. Suposeu que voleu canviar de context quan trobeu una cadena <userinput
>*/</userinput
>, però cal processar aquesta cadena en el següent context. La regla de sota coincidirà, i l'atribut <userinput
>lookAhead</userinput
> farà que es desi la cadena coincident per al següent context. <programlisting
><Detect2Chars attribute="Comment" context="#pop" char="*" char1="/" lookAhead="true" /></programlisting>
</para>
</listitem>
<listitem>
<para
>Utilitzeu <userinput
>DetectSpaces</userinput
> si sabeu quants espais en blanc hi ha.</para>
</listitem>
<listitem>
<para
>Utilitzeu <userinput
>DetectIdentifier</userinput
> en comptes de l'expressió regular <userinput
>«[a-zA-Z_]\w*»</userinput
>.</para>
</listitem>
<listitem>
<para
>Utilitza els estils predeterminats sempre que es pugui. D'aquesta manera l'usuari es trobarà un entorn familiar.</para>
</listitem>
<listitem>
<para
>Mireu altres fitxers &XML; per a comprovar de quina forma altra gent implementa les regles delicades.</para>
</listitem>
<listitem>
<para
>Podeu validar tots els fitxers &XML; utilitzant l'ordre <command
>validatehl.sh language.xsd mySyntax.xml</command
>. Els fitxers <filename
>validatehl.sh</filename
> i <filename
>language.xsd</filename
> estan disponibles al <ulink url="https://commits.kde.org/syntax-highlighting?path=data/schema"
>repositori del ressaltat de la sintaxi</ulink
>. </para>
</listitem>
<listitem>
<para
>Si tot sovint repetiu expressions regulars complexes podeu utilitzar <emphasis
>ENTITIES</emphasis
>. Exemple:</para>
<programlisting
><?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE language SYSTEM "language.dtd"
[
<!ENTITY la_meva_ref "[A-Za-z_:][\w.:_-]*">
]>
</programlisting>
<para
>Ara podeu utilitzar <emphasis
>&la_meva_ref;</emphasis
> en comptes de l'expressió regular.</para>
</listitem>
</itemizedlist>
</sect3>
</sect2>
</sect1>
<sect1 id="color-themes">
<title
>Treballar amb temes de color</title>
<sect2 id="color-themes-overview">
<title
>Vista general</title>
<para
>Els temes de color defineixen els colors de l'<link linkend="kate-part"
>àrea d'edició de text</link
> i del <link linkend="highlight"
>ressaltat de la sintaxi</link
>. Un tema de color abasta el següent: <itemizedlist>
<listitem
><para
>L'estil del text, utilitzat per a ressaltar la sintaxi mitjançant els <emphasis
>atributs predeterminats d'estil</emphasis
>. Per exemple, el color del text i el del text seleccionat.</para
></listitem>
<listitem
><para
>El fons de l'àrea d'edició de text, inclosa la selecció del text i la línia actual.</para
></listitem>
<listitem
><para
>La vora de la icona de l'àrea de text: el seu fons, la línia de separació, els números de línia, els marcadors per a l'ajust de les paraules a la línia, les marques de línia modificada i el plegat de codi.</para
></listitem>
<listitem
><para
>Els decoradors de text com els marcadors de cerca, el sagnat i les marques de línia per a tabulació/espai, la coincidència dels claudàtors i la verificació ortogràfica.</para
></listitem>
<listitem
><para
>Marcadors i retalls.</para
></listitem>
</itemizedlist>
</para>
<para
>Per evitar confusions, el següent queda fora de l'àmbit: <itemizedlist>
<listitem
><para
>El tipus i mida de la lletra.</para
></listitem>
<listitem
><para
>Els colors de l'aplicació d'edició de text, com el mapa de la barra de desplaçament, els menús, la barra de pestanyes, el color de la finestra, &etc; En les aplicacions &kde;, com el &kate; o el &kdevelop;, aquests colors es defineixen mitjançant l'<userinput
>esquema de color global del &plasma;</userinput
>, el qual s'estableix en el mòdul <ulink url="help:/kcontrol/colors/"
><quote
>Colors</quote
></ulink
> a l'&systemsettings; o des de la mateixa aplicació en el menú <menuchoice
><guimenu
>Arranjament</guimenu
><guisubmenu
>Esquema de color</guisubmenu
></menuchoice
>. </para
></listitem>
</itemizedlist>
</para>
<mediaobject>
<imageobject
><imagedata format="PNG" fileref="breeze-color-theme-preview.png"/></imageobject>
<textobject
><phrase
>Temes de color <quote
>Brisa clara</quote
> i <quote
>Brisa fosca</quote
> amb ressaltat de la sintaxi del <quote
>C++</quote
>.</phrase>
</textobject>
<caption
><para
>Temes de color <quote
>Brisa clara</quote
> i <quote
>Brisa fosca</quote
> amb ressaltat de la sintaxi del <quote
>C++</quote
>.</para>
</caption>
</mediaobject>
</sect2>
<sect2 id="color-themes-ksyntaxhighlighting">
<title
>Els temes de color «KSyntaxHighlighting»</title>
<para
>El marc de treball <ulink url="https://api.kde.org/frameworks/syntax-highlighting/html/"
>KSyntaxHighlighting</ulink
>, el qual és el motor del <link linkend="highlight"
>ressaltat de la sintaxi</link
>, és la biblioteca que <userinput
>proporciona i gestiona els temes de color</userinput
>. Aquest forma part dels &frameworks; del &kde; i s'utilitza en els editors de text del &kde; com el <ulink url="https://apps.kde.org/ca/kate"
>&kate;</ulink
>, <ulink url="https://apps.kde.org/ca/kwrite"
>&kwrite;</ulink
>, <ulink url="https://apps.kde.org/ca/kile"
>&kile;</ulink
> i <ulink url="https://apps.kde.org/ca/kdevelop"
>&kdevelop;</ulink
>. Aquesta dependència té el següent aspecte:</para>
<mediaobject>
<imageobject
><imagedata format="PNG" fileref="kf5-ksyntaxhighlighting.png"/></imageobject>
<textobject
><phrase
>Dependència de les biblioteques dels &frameworks; 5 del &kde; en els editors de text.</phrase
></textobject>
<caption
><para
>Dependència de les biblioteques dels &frameworks; del &kde; en els editors de text.</para>
</caption>
</mediaobject>
<para
>El marc de treball KSyntaxHighlighting inclou una varietat de temes integrats que es mostren a la pàgina <ulink url="https://kate-editor.org/themes/"
><quote
>Temes de color</quote
></ulink
> del lloc web de l'editor &kate;.</para>
<para
>El marc de treball <ulink url="https://api.kde.org/frameworks/ktexteditor/html/"
>KTextEditor</ulink
>, el qual és el motor d'edició de text, proporciona una interfície d'usuari per a crear i editar els temes de color, inclosa una eina per a importar i exportar els temes. Aquesta és la forma més senzilla de crear-los i editar-los, podeu accedir-hi des del <link linkend="config-dialog"
>diàleg <quote
>Configura</quote
></link
> de l'editor de text. Hi ha més detalls a <xref linkend="color-themes-gui"/>.</para>
<mediaobject>
<imageobject
><imagedata format="PNG" fileref="color-themes-gui-breeze-dark-default-text-styles.png"/></imageobject>
<textobject
><phrase
>La &IGU; per a gestionar els temes de color a la configuració del &kate;.</phrase
></textobject>
<caption
><para
>La &IGU; per a gestionar els temes de color a la configuració del &kate;.</para>
</caption>
</mediaobject>
<para
>És important esmentar que, en els editors de text del &kde; com el &kate; o el &kdevelop;, els temes de color de KSyntaxHighlighting s'utilitzen <ulink url="https://kate-editor.org/post/2020/2020-09-13-kate-color-themes-5.75/"
>des dels &frameworks; 5.75 del &kde;</ulink
>, llançats el 10 d'octubre de 2020. Anteriorment, s'utilitzaven els esquemes de color del &kate; (configuració d'esquema basada en el KConfig) i ara estan en desús. No obstant això, és possible convertir els antics esquemes del &kate; als temes de color de KSyntaxHighlighting. El <ulink url="https://invent.kde.org/frameworks/syntax-highlighting"
>repositori KSyntaxHighlighting</ulink
> inclou l'script <userinput
>utils/kateschema_to_theme_converter.py</userinput
> i la utilitat <userinput
>utils/schema-converter/</userinput
> per a aquest propòsit. </para>
</sect2>
<sect2 id="color-themes-json">
<title
>El format &JSON; dels temes de color</title>
<sect3 id="color-themes-json-overview">
<title
>Vista general</title>
<para
>Els temes de color s'emmagatzemen en fitxers de format &JSON;, amb l'extensió <userinput
>.theme</userinput
>.</para>
<para
>En el <ulink url="https://invent.kde.org/frameworks/syntax-highlighting"
>codi font de KSyntaxHighlighting</ulink
>, els fitxers &JSON; dels temes integrats es troben a la carpeta <userinput
>data/themes/</userinput
>. Cal tenir en compte que en els editors de text, els temes integrats es compilen a dins de la biblioteca KSyntaxHighlighting, per tant, la forma d'accedir-hi és a través del codi font o <link linkend="color-themes-gui-import-export"
>exportant-la des de la &IGU; per a gestionar els temes de KTextEditor</link
>.</para>
<para
>També és possible afegir amb facilitat temes addicionals o personalitzats, els quals es carreguen des del sistema de fitxers. Els fitxers de tema personalitzats per l'usuari es troben a la carpeta <filename class="directory"
>org.kde.syntax-highlighting/themes/</filename
> en la vostra carpeta d'usuari, la qual trobareu amb l'ordre <userinput
><command
>qtpaths</command
><option
> --paths GenericDataLocation</option
></userinput
> que normalment és <filename class="directory"
><envar
>$HOME</envar
>/.local/share/</filename
> i <filename class="directory"
>/usr/share/</filename
>. </para>
<para
>En els paquets Flatpak i Snap, la carpeta anterior no funcionarà, ja que la ubicació de les dades és diferent per a cada aplicació. En una aplicació de Flatpak, aquesta ubicació generalment és <filename class="directory"
><envar
>$HOME</envar
>/.var/app/<replaceable
>nom_paquet_flatpak</replaceable
>/data/org.kde.syntax-highlighting/themes/</filename
> i en una aplicació de Snap aquesta ubicació és <filename class="directory"
><envar
>$HOME</envar
>/snap/<replaceable
>nom_paquet_snap</replaceable
>/current/.local/share/org.kde.syntax-highlighting/themes/</filename
>. </para>
<para
>Al &Windows; aquests fitxers es troben a <filename
>%USERPROFILE%\AppData\Local\org.kde.syntax-highlighting\themes</filename
>. <replaceable
>%USERPROFILE%</replaceable
> que generalment s'expandeix a <filename
>C:\Users\<replaceable
>nom_usuari</replaceable
></filename
>.</para>
<para
>En resum, per a la majoria de les configuracions, la carpeta de temes personalitzats és la següent:</para>
<informaltable>
<tgroup cols="2">
<tbody>
<row>
<entry
>Per a l'usuari local</entry>
<entry
><filename class="directory"
><envar
>$HOME</envar
>/.local/share/org.kde.syntax-highlighting/themes/</filename
></entry>
</row>
<row>
<entry
>Per a tots els usuaris</entry>
<entry
><filename class="directory"
>/usr/share/org.kde.syntax-highlighting/themes/</filename
></entry>
</row>
<row>
<entry
>Per als paquets Flatpak</entry>
<entry
><filename class="directory"
><envar
>$HOME</envar
>/.var/app/<replaceable
>nom_paquet_flatpak</replaceable
>/data/org.kde.syntax-highlighting/themes/</filename
></entry>
</row>
<row>
<entry
>Per als paquets Snap</entry>
<entry
><filename class="directory"
><envar
>$HOME</envar
>/snap/<replaceable
>nom_paquet_snap</replaceable
>/current/.local/share/org.kde.syntax-highlighting/themes/</filename
></entry>
</row>
<row>
<entry
>A &Windows;</entry>
<entry
><filename
>%USERPROFILE%\AppData\Local\org.kde.syntax-highlighting\themes</filename
></entry>
</row>
</tbody>
</tgroup>
</informaltable>
<para
>Si hi ha múltiples fitxers de tema amb el mateix nom, es carregarà el fitxer amb la <userinput
>revisió</userinput
> més alta. </para>
</sect3>
<sect3 id="color-themes-json-basic">
<title
>L'estructura &JSON;</title>
<para
>L'estructura d'un fitxer &JSON; s'explica <ulink url="https://www.json.org"
>al seu lloc web</ulink
>. Bàsicament, un fitxer de format &JSON; consta de: <itemizedlist>
<listitem
><para
>Col·leccions de parells clau/valor, separats per comes i agrupats en <userinput
>{}</userinput
>, els quals anomenarem <quote
>objectes</quote
>.</para
></listitem>
<listitem
><para
>Llistes ordenades de valors, separats per comes i agrupats en <userinput
>[]</userinput
>, a les quals anomenarem <quote
>matriu</quote
>.</para
></listitem
></itemizedlist>
</para>
<para
>En aquest article s'utilitzaran les nomenclatures <quote
>clau</quote
>, <quote
>valor</quote
>, <quote
>objecte</quote
> i <quote
>matriu</quote
>. Si és la primera vegada que treballeu amb fitxers &JSON;, comprendre'ls és tan senzill com mirar els exemples que hi ha a continuació. </para>
</sect3>
<sect3 id="color-themes-json-root">
<title
>Seccions principals dels fitxers &JSON; de temes de color</title>
<para
>L'objecte arrel del fitxer &JSON; de tema de color conté les claus d'esquema següents:</para>
<itemizedlist>
<listitem
><para
><userinput
>metadata</userinput
>: És obligatòria. El valor és un objecte amb les metadades del tema, com el nom, la revisió i la llicència.</para>
<para
>Això es detalla a <xref linkend="color-themes-json-metadata"/>.</para>
</listitem>
<listitem
><para
><userinput
>editor-colors</userinput
>: És obligatòria. El valor és un objecte amb els colors de l'àrea per a l'edició de text, com el fons, la vora d'icones i la decoració del text.</para>
<para
>Això es detalla a <xref linkend="color-themes-editor-colors"/>.</para>
</listitem>
<listitem
><para
><userinput
>text-styles</userinput
>: És obligatòria. El valor és un objecte amb els atributs <emphasis
>d'estil per al text predeterminat</emphasis
> del ressaltat de la sintaxi. Cada atribut defineix el seu <emphasis
>color del text</emphasis
>, el seu <emphasis
>color del text seleccionat</emphasis
> o si està en <emphasis
>negreta</emphasis
> o <emphasis
>cursiva</emphasis
>, per exemple. Es pot fer referència als estils de text des dels <link linkend="kate-highlight-default-styles"
>atributs dels fitxers &XML; per a definició de la sintaxi</link
>.</para>
<para
>Això es detalla a <xref linkend="color-themes-text-styles"/>.</para>
</listitem>
<listitem
><para
><userinput
>custom-styles</userinput
>: És opcional. Defineix estils de text per als atributs de les definicions específiques del ressaltat de la sintaxi. Per exemple, en una definició del ressaltat com en <userinput
>Python</userinput
> o <userinput
>Markdown</userinput
>, podreu especificar un estil de text diferent que superposi el predeterminat definit a <userinput
>text-styles</userinput
>.</para>
<para
>Això es detalla a <xref linkend="color-themes-custom-styles"/>.</para>
</listitem>
</itemizedlist>
<para
>El llenguatge &JSON; no admet comentaris. No obstant això, podeu fer servir la clau opcional <userinput
>_comments</userinput
> en l'objecte arrel per a escriure els comentaris, per exemple, si esteu adaptant un tema existent, podeu posar l'&URL; del repositori original. La forma més pràctica és utilitzar una matriu de cadenes. </para>
<para
>A continuació es mostra un fitxer d'exemple per al tema <quote
>Breeze Light</quote
>. Podeu observar que, per a evitar que l'exemple sigui massa gran, els objectes <userinput
>editor-colors</userinput
> i <userinput
>text-styles</userinput
> no contenen totes les claus requerides. Podeu veure tot el fitxer <ulink url="https://invent.kde.org/frameworks/syntax-highlighting/-/blob/master/data/themes/breeze-light.theme"
>del tema <quote
>Breeze Light</quote
> al repositori de KSyntaxHighlighting</ulink
>. </para>
<programlisting
>{
"_comments": [
"Aquest és un comentari.",
"Si aquest tema és una adaptació d'un altre, poseu l'enllaç cap al repositori original."
],
"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
>Les altres claus per al color de l'editor...</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
>Les altres claus per a l'estil del text...</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
>Metadades</title>
<para
>L'objecte &JSON; de la clau de <userinput
>metadata</userinput
> conté informació rellevant sobre el tema. Aquest objecte té les següents claus: <itemizedlist>
<listitem
><para
><userinput
>name</userinput
>: És una <emphasis
>cadena</emphasis
> que estableix el nom de l'idioma. Apareixerà posteriorment en els menús i diàlegs. És obligatòria.</para
></listitem>
<listitem
><para
><userinput
>revision</userinput
>: És un nombre <emphasis
>enter</emphasis
> que especifica la revisió actual del fitxer de tema. Sempre que actualitzeu un fitxer per a tema de colors, assegureu-vos d'augmentar aquest número. És obligatòria.</para
></listitem>
<listitem
><para
><userinput
>license</userinput
>: És una <emphasis
>cadena</emphasis
> que defineix la llicència del tema, utilitzant l'identificador <userinput
>SPDX-License-Identifier</userinput
> des del <ulink url="https://spdx.dev/"
>format SPDX estàndard per a la comunicació de la llicència</ulink
>. És opcional.</para>
<para
>Podeu veure la llista completa dels identificadors de llicència SPDX <ulink url="https://spdx.org/licenses/"
>aquí</ulink
>.</para
></listitem>
<listitem
><para
><userinput
>copyright</userinput
>: És una <emphasis
>matriu</emphasis
> de <emphasis
>cadenes</emphasis
> que especifica els autors del tema, utilitzant l'identificador <userinput
>SPDX-FileCopyrightText</userinput
> des del <ulink url="https://spdx.dev/"
>format SPDX estàndard per a la comunicació de la llicència</ulink
>. És opcional.</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
>Els colors en detall</title>
<para
>Aquesta secció detalla tots els atributs de color disponibles i les opcions de configuració disponibles del color.</para>
<sect3 id="color-themes-editor-colors">
<title
>Colors de l'editor</title>
<para
>Correspon als colors de l'<link linkend="kate-part"
>àrea per a l'edició de text</link
>.</para>
<para
>En el <link linkend="color-themes-json"
>fitxer de tema &JSON;</link
>, la clau respectiva <userinput
>editor-colors</userinput
> té com a valor un <emphasis
>objecte</emphasis
> on cada clau fa referència a un color d'atribut de l'editor de text. Aquí, <userinput
>totes les claus disponibles són obligatòries</userinput
>, els seus valors són <userinput
>cadenes</userinput
> amb codis de color en hexadecimal, com <quote
>#00B5CF</quote
>. </para>
<para
>A <link linkend="color-themes-gui"
>la &IGU; per a gestionar els temes de KTextEditor</link
>, aquests atributs es poden modificar a la pestanya <userinput
><guilabel
>Colors</guilabel
></userinput
>. </para>
<para
>Les claus disponibles són les següents; les claus utilitzades en el <link linkend="color-themes-json"
>fitxer &JSON;</link
> es llisten en negreta, els noms utilitzats a la <link linkend="color-themes-gui"
>&IGU;</link
> es mostren entre parèntesis. </para>
<variablelist>
<varlistentry id="variable-prefcolors-colors-text-background">
<term
><guilabel
>Colors de fons de l'editor</guilabel
></term>
<listitem>
<variablelist>
<varlistentry id="variable-pref-colors-normal-text">
<term
><userinput
>BackgroundColor</userinput
> (<guilabel
>Àrea de text</guilabel
>)</term>
<listitem
><para
>Aquest és el fons predeterminat per a l'àrea d'edició, serà el color dominant a l'àrea d'edició.</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
>Text seleccionat</guilabel
>)</term>
<listitem
><para
>Aquest és el fons per al text seleccionat. </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
>Línia actual</guilabel
>)</term>
<listitem
><para
>Estableix el color per a la línia actual. Estableix aquesta opció una mica diferent del fons del text normal per a ajudar a mantenir el focus en la línia actual. </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
>Ressaltat de la cerca</guilabel
>)</term>
<listitem
><para
>Ajusta el color per al text que coincideixi amb la vostra última cerca. </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
>Ressaltat de la substitució</guilabel
>)</term>
<listitem
><para
>Ajusta el color per al text que coincideixi amb la vostra última operació de substitució.</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
>Vora de la icona</guilabel
></term>
<listitem>
<variablelist>
<varlistentry>
<term
><userinput
>IconBorder</userinput
> (<guilabel
>Àrea de fons</guilabel
>)</term>
<listitem
><para
>Aquest color s'utilitza per a les marques, números de línia i vores de les marques de plegat del codi situats al costat esquerre de la vista d'edició quan aquests siguin mostrats. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><userinput
>LineNumbers</userinput
> (<guilabel
>Números de línia</guilabel
>)</term>
<listitem
><para
>Aquest color s'utilitza per a dibuixar els números de línia al costat esquerre quan siguin mostrats.</para
></listitem>
</varlistentry>
<varlistentry>
<term
><userinput
>CurrentLineNumber</userinput
> (<guilabel
>Número de la línia actual</guilabel
>)</term>
<listitem
><para
>Aquest color s'utilitza per a dibuixar el número de línia de la línia actual, quan es mostra, a la banda esquerra de la vista. Establir això una mica diferent de <quote
>LineNumbers</quote
> ajudarà a mantenir l'enfocament sobre la línia actual. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><userinput
>Separator</userinput
> (<guilabel
>Separador</guilabel
>)</term>
<listitem
><para
>Aquest color s'utilitza per a dibuixar la línia vertical que separa la vora d'icones del fons de l'àrea de text.</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
>Marcador d'ajust de les paraules</guilabel
>)</term>
<listitem
><para
>Aquest color s'utilitza per a dibuixar un patró a l'esquerra de les línies ajustades dinàmicament quan siguin alineades verticalment, i també per a les marques d'ajust estàtic de les línies.</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
>Plegat de codi</guilabel
>)</term>
<listitem
><para
>Aquest color s'utilitza per a ressaltar la secció del codi que es plega quan feu clic a la fletxa de plegat del codi a l'esquerra d'un document. Per a obtenir més informació, vegeu <link linkend="advanced-editing-tools-code-folding"
>la documentació per al plegat del codi</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
>Línies modificades</guilabel
>)</term>
<listitem
><para
>Aquest color s'utilitza per a ressaltar a l'esquerra algunes línies del document que han estat modificades però no desades. Per a obtenir més informació, vegeu <xref linkend="kate-part-line-modification"/>.</para
></listitem>
</varlistentry>
<varlistentry>
<term
><userinput
>SavedLines</userinput
> (<guilabel
>Línies desades</guilabel
>)</term>
<listitem
><para
>Aquest color s'utilitza per a ressaltar a l'esquerra algunes línies del document que han estat modificades i desades en aquesta sessió. Per a obtenir més informació, vegeu <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
>Decoracions de text</guilabel
></term>
<listitem>
<variablelist>
<varlistentry>
<term
><userinput
>SpellChecking</userinput
> (<guilabel
>Línia amb error ortogràfic</guilabel
>)</term>
<listitem
><para
>Aquest color s'utilitza per a indicar els errors ortogràfics.</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
>Marcadors de tabulació i espai</guilabel
>)</term>
<listitem
><para
>Aquest color s'utilitza per a dibuixar els indicadors d'espai en blanc, quan estan activats.</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
>Línia amb sagnat</guilabel
>)</term>
<listitem
><para
>Aquest color s'utilitza per a dibuixar una línia a l'esquerra dels blocs de sagnat, si <link linkend="appearance-general"
>aquesta característica està activada</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
>Ressaltat dels parèntesis</guilabel
>)</term>
<listitem
><para
>Aquest color s'utilitza per a dibuixar el fons dels claudàtors emparellats. </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
>Colors dels marcadors</guilabel
></term>
<listitem>
<variablelist>
<varlistentry>
<term
><userinput
>MarkBookmark</userinput
> (<guilabel
>Punt</guilabel
>)</term>
<listitem
><para
>Aquest color s'utilitza per a indicar els punts. Cal recordar que aquest color té una opacitat del 22% (i del 33% per a la línia actual) pel que fa al fons. Per a més informació, vegeu <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
>Punt d'interrupció actiu</guilabel
>)</term>
<listitem
><para
>El connector GDB utilitza aquest color per a indicar un punt d'interrupció actiu. Cal tenir en compte que aquest color té una opacitat del fons. Per a més informació, vegeu <ulink url="help:/kate/kate-application-plugin-gdb.html"
>la documentació del connector GDB</ulink
>.</para
></listitem>
</varlistentry>
<varlistentry>
<term
><userinput
>MarkBreakpointReached</userinput
> (<guilabel
>S'ha arribat a un punt d'interrupció</guilabel
>)</term>
<listitem
><para
>El connector GDB utilitza aquest color per a indicar un punt d'interrupció que heu assolit durant la depuració. Cal tenir en compte que aquest color té una opacitat del fons. Per a més informació, vegeu <ulink url="help:/kate/kate-application-plugin-gdb.html"
>la documentació del connector GDB</ulink
>.</para
></listitem>
</varlistentry>
<varlistentry>
<term
><userinput
>MarkBreakpointDisabled</userinput
> (<guilabel
>Punt d'interrupció desactivat</guilabel
>)</term>
<listitem
><para
>El connector GDB utilitza aquest color per a indicar un punt d'interrupció inactiu. Cal tenir en compte que aquest color té una opacitat del fons. Per a més informació, vegeu <ulink url="help:/kate/kate-application-plugin-gdb.html"
>la documentació del connector GDB</ulink
>.</para
></listitem>
</varlistentry>
<varlistentry>
<term
><userinput
>MarkExecution</userinput
> (<guilabel
>Execució</guilabel
>)</term>
<listitem
><para
>Aquest color és utilitzat pel connector GDB en la línia que s'està executant. Cal tenir en compte que aquest color té una opacitat del fons. Per a més informació, vegeu <ulink url="help:/kate/kate-application-plugin-gdb.html"
>la documentació del connector GDB</ulink
>.</para
></listitem>
</varlistentry>
<varlistentry>
<term
><userinput
>MarkWarning</userinput
> (<guilabel
>Avís</guilabel
>)</term>
<listitem
><para
>El connector de compilació utilitza aquest color per a indicar una línia que ha provocat un avís del compilador. Cal tenir en compte que aquest color té una opacitat del fons. Per a més informació, vegeu <ulink url="help:/kate/kate-application-plugin-build.html"
>la documentació del connector de construcció</ulink
>.</para
></listitem>
</varlistentry>
<varlistentry>
<term
><userinput
>MarkError</userinput
> (<guilabel
>Error</guilabel
>)</term>
<listitem
><para
>El connector de construcció utilitza aquest color per a indicar una línia que ha provocat un error de compilació. Cal tenir en compte que aquest color té una opacitat del fons. Per a més informació, vegeu <ulink url="help:/kate/kate-application-plugin-build.html"
>la documentació del connector de construcció</ulink
>.</para
></listitem>
</varlistentry>
</variablelist>
</listitem>
</varlistentry>
<varlistentry id="variable-prefcolors-colors-text-templates-snippets">
<term
><guilabel
>Plantilles i retalls de text</guilabel
></term>
<listitem>
<variablelist>
<varlistentry>
<term
><userinput
>TemplateBackground</userinput
> (<guilabel
>Fons</guilabel
>)</term>
<listitem
><para
>El connector Retalls del &kate; utilitza aquest color per a marcar el fons d'un retall. Per a més informació, vegeu <ulink url="help:/kate/kate-application-plugin-snippets.html"
>la documentació dels Retalls del &kate;</ulink
>.</para
></listitem>
</varlistentry>
<varlistentry>
<term
><userinput
>TemplatePlaceholder</userinput
> (<guilabel
>Text variable editable</guilabel
>)</term>
<listitem
><para
>El connector Retalls del &kate; utilitza aquest color per a marcar un text variable en el qual podreu fer clic per a editar-lo manualment. Per a més informació, vegeu <ulink url="help:/kate/kate-application-plugin-snippets.html"
>la documentació de Retalls del &kate;</ulink
>.</para
></listitem>
</varlistentry>
<varlistentry>
<term
><userinput
>TemplateFocusedPlaceholder</userinput
> (<guilabel
>Text variable editable amb el focus</guilabel
>)</term>
<listitem
><para
>El connector Retalls del &kate; utilitza aquest color per a marcar el text variable que esteu editant. Per a més informació, vegeu <ulink url="help:/kate/kate-application-plugin-snippets.html"
>la documentació de Retalls del &kate;</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
>Text variable no editable</guilabel
>)</term>
<listitem
><para
>Aquest color és utilitzat pel connector Retalls del &kate; per a marcar un text variable que no es pot editar de forma manual, com el que s'omple automàticament. Per a obtenir més informació, vegeu <ulink url="help:/kate/kate-application-plugin-snippets.html"
>la documentació per al connector Retalls del &kate;</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
>Estils de text predeterminats</title>
<para
>Els estils predeterminats del text són heretats pels estils del text ressaltat, el qual permet a l'editor presentar el text d'una manera molt coherent, per exemple, el text dels comentaris utilitza el mateix estil en gairebé tots els formats de text que pot ressaltar el KSyntaxHighlighting. </para>
<note>
<para
>Es pot fer referència a aquests estils de text des dels <userinput
>estils predeterminats</userinput
> utilitzats en els fitxers &XML; de definició per al <link linkend="highlight"
>ressaltat de la sintaxi</link
>, per exemple, l'atribut <quote
>Normal</quote
> és equivalent a <quote
>dsNormal</quote
> en els fitxers &XML; i <quote
>DataType</quote
> és equivalent a <quote
>dsDataType</quote
>. Vegeu <xref linkend="kate-highlight-default-styles"/> a la documentació del ressaltat de la sintaxi. </para>
</note>
<tip>
<para
>Assegureu-vos de triar colors llegibles amb bon contrast, especialment en combinació amb els <userinput
><link linkend="color-themes-editor-colors"
>Colors de l'editor</link
></userinput
>. Vegeu <xref linkend="color-themes-contrast"/>. </para>
</tip>
<para
>En el <link linkend="color-themes-json"
>fitxer &JSON;</link
>, la clau respectiva <userinput
>text-styles</userinput
> té com a valor un <emphasis
>objecte</emphasis
> on cada clau correspon al nom d'un <emphasis
>estil predeterminat de text</emphasis
>, el qual és equivalent a l'utilitzat en les definicions de ressaltat de la sintaxi. Aquí, <userinput
>totes les claus d'estil de text disponibles són obligatòries</userinput
>, es llisten a continuació. </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
>Les altres claus de l'estil de text...</replaceable>
}
</programlisting>
<variablelist>
<varlistentry>
<term
>Cada clau de <emphasis
>l'estil predeterminat del text</emphasis
> té un objecte &JSON; com a valor, on s'especifiquen valors com <emphasis
>color</emphasis
>, <emphasis
>negreta</emphasis
>, <emphasis
>cursiva</emphasis
>, &etc; Aquestes claus són les següents: </term>
<listitem>
<para
><userinput
>text-color</userinput
>: És una cadena amb el color del text en el codi de color hexadecimal. Aquesta clau/valor és obligatòria.</para>
<para
><userinput
>selected-text-color</userinput
>: El color del text quan se selecciona generalment és el mateix valor que <quote
>text-color</quote
>. Quan se selecciona el text, el fons és definit pel valor de <link linkend="variable-pref-colors-selected-text"
>TextSelection</link
> als <link linkend="color-themes-editor-colors"
>Colors de l'editor</link
>, de manera que haureu d'assegurar-vos que el text tingui un bon contrast i sigui llegible amb aquest fons. El valor és una cadena amb un codi de color hexadecimal. Aquesta clau/valor és obligatòria.</para>
<para
><userinput
>bold</userinput
>: És un valor <emphasis
>booleà</emphasis
> que determina si el text està en negreta. Aquesta clau és opcional, el valor predeterminat és <userinput
>false</userinput
>.</para>
<para
><userinput
>italic</userinput
>: És un <emphasis
>booleà</emphasis
> que determina si el text està corbat. Aquesta clau és opcional, el valor predeterminat és <userinput
>false</userinput
>.</para>
<para
><userinput
>underline</userinput
>: És un <emphasis
>booleà</emphasis
> que determina si el text està subratllat. Aquesta clau és opcional, el valor predeterminat és <userinput
>false</userinput
>.</para>
<para
><userinput
>strike-through</userinput
>: És un <emphasis
>booleà</emphasis
> que determina si el text està taxat. Aquesta clau és opcional, el valor predeterminat és <userinput
>false</userinput
>.</para>
<para
><userinput
>background-color</userinput
>: Determina el fons del text, utilitzat per exemple en alertes en els comentaris. El valor és una <emphasis
>cadena</emphasis
> amb un codi de color en hexadecimal. Aquesta clau és opcional, de manera predeterminada no hi ha cap fons.</para>
<para
><userinput
>selected-background-color</userinput
>: Determina el fons del text quan se selecciona. El valor és una cadena amb un codi de color en hexadecimal. Aquesta clau és opcional, de manera predeterminada no hi ha cap fons.</para>
</listitem>
</varlistentry>
</variablelist>
<para
>A <link linkend="color-themes-gui"
>la &IGU; per a gestionar els temes de color de KTextEditor</link
>, aquests atributs es poden modificar a la pestanya <userinput
><guilabel
>Estils predeterminats de text</guilabel
></userinput
>. El nom de la llista d'estils utilitza l'estil configurat per a l'element, el qual proporciona una vista prèvia immediata en configurar un estil. Cada estil permet seleccionar atributs comuns, així com els colors de primer pla i de fons. Per a treure un color de fons, feu clic dret per a emprar el menú contextual.</para>
<para
>Les claus d'estil de text disponibles són les següents; les claus utilitzades en el <link linkend="color-themes-json"
>fitxer &JSON;</link
> es llisten en <emphasis
>negreta</emphasis
>, els noms utilitzats en la <link linkend="color-themes-gui"
>&IGU;</link
> es mostraran entre parèntesis si són diferents.</para>
<variablelist>
<varlistentry>
<term
><guilabel
>Text normal i codi font</guilabel
></term>
<listitem>
<para
><userinput
>Normal</userinput
>: Estil predeterminat de text per al text normal i codi font sense un ressaltat especial.</para>
<para
><userinput
>Keyword</userinput
>: Estil de text per a les paraules clau dels llenguatges integrats.</para>
<para
><userinput
>Function</userinput
>: Estil de text per a les definicions de funcions i crides a funcions.</para>
<para
><userinput
>Variable</userinput
>: Estil de text per a les variables, si escau. Per exemple, les variables en PHP/Perl generalment comencen amb un signe <userinput
>$</userinput
>, de manera que tots els identificadors que segueixen el patró <userinput
>$foo</userinput
> es ressaltaran com a variables.</para>
<para
><userinput
>ControlFlow</userinput
> (<guilabel
>Flux de control</guilabel
>): Estil de text per a les paraules clau del flux de control, com <emphasis
>if</emphasis
>, <emphasis
>then</emphasis
>, <emphasis
>else</emphasis
>, <emphasis
>return</emphasis
>, <emphasis
>switch</emphasis
>, <emphasis
>break</emphasis
>, <emphasis
>yield</emphasis
>, <emphasis
>continue</emphasis
>, &etc;</para>
<para
><userinput
>Operator</userinput
>: Estil de text per als operadors, com <userinput
>+</userinput
>, <userinput
>-</userinput
>, <userinput
>*</userinput
>, <userinput
>/</userinput
>, <userinput
>%</userinput
>, &etc;</para>
<para
><userinput
>BuiltIn</userinput
> (<guilabel
>Incorporat</guilabel
>): Estil de text per a classes de llenguatges, funcions i objectes integrats.</para>
<para
><userinput
>Extension</userinput
>: Estil de text per a les extensions conegudes, com les classes de les &Qt;, funcions/macros en C++ i Python o boost.</para>
<para
><userinput
>Preprocessor</userinput
>: Estil de text per a les declaracions de preprocessador o definicions de macro.</para>
<para
><userinput
>Attribute</userinput
>: Estil de text per a les anotacions o atributs de funcions o objectes, p. ex. <userinput
>@override</userinput
> en Java o <userinput
>__declspec(...)</userinput
> i <userinput
>__attribute__((...))</userinput
> en C++.</para>
</listitem>
</varlistentry>
<varlistentry>
<term
><guilabel
>Nombres, tipus i constants</guilabel
></term>
<listitem>
<para
><userinput
>DataType</userinput
> (<guilabel
>Tipus de dades</guilabel
>): Estil de text per a tipus de dades integrades com <emphasis
>int</emphasis
>, <emphasis
>char</emphasis
>, <emphasis
>float</emphasis
>, <emphasis
>void</emphasis
>, <emphasis
>u64</emphasis
>, &etc;</para>
<para
><userinput
>DecVal</userinput
> (<guilabel
>Decimal/valor</guilabel
>): Estil de text per als valors decimals.</para>
<para
><userinput
>BaseN</userinput
> (<guilabel
>Enter base-N</guilabel
>): Estil de text per als números amb una base diferent que 10.</para>
<para
><userinput
>Float</userinput
> (<guilabel
>Coma flotant</guilabel
>): Estil de text per als nombres de coma flotant.</para>
<para
><userinput
>Constant</userinput
>: Estil de text per a les constants del llenguatge i les constants definides per l'usuari, p. ex. <emphasis
>True</emphasis
>, <emphasis
>False</emphasis
>, <emphasis
>None</emphasis
> en Python o <emphasis
>nullptr</emphasis
> en C/C++; o les constants matemàtiques com <emphasis
>PI</emphasis
>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term
><guilabel
>Cadenes i caràcters</guilabel
></term>
<listitem>
<para
><userinput
>Char</userinput
> (<guilabel
>Caràcter</guilabel
>): Estil de text per als caràcters individuals com <userinput
>'x'</userinput
>.</para>
<para
><userinput
>SpecialChar</userinput
> (<guilabel
>Caràcter especial</guilabel
>): Estil de text per als caràcters d'escapament en les cadenes, p. ex. <quote
><userinput
>hola\n</userinput
></quote
> i altres caràcters amb un significat especial en les cadenes, com les substitucions o operadors d'expressió regular.</para>
<para
><userinput
>String</userinput
>: Estil de text per a les cadenes com <quote
><userinput
>hola món</userinput
></quote
>.</para>
<para
><userinput
>VerbatimString</userinput
> (<guilabel
>Cadena literal</guilabel
>): Estil de text per a les cadenes de text o sense processar com <userinput
>'raw \backlash'</userinput
> en Perl, CoffeeScript i els intèrprets d'ordres, així com <userinput
>r'\raw'</userinput
> en Python o com en els documents HERE.</para>
<para
><userinput
>SpecialString</userinput
> (<guilabel
>Cadena especial</guilabel
>): Estil de text per a les cadenes especials, com expressions regulars en ECMAScript, el mode matemàtic &latex;, SQL, &etc;</para>
<para
><userinput
>Import</userinput
> (<guilabel
>Importacions, mòduls i inclusions</guilabel
>): Estil de text per a les inclusions, importacions, mòduls o paquets de &latex;.</para>
</listitem>
</varlistentry>
<varlistentry>
<term
><guilabel
>Comentaris i documentació</guilabel
></term>
<listitem>
<para
><userinput
>Comment</userinput
>: Estil de text per als comentaris normals.</para>
<para
><userinput
>Documentation</userinput
>: Estil de text per als comentaris que reflecteixen la documentació de l'API, com <userinput
>/** doxygen comments */</userinput
> o <userinput
>"""docstrings"""</userinput
>.</para>
<para
><userinput
>Annotation</userinput
>: Estil de text per a les anotacions en comentaris o documentació d'ordres, com <userinput
>@param</userinput
> en Doxygen o JavaDoc.</para>
<para
><userinput
>CommentVar</userinput
> (<guilabel
>Variable de comentari</guilabel
>): Estil de text que es refereix als noms de les variables utilitzades en les ordres anteriors en un comentari, com <userinput
>foobar</userinput
> a <quote
><userinput
>@param foobar</userinput
></quote
>, en Doxygen o JavaDoc.</para>
<para
><userinput
>RegionMarker</userinput
> (<guilabel
>Marcador de regió</guilabel
>): Estil de text per als marcadors de regió, normalment definits per <userinput
>//BEGIN</userinput
> i <userinput
>//END</userinput
> en els comentaris.</para>
<para
><userinput
>Information</userinput
>: Estil de text per a la informació, notes i consells, com la paraula clau <userinput
>@note</userinput
> en Doxygen.</para>
<para
><userinput
>Warning</userinput
>: Estil de text per als avisos, com ara la paraula clau <userinput
>@warning</userinput
> en Doxygen.</para>
<para
><userinput
>Alert</userinput
>: Estil de text per a les paraules especials en els comentaris, com <userinput
>TODO</userinput
>, <userinput
>FIXME</userinput
>, <userinput
>XXXX</userinput
> i <userinput
>WARNING</userinput
>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term
><guilabel
>Miscel·lània</guilabel
></term>
<listitem>
<para
><userinput
>Error</userinput
>: Estil de text que indica error ressaltat i sintaxi incorrecta.</para>
<para
><userinput
>Others</userinput
>: Estil de text per als atributs que no coincideixen amb cap dels altres estils predeterminats.</para>
</listitem>
</varlistentry>
</variablelist>
</sect3>
<sect3 id="color-themes-custom-styles">
<title
>Estils personalitzats per al text ressaltat</title>
<para
>Aquí podreu establir els estils de text per a una definició específica del ressaltat de la sintaxi, superposant l'<userinput
>estil de text predeterminat</userinput
> descrit a <link linkend="color-themes-text-styles"
>la secció anterior</link
>. </para>
<para
>En el <link linkend="color-themes-json"
>fitxer de tema &JSON;</link
>, això es correspon amb la clau <userinput
>custom-styles</userinput
>, el valor és un <emphasis
>objecte</emphasis
> on cada clau de subesquema es correspon amb el <userinput
>nom d'una definició de ressaltat de la sintaxi</userinput
>. El seu valor és un <emphasis
>objecte</emphasis
> on cada clau es refereix al <userinput
>nom dels atributs d'estil</userinput
> definit en <link linkend="kate-highlight-sections"
>els elements <userinput
>itemData</userinput
></link
> del fitxer &XML; de ressaltat de la sintaxi, i el valor respectiu és un subobjecte amb les claus <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
> i <emphasis
>selected-background-color</emphasis
> definides a <link linkend="color-themes-text-styles"
>la secció anterior</link
>. Cadascun d'aquests valors és opcional, ja que si no hi són presents, es considerarà l'estil establert a <userinput
>text-styles</userinput
>. </para>
<para
>Per exemple, en aquest fragment de codi, la definició de ressaltat de la sintaxi <quote
>ISO C++</quote
> té un estil de text especial per als atributs <quote
>Modificadors de tipus</quote
> i <quote
>Classes estàndard</quote
>. En el fitxer &XML; corresponent <quote
>isocpp.xml</quote
>, l'atribut definit <quote
>Classes estàndard</quote
> utilitza l'estil predeterminat <userinput
>BuiltIn</userinput
> (o <userinput
>dsBuiltIn</userinput
>). En aquest atribut, només se sobreescriurà el valor de <userinput
>text-color</userinput
> amb el nou color <quote
>#6431b3</quote
>. </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
>Heu de considerar que aquests estils de text estan associats amb els noms dels atributs definits en els fitxers &XML; de ressaltat de la sintaxi. Si s'actualitza un fitxer &XML; i es canvia el nom o s'eliminen alguns atributs, l'estil personalitzat definit en el tema ja no s'aplicarà.</para>
</listitem>
<listitem>
<para
>Les definicions del ressaltat de la sintaxi sovint inclouen altres definicions. Per exemple, el ressaltador de <quote
>QML</quote
> inclou el ressaltador de <quote
>JavaScript</quote
>, ja que comparteixen la funcionalitat en el ressaltat.</para>
</listitem>
</itemizedlist>
</note>
<para
>A <link linkend="color-themes-gui"
>la &IGU; per a gestionar els temes de KTextEditor</link
>, aquests atributs es poden modificar a la pestanya <userinput
><guilabel
>Estils del text ressaltat</guilabel
></userinput
>. De manera predeterminada, l'editor preselecciona el ressaltat del document actual. Notareu que molts ressaltats contenen altres ressaltats representats per grups en la llista d'estils. Per exemple, la majoria dels ressaltats importen el ressaltat <quote
>Alert</quote
>, i molts formats de codi font importen el ressaltat <quote
>Doxygen</quote
>. </para>
</sect3>
</sect2>
<sect2 id="color-themes-gui">
<title
>Els temes de color de la &IGU;</title>
<para
>La forma més senzilla de crear i editar temes de color és mitjançant la &IGU; dins del diàleg <link linkend="config-dialog"
><quote
>Configura</quote
></link
> proporcionat per <ulink url="https://api.kde.org/frameworks/ktexteditor/html/"
>KTextEditor</ulink
>. Per a accedir-hi, seleccioneu <menuchoice
><guimenu
>Arranjament</guimenu
> <guimenuitem
>Configura l'<replaceable
>Aplicació</replaceable
>...</guimenuitem
></menuchoice
> a la barra de menús del vostre editor de text. Això obrirà el diàleg <guilabel
>Configura</guilabel
>, allà seleccioneu <guilabel
>Temes de color</guilabel
> a la barra lateral. </para>
<mediaobject>
<imageobject
><imagedata format="PNG" fileref="color-themes-gui-default-text-styles.png"/></imageobject>
<textobject
><phrase
>Diàleg de configuració del &kate; amb la gestió del tema de color.</phrase
></textobject>
<caption
><para
>Diàleg de configuració del &kate; amb la gestió del tema de color.</para>
</caption>
</mediaobject>
<para
>En aquest <link linkend="config-dialog"
>diàleg</link
> podreu configurar tots els colors en qualsevol tema que tingueu, així com crear/copiar temes nous, eliminar-los, exportar-los a un fitxer <userinput
>.theme</userinput
> amb <link linkend="color-themes-json"
>format &JSON;</link
> o importar-los des de fitxers <userinput
>.theme</userinput
> externs. Cada tema té les opcions de configuració per als colors i els estils de text. </para>
<para
>De manera predeterminada, els temes integrats no es poden modificar. Per a fer això, els haureu de copiar i donar un nom nou.</para>
<para
>Per a utilitzar un tema de forma permanent en el vostre editor de text, haureu de seleccionar-lo en el quadre combinat anomenat <guilabel
>Tema predeterminat per a l'<replaceable
>aplicació</replaceable
></guilabel
> que hi ha a la part inferior del diàleg i prémer <guibutton
>Aplica</guibutton
> o <guibutton
>D'acord</guibutton
>. De manera predeterminada, l'opció <userinput
><guilabel
>Selecció automàtica</guilabel
></userinput
> està activada, la qual triarà un tema de color més apropiat d'acord amb l'<emphasis
>esquema de color del &plasma;</emphasis
> utilitzat en l'aplicació d'edició de text; normalment es tria <quote
>Brisa clara</quote
> i <quote
>Brisa fosca</quote
> si l'esquema és clar o fosc, respectivament. </para>
<tip>
<para
>Podeu ajustar l'esquema de color global del &kde; en el mòdul <ulink url="help:/kcontrol/colors/"
><quote
>Colors</quote
> a l'&systemsettings;</ulink
>. També el podreu canviar individualment en algunes aplicacions com el &kate; o el &kdevelop;, des del menú <menuchoice
><guimenu
>Arranjament</guimenu
><guisubmenu
>Esquema de color</guisubmenu
></menuchoice
>. </para>
</tip>
<sect3 id="color-themes-gui-new-theme">
<title
>Crea un tema nou</title>
<para
>Per a crear un tema nou, primer cal copiar-ne un d'existent. Seleccioneu un tema existent que voleu utilitzar com a base, com el <quote
>Brisa clar</quote
> o <quote
>Brisa fosca</quote
> i feu clic a <guibutton
>Copia</guibutton
>. Després escriviu un nom per al tema nou. </para>
<para
>Si voleu modificar un tema integrat o només de lectura, primer l'haureu de copiar amb un nom diferent.</para>
</sect3>
<sect3 id="color-themes-gui-import-export">
<title
>Importar o exportar fitxers de tema en &JSON;</title>
<para
>Amb el botó <guibutton
>Exporta</guibutton
> podreu exportar un tema seleccionat (inclosos els integrats) a un <link linkend="color-themes-json"
>fitxer &JSON;</link
> amb l'extensió <userinput
>.theme</userinput
>. Això obrirà un diàleg per a desar el fitxer. Per a afegir un tema de color des d'un <link linkend="color-themes-json"
>fitxer &JSON;</link
> extern, senzillament premeu el botó <guibutton
>Importa</guibutton
> i seleccioneu el fitxer <userinput
>.theme</userinput
> des del diàleg. </para>
<tip>
<itemizedlist>
<listitem>
<para
>Com s'ha <link linkend="color-themes-json-overview"
>esmentat anteriorment</link
>, els fitxers de tema personalitzat per l'usuari s'emmagatzemen a la carpeta <filename class="directory"
>org.kde.syntax-highlighting/themes/</filename
>. Quan feu còpies o creeu un tema, apareixerà automàticament allà. A més, importar o afegir un tema és equivalent a copiar un fitxer <userinput
>.theme</userinput
> extern en aquesta carpeta. El KSyntaxHighlighting recollirà automàticament els fitxers de tema de color des d'aquesta carpeta.</para>
</listitem>
<listitem>
<para
>Si voleu publicar un tema creat per vós, és fonamental comprovar l'objecte <link linkend="color-themes-json-metadata"
>metadata</link
> del <link linkend="color-themes-json"
>fitxer &JSON;</link
>, afegint-hi la llicència respectiva i comprovant el número de la revisió.</para>
</listitem>
</itemizedlist>
</tip>
</sect3>
<sect3 id="color-themes-gui-editing">
<title
>Editar els temes de color</title>
<sect4 id="prefcolors-colors">
<title
>Colors</title>
<para
>Aquí s'ajusten els colors de l'àrea d'edició de text. Aquests es detallen a <xref linkend="color-themes-editor-colors"/>.</para>
</sect4>
<sect4 id="prefcolors-normal-text-styles">
<title
>Estils de text predeterminats</title>
<para
>Els estils predeterminats del text són heretats pels estils del text ressaltat, el qual permet a l'editor presentar el text d'una manera molt coherent, per exemple, el text dels comentaris utilitza el mateix estil en gairebé tots els formats de text que pot ressaltar el KSyntaxHighlighting.</para>
<para
>El nom en la llista d'estils utilitza l'estil configurat per a l'element, proporcionant-vos una vista prèvia quan un estil està configurat. </para>
<para
>Cada estil permet seleccionar atributs comuns com els colors de fons i de primer pla. Per a desseleccionar un color de fons, feu clic dret per a utilitzar el menú contextual.</para>
<para
>Els atributs d'aquesta àrea es detallen a <xref linkend="color-themes-text-styles"/>.</para>
</sect4>
<sect4 id="prefcolors-highlighting-text-styles">
<title
>Estils del text ressaltat</title>
<para
>Aquí podeu editar els estils de text utilitzats per una definició de ressaltat específica. L'editor preselecciona el ressaltat usat per al vostre document actual. Per a treballar amb un ressaltat diferent, seleccioneu-ne un en el quadre combinat <guilabel
>Ressaltat</guilabel
> sobre la llista d'estil. </para>
<para
>El nom en la llista d'estils utilitza l'estil configurat per a l'element, proporcionant-vos una vista prèvia quan un estil està configurat. </para>
<para
>Cada estil us permet seleccionar atributs comuns com els colors de fons i de primer pla. Per a desseleccionar un color de fons, feu clic dret per a utilitzar el menú contextual. A més podreu veure si un estil és igual que l'estil predeterminat utilitzat per l'element, i assignar-lo si no l'és.</para>
<para
>Cal tenir present que molts ressaltats contenen d'altres ressaltats representats per grups en la llista d'estil. Per exemple, la majoria dels ressaltats inclouen el ressaltat Alerta, i molts dels formats de codi font inclouen el ressaltat Doxygen. Editar colors en aquests grups només afectarà els estils quan s'usin en el format de ressaltat editat. </para>
</sect4>
</sect3>
</sect2>
<sect2 id="color-themes-tips-and-tricks">
<title
>Consells i trucs</title>
<sect3 id="color-themes-contrast">
<title
>Contrast dels colors del text</title>
<para
>Un aspecte important en treballar amb els temes de color és triar un contrast de text que faciliti la lectura, especialment en combinació amb el fons.</para>
<para
>L'aplicació <userinput
>Kontrast</userinput
> és un verificador del contrast de color. Us indicarà que les combinacions del color de text i color de fons són llegibles i accessibles, de manera que aquesta és una excel·lent eina per a ajudar-vos a crear temes de color.</para>
<para
>Podeu descarregar el <userinput
>Kontrast</userinput
> des del <ulink url="https://apps.kde.org/ca/kontrast"
>lloc web d'aplicacions del &kde;</ulink
> o des del <ulink url="https://flathub.org/apps/details/org.kde.kontrast"
>paquet Flatpak a Flathub</ulink
> (només a GNU/Linux).</para>
<para
>L'aplicació <userinput
>Contrast</userinput
> de GNOME és similar. Podeu descarregar <ulink url="https://flathub.org/apps/details/org.gnome.design.Contrast"
>el paquet Flatpak a Flathub</ulink
> (només en GNU/Linux).</para>
</sect3>
<sect3 id="color-themes-tips-and-tricks-consistency">
<title
>Consells de coherència amb el ressaltat de la sintaxi</title>
<para
>El KSyntaxHighlighting inclou <ulink url="https://kate-editor.org/syntax/"
>més de 300 definicions de ressaltat de la sintaxi</ulink
>, de manera que és ideal assegurar-vos que el nou tema es vegi bé en totes les definicions de ressaltat de la sintaxi. Els temes de color incorporats tenen les següents similituds que es recomana (però no és obligatori) seguir per a aconseguir una visualització correcta de totes les definicions de ressaltat de la sintaxi:</para>
<itemizedlist>
<listitem
><para
>Utilitzeu negreta per als <link linkend="color-themes-text-styles"
>estils de text</link
> <quote
>Keyword</quote
> i <quote
>ControlFlow</quote
>.</para
></listitem>
<listitem
><para
>No utilitzeu el color de fons en cap <link linkend="color-themes-text-styles"
>estil de text</link
>, excepte <quote
>Alert</quote
> i <quote
>RegionMarker</quote
>.</para
></listitem>
</itemizedlist>
<para
>La majoria dels ressaltadors de la sintaxi estan pensats perquè es vegi bé en els temes predeterminats <quote
>Brisa clara</quote
> i <quote
>Brisa fosca</quote
>, per tant, una altra forma de mantenir la coherència és utilitzar colors similars en els <link linkend="color-themes-text-styles"
>estils de text</link
>, com el <emphasis
>green</emphasis
> per a <quote
>Preprocessor</quote
> i <quote
>Others</quote
>, <emphasis
>blue</emphasis
> per a <quote
>DataType</quote
> i <quote
>Attribute</quote
>, o <emphasis
>purple</emphasis
> per a <quote
>Function</quote
>.</para>
<para
>Recordeu que aquestes recomanacions no són obligatòries quan es crea i publica un tema.</para>
</sect3>
</sect2>
</sect1>
<sect1 id="dev-scripting">
<title
>Crear scripts en &javascript;</title>
<para
>El component d'edició de la &kappname; és fàcilment extensible, escrivint scripts. El llenguatge per a crear scripts és ECMAScript (conegut com a &javascript;). La &kappname; admet dos tipus de script: de sagnat i de línia d'ordres. </para>
<sect2 id="dev-scripting-indentation">
<title
>Scripts de sagnat</title>
<para
>Els scripts de sagnat: També coneguts com a «indenters», sagnen automàticament el codi font en escriure text. Com a exemple, després de prémer la tecla de retorn el nivell de sagnat sovint és incrementat. </para>
<para
>En les següents seccions es descriuen pas a pas com crear l'esquelet d'un sagnat simple. Com a primer pas, creeu un fitxer <filename
>*.js</filename
> nou anomenat, &pex;, <filename
>javascript.js</filename
> a la carpeta d'inici local <filename
>$<envar
>XDG_DATA_HOME</envar
>/katepart5/script/indentation</filename
>. En aquest sentit, la variable d'entorn <envar
>XDG_DATA_HOME</envar
> normalment s'expandeix a <filename
>~/.local</filename
> o <filename
>~/.local/share</filename
>. </para>
<para
>Al &Windows; aquests fitxers es troben a <filename
>%USERPROFILE%\AppData\Local\katepart5\script\indentation</filename
>. <replaceable
>%USERPROFILE%</replaceable
> que generalment s'expandeix a <filename
>C:\\Users\\<replaceable
>usuari</replaceable
></filename
>.</para>
<sect3 id="dev-scripting-indentation-header">
<title
>La capçalera de l'script de sagnat</title>
<para
>La capçalera del fitxer <filename
>javascript.js</filename
> està incrustada com un &JSON; al començament del document de la forma següent: <programlisting>
var katescript = {
"name": "JavaScript",
"author": "Nom exemple <nom.exemple@alguna.adreça.org>",
"license": "BSD License",
"revision": 1,
"kate-version": "5.1",
"required-syntax-style": "javascript",
"indent-languages": ["javascript"],
"priority": 0,
}; // kate-script-header, haurà d'estar al començament del fitxer sense comentaris
</programlisting
> Cada entrada s'explica en detall tot seguit: <itemizedlist>
<listitem
><para
><literal
>name</literal
> [requerit]: Aquest és el nom del sagnat que apareix al menú <menuchoice
><guimenu
>Eines</guimenu
><guimenuitem
>Sagnat</guimenuitem
></menuchoice
> i en el diàleg de configuració. </para
></listitem>
<listitem
><para
><literal
>author</literal
> [opcional]: El nom de l'autor i la informació de contacte. </para
></listitem>
<listitem
><para
><literal
>license</literal
> [opcional]: La forma curta de la llicència, com ara BSD o LGPLv3. </para
></listitem>
<listitem
><para
><literal
>revision</literal
> [requerit]: La revisió de l'script. Aquest número ha de ser major cada vegada que es modifica l'script. </para
></listitem>
<listitem
><para
><literal
>kate-version</literal
> [requerit]: La versió mínima requerida per la &kappname;. </para
></listitem>
<listitem
><para
><literal
>required-syntax-style</literal
> [opcional]: L'estil de la sintaxi requerida, el qual coincideix amb <literal
>style</literal
> especificat als fitxers de ressaltat de la sintaxi. Això és important per als sagnats que es basen en la informació de ressaltat específica en el document. Si s'especifica un estil de la sintaxi requerit, el sagnat només estarà disponible amb el ressaltat actiu apropiat. Això evita <quote
>comportament sense definir</quote
> causat per l'ús del sagnat sense l'esquema del ressaltat esperat. Per exemple, el sagnat de Ruby en fa ús en els fitxers <filename
>ruby.js</filename
> i <filename
>ruby.xml</filename
>. </para
></listitem>
<listitem
><para
><literal
>indent-languages</literal
> [opcional]: Una matriu &JSON; dels estils de la sintaxi que pot sagnar correctament, &pex;: <literal
>["c++", "java"]</literal
>. </para
></listitem>
<listitem
><para
><literal
>priority</literal
> [opcional]: Si els diversos sagnats són adequats per a un determinat fitxer ressaltat, la prioritat decideix quin sagnat és triat com a sagnat predeterminat. </para
></listitem>
</itemizedlist>
</para>
</sect3>
<sect3 id="dev-scripting-indentation-body">
<title
>El codi font del sagnat</title>
<para
>Després d'haver especificat la capçalera aquesta secció explica com funciona la creació de scripts de sagnat. L'esquelet bàsic del cos s'assembla a això: <programlisting>
// es necessiten les biblioteques «js» de katepart, per exemple, «range.js»
// si utilitzeu «Range»
require ("range.js");
triggerCharacters = "{}/:;";
function indent(line, indentWidth, ch)
{
// crida per a cada línia nova (ch == «\n») i tots els caràcters s'especifiquen en
// la variable global triggerCharacters. Quan es crida <menuchoice
><guimenu
>Eines</guimenu
><guimenuitem
>Format del sagnat</guimenuitem
></menuchoice>
// la variable ch és buidada, &ead;, ch == «».
//
// Vegeu també: L'API per a crear scripts
return -2;
}
</programlisting
> La funció <function
>indent()</function
> té tres paràmetres: <itemizedlist
> <listitem
><para
><literal
>line</literal
>: La línia que ha d'estar amb sagnat.</para
></listitem
> <listitem
><para
><literal
>indentWidth</literal
>: L'amplada del sagnat en nombre d'espais.</para
></listitem
> <listitem
><para
><literal
>ch</literal
>: o bé un caràcter de línia nova (<literal
>ch == '\n'</literal
>),el caràcter de tall especificat en <literal
>triggerCharacters</literal
> o buida si l'usuari invoca l'acció <menuchoice
><guimenu
>Eines</guimenu
><guimenuitem
>Alinea</guimenuitem
></menuchoice
>.</para
></listitem
> </itemizedlist
> El valor retornat de la funció <function
>indent()</function
> especifica com se sagna la línia. Si el valor retornat és un nombre enter simple, aquest s'interpreta de la següent manera: <itemizedlist
> <listitem
><para
>El valor retornat <literal
>-2</literal
>: No fa res.</para
></listitem
> <listitem
><para
>El valor retornat <literal
>-1</literal
>: Es manté el sagnat (cerca la línia anterior que no estigui en blanc).</para
></listitem
> <listitem
><para
>El valor retornat <literal
> 0</literal
>: Un número >= 0 especifica la profunditat del sagnat en nombre d'espais.</para
></listitem
> </itemizedlist
> Alternativament, un conjunt de dos elements poden retornar: <itemizedlist
> <listitem
><para
><literal
>return [ indent, align ];</literal
></para
></listitem
> </itemizedlist
> En aquest cas, el primer element és la profunditat de sagnat com anteriorment amb el mateix significat dels valors especials. No obstant això, el segon element és un valor absolut que representa una columna d'<quote
>alineació</quote
>. Si aquest valor és major que el valor de sagnat, la diferència representa un nombre d'espais a afegir després del sagnat del primer paràmetre. En cas contrari, el segon nombre serà ignorat. L'ús de tabulacions i espais per al sagnat sovint és referit com <quote
>mode mixt</quote
>. </para>
<para
>Considerem el següent exemple: Suposem que s'utilitzen tabulacions per a sagnar, i l'amplada de la tabulació és 4. Aquí, <tab> representa una tabulació i «.» un espai: <programlisting>
1: <tab><tab>foobar("hola",
2: <tab><tab>......."món");
</programlisting
> Quan se sagna la línia 2, la funció <function
>indent()</function
> retorna [8, 15]. Com a resultat, s'insereixen dues tabulacions per a sagnar fins a la columna 8, i s'afegeixen 7 espais per a alinear el segon paràmetre a la primera, de manera que quedi alineat si el fitxer es veu amb una amplada de tabulació diferent. </para>
<para
>Una instal·lació predeterminada del &kde; ens dona la &kappname; amb diversos sagnats. El corresponent codi font de &javascript; d'origen pot trobar-se en <filename
>$<envar
>XDG_DATA_DIRS</envar
>/katepart5/script/indentation</filename
>.</para>
<para
>Al &Windows; aquests fitxers es troben a <filename
>%USERPROFILE%\AppData\Local\katepart5\script\indentation</filename
>. <replaceable
>%USERPROFILE%</replaceable
> que generalment s'expandeix a <filename
>C:\\Users\\<replaceable
>usuari</replaceable
></filename
>. </para>
<para
>El desenvolupament d'un sagnat requereix tornar a carregar els scripts per a veure si els canvis es comporten adequadament. En comptes de reiniciar l'aplicació, simplement canvieu a la línia d'ordres i crideu l'ordre <command
>reload-scripts</command
>. </para>
<para
>Si desenvolupeu scripts útils, si us plau, considereu contribuir al projecte &kappname; <ulink url="mailto:kwrite-devel@kde.org"
>posant-vos en contacte amb la llista de correu</ulink
>. </para>
</sect3>
</sect2>
<sect2 id="dev-scripting-command-line">
<title
>Els scripts de la línia d'ordres</title>
<para
>Com és difícil satisfer les necessitats de tothom, la &kappname; suporta unes quantes eines d'ajuda per a la manipulació ràpida de text a través de la <link linkend="advanced-editing-tools-commandline"
>línia d'ordres inclosa</link
>. Per exemple, l'ordre <command
>sort</command
> s'implementa com un script. En aquesta secció s'explica com crear fitxers <filename
>*.js</filename
> per a estendre la &kappname; amb scripts d'ajuda arbitrària. </para>
<para
>Els scripts de línia d'ordres es troben a la mateixa carpeta que els scripts de sagnat. Així que com a primer pas, creeu un fitxer <filename
>*.js</filename
> nou anomenat <filename
>myutils.js</filename
> a la carpeta d'inici local <filename
>$<envar
>XDG_DATA_HOME</envar
>/katepart5/script/commands</filename
>. En aquest sentit, la variable d'entorn <envar
>XDG_DATA_HOME</envar
> normalment s'expandeix a <filename
>~/.local</filename
> o <filename
>~/.local/share</filename
>.</para>
<para
>Al &Windows; aquests fitxers es troben a <filename
>%USERPROFILE%\AppData\Local\katepart5\script\commands</filename
>. <replaceable
>%USERPROFILE%</replaceable
> que generalment s'expandeix a <filename
>C:\\Users\\<replaceable
>usuari</replaceable
></filename
>. </para>
<sect3 id="dev-scripting-command-line-header">
<title
>La capçalera de l'script de línia d'ordres</title>
<para
>La capçalera de cada script de la línia d'ordres està incrustada en el &JSON; al començament de l'script de la forma següent: <programlisting>
var katescript = {
"author": "Nom exemple <nom.exemple@alguna.adreça.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, haurà d'estar al començament del fitxer sense comentaris
</programlisting
> Cada entrada s'explica en detall tot seguit: <itemizedlist>
<listitem
><para
><literal
>author</literal
> [opcional]: El nom de l'autor i la informació de contacte.</para
></listitem>
<listitem
><para
><literal
>license</literal
> [opcional]: La forma curta de la llicència, com ara BSD o LGPLv2.</para
></listitem>
<listitem
><para
><literal
>revision</literal
> [requerit]: La revisió de l'script. Aquest número ha de ser major cada vegada que es modifica l'script.</para
></listitem>
<listitem
><para
><literal
>kate-version</literal
> [requerit]: La versió mínima requerida per la &kappname;.</para
></listitem>
<listitem
><para
><literal
>functions</literal
> [requerit]: Matriu &JSON; de les ordres a l'script.</para
></listitem>
<listitem
><para
><literal
>actions</literal
> [opcional]: La matriu &JSON; dels objectes &JSON; que defineixen les accions que apareixen al menú de l'aplicació. Es proporciona informació detallada a la secció <link linkend="advanced-editing-tools-commandline"
>Vincular dreceres</link
>.</para
></listitem>
</itemizedlist>
</para>
<para
>Atès que el valor de <literal
>functions</literal
> és una matriu &JSON;, un únic script és capaç de contenir un nombre arbitrari d'ordres de la línia d'ordres. Cada funció està disponible a través de la <link linkend="advanced-editing-tools-commandline"
>línia d'ordres integrada</link
> a la &kappname;. </para>
</sect3>
<sect3 id="dev-scripting-command-line-body">
<title
>El codi font de l'script</title>
<para
>Totes les funcions especificades a la capçalera s'han d'implementar a l'script. Per exemple, el fitxer de script en l'exemple anterior necessita implementar les dues funcions <command
>sort</command
> i <command
>moveLinesDown</command
>. Totes les funcions tenen la següent sintaxi: <programlisting
>// es necessiten les biblioteques «js» de la katepart, &pex;, «range.js»
// si utilitzeu «Range»
require ("range.js");
function <nom>(arg1, arg2...)
{
// «...» implementació, vegeu també: L'API de creació de scripts.
}
</programlisting>
</para>
<para
>Els arguments en la línia d'ordres es passen a la funció com <parameter
>arg1</parameter
>, <parameter
>arg2</parameter
>, &etc; Per tal de proveir documentació per a cada ordre, simplement implementeu la funció «<function
>help</function
>» de la següent manera: <programlisting>
{
if (cmd == "sort") {
return i18n("Ordena el text seleccionat.");
} else if (cmd == "...") {
// ...
}
}
</programlisting
> Executar <command
>help sort</command
> a la línia d'ordres crida a aquesta funció d'ajuda amb l'argument <parameter
>cmd</parameter
> establert en l'ordre donada, &ead;, <parameter
>cmd == "sort"</parameter
>. La &kappname; presentarà el text retornat com a documentació per a l'usuari. Assegureu-vos de <link linkend="dev-scripting-api-i18n"
>traduir les cadenes</link
>. </para>
<para
>El desenvolupament d'un script de línia d'ordres requereix tornar a carregar els scripts per a veure si els canvis es comporten adequadament. En comptes de reiniciar l'aplicació, simplement canvieu a la línia d'ordres i crideu l'ordre <command
>reload-scripts</command
>. </para>
<sect4 id="dev-scripting-command-line-shortcuts">
<title
>Vincular les dreceres</title>
<para
>Per tal de fer que els scripts siguin accessibles al menú de l'aplicació i assignar dreceres, l'script ha de proporcionar una capçalera de script adequada. En l'exemple anterior, ambdues funcions <literal
>sort</literal
> i <literal
>moveLinesDown</literal
> apareixen al menú per la següent part a la capçalera de l'script: <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
> Els camps per a una acció són els següents: <itemizedlist>
<listitem
><para
><literal
>function</literal
> [requerit]: La funció que ha d'aparèixer al menú <menuchoice
><guimenu
>Eines</guimenu
> <guisubmenu
>Scripts</guisubmenu
></menuchoice
>.</para
></listitem>
<listitem
><para
><literal
>name</literal
> [requerit]: El text apareix al menú de l'script.</para
></listitem>
<listitem
><para
><literal
>icon</literal
> [opcional]: La icona apareix al costat del text en el menú. Aquí es poden utilitzar tots els noms d'icones del &kde;.</para
></listitem>
<listitem
><para
><literal
>category</literal
> [opcional]: Si s'especifica una categoria, l'script apareixerà en un submenú.</para
></listitem>
<listitem
><para
><literal
>shortcut</literal
> [opcional]: La drecera indicada serà la drecera predeterminada. Exemple: <literal
>Ctrl+Alt+t</literal
>. Per a més detalls, vegeu la <ulink url="https://doc.qt.io/qt-5/qt.html#Key-enum"
>Documentació de les &Qt;</ulink
>.</para
></listitem>
<listitem
><para
><literal
>interactive</literal
> [opcional]: Si l'script necessita utilitzar l'entrada a la línia d'ordres, establiu-ho a <literal
>true</literal
> (cert).</para
></listitem>
</itemizedlist>
</para>
<para
>Si desenvolupeu scripts útils, si us plau, considereu contribuir al projecte &kappname; <ulink url="mailto:kwrite-devel@kde.org"
>posant-vos en contacte amb la llista de correu</ulink
>. </para>
</sect4>
</sect3>
</sect2>
<sect2 id="dev-scripting-api">
<title
>L'API de creació de scripts</title>
<para
>L'API per a crear scripts que es presenta aquí està disponible per a tots els scripts, &pex;, els scripts de sagnat i una ordre de línia d'ordres. Les classes <classname
>Cursor</classname
> i <classname
>Range</classname
> són proporcionades pels fitxers de la biblioteca a <filename
>$<envar
>XDG_DATA_DIRS</envar
>/katepart5/libraries</filename
>. Si voleu utilitzar-los en el seu vostre script, serà necessari utilitzar algunes de les funcions <classname
>Document</classname
> o <classname
>View</classname
>, si us plau, afegiu la biblioteca necessària mitjançant: <programlisting
>// es necessiten les biblioteques «js» de la katepart, &pex;, «range.js»
// si utilitzeu «Range»
require ("range.js");
</programlisting>
</para>
<para
>Per a estendre la norma de l'API per a crear scripts amb les vostres pròpies funcions i prototips n'hi ha prou amb crear un fitxer nou a la carpeta de configuració local del &kde; <filename
>$<envar
>XDG_DATA_HOME</envar
>/katepart5/libraries</filename
> i incloure'l a l'script utilitzant: <programlisting
>require ("nom_script.js");
</programlisting>
</para>
<para
>Al &Windows; aquests fitxers es troben a <filename
>%USERPROFILE%\AppData\Local\katepart5\libraries</filename
>. <replaceable
>%USERPROFILE%</replaceable
> que generalment s'expandeix a <filename
>C:\\Users\\<replaceable
>usuari</replaceable
></filename
>.</para>
<para
>Per a estendre els prototips com <classname
>Cursor</classname
> o <classname
>Range</classname
>, la manera més recomanable és <emphasis
>no</emphasis
> modificar els fitxers <filename
>*.js</filename
> globals. En el seu lloc, canvieu el prototip <classname
>Cursor</classname
> en &javascript;, després afegiu el <filename
>cursor.js</filename
> al vostre script mitjançant <literal
>require</literal
>. </para>
<sect3 id="dev-scripting-api-prototypes">
<title
>Cursors i intervals</title>
<para
>Com la &kappname; és un editor de text, tota l'API per a la creació de scripts es basa en els cursors i els intervals sempre que sigui possible. Un Cursor és una simple <literal
>(line, column)</literal
> que representa una posició del text en el document. Un «Range» s'estén pel text des de la posició del cursor fins a una posició final del cursor. L'API s'explica amb detall en les següents seccions. </para>
<sect4 id="dev-scripting-api-cursors">
<title
>El prototip de «Cursor»</title>
<variablelist
><varlistentry>
<term
><synopsis
>Cursor();
</synopsis
></term>
<listitem
><para
>Constructor. Retorna un cursor a la posició <literal
>(0, 0)</literal
>.</para>
<para
>Exemple: <function
>var cursor = new Cursor();</function
> </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>Cursor(<parameter
>int <replaceable
>línia</replaceable
></parameter
>, <parameter
>int <replaceable
>columna</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Constructor. Retorna un cursor a la posició (línia, columna). </para>
<para
>Exemple: <function
>var cursor = new Cursor(3, 42);</function
> </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>Cursor(<parameter
>Cursor <replaceable
>altra</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>El constructor de còpia. Retorna una còpia del cursor <replaceable
>altra</replaceable
>. </para>
<para
>Exemple: <function
>var copy = new Cursor(altra);</function
> </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>Cursor Cursor.clone();
</synopsis
></term>
<listitem
><para
>Retorna una còpia del cursor.</para>
<para
>Exemple: <function
>var clone = cursor.clone();</function
> </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>Cursor.setPosition(<parameter
>int <replaceable
>línia</replaceable
></parameter
>, <parameter
>int <replaceable
>columna</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Estableix la posició del cursor a <replaceable
>línia</replaceable
> i <replaceable
>columna</replaceable
>.</para>
<para
>Des del: &kde; 4.11 </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>bool Cursor.isValid();
</synopsis
></term>
<listitem
><para
>Comproveu si el cursor és vàlid. El cursor no és vàlid, si la línia i/o la columna s'estableix a <literal
>-1</literal
>. </para>
<para
>Exemple: <function
>var valid = cursor.isValid();</function
> </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>Cursor Cursor.invalid();
</synopsis
></term>
<listitem
><para
>Retorna un cursor nou no vàlid situat a <literal
>(-1, -1)</literal
>. </para>
<para
>Exemple: <function
>var invalidCursor = cursor.invalid();</function
> </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>int Cursor.compareTo(<parameter
>Cursor <replaceable
>altra</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Compara aquest cursor al cursor <replaceable
>altra</replaceable
>. Retorna <itemizedlist>
<listitem
><para
><literal
>-1</literal
>, si el cursor està situat abans del cursor <replaceable
>altra</replaceable
>,</para
></listitem>
<listitem
><para
><literal
>0</literal
>, si tots dos cursors són iguals i</para
></listitem>
<listitem
><para
><literal
>+1</literal
>, si el cursor està situat després del cursor <replaceable
>altra</replaceable
>.</para
></listitem>
</itemizedlist>
</para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>bool Cursor.equals(<parameter
>Cursor <replaceable
>altra</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Retorna <literal
>true</literal
> (cert), si aquest cursor i el cursor <replaceable
>altra</replaceable
> són iguals, en cas contrari retornarà <literal
>false</literal
> (fals). </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>String Cursor.toString();
</synopsis
></term>
<listitem
><para
>Retorna el cursor com una cadena de la forma <quote
><literal
>Cursor(line, column)</literal
></quote
>. </para
></listitem>
</varlistentry
></variablelist>
</sect4>
<sect4 id="dev-scripting-api-ranges">
<title
>El prototip «Range»</title>
<variablelist
><varlistentry>
<term
><synopsis
>Range();
</synopsis
></term>
<listitem
><para
>El constructor. Crida <literal
>new Range()</literal
> retornant un interval (0, 0) - (0, 0). </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>Range(<parameter
>Cursor <replaceable
>inici</replaceable
></parameter
>, <parameter
>Cursor <replaceable
>final</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>El constructor. Crida <literal
>new Range(<replaceable
>inici</replaceable
>, <replaceable
>final</replaceable
>)</literal
> retorna l'interval de (<replaceable
>inici</replaceable
>, <replaceable
>final</replaceable
>). </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>Range(<parameter
>int <replaceable
>líniaInici</replaceable
></parameter
>, <parameter
>int <replaceable
>columnaInici</replaceable
></parameter
>, <parameter
>int <replaceable
>líniaFinal</replaceable
></parameter
>, <parameter
>int <replaceable
>columnaFinal</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>El constructor. Crida <literal
>new Range(<replaceable
>líniaInici</replaceable
>, <replaceable
>columnaInici</replaceable
>, <replaceable
>líniaFinal</replaceable
>, <replaceable
>columnaFinal</replaceable
>)</literal
> retorna l'interval de (<replaceable
>líniaInici</replaceable
>, <replaceable
>columnaInici</replaceable
>) a (<replaceable
>líniaFinal</replaceable
>, <replaceable
>columnaFinal</replaceable
>). </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>Range(<parameter
>Range <replaceable
>altra</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>El constructor de còpia. Retorna una còpia de l'interval <replaceable
>altra</replaceable
>. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>Range Range.clone();
</synopsis
></term>
<listitem
><para
>Retorna una còpia de l'interval. </para>
<para
>Exemple: <function
>var clone = range.clone();</function
> </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>bool Range.isEmpty();
</synopsis
></term>
<listitem
><para
>Retorna <literal
>true</literal
> (cert), si inici i final del cursor són iguals. </para>
<para
>Exemple: <function
>var empty = range.isEmpty();</function
> </para>
<para
>Des del: &kde; 4.11 </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>bool Range.isValid();
</synopsis
></term>
<listitem
><para
>Retorna <literal
>true</literal
> (cert), si inici i final del cursor són vàlids, en cas contrari retornarà <literal
>false</literal
> (fals). </para>
<para
>Exemple: <function
>var valid = range.isValid();</function
> </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>Range Range.invalid();
</synopsis
></term>
<listitem
><para
>Retorna l'interval de (-1, -1) a (-1, -1). </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>bool Range.contains(<parameter
>Cursor <replaceable
>cursor</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Retorna <literal
>true</literal
> (cert) si aquest interval conté la posició de cursor, en cas contrari retornarà <literal
>false</literal
> (fals). </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>bool Range.contains(<parameter
>Range <replaceable
>altra</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Retorna <literal
>true</literal
> (cert), si aquest interval conté l'interval <replaceable
>altra</replaceable
>, en cas contrari retornarà <literal
>false</literal
> (fals). </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>bool Range.containsColumn(<parameter
>int <replaceable
>columna</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Retorna <literal
>true</literal
> (cert), si <replaceable
>columna</replaceable
> està en l'interval obert mig <literal
>[start.column, end.column)</literal
>, en cas contrari retornarà <literal
>false</literal
> (fals). </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>bool Range.containsLine(<parameter
>int <replaceable
>línia</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Retorna <literal
>true</literal
> (cert), si <replaceable
>línia</replaceable
> està en l'interval obert mig <literal
>[start.line, end.line)</literal
>, en cas contrari retornarà <literal
>false</literal
> (fals). </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>bool Range.overlaps(<parameter
>Range <replaceable
>altre</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Retorna <literal
>true</literal
> (cert), si aquest interval i l'interval <replaceable
>altre</replaceable
> comparteixen una regió comuna, en cas contrari retornarà <literal
>false</literal
> (fals). </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>bool Range.overlapsLine(<parameter
>int <replaceable
>línia</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Retorna <literal
>true</literal
> (cert), si <replaceable
>línia</replaceable
> està en l'interval <literal
>[start.line, end.line]</literal
>, en cas contrari retornarà <literal
>false</literal
> (fals). </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>bool Range.overlapsColumn(<parameter
>int <replaceable
>columna</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Retorna <literal
>true</literal
> (cert), si <replaceable
>columna</replaceable
> està en l'interval <literal
>[start.column, end.column]</literal
>, en cas contrari retornarà <literal
>false</literal
> (fals). </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>bool Range.onSingleLine();
</synopsis
></term>
<listitem
><para
>Retorna <literal
>true</literal
> (cert), si l'interval comença i finalitza a la mateixa línia, &ead; si <replaceable
>Línia.comença.interval == Línia.finalitza.interval</replaceable
>. </para>
<para
>Des del: &kde; 4.9 </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>bool Range.equals(<parameter
>Range <replaceable
>altra</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Retorna <literal
>true</literal
> (cert), si aquest interval i l'interval <replaceable
>altra</replaceable
> són iguals, en cas contrari retornarà <literal
>false</literal
> (fals). </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>String Range.toString();
</synopsis
></term>
<listitem
><para
>Retorna l'interval com una cadena de la forma <quote
><literal
>Rang(Cursor(line, column), Cursor(line, column))</literal
></quote
>. </para
></listitem>
</varlistentry
></variablelist>
</sect4>
</sect3>
<sect3 id="dev-scripting-api-global">
<title
>Funcions globals</title>
<para
>Aquesta secció llista totes les funcions globals.</para>
<sect4 id="dev-scripting-api-includes">
<title
>Llegir i incloure fitxers</title>
<variablelist
><varlistentry>
<term
><synopsis
>String read(<parameter
>String <replaceable
>fitxer</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Cercarà el <replaceable
>fitxer</replaceable
> donat en relació amb el directori <literal
>katepart5/script/files</literal
> i retorna el seu contingut com una cadena. </para
></listitem>
</varlistentry
></variablelist>
<variablelist
><varlistentry>
<term
><synopsis
>void require(<parameter
>String <replaceable
>fitxer</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Cercarà el <replaceable
>fitxer</replaceable
> donat en relació amb el directori <literal
>katepart5/script/libraries</literal
> i l'avaluarà. <literal
>require</literal
> està internament protegit contra inclusions múltiples del mateix <replaceable
>fitxer</replaceable
>. </para>
<para
>Des del: &kde; 4.10 </para>
</listitem>
</varlistentry
></variablelist>
</sect4>
<sect4 id="dev-scripting-api-debug">
<title
>Depuració</title>
<variablelist
><varlistentry>
<term
><synopsis
>void debug(<parameter
>String <replaceable
>text</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Imprimeix <replaceable
>text</replaceable
> a <literal
>stdout</literal
> a la consola de llançament de l'aplicació. </para
></listitem>
</varlistentry
></variablelist>
</sect4>
<sect4 id="dev-scripting-api-i18n">
<title
>Traducció</title>
<para
>Per tal de donar suport a la completa localització, hi ha diverses funcions per a convertir cadenes en els scripts, anomenades <literal
>i18n</literal
>, <literal
>i18nc</literal
>, <literal
>i18np</literal
> i <literal
>i18ncp</literal
>. Aquestes funcions es comporten exactament com les <ulink url="https://techbase.kde.org/Development/Tutorials/Localization/i18n"
>funcions de traducció del &kde;</ulink
>. </para>
<para
>Les funcions de traducció tradueixen les cadenes embolcallades a través del sistema de traducció del &kde; per a l'idioma utilitzat en l'aplicació. Les cadenes als scripts es desenvolupen a les fonts oficials de la &kappname; i s'extrauen de forma automàtica i traduïble. En altres paraules, com a desenvolupador de la &kappname; no haureu de preocupar-vos per l'extracció dels missatges i la traducció. Però cal assenyalar que la traducció només funciona dins de la infraestructura del &kde;, &ead;, les cadenes noves als scripts de terceres parts desenvolupats fora del &kde; no seran traduïbles. Per tant, considereu en contribuir els vostres scripts al &kate;, de tal manera que sigui possible una traducció apropiada. </para>
<variablelist
><varlistentry>
<term
><synopsis
>void i18n(<parameter
>String <replaceable
>text</replaceable
></parameter
>, <replaceable
>arg1</replaceable
>...);
</synopsis
></term>
<listitem
><para
>Tradueix <replaceable
>text</replaceable
> a l'idioma emprat per l'aplicació. Els arguments <replaceable
>arg1</replaceable
>..., són opcionals i s'utilitzen per a substituir els arguments <literal
>%1</literal
>, <literal
>%2</literal
>, &etc;</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
>Tradueix <replaceable
>text</replaceable
> a l'idioma emprat per l'aplicació. A més, la cadena <replaceable
>context</replaceable
> és visible a l'equip de traducció perquè puguin oferir una millor traducció. Els arguments <replaceable
>arg1</replaceable
>..., són opcionals i s'utilitzen per a substituir els arguments <literal
>%1</literal
>, <literal
>%2</literal
>, &etc;</para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>void i18np(<parameter
>String <replaceable
>singular</replaceable
></parameter
>, <parameter
>String <replaceable
>plural</replaceable
></parameter
>, <parameter
>int <replaceable
>número</replaceable
></parameter
>, <replaceable
>arg1</replaceable
>...);
</synopsis
></term>
<listitem
><para
>Tradueix <replaceable
>singular</replaceable
> o <replaceable
>plural</replaceable
> a l'idioma emprat per l'aplicació, en funció del <replaceable
>número</replaceable
> indicat. Els arguments <replaceable
>arg1</replaceable
>..., són opcionals i s'utilitzen per a substituir els arguments <literal
>%1</literal
>, <literal
>%2</literal
>, &etc;</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
>número</replaceable
></parameter
>, <replaceable
>arg1</replaceable
>...);
</synopsis
></term>
<listitem
><para
>Tradueix <replaceable
>singular</replaceable
> o <replaceable
>plural</replaceable
> a l'idioma emprat per l'aplicació, en funció del <replaceable
>número</replaceable
> indicat. A més, la cadena <replaceable
>context</replaceable
> és visible a l'equip de traducció perquè puguin oferir una millor traducció. Els arguments <replaceable
>arg1</replaceable
>..., són opcionals i s'utilitzen per a substituir els arguments <literal
>%1</literal
>, <literal
>%2</literal
>, &etc;</para
></listitem>
</varlistentry
></variablelist>
</sect4>
</sect3>
<sect3 id="dev-scripting-api-view">
<title
>L'API de «View»</title>
<para
>Cada vegada que s'executa un script, si hi ha una variable global <quote
><literal
>view</literal
></quote
> que representa la vista actual de l'editor actiu. La següent és una llista de totes les funcions «View» disponibles. <variablelist>
<varlistentry>
<term
><synopsis
><function
>void view.copy()</function
>
</synopsis
></term>
<listitem>
<para
>Copia la selecció si n'hi ha una, en cas contrari la línia actual si s'ha establert l'opció <userinput
>[] Copia/retalla la línia actual si no hi ha cap selecció</userinput
>.</para>
<para
>Des del: &kde-frameworks; 5.79</para>
</listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
><function
>void view.cut()</function
>
</synopsis
></term>
<listitem>
<para
>Retalla la selecció si n'hi ha una, en cas contrari la línia actual si s'ha establert l'opció <userinput
>[ ] Copia/retalla la línia actual si no hi ha cap selecció</userinput
>.</para>
<para
>Des del: &kde-frameworks; 5.79</para>
</listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
><function
>void view.paste()</function
>
</synopsis
></term>
<listitem>
<para
>Enganxa el contingut del porta-retalls.</para>
<para
>Des del: &kde-frameworks; 5.79</para>
</listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
><function
>Cursor view.cursorPosition()</function
>
</synopsis
></term>
<listitem
><para
>Retorna la posició actual del cursor en la vista.</para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>void view.setCursorPosition(<parameter
>int <replaceable
>línia</replaceable
></parameter
>, <parameter
>int <replaceable
>columna</replaceable
></parameter
>);
void view.setCursorPosition(<parameter
>Cursor <replaceable
>cursor</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Estableix la posició actual del cursor a (línia, columna) o el cursor indicat. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>Cursor view.virtualCursorPosition();
</synopsis
></term>
<listitem
><para
>Retorna la posició del cursor virtual amb cada tabulació comptant la corresponent quantitat d'espais depenent de l'amplada de la tabulació actual. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>void view.setVirtualCursorPosition(<parameter
>int <replaceable
>línia</replaceable
></parameter
>, <parameter
>int <replaceable
>column</replaceable
></parameter
>);
void view.setVirtualCursorPosition(<parameter
>Cursor <replaceable
>cursor</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Estableix la posició actual del cursor virtual (línia, columna) o el cursor indicat. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>String view.selectedText();
</synopsis
></term>
<listitem
><para
>Retorna el text seleccionat. Si no hi ha text seleccionat, la cadena retornada estarà buida. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>bool view.hasSelection();
</synopsis
></term>
<listitem
><para
>Retorna <literal
>true</literal
> (cert), si la vista conté el text seleccionat, en cas contrari retornarà <literal
>false</literal
> (fals). </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>Range view.selection();
</synopsis
></term>
<listitem
><para
>Retorna l'interval de text seleccionat. L'interval retornat no serà vàlid si no hi ha text seleccionat. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>void view.setSelection(<parameter
>Range <replaceable
>rang</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Estableix el text seleccionat a l'interval indicat. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>void view.removeSelectedText();
</synopsis
></term>
<listitem
><para
>Elimina el text seleccionat. Si la vista no té cap text seleccionat, no farà res. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>void view.selectAll();
</synopsis
></term>
<listitem
><para
>Selecciona el text sencer en el document. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>void view.clearSelection();
</synopsis
></term>
<listitem
><para
>Neteja la selecció de text sense eliminar-lo. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>void view.setBlockSelection(bool on);
</synopsis
></term>
<listitem
><para
>Activa o desactiva el mode de selecció de blocs («on» o «off»). </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>bool view.blockSelection();
</synopsis
></term>
<listitem
><para
>Retorna <literal
>true</literal
> (cert), si el mode de selecció de blocs està activat, en cas contrari retornarà <literal
>false</literal
> (fals). </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>void view.align(<parameter
>Range <replaceable
>interval</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Torna a sagnar correctament les línies dins de l'<replaceable
>interval</replaceable
> segons els paràmetres actuals del sagnat. </para>
</listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>void view.alignOn(<parameter
>Range <replaceable
>interval</replaceable
></parameter
>, <parameter
>String <replaceable
>patró</replaceable
> = ""</parameter
>);
</synopsis
></term>
<listitem
><para
>Alinea les línies de l'<replaceable
>interval</replaceable
> a la columna indicada pel <replaceable
>patró</replaceable
> de l'expressió regular. Amb un <replaceable
>patró</replaceable
> buit s'alinearà amb el primer caràcter no blanc de manera predeterminada. Si el patró té una captura, se sagnarà a la coincidència capturada. </para>
<para
><emphasis
>Exemples:</emphasis
></para>
<para
><literal
>view.alignOn(document.documentRange(), '-');</literal
> inserirà espais abans del primer <literal
>-</literal
> de cada línia per a alinear-les totes a la mateixa columna.</para>
<para
>
><literal
>view.alignOn(document.documentRange(), ':\\s+(.)');</literal
> inserirà espais abans del primer caràcter no blanc que hi hagi després de dos punts (:) per a alinear-les totes a la mateixa columna.</para>
</listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>object view.executeCommand(<parameter
>String <replaceable
>ordre</replaceable
></parameter
>,
<parameter
>String <replaceable
>args</replaceable
></parameter
>,
<parameter
>Range <replaceable
>interval</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Executa l'<link linkend="advanced-editing-tools-commandline"
><replaceable
>ordre</replaceable
>des de la línia d'ordres</link
> amb els arguments <replaceable
>args</replaceable
> opcionals i l'<replaceable
>interval</replaceable
> opcional. L'<replaceable
>objecte</replaceable
> retornat tindrà una propietat booleana <replaceable
>object.ok</replaceable
>, la qual indica que l'execució de l'<replaceable
>ordre</replaceable
> ha tingut èxit. En cas d'error, la cadena <replaceable
>object.status</replaceable
> contindrà un missatge d'error. </para>
<para
>Des del: &kde-frameworks; 5.0</para>
</listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>Range view.searchText(<parameter
>Range <replaceable
>interval</replaceable
></parameter
>,
<parameter
>String <replaceable
>patró</replaceable
></parameter
>,
<parameter
>bool <replaceable
>enrere</replaceable
> = false</parameter
>);
</synopsis
></term>
<listitem
><para
>Cerca la primera ocurrència de <replaceable
>patró</replaceable
>a l'<replaceable
>interval</replaceable
> i retorna l'interval coincident. La cerca es porta a terme cap enrere si el paràmetre booleà opcional <replaceable
>enrere</replaceable
> s'estableix a <literal
>cert</literal
>. </para>
<para
>L'interval retornat no és vàlid (vegeu Range.isValid()) si el <replaceable
>patró</replaceable
> no s'ha trobat en l'<replaceable
>interval</replaceable
>. </para>
<para
>Des del: &kde-frameworks; 5.97</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</sect3>
<sect3 id="dev-scripting-api-document">
<title
>L'API de «Document»</title>
<para
>Cada vegada que s'executa un script, si hi ha una variable global <quote
><literal
>document</literal
></quote
> que representa el document actiu actual. La següent és una llista de totes les funcions de «Document» disponibles. <variablelist>
<varlistentry>
<term
><synopsis
>String document.fileName();
</synopsis
></term>
<listitem
><para
>Retorna el nom de fitxer del document o una cadena buida per a la memòria cau del text sense desar. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>String document.url();
</synopsis
></term>
<listitem
><para
>Retorna l'&URL; complet del document o una cadena buida per a la memòria cau del text sense desar. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>String document.mimeType();
</synopsis
></term>
<listitem
><para
>Retorna el tipus &MIME; del document o el tipus &MIME; <literal
>application/octet-stream</literal
> si no es pot trobar un tipus &MIME; adequat. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>String document.encoding();
</synopsis
></term>
<listitem
><para
>Retorna la codificació emprada actualment per a desar el fitxer. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>String document.highlightingMode();
</synopsis
></term>
<listitem
><para
>Retorna el mode de ressaltat global emprat per a tot el document. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>String document.highlightingModeAt(<parameter
>Cursor <replaceable
>pos</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Retorna el mode de ressaltat emprat a la posició indicada en el document. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>Array document.embeddedHighlightingModes();
</synopsis
></term>
<listitem
><para
>Retorna una cadena dels modes de ressaltat incrustats en aquest document. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>bool document.isModified();
</synopsis
></term>
<listitem
><para
>Retorna <literal
>true</literal
> (cert), si el document conté canvis sense desar (modificat), en cas contrari retornarà <literal
>false</literal
> (fals). </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>String document.text();
</synopsis
></term>
<listitem
><para
>Retorna el contingut complet del document en una cadena de text única. Els salts de línia estan marcats amb el caràcter de nova línia <quote
><literal
>\n</literal
></quote
>. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>String document.text(<parameter
>int <replaceable
>desDeLínia</replaceable
></parameter
>, <parameter
>int <replaceable
>desDeColumna</replaceable
></parameter
>, <parameter
>int <replaceable
>alaLínia</replaceable
></parameter
>, <parameter
>int <replaceable
>alaColumna</replaceable
></parameter
>);
String document.text(<parameter
>Cursor <replaceable
>desDe</replaceable
></parameter
>, <parameter
>Cursor <replaceable
>a</replaceable
></parameter
>);
String document.text(<parameter
>Range <replaceable
>rang</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Retorna el text en l'interval donat. Es recomana utilitzar el cursor i la versió basada en l'interval per a una millor lectura del codi font. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>String document.line(<parameter
>int <replaceable
>línia</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Retorna la línia de text donada com a cadena. La cadena estarà buida si la línia demanada està fora de l'interval. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>String document.wordAt(<parameter
>int <replaceable
>línia</replaceable
></parameter
>, <parameter
>int <replaceable
>columna</replaceable
></parameter
>);
String document.wordAt(<parameter
>Cursor <replaceable
>cursor</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Retorna la paraula a la posició del cursor donada. </para
></listitem>
</varlistentry>
<varlistentry>
<term>
<synopsis
>Range document.wordRangeAt(<parameter
>int <replaceable
>línia</replaceable
></parameter
>, <parameter
>int <replaceable
>columna</replaceable
></parameter
>);
Range document.wordRangeAt(<parameter
>Cursor <replaceable
>cursor</replaceable
></parameter
>);
</synopsis>
</term>
<listitem
><para
>Retorna l'interval de la paraula a la posició del cursor donada. L'interval retornat no serà vàlid (vegeu Range.isValid()), si la posició del text és després del final d'una línia. Si no hi ha paraula al cursor donat, es retornarà un interval buit. </para>
<para
>Des del: &kde; 4.9 </para>
</listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>String document.charAt(<parameter
>int <replaceable
>línia</replaceable
></parameter
>, <parameter
>int <replaceable
>columna</replaceable
></parameter
>);
String document.charAt(<parameter
>Cursor <replaceable
>cursor</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Retorna el caràcter a la posició del cursor donada. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>String document.firstChar(<parameter
>int <replaceable
>línia</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Retorna el primer caràcter en la <replaceable
>línia</replaceable
> donada que no és un espai en blanc. El primer caràcter és a la columna 0. Si la línia està buida o només conté espais en blanc, la cadena retornada estarà buida. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>String document.lastChar(<parameter
>int <replaceable
>línia</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Retorna l'últim caràcter de la <replaceable
>línia</replaceable
> donada que no és un espai en blanc. Si la línia està buida o només conté espais en blanc, la cadena retornada estarà buida. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>bool document.isSpace(<parameter
>int <replaceable
>línia</replaceable
></parameter
>, <parameter
>int <replaceable
>columna</replaceable
></parameter
>);
bool document.isSpace(<parameter
>Cursor <replaceable
>cursor</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Retorna <literal
>true</literal
> (cert), si el caràcter a la posició del cursor donada és un espai en blanc, en cas contrari retornarà <literal
>false</literal
> (fals). </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>bool document.matchesAt(<parameter
>int <replaceable
>línia</replaceable
></parameter
>, <parameter
>int <replaceable
>columna</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
>Retorna <literal
>true</literal
> (cert), si el <replaceable
>text</replaceable
> donat coincideix a la posició del cursor corresponent, en cas contrari retornarà <literal
>false</literal
> (fals). </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>bool document.startsWith(<parameter
>int <replaceable
>línia</replaceable
></parameter
>, <parameter
>String <replaceable
>text</replaceable
></parameter
>, <parameter
>bool <replaceable
>skipWhiteSpaces</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Retorna <literal
>true</literal
> (cert), si la línia comença amb <replaceable
>text</replaceable
>, en cas contrari retornarà <literal
>false</literal
> (fals). L'argument <replaceable
>skipWhiteSpaces</replaceable
> controla si s'han d'ometre els espais en blanc al davant. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>bool document.endsWith(<parameter
>int <replaceable
>línia</replaceable
></parameter
>, <parameter
>String <replaceable
>text</replaceable
></parameter
>, <parameter
>bool <replaceable
>skipWhiteSpaces</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Retorna <literal
>true</literal
> (cert), si la línia acaba amb <replaceable
>text</replaceable
>, en cas contrari retornarà <literal
>false</literal
> (fals). L'argument <replaceable
>skipWhiteSpaces</replaceable
> controla si s'han d'ometre els espais en blanc finals. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>bool document.setText(<parameter
>String <replaceable
>text</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Estableix el text a tot el document. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>bool document.clear();
</synopsis
></term>
<listitem
><para
>Elimina tot el text en el document. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>bool document.truncate(<parameter
>int <replaceable
>línia</replaceable
></parameter
>, <parameter
>int <replaceable
>columna</replaceable
></parameter
>);
bool document.truncate(<parameter
>Cursor <replaceable
>cursor</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Trunca la línia donada a la columna o la posició donada del cursor. Retorna <literal
>true</literal
> (cert) en cas d'èxit, o <literal
>false</literal
> (fals) si la línia donada no forma part de l'interval del document. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>bool document.insertText(<parameter
>int <replaceable
>línia</replaceable
></parameter
>, <parameter
>int <replaceable
>columna</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
>Insereix el <replaceable
>text</replaceable
> a la posició donada del cursor. Retorna <literal
>true</literal
> (cert) en cas d'èxit, o <literal
>false</literal
> (fals), si el document està en el mode de només lectura. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>bool document.removeText(<parameter
>int <replaceable
>desDeLínia</replaceable
></parameter
>, <parameter
>int <replaceable
>desDeColumna</replaceable
></parameter
>, <parameter
>int <replaceable
>alaLínia</replaceable
></parameter
>, <parameter
>int <replaceable
>alaColumna</replaceable
></parameter
>);
bool document.removeText(<parameter
>Cursor <replaceable
>desDe</replaceable
></parameter
>, <parameter
>Cursor <replaceable
>a</replaceable
></parameter
>);
bool document.removeText(<parameter
>Range <replaceable
>rang</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Elimina el text dins de l'interval donat. Retorna <literal
>true</literal
> (cert) en cas d'èxit, o <literal
>false</literal
> (fals), si el document està en el mode de només lectura. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>bool document.insertLine(<parameter
>int <replaceable
>línia</replaceable
></parameter
>, <parameter
>String <replaceable
>text</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Insereix text en la línia donada. Retorna <literal
>true</literal
> (cert) en cas d'èxit, o <literal
>false</literal
> (fals), si el document està en el mode de només lectura o la línia no està en l'interval del document. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>bool document.removeLine(<parameter
>int <replaceable
>línia</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Elimina la línia de text donada. Retorna <literal
>true</literal
> (cert) en cas d'èxit, o <literal
>false</literal
> (fals), si el document està en el mode de només lectura o la línia no està en l'interval del document. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>bool document.wrapLine(<parameter
>int <replaceable
>línia</replaceable
></parameter
>, <parameter
>int <replaceable
>columna</replaceable
></parameter
>);
bool document.wrapLine(<parameter
>Cursor <replaceable
>cursor</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Ajusta la línia a la posició del cursor donada. Retorna <literal
>true</literal
> (cert) en cas d'èxit, o <literal
>false</literal
> (fals), &pex; si la línia < 0. </para>
<para
>Des del: &kde; 4.9 </para>
</listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>void document.joinLines(<parameter
>int <replaceable
>iniciLínia</replaceable
></parameter
>, <parameter
>int <replaceable
>finalLínia</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>S'uneix a les línies de <replaceable
>iniciLínia</replaceable
> a <replaceable
>finalLínia</replaceable
>. Dues línies de text successives sempre estan separades per un espai. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>int document.lines();
</synopsis
></term>
<listitem
><para
>Retorna el nombre de línies en el document. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>bool document.isLineModified(<parameter
>int <replaceable
>línia</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Retorna <literal
>true</literal
> (cert), si la <replaceable
>línia</replaceable
> actual conté dades sense desar. </para>
<para
>Des del: &kde; 5.0 </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>bool document.isLineSaved(<parameter
>int <replaceable
>línia</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Retorna <literal
>true</literal
> (cert), si la <replaceable
>línia</replaceable
> ha canviat, però el document ha estat desat. Per tant, la línia actual no conté cap dada sense desar. </para>
<para
>Des del: &kde; 5.0 </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>bool document.isLineTouched(<parameter
>int <replaceable
>línia</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Retorna <literal
>true</literal
> (cert), si la <replaceable
>línia</replaceable
> actual conté dades sense desar o que s'han canviat abans. </para>
<para
>Des del: &kde; 5.0 </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>bool document.findTouchedLine(<parameter
>int <replaceable
>iniciLínia</replaceable
></parameter
>, <parameter
>bool <replaceable
>avall</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Cerca la següent línia tocada començant per la <replaceable
>línia</replaceable
>. La cerca es realitza amunt o avall depenent de la direcció especificada a <replaceable
>avall</replaceable
>. </para>
<para
>Des del: &kde; 5.0 </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>int document.length();
</synopsis
></term>
<listitem
><para
>Retorna el nombre de caràcters en el document. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>int document.lineLength(<parameter
>int <replaceable
>línia</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Retorna la longitud de la <replaceable
>línia</replaceable
>. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>void document.editBegin();
</synopsis
></term>
<listitem
><para
>Comença un grup d'edició per a agrupar desfer/refer. Assegureu-vos de cridar sempre <function
>editEnd()</function
> tan aviat com crideu <function
>editBegin()</function
>. La crida <function
>editBegin()</function
> utilitza internament un comptador de referència, &ead;, aquesta crida es pot imbricar. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>void document.editEnd();
</synopsis
></term>
<listitem
><para
>Finalitza un grup d'edició. L'última crida de <function
>editEnd()</function
> (&ead;, una per a la primera crida de <function
>editBegin()</function
>) finalitza el pas d'edició. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>int document.firstColumn(<parameter
>int <replaceable
>línia</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Retorna la primera columna que no està en blanc en la <replaceable
>línia</replaceable
> donada. Si només hi ha espais en blanc a la línia, el valor retornat serà <literal
>-1</literal
>. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>int document.lastColumn(<parameter
>int <replaceable
>línia</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Retorna la darrera columna que no està en blanc en la <replaceable
>línia</replaceable
> donada. Si només hi ha espais en blanc a la línia, el valor retornat serà <literal
>-1</literal
>. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>int document.prevNonSpaceColumn(<parameter
>int <replaceable
>línia</replaceable
></parameter
>, <parameter
>int <replaceable
>columna</replaceable
></parameter
>);
int document.prevNonSpaceColumn(<parameter
>Cursor <replaceable
>cursor</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Retorna la columna no buida que conté un caràcter no en blanc a partir de la posició donada del cursor i cercant cap enrere. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>int document.nextNonSpaceColumn(<parameter
>int <replaceable
>línia</replaceable
></parameter
>, <parameter
>int <replaceable
>columna</replaceable
></parameter
>);
int document.nextNonSpaceColumn(<parameter
>Cursor <replaceable
>cursor</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Retorna la columna no buida que conté un caràcter no en blanc a partir de la posició donada del cursor i cercant cap endavant. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>int document.prevNonEmptyLine(<parameter
>int <replaceable
>línia</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Retorna la línia següent no buida que conté caràcters no en blanc a la cerca cap enrere. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>int document.nextNonEmptyLine(<parameter
>int <replaceable
>línia</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Retorna la línia següent no buida que conté caràcters no en blanc a la cerca cap endavant. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>bool document.isInWord(<parameter
>String <replaceable
>caràcter</replaceable
></parameter
>, <parameter
>int <replaceable
>atribut</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Retorna <literal
>true</literal
> (cert), si el <replaceable
>caràcter</replaceable
> donat amb l'<replaceable
>atribut</replaceable
> donat pot formar part d'una paraula, en cas contrari retornarà <literal
>false</literal
> (fals). </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>bool document.canBreakAt(<parameter
>String <replaceable
>caràcter</replaceable
></parameter
>, <parameter
>int <replaceable
>atribut</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Retorna <literal
>true</literal
> (cert), si el <replaceable
>caràcter</replaceable
> donat amb l'<replaceable
>atribut</replaceable
> donat és adequat com a embolcall d'una línia, en cas contrari retornarà <literal
>false</literal
> (fals). </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>bool document.canComment(<parameter
>int <replaceable
>iniciAtribut</replaceable
></parameter
>, <parameter
>int <replaceable
>finalAtribut</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Retorna <literal
>true</literal
> (cert), si un interval inicial i final amb els atributs donats es presten a ser descomentats, en cas contrari retornarà <literal
>false</literal
> (fals). </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>String document.commentMarker(<parameter
>int <replaceable
>atribut</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Retorna el marcador de comentari per als comentaris de línia única per a un <replaceable
>atribut</replaceable
> donat. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>String document.commentStart(<parameter
>int <replaceable
>atribut</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Retorna el marcador de comentari per al començament de comentaris de múltiples línies per a un <replaceable
>atribut</replaceable
> donat. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>String document.commentEnd(<parameter
>int <replaceable
>atribut</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Retorna el marcador de comentari per al final de comentaris de múltiples línies per a un <replaceable
>atribut</replaceable
> donat. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>Range document.documentRange();
</synopsis
></term>
<listitem
><para
>Retorna un interval que abasta tot el document. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>Cursor documentEnd();
</synopsis
></term>
<listitem
><para
>Retorna un cursor situat a l'última columna de l'última línia al document. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>bool isValidTextPosition(<parameter
>int <replaceable
>línia</replaceable
></parameter
>, <parameter
>int <replaceable
>columna</replaceable
></parameter
>);
bool isValidTextPosition(<parameter
>Cursor <replaceable
>cursor</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Retorna <literal
>true</literal
> (cert), si la posició indicada del cursor està situada a una posició vàlida del text. Una posició de text només és vàlida si es localitza al començament, al mig o al final d'una línia vàlida. A més, una posició de text no serà vàlida si es troba en un substitut Unicode. </para
><para
>Des del: &kde; 5.0 </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>int document.attribute(<parameter
>int <replaceable
>línia</replaceable
></parameter
>, <parameter
>int <replaceable
>columna</replaceable
></parameter
>);
int document.attribute(<parameter
>Cursor <replaceable
>cursor</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Retorna l'atribut a la posició del cursor donada. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>bool document.isAttribute(<parameter
>int <replaceable
>línia</replaceable
></parameter
>, <parameter
>int <replaceable
>columna</replaceable
></parameter
>, <parameter
>int <replaceable
>atribut</replaceable
></parameter
>);
bool document.isAttribute(<parameter
>Cursor <replaceable
>cursor</replaceable
></parameter
>, <parameter
>int <replaceable
>atribut</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Retorna <literal
>true</literal
> (cert), si l'atribut a la posició del cursor és igual que l'<replaceable
>atribut</replaceable
>, en cas contrari retornarà <literal
>false</literal
> (fals). </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>String document.attributeName(<parameter
>int <replaceable
>línia</replaceable
></parameter
>, <parameter
>int <replaceable
>columna</replaceable
></parameter
>);
String document.attributeName(<parameter
>Cursor <replaceable
>cursor</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Retorna el nom de l'atribut com a text llegible. Això equival al nom <literal
>itemData</literal
> en els fitxers de ressaltat de la sintaxi. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>bool document.isAttributeName(<parameter
>int <replaceable
>línia</replaceable
></parameter
>, <parameter
>int <replaceable
>columna</replaceable
></parameter
>, <parameter
>String <replaceable
>nom</replaceable
></parameter
>);
bool document.isAttributeName(<parameter
>Cursor <replaceable
>cursor</replaceable
></parameter
>, <parameter
>String <replaceable
>nom</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Retorna <literal
>true</literal
> (cert), si el nom de l'atribut en una posició determinada del cursor coincideix amb el <replaceable
>nom</replaceable
> donat, en cas contrari retornarà <literal
>false</literal
> (fals). </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>String document.variable(<parameter
>String <replaceable
>clau</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Retorna el valor de la variable de document demanada <replaceable
>clau</replaceable
>. Si la variable de document no existeix, el valor retornat serà una cadena buida. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>void document.setVariable(<parameter
>String <replaceable
>clau</replaceable
></parameter
>, <parameter
>String <replaceable
>valor</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Estableix el valor de la variable de document demanada <replaceable
>clau</replaceable
>. </para>
<para
>Vegeu també: <link linkend="config-variables"
>variables de document del Kate</link
> </para>
<para
>Des del: &kde; 4.8 </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>int document.firstVirtualColumn(<parameter
>int <replaceable
>línia</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Retorna la columna virtual del primer caràcter que no està en blanc a la línia donada o <literal
>-1</literal
>, si la línia està buida o només conté caràcters d'espai en blanc. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>int document.lastVirtualColumn(<parameter
>int <replaceable
>línia</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Retorna la columna virtual de l'últim caràcter que no està en blanc a la línia donada o <literal
>-1</literal
>, si la línia està buida o només conté caràcters d'espai en blanc. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>int document.toVirtualColumn(<parameter
>int <replaceable
>línia</replaceable
></parameter
>, <parameter
>int <replaceable
>columna</replaceable
></parameter
>);
int document.toVirtualColumn(<parameter
>Cursor <replaceable
>cursor</replaceable
></parameter
>);
Cursor document.toVirtualCursor(<parameter
>Cursor <replaceable
>cursor</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Converteix la posició <quote
>real</quote
> donada del cursor a una posició virtual del cursor, d'altra manera retorna un «int» o un objecte «Cursor». </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>int document.fromVirtualColumn(<parameter
>int <replaceable
>línia</replaceable
></parameter
>, <parameter
>int <replaceable
>virtualColumna</replaceable
></parameter
>);
int document.fromVirtualColumn(<parameter
>Cursor <replaceable
>virtualCursor</replaceable
></parameter
>);
Cursor document.fromVirtualCursor(<parameter
>Cursor <replaceable
>virtualCursor</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Converteix la posició virtual donada del cursor a una posició <quote
>real</quote
> del cursor, d'altra manera retorna un «int» o un objecte «Cursor». </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>Cursor document.anchor(<parameter
>int <replaceable
>línia</replaceable
></parameter
>, <parameter
>int <replaceable
>columna</replaceable
></parameter
>, <parameter
>Char <replaceable
>caràcter</replaceable
></parameter
>);
Cursor document.anchor(<parameter
>Cursor <replaceable
>cursor</replaceable
></parameter
>, <parameter
>Char <replaceable
>caràcter</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Cerca enrere pel caràcter donat a partir del cursor donat. Com a exemple, si es passa «(» com a caràcter, aquesta funció retornarà la posició de l'obertura «(». Això compta la referència, &ead;, els altres «(...)» seran ignorats. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>Cursor document.rfind(<parameter
>int <replaceable
>línia</replaceable
></parameter
>, <parameter
>int <replaceable
>columna</replaceable
></parameter
>, <parameter
>String <replaceable
>text</replaceable
></parameter
>, <parameter
>int <replaceable
>atribut</replaceable
> = -1</parameter
>);
Cursor document.rfind(<parameter
>Cursor <replaceable
>cursor</replaceable
></parameter
>, <parameter
>String <replaceable
>text</replaceable
></parameter
>, <parameter
>int <replaceable
>atribut</replaceable
> = -1</parameter
>);
</synopsis
></term>
<listitem
><para
>Cerca cap enrere el text donat amb l'<replaceable
>atribut</replaceable
> adequat. L'argument <replaceable
>atribut</replaceable
> s'ignorarà si s'estableix a <literal
>-1</literal
>. El cursor retornat no serà vàlid, si el text no s'ha pogut trobar. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>int document.defStyleNum(<parameter
>int <replaceable
>línia</replaceable
></parameter
>, <parameter
>int <replaceable
>columna</replaceable
></parameter
>);
int document.defStyleNum(<parameter
>Cursor <replaceable
>cursor</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Retorna l'estil predeterminat utilitzat a la posició donada del cursor. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>bool document.isCode(<parameter
>int <replaceable
>línia</replaceable
></parameter
>, <parameter
>int <replaceable
>columna</replaceable
></parameter
>);
bool document.isCode(<parameter
>Cursor <replaceable
>cursor</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Retorna <literal
>true</literal
> (cert), si l'atribut a la posició donada del cursor no és igual per a tots els següents estils: <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
>línia</replaceable
></parameter
>, <parameter
>int <replaceable
>columna</replaceable
></parameter
>);
bool document.isComment(<parameter
>Cursor <replaceable
>cursor</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Retorna <literal
>true</literal
> (cert), si l'atribut del caràcter a la posició del cursor és <literal
>dsComment</literal
>, en cas contrari retornarà <literal
>false</literal
> (fals). </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>bool document.isString(<parameter
>int <replaceable
>línia</replaceable
></parameter
>, <parameter
>int <replaceable
>columna</replaceable
></parameter
>);
bool document.isString(<parameter
>Cursor <replaceable
>cursor</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Retorna <literal
>true</literal
> (cert), si l'atribut del caràcter a la posició del cursor és <literal
>dsString</literal
>, en cas contrari retornarà <literal
>false</literal
> (fals). </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>bool document.isRegionMarker(<parameter
>int <replaceable
>línia</replaceable
></parameter
>, <parameter
>int <replaceable
>columna</replaceable
></parameter
>);
bool document.isRegionMarker(<parameter
>Cursor <replaceable
>cursor</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Retorna <literal
>true</literal
> (cert), si l'atribut del caràcter a la posició del cursor és <literal
>dsRegionMarker</literal
>, en cas contrari retornarà <literal
>false</literal
> (fals). </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>bool document.isChar(<parameter
>int <replaceable
>línia</replaceable
></parameter
>, <parameter
>int <replaceable
>columna</replaceable
></parameter
>);
bool document.isChar(<parameter
>Cursor <replaceable
>cursor</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Retorna <literal
>true</literal
> (cert), si l'atribut del caràcter a la posició del cursor és <literal
>dsChar</literal
>, en cas contrari retornarà <literal
>false</literal
> (fals). </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>bool document.isOthers(<parameter
>int <replaceable
>línia</replaceable
></parameter
>, <parameter
>int <replaceable
>columna</replaceable
></parameter
>);
bool document.isOthers(<parameter
>Cursor <replaceable
>cursor</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Retorna <literal
>true</literal
> (cert), si l'atribut del caràcter a la posició del cursor és <literal
>dsOthers</literal
>, en cas contrari retornarà <literal
>false</literal
> (fals). </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>void document.indent(<parameter
>Range <replaceable
>interval</replaceable
></parameter
>, <parameter
>int <replaceable
>canvi</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Sagna totes les línies de l'<replaceable
>interval</replaceable
> <replaceable
>canviant</replaceable
> les tabulacions o <replaceable
>canviant</replaceable
> <literal
>tabSize</literal
> vegades els espais depenent de les preferències dels usuaris. El paràmetre <replaceable
>canvi</replaceable
> pot ser negatiu. </para
></listitem>
</varlistentry>
</variablelist>
</para>
</sect3>
<sect3 id="dev-scripting-api-editor">
<title
>L'API de l'editor</title>
<para
>A més de l'API del document i la visualització, hi ha una API general de l'editor que proporciona funcions per a la funcionalitat per a crear scripts general de l'editor. <variablelist>
<varlistentry>
<term
><synopsis
>Cadena editor.clipboardText();
</synopsis
></term>
<listitem
><para
>Retorna el text que es troba actualment al porta-retalls global. </para>
<para
>Des del: &kde-frameworks; 5.0</para>
</listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>Cadena editor.clipboardHistory();
</synopsis
></term>
<listitem
><para
>L'editor manté un historial del porta-retalls que conté fins a 10 entrades. Aquesta funció retorna totes les entrades que actualment es troben a l'historial del porta-retalls. </para>
<para
>Des del: &kde-frameworks; 5.0</para>
</listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>void editor.setClipboardText(<parameter
>String <replaceable
>text</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Estableix el contingut del porta-retalls al <replaceable
>text</replaceable
>. El <replaceable
>text</replaceable
> serà afegit a l'historial del porta-retalls. </para>
<para
>Des del: &kde-frameworks; 5.0</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</sect3>
</sect2>
</sect1>
</chapter>
Generated by dwww version 1.15 on Thu Jun 27 09:21:21 CEST 2024.