<!-- auto-generate scripting documentation (kwrite-devel@kde.org Re: [kate] doc/kate: document most of the new scripts in 4.10) -->
<chapter id="dev">
<chapterinfo>
<authorgroup>
<author
>&TC.Hollingsworth; &TC.Hollingsworth.mail;</author>
<othercredit role="translator"
><firstname
>Nicola</firstname
> <surname
>Ruggero</surname
> <affiliation
><address
><email
>nicola@nxnt.org</email
></address
></affiliation
><contrib
>Traduzione della documentazione.</contrib
></othercredit
><othercredit role="translator"
><firstname
>Luciano</firstname
><surname
>Montanaro</surname
><affiliation
><address
><email
>mikelima@cirulla.net</email
></address
></affiliation
><contrib
>Aggiornamento per Kate 2.5.6</contrib
></othercredit
><othercredit role="translator"
><firstname
>Paolo</firstname
><surname
>Zamponi</surname
><affiliation
><address
><email
>zapaolo@email.it</email
></address
></affiliation
><contrib
>Aggiornamento e manutenzione della traduzione</contrib
></othercredit
>
</authorgroup>
</chapterinfo>
<title
>Estensione di &katepart;</title>
<sect1 id="dev-intro">
<title
>Introduzione</title>
<para
>Come ogni componente editor di testi avanzato, &katepart; offre una moltitudine di modi per espandere le proprie funzionalità: puoi <link linkend="dev-scripting"
>scrivere semplici script per aggiungere funzionalità con &javascript;</link
>. Infine, dopo aver esteso &katepart; saresti il benvenuto <ulink url="https://kate-editor.org/join-us/"
>nel nostro gruppo</ulink
>, per condividere il tuo lavoro con il mondo intero!</para>
</sect1>
<sect1 id="highlight">
<title
>Lavorare con l'evidenziazione della sintassi</title>
<sect2 id="highlight-overview">
<title
>Panoramica</title>
<para
>L'evidenziazione della sintassi è quel qualcosa che rende l'editor in grado di visualizzare automaticamente il testo con stili e colori differenti, a seconda delle funzioni delle stringhe in relazione allo scopo del file. Nel sorgente di un programma, per esempio, le istruzioni di controllo potrebbero essere rese in grassetto, mentre i tipi di dati e i commenti in colori diversi dal resto del testo. Questo migliora di molto la leggibilità del testo, e rende l'autore più efficiente e più produttivo.</para>
<mediaobject>
<imageobject
><imagedata format="PNG" fileref="highlighted.png"/></imageobject>
<textobject
><phrase
>Una funzione C++, resa con l'evidenziazione della sintassi.</phrase
></textobject>
<caption
><para
>Una funzione C++, resa con l'evidenziazione della sintassi.</para>
</caption>
</mediaobject>
<mediaobject>
<imageobject
><imagedata format="PNG" fileref="unhighlighted.png"/></imageobject>
<textobject
><phrase
>La stessa funzione C++, senza l'evidenziazione.</phrase
></textobject>
<caption
><para
>La stessa funzione C++, senza l'evidenziazione.</para
></caption>
</mediaobject>
<para
>Dei due esempi, qual è il più semplice da leggere?</para>
<para
>&kappname; nasce con un sistema flessibile e configurabile che è in grado di eseguire l'evidenziazione della sintassi. Già nella distribuzione standard vengono fornite alcune definizioni che coprono una vasta gamma di linguaggi di programmazione, di scripting e di markup e per altri formati di file di testo; puoi inoltre inserire le tue definizioni in un semplice file &XML;.</para>
<para
>Quando apri un file basato sul tipo &MIME; del file &kappname;, riconoscerà automaticamente le giuste regole della sintassi; questo in base alla sua estensione o, se non presente, al suo contenuto. Puoi sempre impostare manualmente la sintassi da usare, qualora notassi dei problemi, facendo clic su <menuchoice
><guimenu
>Strumenti</guimenu
><guisubmenu
>Evidenziazione</guisubmenu
></menuchoice
>.</para>
<para
>Gli stili e i colori usati da ciascuna definizione di evidenziazione della sintassi possono essere configurati usando la scheda <link linkend="prefcolors-highlighting-text-styles"
>Stili di testo evidenziato</link
>, mentre i tipi &MIME; e le estensioni del file che dovrebbero essere usate a questo scopo sono gestiti nella scheda <link linkend="pref-open-save-modes-filetypes"
>Modi e tipi di file</link
>.</para>
<note>
<para
>L'evidenziazione della sintassi serve per migliorare la leggibilità del testo, ma non puoi affidarti ad essa per convalidarlo. La marcatura del testo in base alla sintassi può essere difficoltosa a seconda del formato che stai utilizzando: in qualche caso l'autore delle regole della sintassi sarà orgoglioso se il 98% del testo venisse renderizzato correttamente. Ad ogni modo, in genere, sarà difficile incontrare quel 2% non corretto.</para>
</note>
</sect2>
<sect2 id="katehighlight-system">
<title
>Il sistema di evidenziazione della sintassi di &kappname;</title>
<para
>In questa sezione sarà trattato più in dettaglio il meccanismo di evidenziazione della sintassi. Ti servirà se vorrai saperne di più, oppure se vorrai cambiare o creare delle definizioni di sintassi.</para>
<sect3 id="katehighlight-howitworks">
<title
>Come funziona</title>
<para
>Una delle prime cose che l'editor &kappname; fa ogni volta che apri un file è quella di individuare la definizione di sintassi da usare. Mentre stai leggendo il testo del file, e mentre stai digitando qualcosa, il sistema di evidenziazione della sintassi analizza il testo usando le regole definite dalle definizioni di sintassi, e lo marca dove i diversi contesti e gli stili iniziano e finiscono.</para>
<para
>Quando digiti nel documento, il nuovo testo viene analizzato e marcato al volo. In questo modo, se cancelli un carattere che è marcato come inizio o fine di un contesto, lo stile del testo circostante viene modificato di conseguenza.</para>
<para
>Le definizioni di sintassi usate dal sistema di evidenziazione di &kappname; sono dei file &XML;, contenenti <itemizedlist>
<listitem
><para
>Regole per individuare il ruolo del testo, organizzate in blocchi di contesto</para
></listitem>
<listitem
><para
>Liste di parole chiave</para
></listitem>
<listitem
><para
>Definizioni di oggetti di stile</para
></listitem>
</itemizedlist>
</para>
<para
>Quando il testo viene analizzato, le regole di rilevamento vengono valutate nell'ordine in cui sono definite: se l'inizio della stringa corrente coincide con una qualche regola, allora viene usato il relativo contesto. Il punto di inizio del testo viene spostato nel punto finale in cui la regola è stata applicata; inizia così un nuovo ciclo, che comincia nel contesto impostato dalla regola applicata.</para>
</sect3>
<sect3 id="highlight-system-rules">
<title
>Regole</title>
<para
>Le regole di rilevamento sono il cuore del sistema di rilevamento della sintassi. Una regola è una stringa, un carattere o un'<link linkend="regular-expressions"
>espressione regolare</link
> con cui confrontare il testo che viene analizzato. Contiene le informazioni sullo stile da usare per la parte corrispondente del testo. Può passare il contesto di lavoro del sistema sia ad un contesto menzionato esplicitamente che al contesto precedente usato dal testo.</para>
<para
>Le regole sono organizzate in gruppi di contesto, ciascuno dei quali viene usato per i concetti principali di testo all'interno del formato, per esempio le stringhe di testo virgolettato o i blocchi di commenti nei sorgenti dei programmi. Questo assicura che il sistema di evidenziazione non abbia la necessità di cercare tra le regole se non è necessario, e che alcune sequenze di caratteri nel testo possono essere trattate in maniera diversa a seconda del contesto corrente. </para>
<para
>I contesti possono essere generati dinamicamente per permettere l'uso di istanze di dati specifici nelle regole.</para>
</sect3>
<sect3 id="highlight-context-styles-keywords">
<title
>Stili di contesto e parole chiave</title>
<para
>In alcuni linguaggi di programmazione i numeri interi sono trattati dal compilatore (il programma che converte il codice sorgente in binario eseguibile) in maniera diversa da quelli in virgola mobile, inoltre all'interno di una stringa virgolettata ci possono essere dei caratteri con un significato speciale. In questi casi ha senso visualizzarli in modo differente da quelli circostanti, in modo che possano essere identificati facilmente durante la lettura del testo. Così, pur non rappresentando un contesto speciale, questi possono essere comunque trattati come tali dal sistema di evidenziazione della sintassi, in modo da essere contrassegnati e quindi visualizzati in modo diverso.</para>
<para
>Una definizione di sintassi può contenere tutti gli stili richiesti per racchiudere i concetti del formato per cui è usata.</para>
<para
>In molti formati ci sono liste di parole che rappresentano un concetto specifico: per esempio nei linguaggi di programmazione le istruzioni di controllo sono un concetto, i nomi dei tipi di dato un altro, e le funzioni proprie del linguaggio un terzo. Il sistema di evidenziazione della sintassi di &kappname; può usare queste liste per individuare le parole marcandole nel testo, in modo da enfatizzare i concetti dei formati di testo.</para>
</sect3>
<sect3 id="kate-highlight-system-default-styles">
<title
>Stili predefiniti</title>
<para
>Se apri in &kappname; un file sorgente in C++, un sorgente &Java; o un documento &HTML; vedrai che, anche se i formati e le parole scelte per il trattamento speciale sono diversi, i colori utilizzati sono gli stessi. Questo perché &kappname; ha una lista di stili predefiniti che vengono impiegati dalle definizioni individuali di sintassi.</para>
<para
>Questo rende semplice riconoscere concetti simili in formati di testo diversi. Per esempio, i commenti sono presenti in quasi tutti i linguaggi di programmazione, di scripting e di markup: se sono sempre renderizzati utilizzando lo stesso stile in tutti i linguaggi, allora non avrai bisogno di fermarti a pensare per identificarli nel testo.</para>
<tip>
<para
>Tutti gli stili di una definizione di sintassi usano uno degli stili predefiniti: solo poche di esse fanno uso di altri stili non predefiniti. Potrebbe essere il caso di lanciare la finestra di configurazione se usi spesso un formato, così da vedere se alcuni concetti fanno uso di uno stesso stile. Per esempio, c'è solo uno stile predefinito per le stringhe, ma il linguaggio di programmazione Perl ha due tipi di stringhe: potresti quindi migliorarne l'evidenziazione, configurandoli in modo che siano leggermente diversi. Tutti gli <link linkend="kate-highlight-default-styles"
>stili predefiniti disponibili</link
> verranno spiegati in seguito.</para>
</tip>
</sect3>
</sect2>
<sect2 id="katehighlight-xml-format">
<title
>Il formato &XML; di definizione dell'evidenziazione</title>
<sect3>
<title
>Panoramica</title>
<para
>&kappname; usa l'infrastruttura di evidenziazione della sintassi di &kde-frameworks;. I file &XML; per l'evidenziazione predefinita forniti insieme a &kappname; sono compilati in modo predefinito nella libreria di evidenziazione della sintassi. </para>
<para
>Questa sezione è una panoramica sul formato &XML; di definizione dell'evidenziazione. Basandosi su un piccolo esempio saranno descritti i componenti principali, il loro significato e il loro uso. La prossima sezione scenderà invece nei dettagli delle regole di rilevamento dell'evidenziazione.</para>
<para
>La definizione formale, anche conosciuta come <acronym
>XSD</acronym
>, si trova nel <ulink url="https://commits.kde.org/syntax-highlighting?path=data/schema"
>deposito dell'evidenziazione della sintassi</ulink
>, nel file <filename
>language.xsd</filename
> </para>
<para
>I file <filename class="extension"
>.xml</filename
> per la definizione personalizzata di evidenziazione si trovano in <filename class="directory"
>org.kde.syntax-highlighting/syntax/</filename
> nella tua cartella utente, e vengono trovati con <userinput
><command
>qtpaths</command
><option
>--paths GenericDataLocation</option
></userinput
>, che generalmente sono <filename class="directory"
><envar
>$HOME</envar
>/.local/share/</filename
> e <filename class="directory"
>/usr/share/</filename
>. </para>
<para
>Per i pacchetti Flatpak e Snap la cartella qui sopra non funzionerà perché la posizione dei dati è diversa per ogni applicazione. In un'applicazione Flatpak la posizione dei file &XML; personalizzati è generalmente <filename class="directory"
><envar
>$HOME</envar
>/.var/app/<replaceable
>nome-del-pacchetto-flatpak</replaceable
>/data/org.kde.syntax-highlighting/syntax/</filename
>, mentre in una Snap la posizione è <filename class="directory"
><envar
>$HOME</envar
>/snap/<replaceable
>snap-package-name</replaceable
>/current/.local/share/org.kde.syntax-highlighting/syntax/</filename
>. </para>
<para
>In &Windows; questi file si trovano in <filename
>%USERPROFILE%\AppData\Local\org.kde.syntax-highlighting\syntax</filename
>. <replaceable
>%USERPROFILE%</replaceable
> viene generalmente espanso in <filename
>C:\Users\<replaceable
>utente</replaceable
></filename
>.</para>
<para
>In sintesi, per la maggior parte delle configurazioni la cartella dei file &XML; personalizzati è la seguente:</para>
<informaltable>
<tgroup cols="2">
<tbody>
<row>
<entry
>Per l'utente locale</entry>
<entry
><filename class="directory"
><envar
>$HOME</envar
>/.local/share/org.kde.syntax-highlighting/syntax/</filename
></entry>
</row>
<row>
<entry
>Per tutti gli utenti</entry>
<entry
><filename class="directory"
>/usr/share/org.kde.syntax-highlighting/syntax/</filename
></entry>
</row>
<row>
<entry
>Per i pacchetti Flatpak</entry>
<entry
><filename class="directory"
><envar
>$HOME</envar
>/.var/app/<replaceable
>nome-pacchetto-flatpak</replaceable
>/data/org.kde.syntax-highlighting/syntax/</filename
></entry>
</row>
<row>
<entry
>Per i pacchetti Snap</entry>
<entry
><filename class="directory"
><envar
>$HOME</envar
>/snap/<replaceable
>nome-pacchetto-snap</replaceable
>/current/.local/share/org.kde.syntax-highlighting/syntax/</filename
></entry>
</row>
<row>
<entry
>In &Windows;</entry>
<entry
><filename
>%USERPROFILE%\AppData\Local\org.kde.syntax-highlighting\syntax</filename
></entry>
</row>
</tbody>
</tgroup>
</informaltable>
<para
>Se esistono più file per lo stesso linguaggio verrà caricato quello che ha il valore più alto dell'attributo <userinput
>version</userinput
> nell'elemento <userinput
>language</userinput
>.</para>
<variablelist>
<title
>Le sezioni principali dei file di definizione dell'evidenziazione di &kappname;</title>
<varlistentry>
<term
>Un file di evidenziazione contiene un'intestazione che imposta la versione &XML;:</term>
<listitem>
<programlisting
><?xml version="1.0" encoding="UTF-8"?>
</programlisting>
</listitem>
</varlistentry>
<varlistentry>
<term
>Il file di definizione inizia con l'elemento <userinput
>language</userinput
>. Gli attributi disponibili sono:</term>
<listitem>
<para
>Attributi richiesti:</para>
<para
><userinput
>name</userinput
> imposta il nome del linguaggio. Appare successivamente nei menu e nelle finestre.</para>
<para
><userinput
>section</userinput
> specifica la categoria.</para>
<para
><userinput
>extensions</userinput
> definisce le estensioni dei file, come "*.cpp;*.h"</para>
<para
><userinput
>version</userinput
> specifica l'attuale revisione del file di definizione in termini di un numero intero; sii certo di incrementare questo numero se cambi un file di definizione dell'evidenziazione.</para>
<para
><userinput
>kateversion</userinput
> specifica l'ultima versione supportata di &kappname;.</para>
<para
>Attributi opzionali:</para>
<para
><userinput
>mimetype</userinput
> associa i tipi &MIME; dei file.</para>
<para
><userinput
>casesensitive</userinput
> definisce se le parole chiave sono sensibili alle maiuscole oppure no.</para>
<para
><userinput
>priority</userinput
> è necessaria se un'altra definizione di evidenziazione usa le stesse estensioni; vince quella con priorità più alta.</para>
<para
><userinput
>author</userinput
> contiene il nome dell'autore e il suo indirizzo di posta elettronica.</para>
<para
><userinput
>license</userinput
> contiene la licenza, di solito MIT, per i nuovi file di evidenziazione della sintassi.</para>
<para
><userinput
>style</userinput
> contiene il linguaggio fornito, ed è usato dai rientratori per gli attributi <literal
>required-syntax-style</literal
>.</para>
<para
><userinput
>rientratore</userinput
> definisce quale rientratore sarà usato come predefinito. Quelli disponibili sono: <emphasis
>ada, normal, cstyle, cmake, haskell, latex, lilypond, lisp, lua, pascal, python, replicode, ruby</emphasis
> e <emphasis
>xml</emphasis
>.</para>
<para
><userinput
>hidden</userinput
> definisce se il nome deve apparire nei menu di &kappname;.</para>
<para
>Allora la prossima riga potrebbe apparire così:</para>
<programlisting
><language name="C++" version="1" kateversion="2.4" section="Sources" extensions="*.cpp;*.h" />
</programlisting>
</listitem>
</varlistentry>
<varlistentry>
<term
>Viene poi l'elemento <userinput
>highlighting</userinput
>, che contiene l'elemento opzionale <userinput
>list</userinput
>, e i richiesti <userinput
>contexts</userinput
> e <userinput
>itemDatas</userinput
>.</term>
<listitem>
<para
>L'elemento <userinput
>list</userinput
> contiene una lista di parole chiave; in questo caso le parole chiave sono <emphasis
>class</emphasis
> e <emphasis
>const</emphasis
>; puoi aggiungere tutte le liste di cui hai bisogno.</para>
<para
>Da &kde-frameworks; 5.53 una lista può includere delle parole chiave di un'altra lista oppure da un'altra lingua (o da un altro file) usando l'elemento <userinput
>include</userinput
>. Viene usato <userinput
>##</userinput
> per separare il nome della lista da quello del linguaggio di definizione del nome, come per il ruolo <userinput
>IncludeRules</userinput
>. Ciò è utile per evitare la duplicazione di liste delle parole se hai bisogno di includere le parole chiave di un altro linguaggio o file. Ad esempio, la lista <emphasis
>othername</emphasis
> contiene la parola chiave <emphasis
>str</emphasis
> e tutte le parole chiave della lista <emphasis
>types</emphasis
> che appartiene al linguaggio <emphasis
>ISO C++</emphasis
>.</para>
<para
>L'elemento <userinput
>contexts</userinput
> contiene tutti i contesti; il primo è di default l'inizio dell'evidenziazione. Ci sono due regole nel contesto <emphasis
>Normal Text</emphasis
>, una associa la lista delle parole chiave con nome <emphasis
>somename</emphasis
>, e un'altra rileva una virgoletta, passando il contesto a <emphasis
>string</emphasis
>. Per saperne di più leggi il prossimo capitolo.</para>
<para
>La terza parte è l'elemento <userinput
>itemDatas</userinput
>: contiene tutti i colori e gli stili dei caratteri che sono necessari per il contesto e per le regole. In questo esempio vengono usati <userinput
>itemData</userinput
> <emphasis
>Normal Text</emphasis
>, <emphasis
>String</emphasis
> e <emphasis
>Keyword</emphasis
>. </para>
<programlisting
><highlighting>
<list name="somename">
<item>class</item>
<item>const</item>
</list>
<list name="othername">
<item>str</item>
<include>types##ISO C++</include>
</list>
<contexts>
<context attribute="Normal Text" lineEndContext="#pop" name="Normal Text" >
<keyword attribute="Keyword" context="#stay" String="somename" />
<keyword attribute="Keyword" context="#stay" String="othername" />
<DetectChar attribute="String" context="string" char="&quot;" />
</context>
<context attribute="String" lineEndContext="#stay" name="string" >
<DetectChar attribute="String" context="#pop" char="&quot;" />
</context>
</contexts>
<itemDatas>
<itemData name="Normal Text" defStyleNum="dsNormal" />
<itemData name="Keyword" defStyleNum="dsKeyword" />
<itemData name="String" defStyleNum="dsString" />
</itemDatas>
</highlighting>
</programlisting>
</listitem>
</varlistentry>
<varlistentry>
<term
>L'ultima parte di una definizione di evidenziazione è la sezione opzionale <userinput
>general</userinput
>. Può contenere informazioni sulle parole chiave, sul raggruppamento del codice, sui commenti, sui rientri, sulle righe vuote e sul controllo ortografico.</term>
<listitem>
<para
>La sezione <userinput
>comment</userinput
> definisce con quale stringa viene introdotta una singola riga di commento. Puoi anche definire un commento multi-riga usando <emphasis
>multiLine</emphasis
> con l'attributo addizionale <emphasis
>end</emphasis
>. Questo viene usato se l'utente preme la scorciatoia per <emphasis
>commentare/non commentare</emphasis
>.</para>
<para
>La sezione <userinput
>keywords</userinput
> definisce se la lista delle parole chiave è sensibile alle maiuscole oppure no. Altri attributi verranno spiegati più tardi.</para>
<para
>Le altre sezioni, <userinput
>folding</userinput
>, <userinput
>emptyLines</userinput
> e <userinput
>spellchecking</userinput
> sono di solito non necessarie e verranno spiegate in seguito.</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
>Le sezioni in dettaglio</title>
<para
>Questa parte descriverà tutti gli attributi disponibili per contexts, itemDatas, keywords, comments, il raggruppamento del codice e i rientri.</para>
<variablelist>
<varlistentry>
<term
>L'elemento <userinput
>context</userinput
> appartiene al gruppo <userinput
>contexts</userinput
>. Di per sé un contesto definisce le regole specifiche del contesto, tipo cosa dovrebbe accadere qualora il sistema di evidenziazione raggiunga il fine riga. Gli attributi disponibili sono:</term>
<listitem>
<para
><userinput
>name</userinput
> dichiara il nome del contesto. Le regole faranno uso di questo nome per specificare il contesto al quale passare se la regola viene soddisfatta.</para>
<para
><userinput
>lineEndContext</userinput
> definisce il contesto a cui il sistema di evidenziazione passa se viene raggiunta la fine della riga. Questo può essere sia il nome di un altro contesto, <userinput
>#stay</userinput
> per non lasciare il contesto (⪚. non fare niente), oppure <userinput
>#pop</userinput
>, che causerà l'abbandono di questo contesto. È possibile usare per esempio <userinput
>#pop#pop#pop</userinput
> per saltare tre volte, o anche <userinput
>#pop#pop!OtherContext</userinput
> per saltare due volte e passare al contesto chiamato <userinput
>OtherContext</userinput
>. È possibile passare anche ad un contesto che appartiene ad un'altra definizione di linguaggio, come in <userinput
>IncludeRules</userinput
>, ⪚ <userinput
>SomeContext##JavaScript</userinput
>. Nota che non è possibile usare questo cambio di contesto in combinazione con <userinput
>#pop</userinput
>, ad esempio <userinput
>#pop!SomeContext##JavaScript</userinput
> non è valido. I cambi di contesto sono descritti anche in <xref linkend="kate-highlight-rules-detailled"/>.</para>
<para
><userinput
>lineEmptyContext</userinput
> definisce il contesto se viene incontrata una riga vuota. Predefinito: #stay. La nomeclatura dei cambi di contesto è la stessa che è stata precedentemente descritta in <emphasis
>lineEndContext</emphasis
>. Predefinito: #stay.</para>
<para
><userinput
>fallthroughContext</userinput
> specifica il contesto successivo a cui passare se nessuna regola viene soddisfatta. La nomenclatura dei cambi di contesto è la stessa che era stata descritta in precedenza in <emphasis
>lineEndContext</emphasis
>. Predefinito: #stay.</para>
<para
><userinput
>fallthrough</userinput
> definisce se il sistema di evidenziazione passa al contesto specificato in <userinput
>fallthroughContext</userinput
> se non viene soddisfatta nessuna regola. Note che da &kde; &frameworks; 5.62 questo attributo è deprecato in favore di <userinput
>fallthroughContext</userinput
>, dal momento che se l'attributo <userinput
>fallthroughContext</userinput
> è presente, è implicitamente inteso che il valore di <userinput
>fallthrough</userinput
> è <emphasis
>true</emphasis
>. Predefinito: <emphasis
>false</emphasis
>.</para>
<para
><userinput
>noIndentationBasedFolding</userinput
> disabilita il raggruppamento basato sui rientri nel contesto. Se il raggruppamento basato sui rientri non è attivato questo attributo è inutile. Esso è definito nell'elemento <emphasis
>folding</emphasis
> del gruppo <emphasis
>general</emphasis
>. Predefinito: <emphasis
>falso</emphasis
>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term
>L'elemento <userinput
>itemData</userinput
> appartiene al gruppo <userinput
>itemDatas</userinput
>. Definisce lo stile del carattere e i colori, e quindi è possibile definire i propri stili e i propri colori. Raccomandiamo però di attenersi agli stili predefiniti, se possibile, cosicché gli utenti vedranno sempre gli stessi colori anche in linguaggi diversi. Tuttavia a volte non c'è altro modo se non quello di cambiare i colori e gli attributi dei caratteri. Sono richiesti il nome degli attributi e StileNumDef, ma gli altri sono opzionali. Gli attributi disponibili sono:</term>
<listitem>
<para
><userinput
>name</userinput
> imposta il nome di itemData. I contesti e le regole useranno questo nome nei loro attributi <emphasis
>attribute</emphasis
> a cui fa riferimento itemData.</para>
<para
><userinput
>defStyleNum</userinput
> definisce quale stile predefinito usare. Gli stili predefiniti disponibili sono spiegati in dettaglio più tardi.</para>
<para
><userinput
>color</userinput
> definisce un colore. Sono validi i formati «#rrggbb» o «#rgb».</para>
<para
><userinput
>selColor</userinput
> definisce la selezione del colore.</para>
<para
>Il testo sarà in corsivo se <userinput
>italic</userinput
> è <emphasis
>true</emphasis
>.</para>
<para
>Il testo sarà in grassetto se <userinput
>bold</userinput
> è <emphasis
>true</emphasis
>.</para>
<para
>Il testo sarà sottolineato se <userinput
>underline</userinput
> è <emphasis
>true</emphasis
>.</para>
<para
>Il testo sarà in barrato se <userinput
>strikeout</userinput
> è <emphasis
>true</emphasis
>.</para>
<para
>Il testo sarà controllato ortograficamente se <userinput
>spellChecking</userinput
> è <emphasis
>true</emphasis
>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term
>L'elemento <userinput
>keywords</userinput
> del gruppo <userinput
>general</userinput
> definisce le proprietà delle parole chiave. Gli attributi disponibili sono:</term>
<listitem>
<para
><userinput
>casesensitive</userinput
> può essere <emphasis
>true</emphasis
> oppure <emphasis
>false</emphasis
>; se è <emphasis
>true</emphasis
> tutte le parole chiave soddisfano la sensibilità alle maiuscole.</para>
<para
><userinput
>weakDeliminator</userinput
> è una lista di caratteri che non agiscono da delimitatori di parole; per esempio, il punto <userinput
>«.»</userinput
> è un delimitatore di parola. Se assumiamo che una parola chiave in una <userinput
>lista</userinput
> possa contenere un punto, sarà soddisfatta solo se specifichi che il punto è un delimitatore debole.</para>
<para
><userinput
>additionalDeliminator</userinput
> definisce delimitatori addizionali.</para>
<para
><userinput
>wordWrapDeliminator</userinput
> definisce i caratteri dopo dei quali una riga può andare a capo.</para>
<para
>Sono delimitatori predefiniti e terminatori di parola i caratteri <userinput
>.():!+,-<=>%&*/;?[]^{|}~\</userinput
>, gli spazi (<userinput
>« »</userinput
>) e i tabulatori (<userinput
>«\t»</userinput
>).</para>
</listitem>
</varlistentry>
<varlistentry>
<term
>L'elemento <userinput
>comment</userinput
> del gruppo <userinput
>comments</userinput
> definisce le proprietà che sono usate in <menuchoice
><guimenu
>Strumenti</guimenu
><guimenuitem
>Commenta</guimenuitem
></menuchoice
>, <menuchoice
><guimenu
>Strumenti</guimenu
><guimenuitem
>Decommenta</guimenuitem
></menuchoice
> e <menuchoice
><guimenu
>Strumenti</guimenu
><guimenuitem
>Commenta/decommenta</guimenuitem
></menuchoice
>. Gli attributi disponibili sono:</term>
<listitem>
<para
><userinput
>name</userinput
> può essere <emphasis
>singleLine</emphasis
> o <emphasis
>multiLine</emphasis
>. Se scegli <emphasis
>multiLine</emphasis
> sono richiesti gli attributi <emphasis
>end</emphasis
> e <emphasis
>region</emphasis
>. Se scegli <emphasis
>singleLine</emphasis
> puoi aggiungere l'attributo facoltativo <emphasis
>position</emphasis
>.</para>
<para
><userinput
>start</userinput
> definisce la stringa usata per iniziare un commento. In C++ sarebbe "/*" nei commenti multi-riga. Questo attributo è richiesto per i tipi <emphasis
>multiLine</emphasis
> e <emphasis
>singleLine</emphasis
>.</para>
<para
><userinput
>end</userinput
> definisce la stringa per chiudere un commento. In C++ questo sarebbe "*/". Questo attributo è solo disponibile ed è richiesto per i commenti di tipo <emphasis
>multiLine</emphasis
>.</para>
<para
><userinput
>region</userinput
> dovrebbe essere il nome dei commenti multi-riga raggruppabili. Assumendo di avere nelle regole <emphasis
>beginRegion="Comment"</emphasis
> ... <emphasis
>endRegion="Comment"</emphasis
> si dovrebbe usare <emphasis
>region="Comment"</emphasis
>. In questo modo l'azione di decommento funziona anche se non viene selezionato tutto il testo di un commento multi-riga, il cursore deve solo essere all'interno del commento. Questo attributo è disponibile solo per il tipo <emphasis
>multiLine</emphasis
>.</para>
<para
><userinput
>position</userinput
> definisce dove vengono inseriti i commenti di una sola riga. Per impostazione predefinita essi sono posizionati all'inizio della riga, alla colonna 0, ma se utilizzi <emphasis
>position="afterwhitespace"</emphasis
> il commento viene inserito dopo i primi spazi sulla destra, prima del primo carattere non di spaziatura. Ciò è utile per inserire correttamente i commenti nei linguaggi in cui il rientro è importante, ad esempio Python o YAML. Questo attributo è facoltativo, e l'unico valore possibile è <emphasis
>afterwhitespace</emphasis
>. È disponibile solo per il tipo <emphasis
>singleLine</emphasis
>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term
>L'elemento <userinput
>raggruppamento</userinput
> del gruppo <userinput
>general</userinput
> definisce le proprietà di raggruppamento del codice. Gli attributi disponibili sono:</term>
<listitem>
<para
>Se <userinput
>indentationsensitive</userinput
> è <emphasis
>true</emphasis
> i marcatori del raggruppamento del codice saranno aggiunti basandosi sul rientro, come nel linguaggio di scripting Python. Di solito non hai necessità di impostarlo, e di solito è impostato a <emphasis
>false</emphasis
>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term
>L'elemento <userinput
>emptyLine</userinput
> nel gruppo <userinput
>emptyLines</userinput
> definisce quali righe dovrebbero essere trattate come vuote. Ciò permette di modificare il comportamento dell'attributo <emphasis
>lineEmptyContext</emphasis
> negli elementi <userinput
>context</userinput
>. Gli attributi disponibili sono:</term>
<listitem>
<para
><userinput
>regexpr</userinput
> definisce un'espressione regolare che verrà trattata come una riga vuota. Per impostazione predefinita le righe vuote non contengono nessun carattere, perciò esso aggiunge delle altre righe vuote, ad esempio se vuoi considerare come vuote anche le righe con gli spazi. Ad ogni modo, nella maggior parte delle definizioni di sintassi non è necessario impostare questo attributo.</para>
</listitem>
</varlistentry>
<varlistentry>
<term
>L'elemento <userinput
>encoding</userinput
> del gruppo <userinput
>spellchecking</userinput
> definisce una codifica dei caratteri per il controllo ortografico. Gli attributi disponibili sono:</term>
<listitem>
<para
><userinput
>char</userinput
> è un carattere codificato.</para>
<para
><userinput
>string</userinput
> è una sequenza di caratteri che verrà codificata come il carattere<emphasis
>char</emphasis
> nel controllo ortografico. Ad esempio, nel linguaggio LaTex la stringa <userinput
>\"{A}</userinput
> rappresenta il carattere <userinput
>Ä</userinput
>.</para>
</listitem>
</varlistentry>
</variablelist>
</sect3>
<sect3 id="kate-highlight-default-styles">
<title
>Stili predefiniti disponibili</title>
<para
>Gli stili predefiniti sono stati <link linkend="kate-highlight-system-default-styles"
>già trattati</link
>, come piccolo riassunto: gli stili predefiniti sono i caratteri predefiniti e gli stili colore.</para>
<variablelist>
<varlistentry>
<term
>Stili generali predefiniti:</term>
<listitem>
<para
><userinput
>dsNormal</userinput
>, quando non è richiesta nessuna evidenziazione speciale.</para>
<para
><userinput
>dsKeyword</userinput
>, parola chiave integrata nel linguaggio.</para>
<para
><userinput
>dsFunction</userinput
>, chiamate di funzioni e definizioni.</para>
<para
><userinput
>dsVariabile</userinput
>, se applicabile: nomi delle variabili (⪚ $someVar in PHP/Perl).</para>
<para
><userinput
>dsControlFlow</userinput
>, parole chiave per il controllo del flusso, come if, else, switch, break, return, yield, ...</para>
<para
><userinput
>dsOperator</userinput
>, operatori come + - * / :: < ></para>
<para
><userinput
>dsBuiltIn</userinput
>, funzioni integrate, classi e oggetti.</para>
<para
><userinput
>dsExtension</userinput
>, estensioni comuni, come le classi &Qt; e le funzioni o le macro in C++ e in Python.</para>
<para
><userinput
>dsPreprocessor</userinput
>, direttive al preprocessore o definizioni di macro.</para>
<para
><userinput
>dsAttribute</userinput
>, annotazioni come @override e __declspec(...).</para>
</listitem>
</varlistentry>
<varlistentry>
<term
>Stili predefiniti relativi alle stringhe:</term>
<listitem>
<para
><userinput
>dsChar</userinput
>, caratteri singoli, come 'x'.</para>
<para
><userinput
>dsSpecialChar</userinput
>, caratteri con significati speciali nelle stringhe, come escape, sostituzioni, oppure operatori regex.</para>
<para
><userinput
>dsString</userinput
>, stringhe come "hello world".</para>
<para
><userinput
>dsVerbatimString</userinput
>, letterale o stringa grezza, come 'raw \backlash' in Perl, CoffeeScript, e shell, come r'\raw' in Python.</para>
<para
><userinput
>dsSpecialString</userinput
>, SQL, regexes, documenti HERE, modi &latex; math, ...</para>
<para
><userinput
>dsImport</userinput
>, importazione, inclusione, richieste di moduli.</para>
</listitem>
</varlistentry>
<varlistentry>
<term
>Stili predefiniti relativi ai numeri:</term>
<listitem>
<para
><userinput
>dsDataType</userinput
>, tipi di dati integrati, come int, void, u64.</para>
<para
><userinput
>dsDecVal</userinput
>, valori decimali.</para>
<para
><userinput
>dsBaseN</userinput
>, valori con base diversa da 10.</para>
<para
><userinput
>dsFloat</userinput
>, valori in virgola mobile.</para>
<para
><userinput
>dsCostant</userinput
>, costanti integrate e definite dall'utente, come PI.</para>
</listitem>
</varlistentry>
<varlistentry>
<term
>Commenti e stili predefiniti relativi alla documentazione:</term>
<listitem>
<para
><userinput
>dsComment</userinput
>, commenti.</para>
<para
><userinput
>dsDocumentation</userinput
>, /** Commenti nella documentazione */ o """docstrings""".</para>
<para
><userinput
>dsAnnotation</userinput
>, comandi nella documentazione, come @param, @brief.</para>
<para
><userinput
>dsCommentVar</userinput
>, i nomi delle variabili usati nei comandi precedenti, come "pippobar" in @param pippobar.</para>
<para
><userinput
>dsRegionMarker</userinput
>, delimitatori di regioni, come //BEGIN e //END nei commenti.</para>
</listitem>
</varlistentry>
<varlistentry>
<term
>Altri stili predefiniti:</term>
<listitem>
<para
><userinput
>dsInformation</userinput
>, annotazioni e suggerimenti, come @note in doxygen.</para>
<para
><userinput
>dsWarning</userinput
>, avvisi, come @warning in doxygen.</para>
<para
><userinput
>dsAlert</userinput
>, parole speciali, come TODO, FIXME, XXXX.</para>
<para
><userinput
>dsError</userinput
>, evidenziazione di errori e sintassi errata.</para>
<para
><userinput
>dsOthers</userinput
> per tutto il resto.</para>
</listitem>
</varlistentry>
</variablelist>
</sect3>
</sect2>
<sect2 id="kate-highlight-rules-detailled">
<title
>Regole di rilevamento dell'evidenziazione</title>
<para
>Questa sezione descrive le regole di rilevamento della sintassi.</para>
<para
>Ogni regola può associare zero o più caratteri all'inizio della stringa su cui è testata. Se la regola corrisponde i caratteri associati sono assegnati allo stile o all'<emphasis
>attributo</emphasis
> definito dalla regola; una regola può chiedere che l'attuale contesto venga cambiato.</para>
<para
>Una regola è un qualcosa che assomiglia a questo:</para>
<programlisting
><RuleName attribute="(identifier)" context="(identifier)" [attributi specifici della regola] /></programlisting>
<para
><emphasis
>attribute</emphasis
> identifica lo stile da usare per i caratteri associati secondo il nome, mentre <emphasis
>context</emphasis
> identifica il contesto da usare da qui in avanti.</para>
<para
><emphasis
>context</emphasis
> può essere identificato da:</para>
<itemizedlist>
<listitem>
<para
><emphasis
>identifier</emphasis
>, che è il nome dell'altro contesto.</para>
</listitem>
<listitem>
<para
><emphasis
>order</emphasis
>, che dice al motore di rimanere nel contesto attuale (<userinput
>#stay</userinput
>), oppure di ritornare a quello precedentemente usato nella stringa (<userinput
>#pop</userinput
>).</para>
<para
>Per tornare indietro di più passi la parola chiave #pop può essere ripetuta: <userinput
>#pop#pop#pop</userinput
></para>
</listitem>
<listitem>
<para
><emphasis
>order</emphasis
> seguito da un punto esclamativo (<emphasis
>!</emphasis
>) e <emphasis
>identifier</emphasis
>, che faranno prima seguire al motore l'ordine, e poi lo mandano in un altro contesto, ⪚ <userinput
>#pop#pop!OtherContext</userinput
>.</para>
</listitem>
<listitem>
<para
>Un identificatore, che è un nome di contesto, seguito da due cancelletti (<userinput
>##</userinput
>) e da un altro <emphasis
>identificatore</emphasis
>, cioè dal nome di una definizione di linguaggio. Questa denominazione è simile a quella usata nelle regole <userinput
>IncludeRules</userinput
>, e ti permette di passare ad un contesto appartenente ad un'altra definizione di evidenziazione della sintassi, ad esempio <userinput
>SomeContext##JavaScript</userinput
>. Nota che non è possibile usare questo cambio di contesto in combinazione con <userinput
>#pop</userinput
>, ad esempio <userinput
>#pop!SomeContext##JavaScript</userinput
> non è valido.</para>
</listitem>
</itemizedlist>
<para
>Gli attributi specifici per la regola variano, e sono descritti nelle sezioni seguenti.</para>
<itemizedlist>
<title
>Attributi comuni</title>
<para
>Tutte le regole hanno in comune i seguenti attributi, e sono disponibili ogni volta che compare <userinput
>(attributi comuni)</userinput
>. Sono attributi richiesti <emphasis
>attribute</emphasis
> e <emphasis
>context</emphasis
>, tutti gli altri sono opzionali. </para>
<listitem>
<para
><emphasis
>attribute</emphasis
>: un attributo associato ad un determinato <emphasis
>itemData</emphasis
>.</para>
</listitem>
<listitem>
<para
><emphasis
>context</emphasis
>: specifica il contesto al quale il sistema di evidenziazione passa se la regola corrisponde.</para>
</listitem>
<listitem>
<para
><emphasis
>beginRegion</emphasis
>: inizia un blocco di raggruppamento del codice. Predefinito: non impostato.</para>
</listitem>
<listitem>
<para
><emphasis
>endRegion</emphasis
>: chiude un un blocco di raggruppamento del codice. Predefinito: non impostato.</para>
</listitem>
<listitem>
<para
><emphasis
>lookAhead</emphasis
>: se impostato a <emphasis
>true</emphasis
> il sistema di evidenziazione non processerà la lunghezza assegnata. Predefinito: <emphasis
>false</emphasis
>.</para>
</listitem>
<listitem>
<para
><emphasis
>firstNonSpace</emphasis
>: corrisponde solo se la stringa è la prima senza spazi nella riga. Predefinito: <emphasis
>false</emphasis
>.</para>
</listitem>
<listitem>
<para
><emphasis
>column</emphasis
>: corrisponde solo se la colonna combacia. Predefinito: non impostato.</para>
</listitem>
</itemizedlist>
<itemizedlist>
<title
>Regole dinamiche</title>
<para
>Alcune regole permettono di usare l'attributo opzionale <userinput
>dynamic</userinput
> di tipo booleano il cui valore predefinito è <emphasis
>false</emphasis
>. Se dynamic è <emphasis
>true</emphasis
>, una regola può usare un segnaposto che rappresenta le corrispondenze di una regola di tipo <emphasis
>espressione regolare</emphasis
> che è passata al contesto corretto nei proprio attributi <userinput
>string</userinput
> o <userinput
>char</userinput
>. Nel caso di <userinput
>string</userinput
> il segnaposto <replaceable
>%N</replaceable
> (dove N è un numero) sarà sostituito con la corrispondente stringa di cattura <replaceable
>N</replaceable
> dall'espressione regolare chiamante, a partire da 1. Nel caso di <userinput
>char</userinput
> il segnaposto deve essere un numero <replaceable
>N</replaceable
> e sarà sostituito con il primo carattere della corrispondente stringa di cattura <replaceable
>N</replaceable
> dall'espressione regolare chiamante. Quando una regola permette l'uso di questo attributo conterrà <emphasis
>(dynamic)</emphasis
>.</para>
<listitem>
<para
><emphasis
>dynamic</emphasis
>: può essere <emphasis
>(true|false)</emphasis
>.</para>
</listitem>
</itemizedlist>
<para
><userinput
>Come funziona:</userinput
></para>
<para
>Nelle <link linkend="regular-expressions"
>espressioni regolari</link
> delle regole <userinput
>RegExpr</userinput
>, tutto il testo all'interno delle parentesi curve semplici <userinput
>(MODELLO)</userinput
> viene catturato e ricordato. Queste catture possono essere usate nel contesto nel quale ci si è spostati, nelle regole con l'attributo <userinput
>dynamic</userinput
> <emphasis
>vero</emphasis
>, da <replaceable
>%N</replaceable
> (in <emphasis
>String</emphasis
>) oppure <replaceable
>N</replaceable
> (in <emphasis
>char</emphasis
>).</para>
<para
>È importante ricordare che il testo catturato in una regola <userinput
>RegExpr</userinput
> viene memorizzato solo per il contesto nel quale si è passati, specificato nel suo attributo <userinput
>context</userinput
>.</para>
<tip>
<itemizedlist>
<listitem>
<para
>Se le catture non vengono usate, nelle regole dinamiche o nell'espressione regolare stessa, si dovrebbe usare <userinput
>gruppi non di cattura</userinput
>: <userinput
>(?:MODELLO)</userinput
></para>
<para
>I gruppi <emphasis
>lookahead</emphasis
> o <emphasis
>lookbehind</emphasis
> come <userinput
>(?=MODELLO)</userinput
> o <userinput
>(?!MODELLO)</userinput
> non vengono catturati. Vedi <link linkend="regular-expressions"
>espressioni regolari</link
> per maggiori informazioni.</para>
</listitem>
<listitem>
<para
>I gruppi di cattura possono essere usati all'interno dell'espressione regolare stessa, utilizzando rispettivamente <replaceable
>\N</replaceable
> al posto di <replaceable
>%N</replaceable
>. Per maggiori informazioni, vedi <link linkend="regex-capturing"
>catturare il testo corrispondente (riferimenti all'indietro)</link
> nelle <link linkend="regular-expressions"
>espressioni regolari</link
>.</para>
</listitem>
</itemizedlist>
</tip>
<para
>Esempio 1:</para>
<para
>In questo semplice esempio il testo corrispondente all'espressione regolare <userinput
>=*</userinput
> viene catturato ed inserito in <replaceable
>%1</replaceable
> nella regola dinamica. Ciò permette al commento di terminare con la stessa quantità di <userinput
>=</userinput
> che ha all'inizio. Questo associa del testo tipo: <userinput
>[[ commento ]]</userinput
>, <userinput
>[=[ commento ]=]</userinput
> oppure <userinput
>[=====[ commento ]=====]</userinput
>.</para>
<para
>Inoltre le catture sono disponibili solo nel contesto cambiato <emphasis
>Multi-line Comment</emphasis
>.</para>
<programlisting
><context name="Normal" attribute="Normal Text" lineEndContext="#stay">
<RegExpr context="Multi-line Comment" attribute="Comment" String="\[(=*)\[" beginRegion="RegionComment"/>
</context>
<context name="Multi-line Comment" attribute="Comment" lineEndContext="#stay">
<StringDetect context="#pop" attribute="Comment" String="]%1]" dynamic="true" endRegion="RegionComment"/>
</context>
</programlisting>
<para
>Esempio 2:</para>
<para
>Nella regola dinamica, <replaceable
>%1</replaceable
> corrisponde alle catture che associano <userinput
>#+</userinput
>, e <replaceable
>%2</replaceable
> a <userinput
>&quot;+</userinput
>. Ciò associa del testo come: <userinput
>#label""""dentro al contesto""""#</userinput
>.</para>
<para
>Queste catture non saranno disponibili in altri contesti, tipo <emphasis
>OtherContext</emphasis
>, <emphasis
>FindEscapes</emphasis
> oppure <emphasis
>SomeContext</emphasis
>.</para>
<programlisting
><context name="SomeContext" attribute="Normal Text" lineEndContext="#stay">
<RegExpr context="#pop!NamedString" attribute="String" String="(#+)(?:[\w-]|[^[:ascii:]])(&quot;+)"/>
</context>
<context name="NamedString" attribute="String" lineEndContext="#stay">
<RegExpr context="#pop!OtherContext" attribute="String" String="%2(?:%1)?" dynamic="true"/>
<DetectChar context="FindEscapes" attribute="Escape" char="\"/>
</context>
</programlisting>
<para
>Esempio 3:</para>
<para
>Questo corrisponde a testo come: <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
>Delimitatori locali</title>
<para
>Alcune regole permettono gli attributi opzionali <userinput
>weakDeliminator</userinput
> e <userinput
>additionalDeliminator</userinput
>, che sono combinati con attributi con lo stesso nome delle etichette <userinput
>keywords</userinput
>. Ad esempio, se <userinput
>«%»</userinput
> è un delimitatore debole di <userinput
>keywords</userinput
>, esso può essere un delimitatore di parole solo con una regola al cui interno sia stato inserito il suo attributo <userinput
>additionalDeliminator</userinput
>. Se una regola permette questi attributi, essa conterrà un <emphasis
>(deliminatori locali)</emphasis
>.</para>
<listitem>
<para
><emphasis
>weakDeliminator</emphasis
>: elenco di caratteri che non agiscono come delimitatori di parole.</para>
</listitem>
<listitem>
<para
><emphasis
>additionalDeliminator</emphasis
>: definisce dei delimitatori addizionali.</para>
</listitem>
</itemizedlist>
<sect3 id="highlighting-rules-in-detail">
<title
>Le regole in dettaglio</title>
<variablelist>
<varlistentry>
<term
>DetectChar</term>
<listitem>
<para
>Rileva un singolo carattere specifico. Usato comunemente per trovare ad esempio la fine di una stringa tra virgolette.</para>
<programlisting
><DetectChar char="(carattere)" (attributi comuni) (dynamic) /></programlisting>
<para
>L'attributo <userinput
>char</userinput
> definisce il carattere da abbinare.</para>
</listitem>
</varlistentry>
<varlistentry>
<term
>Detect2Chars</term>
<listitem>
<para
>Rileva due caratteri specifici in un ordine definito.</para>
<programlisting
><Detect2Chars char="(carattere)" char1="(carattere)" (attributi comuni) /></programlisting>
<para
>L'attributo <userinput
>char</userinput
> definisce il primo carattere da associare, <userinput
>char1</userinput
> il secondo.</para>
</listitem>
</varlistentry>
<varlistentry>
<term
>AnyChar</term>
<listitem>
<para
>Rileva un carattere da un insieme di caratteri specificati.</para>
<programlisting
><AnyChar String="(stringa)" (attributi comuni) /></programlisting>
<para
>L'attributo <userinput
>String</userinput
> definisce l'insieme dei caratteri.</para>
</listitem>
</varlistentry>
<varlistentry>
<term
>StringDetect</term>
<listitem>
<para
>Rileva una stringa esatta.</para>
<programlisting
><StringDetect String="(stringa)" [insensitive="true|false"] (attributi comuni) (dynamic) /></programlisting>
<para
>L'attributo <userinput
>String</userinput
> definisce la stringa da abbinare. All'attributo <userinput
>insensitive</userinput
> viene assegnato come valore predefinito <emphasis
>false</emphasis
>, e viene passato alla funzione di confronto della stringa. Se il valore è <emphasis
>true</emphasis
> allora nel confronto non si terrebbe conto delle maiuscole.</para>
</listitem>
</varlistentry>
<varlistentry>
<term
>WordDetect</term>
<listitem>
<para
>Non rileva una stringa esatta, ma i confini di una parola quali un punto <userinput
>'.'</userinput
> o uno spazio all'inizio o alla fine della parola. Pensa <userinput
>\b<string>\b</userinput
> come un'espressione regolare, ma più veloce della regola <userinput
>RegExpr</userinput
>.</para>
<programlisting
><WordDetect String="(stringa)" [insensitive="true|false"] (attributi comuni) (deliminatori locali) /></programlisting>
<para
>L'attributo <userinput
>String</userinput
> definisce la stringa da abbinare. All'attributo <userinput
>insensitive</userinput
> viene assegnato come valore predefinito <emphasis
>false</emphasis
>, e viene passato alla funzione di confronto della stringa. Se il valore è <emphasis
>true</emphasis
> allora nel confronto non si terrebbe conto delle maiuscole.</para>
<para
>Da: &kate; 3.5 (&kde; 4.5)</para>
</listitem>
</varlistentry>
<varlistentry>
<term
>RegExpr</term>
<listitem>
<para
>Corrisponde con un'espressione regolare.</para>
<programlisting
><RegExpr String="(stringa)" [insensitive="true|false"] [minimal="true|false"] (attributi comuni) (dynamic) /></programlisting>
<para
>L'attributo <userinput
>String</userinput
> definisce l'espressione regolare.</para>
<para
><userinput
>insensitive</userinput
> ha come valore predefinito <emphasis
>false</emphasis
>, e viene passato al motore per le espressioni regolari.</para>
<para
><userinput
>minimal</userinput
> ha come valore predefinito <emphasis
>false</emphasis
>, e viene passato al motore per le espressioni regolari.</para>
<para
>Le regole sono sempre confrontate con l'inizio della stringa corrente, tuttavia un'espressione regolare iniziante con un apice (<literal
>^</literal
>) è segno che la regola dovrebbe essere confrontata invece con l'inizio di una riga.</para>
<para
>Vedi <link linkend="regular-expressions"
>Espressioni regolari</link
> per maggiori informazioni.</para>
</listitem>
</varlistentry>
<varlistentry>
<term
>keyword</term>
<listitem>
<para
>Rileva una parola chiava da una lista specifica.</para>
<programlisting
><keyword String="(nome lista)" (attributi comuni) (deliminatori locali) /></programlisting>
<para
>L'attributo <userinput
>String</userinput
> identifica la lista di parole chiave per nome. Deve esistere una lista con questo nome.</para>
<para
>Il sistema di evidenziazione elabora regole di parole chiave in maniera molto ottimizzata. Questo rende assolutamente necessario che ogni parola chiave da confrontare sia circondata da delimitatori definiti, sia impliciti (i delimitatori predefiniti) che espliciti, specificati dalla proprietà <emphasis
>additionalDeliminator</emphasis
> con l'etichetta <emphasis
>keywords</emphasis
>.</para>
<para
>Se una parola chiave da confrontare dovesse contenere un carattere di delimitazione, allora questo dovrebbe essere aggiunto alla proprietà <emphasis
>weakDeliminator</emphasis
> con l'etichetta <emphasis
>keywords</emphasis
>. Questo carattere perderebbe le sue proprietà di delimitatore in tutte le regole <emphasis
>keywords</emphasis
>. È possibile anche usare l'attributo <emphasis
>weakDeliminator</emphasis
> di <emphasis
>keyword</emphasis
> in modo da applicare questa modifica solo a questa regola.</para>
</listitem>
</varlistentry>
<varlistentry>
<term
>Int</term>
<listitem>
<para
>Rileva un numero intero (come nell'espressione regolare <userinput
>\b[0-9]+</userinput
>).</para>
<para
><programlisting
><Int (attributi comuni) (deliminatori locali) /></programlisting
></para>
<para
>Questa regola non ha attributi specifici.</para>
</listitem>
</varlistentry>
<varlistentry>
<term
>Float</term>
<listitem>
<para
>Rileva un numero in virgola mobile (come nell'espressione regolare <userinput
>(\b[0-9]+\.[0-9]*|\.[0-9]+)([eE][-+]?[0-9]+)?</userinput
>).</para>
<para
><programlisting
><Float (attributi comuni) (deliminatori locali) /></programlisting
></para>
<para
>Questa regola non ha attributi specifici.</para>
</listitem>
</varlistentry>
<varlistentry>
<term
>HlCOct</term>
<listitem>
<para
>Rileva un numero rappresentato in ottale (come nell'espressione regolare <userinput
>\b0[0-7]+</userinput
>).</para>
<para
><programlisting
><HlCOct (attributi comuni) (deliminatori locali) /></programlisting
></para>
<para
>Questa regola non ha attributi specifici.</para>
</listitem>
</varlistentry>
<varlistentry>
<term
>HlCHex</term>
<listitem>
<para
>Rileva un numero rappresentato in esadecimale (come nell'espressione regolare <userinput
>\b0[xX][0-9a-fA-F]+</userinput
>).</para>
<para
><programlisting
><HlCHex (attributi comuni) (deliminatori locali) /></programlisting
></para>
<para
>Questa regola non ha attributi specifici.</para>
</listitem>
</varlistentry>
<varlistentry>
<term
>HlCStringChar</term>
<listitem>
<para
>Rileva un carattere di escape.</para>
<para
><programlisting
><HlCStringChar (attributi comuni) /></programlisting
></para>
<para
>Questa regola non ha attributi specifici.</para>
<para
>Controlla la corrispondenza di espressioni letterali di caratteri generalmente usate nel codice dei programmi, per esempio <userinput
>\n</userinput
> (nuova riga) o <userinput
>\t</userinput
> (TAB).</para>
<para
>I seguenti caratteri corrisponderanno se saranno seguiti da una barra inversa (<literal
>\</literal
>): <userinput
>abefnrtv"'?\</userinput
>. Inoltre corrisponderanno numeri esadecimali preceduti dal carattere di escape, come per esempio <userinput
>\xff</userinput
> e numeri ottali preceduti dal carattere di escape, per esempio <userinput
>\033</userinput
>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term
>HlCChar</term>
<listitem>
<para
>Rileva il carattere C</para>
<para
><programlisting
><HlCChar (attributi comuni) /></programlisting
></para>
<para
>Questa regola non ha attributi specifici.</para>
<para
>Controlla la corrispondenza di caratteri C racchiusi da un accento (Esempio: <userinput
>'c'</userinput
>). Gli accenti possono essere caratteri singoli o caratteri di escape. Vedi HlCStringChar per le sequenze di caratteri di escape associate.</para>
</listitem>
</varlistentry>
<varlistentry>
<term
>RangeDetect</term>
<listitem>
<para
>Rileva una stringa con caratteri di inizio e di fine definiti.</para>
<programlisting
><RangeDetect char="(carattere)" char1="(carattere)" (attributi comuni) /></programlisting>
<para
><userinput
>char</userinput
> definisce il carattere con cui inizia l'intervallo, <userinput
>char1</userinput
> il carattere con cui finisce.</para>
<para
>Utile per individuare per esempio piccole stringhe tra virgolette e simili; nota però che non verranno in questo modo trovate le stringhe che si estendono dopo un'interruzione di riga. Questo perché il motore di evidenziazione lavora su una riga alla volta.</para>
</listitem>
</varlistentry>
<varlistentry>
<term
>LineContinue</term>
<listitem>
<para
>Associa un carattere specificato con la fine di una riga.</para>
<programlisting
><LineContinue (attributi comuni) [char="\"] /></programlisting>
<para
><userinput
>char</userinput
> carattere opzionale da associare; come predefinito c'è la barra inversa (<userinput
>'\'</userinput
>). Novità da &kde; 4.13.</para>
<para
>Questa regola è utile per cambiare il contesto alla fine di una riga. È necessaria per esempio in C/C++, per continuare le macro o le stringhe.</para>
</listitem>
</varlistentry>
<varlistentry>
<term
>IncludeRules</term>
<listitem>
<para
>Include delle regole da un altro file di contesto o da un linguaggio.</para>
<programlisting
><IncludeRules context="contextlink" [includeAttrib="true|false"] /></programlisting>
<para
>L'attributo <userinput
>context</userinput
> definisce quale contesto includere.</para>
<para
>Se è una stringa semplice include tutte le regole nel contesto corrente, per esempio: <programlisting
><IncludeRules context="altroContesto" /></programlisting
></para>
<para
>Se la stringa contiene <userinput
>##</userinput
> il sistema di evidenziazione cercherà un contesto in un altra definizione di linguaggio con il nome assegnato, per esempio <programlisting
><IncludeRules context="String##C++" /></programlisting
> dovrebbe includere il contesto <emphasis
>String</emphasis
> dalle definizioni di evidenziazione del <emphasis
>C++</emphasis
>.</para>
<para
>Se l'attributo <userinput
>includeAttrib</userinput
> è <emphasis
>true</emphasis
> cambia l'attributo di destinazione con uno del sorgente. Questo è richiesto per esempio per fare dei commenti, se il testo associato al contesto incluso ha una diversa evidenziazione dal contesto che lo ospita. </para>
</listitem>
</varlistentry>
<varlistentry>
<term
>DetectSpaces</term>
<listitem>
<para
>Rileva gli spazi.</para>
<programlisting
><DetectSpaces (attributi comuni) /></programlisting>
<para
>Questa regola non ha attributi specifici.</para>
<para
>Usa questa regola quando sai che potrai incontrare numerosi spazi, per esempio all'inizio di righe rientrate. Questa regola salterà tutti gli spazi in un colpo solo, invece di provare regole multiple da scartarle di volta in volta per mancanza di corrispondenza.</para>
</listitem>
</varlistentry>
<varlistentry>
<term
>DetectIdentifier</term>
<listitem>
<para
>Rileva gli identificatori di stringhe (come un'espressione regolare <userinput
>[a-zA-Z_][a-zA-Z0-9_]*</userinput
>).</para>
<programlisting
><DetectIdentifier (attributi comuni) /></programlisting>
<para
>Questa regola non ha attributi specifici.</para>
<para
>Usa questa regola per saltare subito una stringa di caratteri alfanumerici, invece di usare più regole e saltare i caratteri uno alla volta per mancanza di corrispondenza.</para>
</listitem>
</varlistentry>
</variablelist>
</sect3>
<sect3>
<title
>Suggerimenti e trucchi</title>
<itemizedlist>
<para
>Una volta che hai capito come funziona il passaggio del contesto sarà semplice scrivere definizioni di evidenziazione, anche se dovresti controllare attentamente quale regola scegliere e in quale situazione. Le espressioni regolari sono molto potenti, ma sono lente se comparate con altre regole. Così tieni conto dei suggerimenti seguenti. </para>
<listitem>
<para
>Se cerchi la corrispondenza di solo due caratteri, usa <userinput
>Detect2Chars</userinput
> invece che <userinput
>StringDetect</userinput
>. Lo stesso vale per <userinput
>DetectChar</userinput
>.</para>
</listitem>
<listitem>
<para
>Le espressioni regolari sono semplici da usare, ma spesso c'è un altro modo molto più veloce per ottenere gli stessi risultati. Considera di voler semplicemente cercare la corrispondenza del carattere <userinput
>«#»</userinput
> solo quando è il primo della riga. Una soluzione basata su un'espressione regolare assomiglierebbe a questo: <programlisting
><RegExpr attribute="Macro" context="macro" String="^\s*#" /></programlisting
> Puoi ottenere lo stesso risultato in maniera più veloce usando: <programlisting
><DetectChar attribute="Macro" context="macro" char="#" firstNonSpace="true" /></programlisting
> Se vuoi cercare corrispondenze per l'espressione regolare <userinput
>'^#'</userinput
> puoi sempre usare <userinput
>DetectChar</userinput
> con l'attributo <userinput
>column="0"</userinput
>. L'attributo <userinput
>column</userinput
> conta i caratteri, e un tabulatore è un solo carattere. </para>
</listitem>
<listitem>
<para
>Nelle regole <userinput
>RegExpr</userinput
> usa l'attributo <userinput
>column="0"</userinput
> se il modello <userinput
>^MODELLO</userinput
> verrà utilizzato per trovare il testo all'inizio della riga. Ciò migliora le prestazioni, perché evita di cercare le corrispondenze nel resto delle colonne.</para>
</listitem>
<listitem>
<para
>Nelle espressioni regolari usa i gruppi non di cattura <userinput
>(?:MODELLO)</userinput
> invece dei gruppi di cattura <userinput
>(MODELLO)</userinput
> se le catture non verranno utilizzate nella stessa espressione regolare o nelle regole dinamiche. Ciò evita di salvare delle catture quando non è necessario.</para>
</listitem>
<listitem>
<para
>Puoi cambiare i contesti senza bisogno di elaborare dei caratteri. Se vuoi cambiare contesto quando incontri la stringa <userinput
>*/</userinput
> devi almeno elaborare quella stringa nel contesto del testo. La regola qui sotto corrisponderà, e l'attributo <userinput
>lookAhead</userinput
> farà in modo che l'evidenziatore tenga la stringa corrispondente per il contesto successivo. <programlisting
><Detect2Chars attribute="Comment" context="#pop" char="*" char1="/" lookAhead="true" /></programlisting>
</para>
</listitem>
<listitem>
<para
>Usa <userinput
>DetectSpaces</userinput
> se sai di incontrare molti spazi.</para>
</listitem>
<listitem>
<para
>Usa <userinput
>DetectIdentifier</userinput
> al posto dell'espressione regolare <userinput
>'[a-zA-Z_]\w*'</userinput
>.</para>
</listitem>
<listitem>
<para
>Usa gli stili predefiniti ogni volta che puoi. In questo modo l'utente si troverà in un ambiente familiare.</para>
</listitem>
<listitem>
<para
>Guarda dentro altri file &XML;, per vedere come le altre persone implementano le regole difficili.</para>
</listitem>
<listitem>
<para
>Puoi validare ogni file &XML; usando il comando <command
>validatehl.sh language.xsd mySyntax.xml</command
>. I file <filename
>validatehl.sh</filename
> e <filename
>language.xsd</filename
> si trovano nel <ulink url="https://commits.kde.org/syntax-highlighting?path=data/schema"
>deposito di evidenziazione della sintassi</ulink
>. </para>
</listitem>
<listitem>
<para
>Se ripeti molto spesso delle espressioni regolari complesse puoi usare <emphasis
>ENTITIES</emphasis
>. Esempio:</para>
<programlisting
><?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE language SYSTEM "language.dtd"
[
<!ENTITY myref "[A-Za-z_:][\w.:_-]*">
]>
</programlisting>
<para
>Ora puoi usare <emphasis
>&myref;</emphasis
> invece dell'espressione regolare.</para>
</listitem>
</itemizedlist>
</sect3>
</sect2>
</sect1>
<sect1 id="color-themes">
<title
>Lavorare con i temi di colori</title>
<sect2 id="color-themes-overview">
<title
>Panoramica</title>
<para
>I temi di colori definiscono i colori dell'<link linkend="kate-part"
>area di modifica del testo</link
> e dell'<link linkend="highlight"
>evidenziazione della sintassi</link
>. Un tema di colori comprende quanto segue: <itemizedlist>
<listitem
><para
>Lo stile del testo, usato per l'evidenziazione della sintassi attraverso gli <emphasis
>attributi di stile predefiniti</emphasis
>, ad esempio il colore del testo e di quello del testo selezionato.</para
></listitem>
<listitem
><para
>Lo sfondo dell'area di modifica del testo, inclusa la selezione del testo e della riga corrente.</para
></listitem>
<listitem
><para
>Il bordo dell'icona dell'area del testo: il loro sfondo, la riga di separazione, i numeri di riga, i marcatori di ritorno a capo della riga, i segni per le righe modificate e di raggruppamento del codice.</para
></listitem>
<listitem
><para
>I decoratori di testo, come i marcatori di ricerca e quelli di rientro e di tabulazione o di spazio, la corrispondenza delle parentesi e il correttore ortografico.</para
></listitem>
<listitem
><para
>Segnalibri e frammenti.</para
></listitem>
</itemizedlist>
</para>
<para
>Per evitare confusione, quanto segue è fuori ambito: <itemizedlist>
<listitem
><para
>Il tipo di carattere e la sua dimensione.</para
></listitem>
<listitem
><para
>I colori dell'applicazione di modifica del testo, ad esempio quelli della mappa nella barra di scorrimento, del menu, della barra del titolo della finestra, eccetera. Nelle applicazioni di &kde;, quali &kate; o &kdevelop;, questi colori sono definiti dallo <userinput
>schema di colori globali di &kde; &plasma;</userinput
>, che si trova nel modulo <ulink url="help:/kcontrol/colors/"
><quote
>Colori</quote
> delle &systemsettings;</ulink
> o nell'applicazione stessa, nel menu <menuchoice
><guimenu
>Impostazioni</guimenu
><guisubmenu
>Schema di colori</guisubmenu
></menuchoice
>. </para
></listitem>
</itemizedlist>
</para>
<mediaobject>
<imageobject
><imagedata format="PNG" fileref="breeze-color-theme-preview.png"/></imageobject>
<textobject
><phrase
>I temi di colori <quote
>Brezza chiaro</quote
> e <quote
>Brezza scuro</quote
> con l'evidenziazione della sintassi del <quote
>C++</quote
>.</phrase>
</textobject>
<caption
><para
>I temi di colori <quote
>Brezza chiaro</quote
> e <quote
>Brezza scuro</quote
> con l'evidenziazione della sintassi del <quote
>C++</quote
>.</para>
</caption>
</mediaobject>
</sect2>
<sect2 id="color-themes-ksyntaxhighlighting">
<title
>I temi di colori di KSyntaxHighlighting</title>
<para
>Il framework <ulink url="https://api.kde.org/frameworks/syntax-highlighting/html/"
>KSyntaxHighlighting</ulink
>, che è il motore dell'<link linkend="highlight"
>evidenziazione della sintassi</link
>, è la libreria che <userinput
>fornisce e gestisce i temi di colori</userinput
>. È parte di &kde; &frameworks; e viene usata negli editor di testo di &kde; come <ulink url="https://apps.kde.org/en/kate"
>&kate;</ulink
>, <ulink url="https://apps.kde.org/en/kwrite"
>&kwrite;</ulink
>, <ulink url="https://apps.kde.org/en/kile"
>&kile;</ulink
> e <ulink url="https://apps.kde.org/en/kdevelop"
>&kdevelop;</ulink
>. Questa dipendenza assomiglia a quanto segue:</para>
<mediaobject>
<imageobject
><imagedata format="PNG" fileref="kf5-ksyntaxhighlighting.png"/></imageobject>
<textobject
><phrase
>Dipendenze delle librerie di &kde; &frameworks; 5 negli editor di testo.</phrase
></textobject>
<caption
><para
>Dipendenze delle librerie di &kde; &frameworks; negli editor di testo.</para>
</caption>
</mediaobject>
<para
>KSyntaxHighlighting include una varietà di temi incorporati che vengono visualizzati nella <ulink url="https://kate-editor.org/themes/"
>pagina <quote
>temi di colori</quote
> sul sito web dell'editor Kate</ulink
>.</para>
<para
>Il framework <ulink url="https://api.kde.org/frameworks/ktexteditor/html/"
>KTextEditor</ulink
>, che è il motore di modifica dei testi, fornisce un'interfaccia utente per creare e per modificare i temi di colore, incluso uno strumento per importarli e per esportarli. Questo è il modo più semplice di creare e di modificare i temi, a cui puoi accedere dalla <link linkend="config-dialog"
> finestra <quote
>Configura</quote
></link
> dell'editor. Maggiori dettagli in <xref linkend="color-themes-gui"/>.</para>
<mediaobject>
<imageobject
><imagedata format="PNG" fileref="color-themes-gui-breeze-dark-default-text-styles.png"/></imageobject>
<textobject
><phrase
>L'&GUI; per gestire i temi di colori nelle impostazioni di &kate;.</phrase
></textobject>
<caption
><para
>L'&GUI; per gestire i temi di colori nelle impostazioni di &kate;.</para>
</caption>
</mediaobject>
<para
>È importante menzionare che negli editor di testo di &kde;, come &kate; o &kdevelop;, i temi di colori di KSyntaxHighlighting vengono usati <ulink url="https://kate-editor.org/post/2020/2020-09-13-kate-color-themes-5.75/"
>da &kde; &frameworks; 5.75</ulink
>, rilasciato il 10 ottobre 2020. In precedenza venivano usati gli schemi di colori di &kate; (schemi di configurazione basati su KConfig) che ora sono deprecati. Ad ogni modo è possibile convertire i vecchi schemi di &kate; nei temi di colori di KSyntaxHighlighting: il <ulink url="https://invent.kde.org/frameworks/syntax-highlighting"
>deposito di KSyntaxHighlighting</ulink
> include a questo scopo lo script <userinput
>utils/kateschema_to_theme_converter.py</userinput
> e il programma <userinput
>utils/schema-converter/</userinput
>. </para>
</sect2>
<sect2 id="color-themes-json">
<title
>Il formato &JSON; dei temi di colori</title>
<sect3 id="color-themes-json-overview">
<title
>Panoramica</title>
<para
>I temi di colori sono memorizzati in file in formato &JSON; con l'estensione <userinput
>.theme</userinput
>.</para>
<para
>Nel <ulink url="https://invent.kde.org/frameworks/syntax-highlighting"
>codice sorgente di KSyntaxHighlighting</ulink
> i file &JSON; dei temi incorporati sono nella cartella <userinput
>data/themes/</userinput
>. Nota che negli editor di testo i temi incorporati sono compilati nella libreria KSyntaxHighlighting, quindi il modo per accedervi è tramite il codice sorgente oppure <link linkend="color-themes-gui-import-export"
>esportandoli dalla &GUI; che gestisce i temi di KTextEditor</link
>.</para>
<para
>È anche possibile aggiungere facilmente dei temi aggiuntivi o personalizzati, che vengono caricati dal file system. I file dei temi personalizzati dall'utente si trovano nella cartella <filename class="directory"
>org.kde.syntax-highlighting/themes/</filename
> che si trova nella cartella utente e vengono trovati col comando <userinput
><command
>qtpaths</command
><option
> --paths GenericDataLocation</option
></userinput
>; di solito sono <filename class="directory"
><envar
>$HOME</envar
>/.local/share/</filename
> e <filename class="directory"
>/usr/share/</filename
>. </para>
<para
>Per i pacchetti Flatpak e Snap la cartella qui sopra non funzionerà perché la posizione dei dati è diversa per ogni applicazione. In un'applicazione Flatpak generalmente la posizione dei file dei temi personalizzati è <filename class="directory"
><envar
>$HOME</envar
>/.var/app/<replaceable
>nome-del-pacchetto-flatpak</replaceable
>/data/org.kde.syntax-highlighting/themes/</filename
>, mentre in una Snap è <filename class="directory"
><envar
>$HOME</envar
>/snap/<replaceable
>nome-del-pacchetto-snap</replaceable
>/current/.local/share/org.kde.syntax-highlighting/themes/</filename
>. </para>
<para
>In &Windows; questi file si trovano in <filename
>%USERPROFILE%\AppData\Local\org.kde.syntax-highlighting\themes</filename
>. <replaceable
>%USERPROFILE%</replaceable
> viene generalmente espanso in <filename
>C:\Users\<replaceable
>utente</replaceable
></filename
>.</para>
<para
>In sintesi, per la maggior parte delle configurazioni la cartella dei temi personalizzati è la seguente:</para>
<informaltable>
<tgroup cols="2">
<tbody>
<row>
<entry
>Per l'utente locale</entry>
<entry
><filename class="directory"
><envar
>$HOME</envar
>/.local/share/org.kde.syntax-highlighting/themes/</filename
></entry>
</row>
<row>
<entry
>Per tutti gli utenti</entry>
<entry
><filename class="directory"
>/usr/share/org.kde.syntax-highlighting/themes/</filename
></entry>
</row>
<row>
<entry
>Per i pacchetti Flatpak</entry>
<entry
><filename class="directory"
><envar
>$HOME</envar
>/.var/app/<replaceable
>nome-pacchetto-flatpak</replaceable
>/data/org.kde.syntax-highlighting/themes/</filename
></entry>
</row>
<row>
<entry
>Per i pacchetti Snap</entry>
<entry
><filename class="directory"
><envar
>$HOME</envar
>/snap/<replaceable
>nome-pacchetto-snap</replaceable
>/current/.local/share/org.kde.syntax-highlighting/themes/</filename
></entry>
</row>
<row>
<entry
>In &Windows;</entry>
<entry
><filename
>%USERPROFILE%\AppData\Local\org.kde.syntax-highlighting\themes</filename
></entry>
</row>
</tbody>
</tgroup>
</informaltable>
<para
>Se esistono più temi con lo stesso nome, verrà caricato quello che ha il valore più alto dell'attributo <userinput
>revision</userinput
>. </para>
</sect3>
<sect3 id="color-themes-json-basic">
<title
>La struttura &JSON;</title>
<para
>La struttura di un file &JSON; è spiegata nel <ulink url="https://www.json.org"
>loro sito web</ulink
>. Fondamentalmente il formato di file &JSON; consiste in: <itemizedlist>
<listitem
><para
>Collezioni di coppie di chiavi e valori separate da virgole e raggruppate tra <userinput
>{ }</userinput
>, che chiameremo <quote
>oggetti</quote
>.</para
></listitem>
<listitem
><para
>Elenchi ordinati di valori separati da virgole e raggruppate tra <userinput
>[ ]</userinput
>, che chiameremo <quote
>vettori</quote
>.</para
></listitem
></itemizedlist>
</para>
<para
>In questo articolo verrà usata la nomenclatura <quote
>chiave</quote
>, <quote
>valore</quote
>, <quote
>oggetto</quote
> e <quote
>vettore</quote
>. Se è la prima volta che lavori con i file &JSON; la loro comprensione è semplice come guardare l'esempio qui sotto, </para>
</sect3>
<sect3 id="color-themes-json-root">
<title
>Struttura principale dei file &JSON; di un tema di colori</title>
<para
>L'oggetto principale del file del tema di colori &JSON; contiene il seguente schema di chiavi:</para>
<itemizedlist>
<listitem
><para
><userinput
>metadata</userinput
>: è obbligatorio. Il valore è un oggetto coi metadati del tema, come il nome, la revisione e la licenza.</para>
<para
>È spiegato nei dettagli in <xref linkend="color-themes-json-metadata"/>.</para>
</listitem>
<listitem
><para
><userinput
>editor-colors</userinput
>: è obbligatorio. Il valore è un oggetto con i colori dell'area di modifica del testo, come lo sfondo il bordo dell'icona e le decorazioni del testo.</para>
<para
>È spiegato nei dettagli in <xref linkend="color-themes-editor-colors"/>.</para>
</listitem>
<listitem
><para
><userinput
>text-styles</userinput
>: è obbligatorio. Il valore è un oggetto con gli attributi <emphasis
>stili di testo predefiniti</emphasis
> dell'evidenziazione della sintassi. Ciascun attributo definisce il suo <emphasis
>colore del testo</emphasis
>, <emphasis
>colore del testo selezionato</emphasis
>, o se, ad esempio, è in <emphasis
>grassetto</emphasis
> o in <emphasis
>corsivo</emphasis
>. Gli stili del testo possono essere referenziati dagli <link linkend="kate-highlight-default-styles"
>attributi dei file &XML; di definizione della sintassi</link
>.</para>
<para
>È spiegato nei dettagli in <xref linkend="color-themes-text-styles"/>.</para>
</listitem>
<listitem
><para
><userinput
>custom-styles</userinput
>: è facoltativo. Definisce gli stili di testo per gli attributi di definizioni di evidenziazione della sintassi specifiche. Ad esempio, in una definizione di evidenziazione come <userinput
>Python</userinput
> o <userinput
>Markdown</userinput
> puoi specificare uno stile di testo diverso che sostituisce quello predefinito che è definito in <userinput
>text-styles</userinput
>.</para>
<para
>È spiegato nei dettagli in <xref linkend="color-themes-custom-styles"/>.</para>
</listitem>
</itemizedlist>
<para
>Il linguaggio &JSON; non supporta i commenti, tuttavia puoi usare la chiave facoltativa <userinput
>_comments</userinput
> nell'oggetto principale per scrivere dei commenti; ad esempio, se stai adattando un tema esistente puoi mettere l'URL del deposito. Il modo più pratico è quello di usare un vettore di stringhe. </para>
<para
>Qui sotto c'è un file di esempio del tema <quote
>Brezza chiaro</quote
>. Puoi notare che, per evitare che l'esempio sia troppo lungo, gli oggetti <userinput
>editor-colors</userinput
> e <userinput
>text-styles</userinput
>, non contengano tutte le chiavi richieste. Puoi vedere l'intero archivio del <ulink url="https://invent.kde.org/frameworks/syntax-highlighting/-/blob/master/data/themes/breeze-light.theme"
> tema <quote
>Brezza chiaro</quote
> nel deposito di KSyntaxHighlighting</ulink
>. </para>
<programlisting
>{
"_comments": [
"Questo è un commento.",
"Se questo tema è un adattamento di un altro, inserisci il collegamento alla sorgente d'installazione originale."
],
"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
>Le altre chiavi dei colori dell'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
>Le altri chiavi di stile del testo...</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
>Metadati</title>
<para
>L'oggetto &JSON; della chiave <userinput
>metadata</userinput
> contiene informazioni rilevanti sul tema. Questo oggetto ha le seguenti chiavi: <itemizedlist>
<listitem
><para
><userinput
>name</userinput
>: è una <emphasis
>stringa</emphasis
> impostata al nome del linguaggio. Appare successivamente nei menu e nelle finestre. È obbligatoria.</para
></listitem>
<listitem
><para
><userinput
>revision</userinput
>: è un numero <emphasis
>integer</emphasis
> che specifica l'attuale revisione del file del tema. Assicurati di incrementare questo numero ogni volta che aggiorni un file di tema di colori. È obbligatoria.</para
></listitem>
<listitem
><para
><userinput
>license</userinput
>: è una <emphasis
>stringa</emphasis
> che definisce la licenza del tema usando l'identificativo <userinput
>SPDX-License-Identifier</userinput
> dello standard del <ulink url="https://spdx.dev/"
>formato di comunicazione della licenza SPDX</ulink
>. È facoltativa.</para>
<para
><ulink url="https://spdx.org/licenses/"
>Qui</ulink
> puoi vedere l'elenco completo degli identificatori di licenza SPDX.</para
></listitem>
<listitem
><para
><userinput
>copyright</userinput
>: è un <emphasis
>vettore</emphasis
> di <emphasis
>stringhe</emphasis
> che specifica l'autore del tema usando l'identificativo <userinput
>SPDX-FileCopyrightText</userinput
> dello standard del <ulink url="https://spdx.dev/"
>formato di comunicazione della licenza SPDX</ulink
>. È facoltativa.</para
></listitem>
</itemizedlist>
</para>
<programlisting
>"metadata": {
"name" : "Brezza chiaro",
"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
>I colori in dettaglio</title>
<para
>Questa sezione descrive in dettaglio tutti gli attributi di colore disponibili e le tutte le impostazioni di colore disponibili.</para>
<sect3 id="color-themes-editor-colors">
<title
>Modificare i colori</title>
<para
>Corrisponde ai colori dell'<link linkend="kate-part"
>area di modifica del testo</link
>.</para>
<para
>Nel <link linkend="color-themes-json"
>file di tema &JSON;</link
> la rispettiva chiave <userinput
>editor-colors</userinput
> ha come valore un <emphasis
>oggetto</emphasis
> nel quale ciascuna chiave fa riferimento ad un attributo di colore dell'editor di testo. Qui <userinput
>tutte le chiavi disponibili sono obbligatorie</userinput
>: i loro valori sono delle <userinput
>stringhe</userinput
> con i codici esadecimali dei colori, ad esempio <quote
>#00B5CF</quote
>. </para>
<para
>Nell'<link linkend="color-themes-gui"
>&GUI; per gestire i temi di KTextEditor</link
> questi attributi possono essere modificati nella scheda <userinput
><guilabel
>Colori</guilabel
></userinput
>. </para>
<para
>Le chiavi disponibili sono le seguenti: quelle usate nel <link linkend="color-themes-json"
>file &JSON;</link
> sono elencate in <emphasis
>grassetto</emphasis
>, mentre i nomi usati nell'<link linkend="color-themes-gui"
>&GUI;</link
> vengono mostrati tra parentesi. </para>
<variablelist>
<varlistentry id="variable-prefcolors-colors-text-background">
<term
><guilabel
>Colori di sfondo dell'editor</guilabel
></term>
<listitem>
<variablelist>
<varlistentry id="variable-pref-colors-normal-text">
<term
><userinput
>BackgroundColor</userinput
> (<guilabel
>Area di testo</guilabel
>)</term>
<listitem
><para
>Questo è lo sfondo predefinito per l'area dell'editor, sarà il colore dominante dell'area principale.</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
>Testo selezionato</guilabel
>)</term>
<listitem
><para
>Questo è lo sfondo del testo selezionato. </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
>Riga attuale</guilabel
>)</term>
<listitem
><para
>Imposta il colore della riga attuale. Se è un po' diverso da quello del testo normale, permette di mantenere attiva la riga. </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
>Evidenziazione delle ricerche</guilabel
>)</term>
<listitem
><para
>Imposta il colore del testo che corrisponde all'ultima ricerca. </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
>Evidenziazione delle sostituzioni</guilabel
>)</term>
<listitem
><para
>Imposta il colore del testo che corrisponde all'ultima operazione di sostituzione.</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
>Bordo delle icone</guilabel
></term>
<listitem>
<variablelist>
<varlistentry>
<term
><userinput
>IconBorder</userinput
> (<guilabel
>Area di sfondo</guilabel
>)</term>
<listitem
><para
>Questo colore viene usato per gli indicatori, i bordi per i numeri di riga e per gli indicatori di raggruppamento sul lato sinistro della vista dell'editor, quando sono mostrati. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><userinput
>LineNumbers</userinput
> (<guilabel
>Numeri di riga</guilabel
>)</term>
<listitem
><para
>Questo colore viene usato per disegnare i numeri di riga sul lato sinistro della vista, quando sono mostrati.</para
></listitem>
</varlistentry>
<varlistentry>
<term
><userinput
>CurrentLineNumber</userinput
> (<guilabel
>Numero della riga attuale</guilabel
>)</term>
<listitem
><para
>Questo colore viene usato per disegnare il numero della riga attuale, nella parte sinistra della vista quando è visualizzato. Impostandolo leggermente diverso da <quote
>LineNumbers</quote
> può aiutare a mantenere attiva la riga attuale. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><userinput
>Separator</userinput
> (<guilabel
>Separatore</guilabel
>)</term>
<listitem
><para
>Questo colore viene usato per disegnare una linea verticale che separa il bordo dell'icona dallo sfondo dell'area del testo.</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
>Segno di ritorno a capo</guilabel
>)</term>
<listitem
><para
>Questo colore viene usato per disegnare un motivo sulla sinistra delle righe fatte andare a capo automaticamente quando vengono allineate verticalmente, ed anche per l'indicatore di a capo statico.</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
>Raggruppamento del codice</guilabel
>)</term>
<listitem
><para
>Questo colore viene usato per evidenziare la sezione di codice che sarebbe raggruppata al clic sulla freccia di raggruppamento a sinistra del documento. Per maggiori informazioni, vedi <link linkend="advanced-editing-tools-code-folding"
>la documentazione sul raggruppamento del codice</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
>Righe modificate</guilabel
>)</term>
<listitem
><para
>Questo colore viene usato per evidenziare, alla sinistra di un documento, le righe che sono state modificate ma non ancora salvate. Per maggiori informazioni, vedi <xref linkend="kate-part-line-modification"/>.</para
></listitem>
</varlistentry>
<varlistentry>
<term
><userinput
>SavedLines</userinput
> (<guilabel
>Righe salvate</guilabel
>)</term>
<listitem
><para
>Questo colore viene usato per evidenziare indicare, alla sinistra di un documento, le righe che sono state modificate e salvate in questa sessione. Per maggiori informazioni, vedi <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
>Decorazioni del testo</guilabel
></term>
<listitem>
<variablelist>
<varlistentry>
<term
><userinput
>SpellChecking</userinput
> (<guilabel
>Linea degli errori di ortografia</guilabel
>)</term>
<listitem
><para
>Questo colore viene usato per indicare gli errori di ortografia.</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
>Segni di tabulazione e spazio</guilabel
>)</term>
<listitem
><para
>Questo colore viene usato per gli indicatori di spazi bianchi, quando sono abilitati.</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
>Linea di rientro</guilabel
>)</term>
<listitem
><para
>Questo colore viene usato per disegnare una linea alla sinistra dei blocchi rientrati, se <link linkend="appearance-general"
>questa funzionalità è abilitata</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
>Evidenziazione delle parentesi</guilabel
>)</term>
<listitem
><para
>Questo colore viene usato per lo sfondo delle parentesi corrispondenti. </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
>Colori degli indicatori</guilabel
></term>
<listitem>
<variablelist>
<varlistentry>
<term
><userinput
>MarkBookmark</userinput
> (<guilabel
>Segnalibro</guilabel
>)</term>
<listitem
><para
>Questo colore viene usato per indicare i segnalibri. Nota che ha un'opacità del 22% (e del 33% per la riga attuale) rispetto allo sfondo. Per maggiori informazioni, vedi <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
>Punto d'interruzione attivo</guilabel
>)</term>
<listitem
><para
>Questo colore viene usato dall'estensione GDB per indicare un punto d'interruzione attivo. Nota che questo colore ha un'opacità sullo sfondo. Per maggiori informazioni, vedi <ulink url="help:/kate/kate-application-plugin-gdb.html"
>la documentazione dell'estensione GDB</ulink
>.</para
></listitem>
</varlistentry>
<varlistentry>
<term
><userinput
>MarkBreakpointReached</userinput
> (<guilabel
>Punto d'interruzione raggiunto</guilabel
>)</term>
<listitem
><para
>Questo colore viene usato dall'estensione GDB per indicare un punto d'interruzione che hai raggiunto durante il debugging. Nota che questo colore ha un'opacità sullo sfondo. Per maggiori informazioni, vedi <ulink url="help:/kate/kate-application-plugin-gdb.html"
>la documentazione dell'estensione GDB</ulink
>.</para
></listitem>
</varlistentry>
<varlistentry>
<term
><userinput
>MarkBreakpointDisabled</userinput
> (<guilabel
>Punto d'interruzione disabilitato</guilabel
>)</term>
<listitem
><para
>Questo colore viene usato dall'estensione GDB per indicare un punto d'interruzione inattivo. Nota che questo colore ha un'opacità sullo sfondo. Per maggiori informazioni, vedi <ulink url="help:/kate/kate-application-plugin-gdb.html"
>la documentazione dell'estensione GDB</ulink
>.</para
></listitem>
</varlistentry>
<varlistentry>
<term
><userinput
>MarkExecution</userinput
> (<guilabel
>Esecuzione</guilabel
>)</term>
<listitem
><para
>Questo colore viene usato dall'estensione GDB per indicare la riga attualmente in esecuzione. Nota che questo colore ha un'opacità sullo sfondo. Per maggiori informazioni, vedi <ulink url="help:/kate/kate-application-plugin-gdb.html"
>la documentazione dell'estensione GDB</ulink
>.</para
></listitem>
</varlistentry>
<varlistentry>
<term
><userinput
>MarkWarning</userinput
> (<guilabel
>Avviso</guilabel
>)</term>
<listitem
><para
>Questo colore viene usato dall'estensione di compilazione per indicare una riga che ha causato un avviso del compilatore. Nota che questo colore ha un'opacità sullo sfondo. Per maggiori informazioni, vedi <ulink url="help:/kate/kate-application-plugin-build.html"
>la documentazione dell'estensione di compilazione</ulink
>.</para
></listitem>
</varlistentry>
<varlistentry>
<term
><userinput
>MarkError</userinput
> (<guilabel
>Errore</guilabel
>)</term>
<listitem
><para
>Questo colore viene usato dall'estensione di compilazione per indicare una riga che ha causato un errore del compilatore. Nota che questo colore ha un'opacità sullo sfondo. Per maggiori informazioni, vedi <ulink url="help:/kate/kate-application-plugin-build.html"
>la documentazione dell'estensione di compilazione</ulink
>.</para
></listitem>
</varlistentry>
</variablelist>
</listitem>
</varlistentry>
<varlistentry id="variable-prefcolors-colors-text-templates-snippets">
<term
><guilabel
>Modelli e frammenti di testo</guilabel
></term>
<listitem>
<variablelist>
<varlistentry>
<term
><userinput
>TemplateBackground</userinput
> (<guilabel
>Sfondo</guilabel
>)</term>
<listitem
><para
>Questo colore è usato dall'estensione dei frammenti di &kate; per colorare lo sfondo di un frammento. Per maggiori informazioni, vedi <ulink url="help:/kate/kate-application-plugin-snippets.html"
>la documentazione dei frammenti di &kate;</ulink
>.</para
></listitem>
</varlistentry>
<varlistentry>
<term
><userinput
>TemplatePlaceholder</userinput
> (<guilabel
>Segnaposto modificabile</guilabel
>)</term>
<listitem
><para
>Questo colore viene usato dall'estensione dei frammenti di &kate; per marcare un segnaposto su cui puoi fare clic per modificarlo manualmente. Per maggiori informazioni, vedi <ulink url="help:/kate/kate-application-plugin-snippets.html"
>la documentazione dei frammenti di &kate;</ulink
>.</para
></listitem>
</varlistentry>
<varlistentry>
<term
><userinput
>TemplateFocusedPlaceholder</userinput
> (<guilabel
>Segnaposto modificabile attivo</guilabel
>)</term>
<listitem
><para
>Questo colore viene usato dall'estensione dei frammenti di &kate; per marcare il segnaposto che stai attualmente modificando. Per maggiori informazioni, vedi <ulink url="help:/kate/kate-application-plugin-snippets.html"
>la documentazione dei frammenti di &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
>Segnaposto non modificabile</guilabel
>)</term>
<listitem
><para
>Questo colore viene usato dall'estensione dei frammenti di &kate; per segnare un segnaposto non modificabile manualmente, per esempio uno che viene determinato automaticamente. Per maggiori informazioni, vedi <ulink url="help:/kate/kate-application-plugin-snippets.html"
>la documentazione dei frammenti di &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
>Stili di testo predefiniti</title>
<para
>Gli stili di testo predefiniti sono ereditati dagli stili di evidenziazione del testo, permettendo all'editor di presentare il testo in modo coerente; ad esempio, il testo dei commenti è uguale in quasi tutti i formati di testo che KSyntaxHighlighting può evidenziare. </para>
<note>
<para
>È possibile fare riferimento a questi <userinput
>stili di testo</userinput
> dagli stili predefiniti utilizzati nei file &XML; di definizione dell'<link linkend="highlight"
>evidenziazione della sintassi</link
>. Ad esempio, l'attributo <quote
>Normal</quote
> è equivalente a <quote
>dsNormal</quote
> nei file &XML;, mentre <quote
>DataType</quote
> a <quote
>dsDataType</quote
>. Vedi <xref linkend="kate-highlight-default-styles"/> nella documentazione di evidenziazione della sintassi. </para>
</note>
<tip>
<para
>Assicurati di scegliere dei colori leggibili e con un buon contrasto, specialmente in combinazione con l'<userinput
><link linkend="color-themes-editor-colors"
>editor di colori</link
></userinput
>. Vedi <xref linkend="color-themes-contrast"/>. </para>
</tip>
<para
>Nel <link linkend="color-themes-json"
>file &JSON;</link
> la rispettiva chiave <userinput
>text-styles</userinput
> ha come valore un <emphasis
>oggetto</emphasis
> nel quale ogni chiave corrisponde al nome di uno <emphasis
>stile di testo predefinito</emphasis
>, che sono equivalenti a quelli usati nelle definizioni di evidenziazione della sintassi. Qui <userinput
> tutti le chiavi dello stile del testo disponibili sono obbligatorie </userinput
>; queste sono elencate di seguito. </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
>Le altre chiavi di stile del testo...</replaceable>
}
</programlisting>
<variablelist>
<varlistentry>
<term
>Ciascuna chiave degli <emphasis
>stili di testo predefiniti</emphasis
> ha un oggetto &JSON; per valore, dove vengono specificati valori come <emphasis
>colore</emphasis
>, <emphasis
>grassetto</emphasis
>, <emphasis
>corsivo</emphasis
>, ecc. Queste chiavi sono le seguenti: </term>
<listitem>
<para
><userinput
>text-color</userinput
>: è una <emphasis
>stringa</emphasis
> col colore del testo espresso come codice di colore esadecimale. Questa coppia di chiave e valore è richiesta.</para>
<para
><userinput
>selected-text-color</userinput
>: il colore del testo quando è selezionato; generalmente ha lo stesso valore di <quote
>text-color</quote
>. Quando il testo viene selezionato, lo sfondo viene definito dal valore di <link linkend="variable-pref-colors-selected-text"
>TextSelection</link
> nell'<link linkend="color-themes-editor-colors"
>editor di colori</link
>, quindi devi essere sicuro che il testo abbia un buon contrasto e che sia leggibile su questo sfondo. Questo valore è una <emphasis
>stringa</emphasis
> con un codice di colore esadecimale. Questa coppia di chiave e valore è richiesta.</para>
<para
><userinput
>bold</userinput
>: è un valore <emphasis
>booleano</emphasis
> che determina se il testo è in grassetto. Questa chiave è facoltativa, il suo valore predefinito è <userinput
>false</userinput
>.</para>
<para
><userinput
>italic</userinput
>: è un valore <emphasis
>booleano</emphasis
> che determina se il testo è curvo. Questa chiave è facoltativa, il suo valore predefinito è <userinput
>false</userinput
>.</para>
<para
><userinput
>underline</userinput
>: è un valore <emphasis
>booleano</emphasis
> che determina se il testo è sottolineato. Questa chiave è facoltativa, il suo valore predefinito è <userinput
>false</userinput
>.</para>
<para
><userinput
>strike-through</userinput
>: è un valore <emphasis
>booleano</emphasis
> che determina se il testo è barrato. Questa chiave è facoltativa, il suo valore predefinito è <userinput
>false</userinput
>.</para>
<para
><userinput
>background-color</userinput
>: determina lo sfondo del testo, che viene usato per esempio negli avvisi e nei commenti. Il valore è una <emphasis
>stringa</emphasis
> con un codice di colore esadecimale. Questa chiave è facoltativa, per impostazione predefinita non c'è uno sfondo.</para>
<para
><userinput
>selected-background-color</userinput
>: determina lo sfondo del testo quando viene selezionato. Il valore è una <emphasis
>stringa</emphasis
> con un codice di colore esadecimale. Questa chiave è facoltativa, per impostazione predefinita non c'è uno sfondo.</para>
</listitem>
</varlistentry>
</variablelist>
<para
>Nell'<link linkend="color-themes-gui"
>&GUI; per gestire i temi di colori di KTextEditor</link
> questi attributi possono essere modificati nella scheda <userinput
><guilabel
>Stili di testo predefiniti</guilabel
></userinput
>. Il nome nell'elenco degli stili utilizza lo stile configurato per l'elemento, fornendoti un'anteprima immediata durante la configurazione di uno stile. Ogni stile ti permette di selezionare gli attributi comuni, nonché i colori di primo piano e di sfondo. Per annullare l'impostazione di un colore di sfondo, fai clic con il pulsante destro per utilizzare il menu contestuale.</para>
<para
>Le chiavi per lo stile del testo disponibili sono le seguenti: quelle usate nel <link linkend="color-themes-json"
>file &JSON;</link
> sono elencate in <emphasis
>grassetto</emphasis
>, mentre i nomi usati nell'<link linkend="color-themes-gui"
>&GUI;</link
> vengono mostrati tra parentesi se sono diversi.</para>
<variablelist>
<varlistentry>
<term
><guilabel
>Testo normale e codice sorgente</guilabel
></term>
<listitem>
<para
><userinput
>Normal</userinput
>: lo stile del testo predefinito per il testo normale e per il codice sorgente senza un'evidenziazione speciale.</para>
<para
><userinput
>Keyword</userinput
>: lo stile del testo per le parole chiave incorporate nel linguaggio.</para>
<para
><userinput
>Function</userinput
>: lo stile del testo per le definizioni di funzioni e per le chiamate di funzioni.</para>
<para
><userinput
>Variable</userinput
>: lo stile del testo per le variabili, se applicabile. Per esempio, le variabili in PHP o in Perl iniziano tipicamente con <userinput
>$</userinput
>, quindi tutti gli identificatori che seguono il modello <userinput
>$foo</userinput
> vengono evidenziati come variabili.</para>
<para
><userinput
>ControlFlow</userinput
> (<guilabel
>Flusso di controllo</guilabel
>): lo stile del testo per le parole chiave del flusso di controllo, come <emphasis
>if</emphasis
>, <emphasis
>then</emphasis
>, <emphasis
>else</emphasis
>, <emphasis
>return</emphasis
>, <emphasis
>switch</emphasis
>, <emphasis
>break</emphasis
>, <emphasis
>yield</emphasis
>, <emphasis
>continue</emphasis
>, ecc.</para>
<para
><userinput
>Operator</userinput
>: lo stile del testo per gli operatori, come <userinput
>+</userinput
>, <userinput
>-</userinput
>, <userinput
>*</userinput
>, <userinput
>/</userinput
>, <userinput
>%</userinput
>, ecc.</para>
<para
><userinput
>BuiltIn</userinput
> (<guilabel
>Integrato</guilabel
>): lo stile del testo per le classi del linguaggio, le funzioni e gli oggetti integrati.</para>
<para
><userinput
>Extension</userinput
>: lo stile del testo per le estensioni ben note, ad esempio le classi di &Qt;, le funzioni e le macro del C++ e di Python o boost.</para>
<para
><userinput
>Preprocessor</userinput
>: lo stile del testo per le direttive al preprocessore o per le definizioni di macro.</para>
<para
><userinput
>Attribute</userinput
>: lo stile del testo per le annotazioni o per gli attributi delle funzioni o degli oggetti, ad esempio <userinput
>@override</userinput
> in Java, oppure <userinput
>__declspec(...)</userinput
> e <userinput
>__attribute__((...))</userinput
> in C++.</para>
</listitem>
</varlistentry>
<varlistentry>
<term
><guilabel
>Numeri, tipi e costanti</guilabel
></term>
<listitem>
<para
><userinput
>DataType</userinput
> (<guilabel
>Tipo di dato</guilabel
>): stile del testo per i tipi di dati integrati, ad esempio <emphasis
>int</emphasis
>, <emphasis
>char</emphasis
>, <emphasis
>float</emphasis
>, <emphasis
>void</emphasis
>, <emphasis
>u64</emphasis
>, ecc.</para>
<para
><userinput
>DecVal</userinput
> (<guilabel
>Decimale/Valore</guilabel
>): stile del testo per i valori decimali.</para>
<para
><userinput
>BaseN</userinput
> (<guilabel
>Intero in base N</guilabel
>): stile del testo per i numeri in una base diversa da 10.</para>
<para
><userinput
>Float</userinput
> (<guilabel
>Virgola mobile</guilabel
>): stile del testo per i numeri in virgola mobile.</para>
<para
><userinput
>Constant</userinput
>: stile del testo per le costanti del linguaggio e per quelle definite dall'utente, ad esempio <emphasis
>True</emphasis
>, <emphasis
>False</emphasis
>, <emphasis
>None</emphasis
> in Python, oppure <emphasis
>nullptr</emphasis
> in C/C++, o anche per le costanti matematiche come <emphasis
>PI</emphasis
>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term
><guilabel
>Stringhe e caratteri</guilabel
></term>
<listitem>
<para
><userinput
>Char</userinput
> (<guilabel
>Character</guilabel
>): stile del testo per i singoli caratteri, ad esempio <userinput
>'x'</userinput
>.</para>
<para
><userinput
>SpecialChar</userinput
> (<guilabel
>Carattere speciale</guilabel
>): stile del testo per i caratteri di escape nelle stringhe, ad esempio <quote
><userinput
>hello\n</userinput
></quote
>, e per gli altri caratteri con un significato speciale nelle stringhe, ad esempio per gli operatori di sostituzione o di espressione regolare.</para>
<para
><userinput
>String</userinput
>: stile del testo per le stringhe, ad esempio <quote
><userinput
>hello world</userinput
></quote
>.</para>
<para
><userinput
>VerbatimString</userinput
> (<guilabel
>Stringa letterale</guilabel
>): stile del testo per le stringhe letterali o per quelle grezze, ad esempio <userinput
>'raw \backlash'</userinput
> in Perl, in CoffeeScript e in shells, così come <userinput
>r'\raw'</userinput
> in Python, o come negli HERE docs.</para>
<para
><userinput
>SpecialString</userinput
> (<guilabel
>Stringa speciale</guilabel
>): stile del testo per le stringhe speciali, ad esempio le espressioni regolari in ECMAScript, la modalità matematica di &latex;, di SQL, ecc.</para>
<para
><userinput
>Import</userinput
> (<guilabel
>Importazioni, moduli, inclusioni</guilabel
>): stile del testo per le inclusioni, le importazioni, i moduli o i pacchetti di &latex;.</para>
</listitem>
</varlistentry>
<varlistentry>
<term
><guilabel
>Commenti e documentazione</guilabel
></term>
<listitem>
<para
><userinput
>Comment</userinput
>: lo stile del testo per i commenti normali.</para>
<para
><userinput
>Documentation</userinput
>: lo stile del testo per i commenti che riflettono la documentazione API, ad esempio <userinput
>/** doxygen comments */</userinput
> oppure <userinput
>"""docstrings"""</userinput
>.</para>
<para
><userinput
>Annotation</userinput
>: lo stile del testo per le annotazioni nei commenti o nei comandi della documentazione, ad esempio <userinput
>@param</userinput
> in Doxygen o in JavaDoc.</para>
<para
><userinput
>CommentVar</userinput
> (<guilabel
>Variabile di commento</guilabel
>): lo stile del testo che si riferisce ai nomi delle variabili usati nei comandi qui sopra in un commento, ad esempio <userinput
>foobar</userinput
> in <quote
><userinput
>@param foobar</userinput
></quote
>, in Doxygen o in JavaDoc.</para>
<para
><userinput
>RegionMarker</userinput
> (<guilabel
>Delimitatore di regione</guilabel
>): lo stile del testo per i delimitatori di regione, definiti tipicamente da <userinput
>//BEGIN</userinput
> e da <userinput
>//END</userinput
> nei commenti.</para>
<para
><userinput
>Information</userinput
>: lo stile del testo per le informazioni, per le note e per i suggerimenti, ad esempio la parola chiave <userinput
>@note</userinput
> in Doxygen.</para>
<para
><userinput
>Warning</userinput
>: lo stile del testo per gli avvisi, ad esempio la parola chiave <userinput
>@warning</userinput
> in Doxygen.</para>
<para
><userinput
>Alert</userinput
>: lo stile del testo per le parole speciali nei commenti, ad esempio<userinput
>TODO</userinput
>, <userinput
>FIXME</userinput
>, <userinput
>XXXX</userinput
> e <userinput
>WARNING</userinput
>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term
><guilabel
>Varie</guilabel
></term>
<listitem>
<para
><userinput
>Error</userinput
>: lo stile del testo per indicare l'evidenziazione degli errori e la sintassi errata.</para>
<para
><userinput
>Others</userinput
>: lo stile del testo per gli attributi che non soddisfano nessuno degli altri stili predefiniti.</para>
</listitem>
</varlistentry>
</variablelist>
</sect3>
<sect3 id="color-themes-custom-styles">
<title
>Stili di evidenziazione del testo personalizzati</title>
<para
>Qui puoi stabilire gli stili del testo per una definizione di evidenziazione della sintassi specifica, senza tener conto degli <userinput
>stili di testo predefiniti</userinput
> descritti nella <link linkend="color-themes-text-styles"
>sezione precedente</link
>. </para>
<para
>Nel <link linkend="color-themes-json"
>file di tema &JSON;</link
> questo corrisponde alla chiave <userinput
>custom-styles</userinput
>, il cui valore è un <emphasis
>oggetto</emphasis
> nel quale ciascuna chiave del sottoschema corrisponde al <userinput
>nome di una definizione di evidenziazione</userinput
>. Il suo valore è un <emphasis
>oggetto</emphasis
> nel quale ciascuna chiave si riferisce al <userinput
>nome degli attributi di stile</userinput
> definito negli <link linkend="kate-highlight-sections"
>elementi <userinput
>itemData</userinput
></link
> del file &XML; di evidenziazione della sintassi, e il rispettivo valore è un sotto-oggetto con le chiavi <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
> e <emphasis
>selected-background-color</emphasis
>, che sono state definite nella <link linkend="color-themes-text-styles"
>sezione precedente</link
>. Ciascuno di questi valori è facoltativo, dal momento che viene considerato lo stile impostato in <userinput
>text-styles</userinput
> se non sono presenti. </para>
<para
>Ad esempio, in questo pezzetto di codice la definizione di evidenziazione della sintassi di <quote
>C++ ISO</quote
> ha uno stile del testo speciale per gli attributi <quote
>Type Modifiers</quote
> e per <quote
>Standard Classes</quote
>. Nel file &XML; corrispondente <quote
>isocpp.xml</quote
>, l'attributo definito <quote
>Standard Classes</quote
> utilizza lo stile predefinito <userinput
>BuiltIn</userinput
> (o dsBuiltIn). In questo attributo, solamente il valore di <userinput
>text-color</userinput
> è sovrascritto dal nuovo colore <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
>Dovresti considerare che questi stili di testo sono associati con i nomi degli attributi definiti nei file &XML; di evidenziazione della sintassi. Se un file XML viene aggiornato ed alcuni attributi vengono rinominati o rimossi, lo stile personalizzato definito nel tema non verrà più applicato.</para>
</listitem>
<listitem>
<para
>Le definizioni di evidenziazione della sintassi ne includono spesso delle altre. Ad esempio, l'evidenziatore di <quote
>QML</quote
> include quello di <quote
>JavaScript</quote
>, dal momento che essi condividono delle funzionalità di evidenziazione.</para>
</listitem>
</itemizedlist>
</note>
<para
>Nell'<link linkend="color-themes-gui"
>&GUI; per gestire i temi di KTextEditor</link
> questi attributi possono essere modificati nella scheda <userinput
><guilabel
>Stili di testo evidenziato</guilabel
></userinput
>. Per impostazione predefinita, l'editor preseleziona l'evidenziazione del documento corrente. Noterai che molti evidenziatori ne contengono altri, rappresentati dai gruppi nell'elenco degli stili. Ad esempio, la maggior parte degli evidenziatori importa <quote
>Alert</quote
>, mentre molti dei formati di codice sorgente importano <quote
>Doxygen</quote
>. </para>
</sect3>
</sect2>
<sect2 id="color-themes-gui">
<title
>L'&GUI; temi di colori</title>
<para
>Il modo più semplice per creare e per modificare i temi di colori è dall'&GUI; all'interno della <link linkend="config-dialog"
>finestra<quote
>Configura</quote
></link
> fornita da <ulink url="https://api.kde.org/frameworks/ktexteditor/html/"
>KTextEditor</ulink
>. Per accedervi, seleziona <menuchoice
><guimenu
>Impostazioni</guimenu
> <guimenuitem
>Configura <replaceable
>Applicazione</replaceable
>...</guimenuitem
></menuchoice
> dalla barra dei menu del tuo editor di testo. Questo fa apparire la finestra di dialogo <guilabel
>Configura</guilabel
>, lì seleziona <guilabel
>Temi di colore</guilabel
>, che è nel pannello laterale. </para>
<mediaobject>
<imageobject
><imagedata format="PNG" fileref="color-themes-gui-default-text-styles.png"/></imageobject>
<textobject
><phrase
>La finestra delle impostazioni di &kate; con la gestione del tema dei colori.</phrase
></textobject>
<caption
><para
>La finestra delle impostazioni di &kate; con la gestione del tema dei colori.</para>
</caption>
</mediaobject>
<para
>In questa <link linkend="config-dialog"
>finestra</link
> puoi configurare tutti i colori di ogni tema tu abbia, così come creare o copiare nuovi temi, eliminarli, esportarli in un file <userinput
>.theme</userinput
> in <link linkend="color-themes-json"
>formato &JSON;</link
>, o anche importarli da file <userinput
>.theme</userinput
> esterni. Ogni tema ha le impostazioni per i colori e per gli stili del testo. </para>
<para
>I temi integrati non possono essere modificati per impostazione predefinita. Per fare ciò è necessario copiarli dandogli un nuovo nome.</para>
<para
>Per usare permanentemente un tema nell'editor di testo lo devi selezionare nella casella combinata etichettata <guilabel
>Tema predefinito per <replaceable
>Applicazione</replaceable
></guilabel
> in basso nella finestra, poi devi premere <guibutton
>Applica</guibutton
> o <guibutton
>OK</guibutton
>. L'opzione <userinput
><guilabel
>Selezione automatica</guilabel
></userinput
> è attiva per impostazione predefinita, e ti aiuta a scegliere un tema di colori più appropriato in base allo <emphasis
>schema di colori di &kde; &plasma;</emphasis
> che hai usato nelle applicazioni di modifica del testo. Di solito sceglie <quote
>Brezza chiaro</quote
> o <quote
>Brezza scuro</quote
>, a seconda che lo schema sia rispettivamente chiaro o scuro. </para>
<tip>
<para
>Puoi sistemare lo schema di colori globale di &kde; nel modulo <ulink url="help:/kcontrol/colors/"
><quote
>Colori</quote
> delle &systemsettings;</ulink
>. In alcune applicazioni, tipo &kate; o &kdevelop;, puoi anche modificarlo individualmente dal menu <menuchoice
><guimenu
>Impostazioni</guimenu
><guisubmenu
>Schema di colori</guisubmenu
></menuchoice
>. </para>
</tip>
<sect3 id="color-themes-gui-new-theme">
<title
>Creare un nuovo tema</title>
<para
>Per creare un nuovo tema è necessario prima copiarne uno esistente. Selezionane uno che vuoi usare come base, ad esempio <quote
>Brezza chiaro</quote
> o <quote
>Brezza scuro</quote
>, e fai clic su <guibutton
>Copia</guibutton
>. Scrivi quindi il nome del nuovo tema. </para>
<para
>Se vuoi modificare un tema integrato o a sola lettura, è necessario prima copiarlo con un nome diverso.</para>
</sect3>
<sect3 id="color-themes-gui-import-export">
<title
>Importare o esportare i file di tema &JSON;</title>
<para
>Puoi esportare un tema selezionato (inclusi quelli incorporati) in un <link linkend="color-themes-json"
>file &JSON;</link
> con l'estensione <userinput
>.theme</userinput
> per mezzo del pulsante <guibutton
>Esporta</guibutton
>: si aprirà una finestra per salvare il file. Per aggiungere un tema di colori da un <link linkend="color-themes-json"
>file &JSON;</link
>, premi semplicemente il pulsante <guibutton
>Importa</guibutton
> e seleziona il file <userinput
>.theme</userinput
> dalla finestra. </para>
<tip>
<itemizedlist>
<listitem>
<para
>Come <link linkend="color-themes-json-overview"
>sopra menzionato</link
>, i file dei temi personalizzati dall'utente vengono salvati nella cartella <filename class="directory"
>org.kde.syntax-highlighting/themes/</filename
>: quando copi o crei un tema, esso apparirà automaticamente lì. Inoltre l'importazione o l'aggiunta di un tema equivale alla copia di un file <userinput
>.theme</userinput
> esterno in questa cartella. KSyntaxHighlighting preleva automaticamente i file dei temi di colori da questa cartella.</para>
</listitem>
<listitem>
<para
>Se vuoi pubblicare un tema creato da te è essenziale controllare l'oggetto dei <link linkend="color-themes-json-metadata"
>metadati</link
> del <link linkend="color-themes-json"
>file &JSON;</link
>, aggiungendo la rispettiva licenza e controllando il numero della revisione.</para>
</listitem>
</itemizedlist>
</tip>
</sect3>
<sect3 id="color-themes-gui-editing">
<title
>Modificare i temi di colori</title>
<sect4 id="prefcolors-colors">
<title
>Colori</title>
<para
>Qui vengono regolati i colori dell'area di modifica del testo. È spiegato nei dettagli in <xref linkend="color-themes-editor-colors"/>.</para>
</sect4>
<sect4 id="prefcolors-normal-text-styles">
<title
>Stili di testo predefiniti</title>
<para
>Gli stili di testo predefiniti sono ereditati dagli stili di evidenziazione del testo, permettendo all'editor di presentare il testo in modo coerente; ad esempio, il testo dei commenti è uguale in quasi tutti i formati di testo che KSyntaxHighlighting può evidenziare.</para>
<para
>Il nome della lista di stili usa lo stile configurato per tale elemento, fornendo un'anteprima quando si configura lo stile. </para>
<para
>Ogni stile permette di selezionare degli attributi comuni oltre ai colori di sfondo e di primo piano. Per rimuovere l'impostazione del colore di sfondo, fai clic con il &RMB; per usare il menu contestuale.</para>
<para
>Gli attributi di quest'area sono descritti in dettaglio in <xref linkend="color-themes-text-styles"/>.</para>
</sect4>
<sect4 id="prefcolors-highlighting-text-styles">
<title
>Stili di testo evidenziato</title>
<para
>Qui si possono modificare gli stili del testo usati per una specifica definizione di evidenziazione. L'editor preseleziona l'evidenziazione usata per il documento attuale. Per modificare un'evidenziazione diversa, selezionarne una dalla casella combinata <guilabel
>Evidenziazione</guilabel
> sopra l'elenco degli stili. </para>
<para
>Il nome della lista di stili usa lo stile configurato per tale elemento, fornendo un'anteprima quando si configura lo stile. </para>
<para
>Ogni stile permette di selezionare attributi comuni oltre ai colori di sfondo e di primo piano. Per deimpostare un colore di sfondo, fai clic con il &RMB; per usare il menu contestuale. Puoi inoltre vedere se uno stile è uguale a quello predefinito dell'elemento, e renderlo tale se non lo è.</para>
<para
>Noterai che molte evidenziazioni ne contengono altre, che sono rappresentate dai gruppi nell'elenco di stili. Ad esempio, la maggior parte delle evidenziazioni importano quella per Alert, e molte altre quella per Doxygen. La modifica dei colori di questi gruppi ha effetto sugli stili solo quando è usata nel formato di evidenziazione modificato. </para>
</sect4>
</sect3>
</sect2>
<sect2 id="color-themes-tips-and-tricks">
<title
>Suggerimenti e trucchi</title>
<sect3 id="color-themes-contrast">
<title
>Contrasto dei colori del testo</title>
<para
>Un aspetto importante quando si lavora coi temi di colori è quello di scegliere un contrasto del testo che renda più semplice la lettura, specialmente in combinazione con lo sfondo.</para>
<para
>L'applicazione <userinput
>Kontrast</userinput
> è un controllore del contrasto: ti dice se le combinazioni di colore del testo e dello sfondo sono leggibili e accessibili, quindi è un eccellente strumento che ti aiuta a creare i temi di colori.</para>
<para
>Puoi scaricare <userinput
>Kontrast</userinput
> dal <ulink url="https://apps.kde.org/en/kontrast"
>sito web delle applicazioni di &kde;</ulink
> o dal <ulink url="https://flathub.org/apps/details/org.kde.kontrast"
>pacchetto Flatpak su Flathub</ulink
> (solo in GNU/Linux).</para>
<para
>L'applicazione <userinput
>Contrast</userinput
> di GNOME è simile. Puoi scaricare <ulink url="https://flathub.org/apps/details/org.gnome.design.Contrast"
>il pacchetto Flatpak su Flathub</ulink
> (solo in GNU/Linux).</para>
</sect3>
<sect3 id="color-themes-tips-and-tricks-consistency">
<title
>Suggerimenti di consistenza per l'evidenziazione della sintassi</title>
<para
>KSyntaxHighlighting include <ulink url="https://kate-editor.org/syntax/"
>più di 300 definizioni di evidenziazione della sintassi</ulink
>, quindi dovresti assicurarti che il tuo nuovo tema vada bene con tutte le definizioni di evidenziazione della sintassi. I temi di colori integrati hanno le similarità seguenti, che è raccomandabile (ma non obbligatorio) seguire per ottenere una visualizzazione corretta di tutte le definizioni di evidenziazione della sintassi:</para>
<itemizedlist>
<listitem
><para
>Usa il grassetto per le <quote
>parole chiave</quote
> e per lo <link linkend="color-themes-text-styles"
>stili del testo</link
> del <quote
>flusso di controllo</quote
>.</para
></listitem>
<listitem
><para
>Non usare un colore di sfondo in nessuno degli <link linkend="color-themes-text-styles"
>stili di testo</link
>, tranne che in <quote
>Alert</quote
> e in <quote
>RegionMarker</quote
>.</para
></listitem>
</itemizedlist>
<para
>La maggior parte degli evidenziatori di sintassi serve per dare un bell'aspetto nei temi predefiniti, <quote
>Brezza chiaro</quote
> e <quote
>Brezza scuro</quote
>, quindi un altro modo per mantenere la consistenza è quello di usare dei colori simili negli <link linkend="color-themes-text-styles"
>stili di testo</link
>, ad esempio il <emphasis
>verde</emphasis
> per il <quote
>preprocessore</quote
> e <quote
>altri</quote
>, il <emphasis
>blu</emphasis
> per i <quote
>tipi di dato</quote
> e per gli <quote
>attributi</quote
>, oppure il <emphasis
>viola</emphasis
> per le <quote
>funzioni</quote
>.</para>
<para
>Nota che queste raccomandazioni non sono obbligatorie nella creazione e nella pubblicazione di un tema.</para>
</sect3>
</sect2>
</sect1>
<sect1 id="dev-scripting">
<title
>Scripting con &javascript;</title>
<para
>Il componente editor di &kappname; è facilmente estendibile attraverso degli script. Il linguaggio di script è ECMAScript (comunemente noto come &javascript;). &kappname; supporta due tipi di script: script di rientro e a riga di comando. </para>
<sect2 id="dev-scripting-indentation">
<title
>Script di rientro</title>
<para
>Gli script di rientro, noti anche come rientratori, fanno rientrare automaticamente il codice sorgente mentre si scrive. Per esempio, spesso il livello di rientro aumenta dopo aver premuto Invio. </para>
<para
>Le sezioni seguenti descrivono passo-passo come creare la struttura di un semplice rientratore. Come primo passo crea un nuovo file <filename
>*.js</filename
> chiamato ⪚ <filename
>javascript.js</filename
> nella cartella home locale <filename
>$<envar
>XDG_DATA_HOME</envar
>/katepart5/script/indentation</filename
>. Al suo interno la variabile di ambiente <envar
>XDG_DATA_HOME</envar
> viene tipicamente espansa sia in <filename
>~/.local</filename
> che in <filename
>~/.local/share</filename
>. </para>
<para
>In &Windows; questi file si trovano in <filename
>%USERPROFILE%\AppData\Local\katepart5\script\indentation</filename
>. <replaceable
>%USERPROFILE%</replaceable
> viene generalmente espanso in <filename
>C:\\Utenti\\<replaceable
>utente</replaceable
></filename
>.</para>
<sect3 id="dev-scripting-indentation-header">
<title
>L'intestazione dello script di rientro</title>
<para
>L'intestazione del file <filename
>javascript.js</filename
> è incorporata come &JSON; all'inizio del documento, e ha la forma seguente: <programlisting>
var katescript = {
"name": "JavaScript",
"author": "Pippo <pippo@topolinia.it>"
"license": "BSD License",
"revision": 1,
"kate-version": "5.1",
"required-syntax-style":"javascript",
"indent-languages": ["javascript"],
"priority": 0,
}; // kate-script-header, deve essere all'inizio della riga senza commenti
</programlisting
> Ogni voce viene ora spiegata in dettaglio: <itemizedlist>
<listitem
><para
><literal
>name</literal
> [obbligatorio]: questo è il nome del rientratore che appare nel menu <menuchoice
><guimenu
>Strumenti</guimenu
><guimenuitem
>Rientro</guimenuitem
></menuchoice
> e nella finestra di configurazione. </para
></listitem>
<listitem
><para
><literal
>author</literal
> [facoltativo]: il nome dell'autore e informazioni per contattarlo. </para
></listitem>
<listitem
><para
><literal
>license</literal
> [facoltativo]: forma breve della licenza, come Licenza BSD o LGPLv3. </para
></listitem>
<listitem
><para
><literal
>revision</literal
> [obbligatorio]: la revisione dello script. Questo numero va aumentato ad ogni sua modifica. </para
></listitem>
<listitem
><para
><literal
>kate-version</literal
> [obbligatorio]: versione minima di &kappname; richiesta. </para
></listitem>
<listitem
><para
><literal
>required-syntax-style</literal
> [facoltativo]: lo stile della sintassi richiesto, se soddisfa lo <literal
>stile</literal
> specificato nei file di evidenziazione della sintassi. È importante per i rientratori che richiedono informazioni di evidenziazione specifiche nel documento. Se uno stile di sintassi richiesto viene specificato, il rientratore è disponibile solo quando è attivo l'evidenziatore appropriato. Ciò impedisce il <quote
>comportamento non definito</quote
> causato dall'uso del rientratore senza lo schema di evidenziazione atteso. Per esempio, il rientratore di Ruby lo usa nei file <filename
>ruby.js</filename
> e <filename
>ruby.xml</filename
>. </para
></listitem>
<listitem
><para
><literal
>indent-languages</literal
> [facoltativo]: elenco &JSON; di stili di sintassi che il rientratore può far rientrare correttamente, ⪚: <literal
>["c++", "java"]</literal
>. </para
></listitem>
<listitem
><para
><literal
>priority</literal
> [facoltativo]: se ci sono più rientratori che si adattano a un certo file evidenziato la priorità decide quale viene scelto come predefinito. </para
></listitem>
</itemizedlist>
</para>
</sect3>
<sect3 id="dev-scripting-indentation-body">
<title
>Il codice sorgente del rientratore</title>
<para
>Dopo aver specificato l'intestazione, questa sezione spiega come funziona lo script di rientro vero e proprio. La struttura fondamentale ha questo aspetto: <programlisting>
// librerie katepart js necessarie, ⪚ range.js se usi Range
require ("range.js");
triggerCharacters = "{}/:;";
function indent(riga, larghezza_rientro, carattere)
{
// richiamato a ogni ritorno a capo (<varname
>carattere</varname
> == '\n') e per tutti i caratteri
// specificati nella in variabile globale triggerCharacters. Quando si chiama
// <menuchoice
><guimenu
>Strumenti</guimenu
><guimenuitem
>Rientro formato</guimenuitem
></menuchoice>
// la variabile <varname
>carattere</varname
> è vuota, cioè <varname
>caratteri</varname
> == ''.
//
// Vedi anche: API di scripting
return -2;
}
</programlisting
> La funzione <function
>indent()</function
> ha tre argomenti:<itemizedlist
><listitem
><para
><literal
>riga</literal
>: la riga da far rientrare;</para
></listitem
> <listitem
><para
><literal
>larghezza_rientro</literal
>: la larghezza del rientro espressa come numero di spazi;</para
></listitem
> <listitem
><para
><literal
>carattere</literal
>: un carattere di ritorno a capo (<varname
>carattere</varname
> == '\n'), un carattere di attivazione specificato in <varname
>triggerCharacters</varname
>, o vuota se l'utente ha attivato l'azione <menuchoice
><guimenu
>Strumenti</guimenu
><guimenuitem
>Rientro formato</guimenuitem
></menuchoice
>.</para
></listitem
> </itemizedlist
> Il valore restituito dalla funzione <function
>indent()</function
> specifica come far rientrare la riga. Se il valore è un semplice numero intero, viene interpretato come segue: <itemizedlist
> <listitem
><para
>Valore restituito <returnvalue
>-2</returnvalue
>: non fare nulla;</para
></listitem
><listitem
><para
>Valore restituito <returnvalue
>-1</returnvalue
>: mantieni il rientro (cerca una riga non vuota precedente)</para
></listitem
><listitem
><para
>Valore restituito <returnvalue
>0</returnvalue
>: I numeri numbers ≥ 0 specificano il rientro in spazi</para
></listitem
></itemizedlist
>In alternativa, si può restituire un array di due elementi: <itemizedlist
><listitem
><para
><userinput
>return <returnvalue
>[ indent, align ]</returnvalue
>;</userinput
></para
></listitem
></itemizedlist
> In questo caso, il primo elemento è il rientro, con lo stesso significato di cui sopra. Il secondo elemento, invece, è un valore assoluto che rappresenta una colonna di <quote
>allineamento</quote
>. Se questo valore è maggiore del valore di rientro, la differenza rappresenta un numero di spazi da aggiungere dopo il rientro della prima variabile. Altrimenti, il secondo numero viene ignorato. Usare sia tabulatori che spazi per il rientro viene spesso indicato come <quote
>modalità mista</quote
>. </para>
<para
>Considera il seguente esempio: supponiamo di usare le tabulazioni per il rientro, e la loro ampiezza è impostata a 4. Qui, <tab> indica una tabulazione e «.» uno spazio: <programlisting>
1: <tab><tab>pippo("ciao",
2: <tab><tab>......"mondo");
</programlisting
> Quando si fa rientrare la seconda riga, la funzione <function
>indent()</function
> restituisce <returnvalue
>[8, 15]</returnvalue
>. Perciò, si inseriscono due tabulazioni per far rientrare fino alla colonna 8, e vengono aggiunti sette spazi per allineare il secondo argomento al primo, in modo che rimanga allineato se il file viene visualizzato con un'ampiezza di tabulazione diversa. </para>
<para
>Un'installazione predefinita di &kde; include &kappname; con diversi rientratori. Il codice &javascript; corrispondente si può trovare in <filename
>$<envar
>XDG_DATA_DIRS</envar
>/katepart5/script/indentation</filename
>.</para>
<para
>In &Windows; questi file si trovano in <filename
>%USERPROFILE%\AppData\Local\katepart5\script\indentation</filename
>. <replaceable
>%USERPROFILE%</replaceable
> viene generalmente espanso in <filename
>C:\\Utenti\\<replaceable
>utente</replaceable
></filename
>. </para>
<para
>Lo sviluppo di un rientratore richiede il ricaricamento gli script, per testare le modifiche. Invece di riavviare l'applicazione puoi però passare alla riga di comando, e digitare il comando <command
>reload-scripts</command
>. </para>
<para
>Se sviluppi degli script utili, per piacere considera la possibilità di contribuirli al progetto &kappname; <ulink url="mailto:kwrite-devel@kde.org"
>contattando la lista di distribuzione</ulink
>. </para>
</sect3>
</sect2>
<sect2 id="dev-scripting-command-line">
<title
>Script da riga di comando</title>
<para
>Essendo difficile soddisfare le necessità di tutti, &kappname; supporta dei piccoli strumenti di supporto per manipolare velocemente il testo attraverso la <link linkend="advanced-editing-tools-commandline"
>riga di comando integrata</link
>. Per esempio, il comando <command
>sort</command
> è implementato come uno script. Questa sezione spiega come creare file <literal role="extension"
>*.js</literal
> per estendere &kappname; con script di supporto a piacere. </para>
<para
>Gli script da riga di comando si trovano nella stessa cartella degli script di rientro. Come primo passo, crea un nuovo file <filename
>*.js</filename
> chiamato <filename
>myutils.js</filename
> nella home locale <filename
>$<envar
>XDG_DATA_HOME</envar
>/katepart5/script/commands</filename
>. Al suo interno la variabile di ambiente <envar
>XDG_DATA_HOME</envar
> viene tipicamente espansa sia in <filename
>~/.local</filename
> che in <filename
>~/.local/share</filename
>.</para>
<para
>In &Windows; questi file si trovano in <filename
>%USERPROFILE%\AppData\Local\katepart5\script\commands</filename
>. <replaceable
>%USERPROFILE%</replaceable
> viene generalmente espanso in <filename
>C:\\Utenti\\<replaceable
>utente</replaceable
></filename
>. </para>
<sect3 id="dev-scripting-command-line-header">
<title
>L'intestazione dello script per la riga di comando</title>
<para
>L'intestazione di ciascuno script da riga di comando è incorporata in &JSON; all'inizio dello script come segue: <programlisting>
var katescript = {
"author": "Example Name <example.name@some.address.org>",
"license": "LGPLv2+",
"revision": 1,
"kate-version": "5.1",
"functions": ["sort", "moveLinesDown"],
"actions": [
{ "function": "sort",
"name": "Ordina il testo selezionato",
"category": "Editing",
"interactive": "false"
},
{ "function": "moveLinesDown",
"name": "Sposta le righe in basso",
"category": "Editing",
"shortcut": "Ctrl+Shift+Down",
"interactive": "false"
}
]
}; // l'intestazione dello script di kate deve essere all'inizio del file senza commento
</programlisting
> Ciascuna voce è spiegata ora in dettaglio: <itemizedlist>
<listitem
><para
><literal
>author</literal
> [facoltativo]: il nome dell'autore e informazioni per contattarlo.</para
></listitem>
<listitem
><para
><literal
>license</literal
> [facoltativo]: forma breve della licenza, come Licenza BSD o LGPLv2.</para
></listitem>
<listitem
><para
><literal
>revision</literal
> [obbligatorio]: la revisione dello script. Questo numero va aumentato ad ogni sua modifica.</para
></listitem>
<listitem
><para
><literal
>kate-version</literal
> [obbligatorio]: versione minima di &kappname; richiesta.</para
></listitem>
<listitem
><para
><literal
>functions</literal
> [obbligatorio]: vettore &JSON; di comandi nello script.</para
></listitem>
<listitem
><para
><literal
>actions</literal
> [opzionale]: un vettore &JSON; di oggetti &JSON; che definiscono le azioni che appaiono nel menu dell'applicazione. Informazioni dettagliate sono fornite nella sezione <link linkend="advanced-editing-tools-commandline"
>Stabilire le scorciatoie</link
>.</para
></listitem>
</itemizedlist>
</para>
<para
>Dal momento che il valore di <literal
>functions</literal
> è un vettore &JSON;, un singolo script può contenere un numero arbitrario di comandi per la riga di comando. Ciascuna funzione è disponibile attraverso il menu <link linkend="advanced-editing-tools-commandline"
>riga di comando integrata</link
> di &kappname;. </para>
</sect3>
<sect3 id="dev-scripting-command-line-body">
<title
>Il codice sorgente dello script</title>
<para
>Tutte le funzioni specificate nell'intestazione devono essere implementate nello script. Lo script nell'esempio qui sopra deve implementare le due funzioni <command
>sort</command
> e <command
>moveLinesDown</command
>. Tutte le funzioni hanno la sintassi seguente: <programlisting
>// librerie katepart js necessarie, ⪚ range.js se usi Range
require ("range.js");
function <nome>(argomento_1, argomento_2, ...)
{
// ... implementazione, vedi anche: API per gli script
}
</programlisting>
</para>
<para
>Gli argomenti nella riga di comando vengono passati alla funzione come <parameter
>argomento_1</parameter
>, <parameter
>argomento_2</parameter
>, &etc; Per poter documentare ogni comando, basta implementare la funzione <function
>help</function
> come segue: <programlisting>
function help(comando)
{
if (comando == "sort") {
return i18n("Ordina il testo selezionato.");
} else if (comando == "...") {
// ...
}
}
</programlisting
> Eseguire quindi <command
>help sort</command
> nella riga di comando chiamerà questa funzione ausiliaria con l'argomento <parameter
>comando</parameter
> impostato al comando dato, &ie; <parameter
>comando == "sort"</parameter
>. &kappname; presenterà quindi il testo risultante come documentazione per l'utente. Assicurati di <link linkend="dev-scripting-api-i18n"
>tradurre le stringhe</link
>. </para>
<para
>Lo sviluppo di uno script da riga di comando richiede il ricaricamento gli script stesso, per testare le modifiche. Invece di riavviare l'applicazione puoi però passare alla riga di comando, e digitare il comando <command
>reload-scripts</command
>. </para>
<sect4 id="dev-scripting-command-line-shortcuts">
<title
>Stabilire le scorciatoie</title>
<para
>Per rendere gli script accessibili nel menu dell'applicazione e per potergli assegnare delle scorciatoie, gli script devono fornire un'appropriata intestazione. Nell'esempio sottostante entrambe le funzioni <literal
>sort</literal
> e <literal
>moveLinesDown</literal
> appaiono nel menu grazie alla seguente parte dell'intestazione dello script: <programlisting>
var katescript = {
...
"actions": [
{ "function": "sort",
"name": "Ordina il testo selezionato",
"icon": "",
"category": "Editing",
"interactive": "false"
},
{ "function": "moveLinesDown",
"name": "Sposta le righe in basso",
"icon": "",
"category": "Editing",
"shortcut": "Ctrl+Shift+Down",
"interactive": "false"
}
]
};
</programlisting
> I campi necessari sono i seguenti: <itemizedlist>
<listitem
><para
><literal
>function</literal
> [obbligatorio]: la funzione che dovrebbe comparire nel menu <menuchoice
><guimenu
>Strumenti</guimenu
><guisubmenu
>Script</guisubmenu
></menuchoice
>.</para
></listitem>
<listitem
><para
><literal
>name</literal
> [obbligatorio]: il testo che compare nel menu script.</para
></listitem>
<listitem
><para
><literal
>icon</literal
> [facoltativo]: l'icona che appare di fianco al testo nel menu. Qui si possono usare tutti i nomi delle icone di &kde;.</para
></listitem>
<listitem
><para
><literal
>category</literal
> [facoltativo]: se si specifica una categoria, lo script compare in un sottomenu.</para
></listitem>
<listitem
><para
><literal
>shortcut</literal
> [facoltativo]: la scorciatoia qui data è la predefinita, per esempio <literal
>Ctrl+Alt+t</literal
>. Vedi la <ulink url="https://doc.qt.io/qt-5/qt.html#Key-enum"
>documentazione di &Qt;</ulink
> per maggiori dettagli.</para
></listitem>
<listitem
><para
><literal
>interactive</literal
> [facoltativo]: impostalo a <literal
>true</literal
> se allo script serve che l'utente faccia qualcosa.</para
></listitem>
</itemizedlist>
</para>
<para
>Se sviluppi degli script utili, per piacere considera la possibilità di contribuirli al progetto &kappname; <ulink url="mailto:kwrite-devel@kde.org"
>contattando la lista di distribuzione</ulink
>. </para>
</sect4>
</sect3>
</sect2>
<sect2 id="dev-scripting-api">
<title
>API per gli script</title>
<para
>L'API per script qui presentata è disponibile in tutti gli script, cioè gli script di rientro e i comandi da riga di comando. Le classi <classname
>Cursor</classname
> e <classname
>Range</classname
> sono fornite dalle librerie presenti in <filename
>$<envar
>XDG_DATA_DIRS</envar
>/katepart5/libraries</filename
>. Se le vuoi usare nel tuo script, il che è necessario per usare alcune delle funzioni di <classname
>Document</classname
> o <classname
>View</classname
>, includi la libreria necessaria con: <programlisting
>// librerie katepart js necessarie, ⪚ range.js se usi Range
require ("range.js");
</programlisting>
</para>
<para
>Per estendere l'API standard per gli script con funzioni e prototipi propri basta creare un nuovo file nella cartella di configurazione locale di &kde;, <filename
>$<envar
>XDG_DATA_HOME</envar
>/katepart5/libraries</filename
>, e includerlo nel tuo script con: <programlisting
>require ("nome_del_mio_script.js");
</programlisting>
</para>
<para
>In &Windows; questi file si trovano in <filename
>%USERPROFILE%\AppData\Local\katepart5\libraries</filename
>. <replaceable
>%USERPROFILE%</replaceable
> viene generalmente espanso in <filename
>C:\\Utenti\\<replaceable
>utente</replaceable
></filename
>.</para>
<para
>Per estendere i prototipi preesistenti, come <classname
>Cursor</classname
> o <classname
>Range</classname
>, il modo raccomandato di procedere <emphasis
>non</emphasis
> è di modificare i file <literal role="extension"
>*.js</literal
> globali. Cambia piuttosto il prototipo <classname
>Cursor</classname
> in &javascript; dopo aver incluso <filename
>cursor.js</filename
> nello script con <literal
>require</literal
>. </para>
<sect3 id="dev-scripting-api-prototypes">
<title
>Cursori e intervalli</title>
<para
>Essendo &kappname; un editor di testo, tutta l'API per gli script si basa, ovunque sia possibile, su cursori e intervalli. Un cursore (<classname
>Cursor</classname
>) è una semplice tupla del tipo <literal
>(riga, colonna)</literal
> che rappresenta una posizione nel testo del documento. Un intervallo (<classname
>Range</classname
>) si estende sul testo a partire da una posizione di partenza a una finale del cursore. L'API viene spiegata in dettaglio nelle sezioni seguenti. </para>
<sect4 id="dev-scripting-api-cursors">
<title
>Il prototipo dei cursori</title>
<variablelist
><varlistentry>
<term
><synopsis
>Cursor();
</synopsis
></term>
<listitem
><para
>Costruttore. Restituisce un cursore alla posizione <literal
>(0, 0)</literal
>.</para>
<para
>Esempio: <function
>var cursore = new Cursor();</function
> </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>Cursor(<parameter
>int <replaceable
>riga</replaceable
></parameter
>, <parameter
>int <replaceable
>colonna</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Costruttore. Restituisce un cursore alla posizione <literal
>(riga, colonna)</literal
>. </para>
<para
>Esempio: <function
>var cursore = new Cursor(3, 42);</function
> </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>Cursor(<parameter
>Cursor <replaceable
>altro</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Costruttore di copia. Restituisce una copia dell'<replaceable
>altro</replaceable
> cursore. </para>
<para
>Esempio: <function
>var copia = new Cursor(altro);</function
> </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>Cursor Cursor.clone();
</synopsis
></term>
<listitem
><para
>Restituisce un clone del cursore.</para>
<para
>Esempio: <function
>var clone = cursor.clone();</function
> </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>Cursor.setPosition(<parameter
>int <replaceable
>riga</replaceable
></parameter
>, <parameter
>int <replaceable
>colonna</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Imposta la posizione del cursore a <replaceable
>riga</replaceable
> e <replaceable
>colonna</replaceable
>.</para>
<para
>Da: &kde; 4.11 </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>bool Cursor.isValid();
</synopsis
></term>
<listitem
><para
>Controlla se il cursore è valido. Non lo è se la riga o la colonna sono impostate a <literal
>-1</literal
>. </para>
<para
>Esempio: <function
>var valido = cursor.isValid();</function
> </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>Cursor Cursor.invalid();
</synopsis
></term>
<listitem
><para
>Restituisce un nuovo cursore non valido posizionato a <literal
>(-1, -1)</literal
>. </para>
<para
>Esempio: <function
>var cursoreNonValido = cursor.invalid();</function
> </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>int Cursor.compareTo(<parameter
>Cursor <replaceable
>altro</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Confronta un cursore con un <replaceable
>altro</replaceable
>. Restituisce: <itemizedlist>
<listitem
><para
><literal
>-1</literal
>, se il cursore è posizionato prima dell'<replaceable
>altro</replaceable
>,</para
></listitem>
<listitem
><para
><literal
>0</literal
>, se sono uguali, e</para
></listitem>
<listitem
><para
><literal
>+1</literal
>, se il cursore è posizionato dopo l'<replaceable
>altro</replaceable
>.</para
></listitem>
</itemizedlist>
</para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>bool Cursor.equals(<parameter
>Cursor <replaceable
>altro</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Restituisce <literal
>true</literal
> se il cursore e l'<replaceable
>altro</replaceable
> sono uguali, altrimenti <literal
>false</literal
>. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>String Cursor.toString();
</synopsis
></term>
<listitem
><para
>Restituisce un cursore sotto forma di stringa nella forma <quote
><literal
>Cursor(riga, colonna)</literal
></quote
>. </para
></listitem>
</varlistentry
></variablelist>
</sect4>
<sect4 id="dev-scripting-api-ranges">
<title
>Il prototipo degli intervalli</title>
<variablelist
><varlistentry>
<term
><synopsis
>Range();
</synopsis
></term>
<listitem
><para
>Costruttore. Chiamare <userinput
>new Range()</userinput
> restituisce un intervallo tra <literal
>(0, 0)</literal
> e <literal
>(0, 0)</literal
>. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>Range(<parameter
>Cursor <replaceable
>inizio</replaceable
></parameter
>, <parameter
>Cursor <replaceable
>fine</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Costruttore. Chiamare <literal
>new Range(<replaceable
>inizio</replaceable
>, <replaceable
>fine</replaceable
>)</literal
> restituisce l'intervallo (<replaceable
>inizio</replaceable
>, <replaceable
>fine</replaceable
>). </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>Range(<parameter
>int <replaceable
>riga_inizio</replaceable
></parameter
>, <parameter
>int <replaceable
>colonna_inizio</replaceable
></parameter
>, <parameter
>int <replaceable
>riga_fine</replaceable
></parameter
>, <parameter
>int <replaceable
>colonna_fine</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Costruttore. Chiamare <literal
>new Range(<replaceable
>riga_inizio</replaceable
>, <replaceable
>colonna_inizio</replaceable
>, <replaceable
>riga_fine</replaceable
>, <replaceable
>colonna_fine</replaceable
>)</literal
> restituisce l'intervallo da (<replaceable
>riga_inizio</replaceable
>, <replaceable
>colonna_inizio</replaceable
>) a (<replaceable
>riga_fine</replaceable
>, <replaceable
>colonna_fine</replaceable
>). </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>Range(<parameter
>Range <replaceable
>altro</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Costruttore di copia. Restituisce una copia dell'<replaceable
>altro</replaceable
> intervallo. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>Range Range.clone();
</synopsis
></term>
<listitem
><para
>Restituisce un clone dell'intervallo. </para>
<para
>Esempio: <function
>var clone = range.clone();</function
> </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>bool Range.isEmpty();
</synopsis
></term>
<listitem
><para
>Restituisce <literal
>true</literal
> se i cursori di inizio e fine sono uguali. </para>
<para
>Esempio: <function
>var empty = range.isEmpty();</function
> </para>
<para
>Da: &kde; 4.11 </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>bool Range.isValid();
</synopsis
></term>
<listitem
><para
>Restituisce <literal
>true</literal
> se entrambi i cursori, iniziale e finale, sono validi, altrimenti <literal
>false</literal
>. </para>
<para
>Esempio: <function
>var valido = range.isValid();</function
> </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>Range Range.invalid();
</synopsis
></term>
<listitem
><para
>Restituisce l'intervallo da (-1, -1) a (-1, -1). </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>bool Range.contains(<parameter
>Cursor <replaceable
>cursore</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Restituisce <literal
>true</literal
> se l'intervallo contiene la posizione del cursore, altrimenti <literal
>false</literal
>. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>bool Range.contains(<parameter
>Range <replaceable
>altro</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Restituisce <literal
>true</literal
> se l'intervallo contiene l'<replaceable
>altro</replaceable
>, altrimenti <literal
>false</literal
>. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>bool Range.containsColumn(<parameter
>int <replaceable
>colonna</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Restituisce <literal
>true</literal
> se la <replaceable
>colonna</replaceable
> è nell'intervallo semiaperto <literal
>[inizio.colonna, fine.colonna)</literal
>, altrimenti <literal
>false</literal
>. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>bool Range.containsLine(<parameter
>int <replaceable
>riga</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Restituisce <literal
>true</literal
> se la <replaceable
>riga</replaceable
> è nell'intervallo semiaperto <literal
>[inizio.riga, fine.riga)</literal
>, altrimenti <literal
>false</literal
>. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>bool Range.overlaps(<parameter
>Range <replaceable
>altro</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Restituisce <literal
>true</literal
> se l'intervallo e l'<replaceable
>altro</replaceable
> hanno una regione in comune, altrimenti <literal
>false</literal
>. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>bool Range.overlapsLine(<parameter
>int <replaceable
>riga</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Restituisce <literal
>true</literal
> se la <replaceable
>riga</replaceable
> è nell'intervallo <literal
>[inizio.riga, fine.riga]</literal
>, altrimenti <literal
>false</literal
>. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>bool Range.overlapsColumn(<parameter
>int <replaceable
>colonna</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Restituisce <literal
>true</literal
> se la <replaceable
>colonna</replaceable
> è nell'intervallo <literal
>[inizio.colonna, fine.colonna]</literal
>, altrimenti <literal
>false</literal
>. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>bool Range.onSingleLine();
</synopsis
></term>
<listitem
><para
>Restituisce <literal
>true</literal
> se l'intervallo comincia e finisce sulla stessa riga, &ie; se <replaceable
>Range.start.line == Range.end.line</replaceable
>. </para>
<para
>Da: &kde; 4.9 </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>bool Range.equals(<parameter
>Range <replaceable
>altro</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Restituisce <literal
>true</literal
> se l'intervallo e l'<replaceable
>altro</replaceable
> sono uguali, altrimenti <literal
>false</literal
>. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>String Range.toString();
</synopsis
></term>
<listitem
><para
>Restituisce un intervallo sotto forma di stringa nella forma <quote
><literal
>Range(Cursor(riga, colonna), Cursor(riga, colonna))</literal
></quote
>. </para
></listitem>
</varlistentry
></variablelist>
</sect4>
</sect3>
<sect3 id="dev-scripting-api-global">
<title
>Funzioni globali</title>
<para
>Questa sezione elenca tutte le funzioni globali.</para>
<sect4 id="dev-scripting-api-includes">
<title
>Leggere e includere file</title>
<variablelist
><varlistentry>
<term
><synopsis
>String read(<parameter
>String <replaceable
>file</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Cercherà nel <replaceable
>file</replaceable
> dato, relativamente alla cartella <literal
>katepart5/script/files</literal
>, e ne restituirà i contenuti in forma di stringa. </para
></listitem>
</varlistentry
></variablelist>
<variablelist
><varlistentry>
<term
><synopsis
>void require(<parameter
>String <replaceable
>file</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Cercherà nel <replaceable
>file</replaceable
> dato, relativamente alla <literal
>katepart5/script/libraries</literal
>, e lo valuterà. <literal
>require</literal
> è già programmato per evitare inclusioni multiple dello stesso <replaceable
>file</replaceable
>. </para>
<para
>Da: &kde; 4.10 </para>
</listitem>
</varlistentry
></variablelist>
</sect4>
<sect4 id="dev-scripting-api-debug">
<title
>Debug</title>
<variablelist
><varlistentry>
<term
><synopsis
>void debug(<parameter
>String <replaceable
>testo</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Stampa il <replaceable
>testo</replaceable
> su <literal
>stdout</literal
> nella console che ha avviato l'applicazione. </para
></listitem>
</varlistentry
></variablelist>
</sect4>
<sect4 id="dev-scripting-api-i18n">
<title
>Traduzione</title>
<para
>Per supportare una localizzazione completa ci sono diverse funzioni per tradurre le stringhe negli script, cioè <literal
>i18n</literal
>, <literal
>i18nc</literal
>, <literal
>i18np</literal
> e <literal
>i18ncp</literal
>. Queste funzioni si comportano esattamente come le <ulink url="https://techbase.kde.org/Development/Tutorials/Localization/i18n"
>funzioni di traduzione di &kde;</ulink
>. </para>
<para
>Le funzioni traducono le stringhe incluse con il sistema di traduzione di &kde; nella lingua usata nell'applicazione. Le stringhe negli script sviluppati nel codice sorgente ufficiale di &kappname; sono automaticamente estratte e traducibili: in altre parole gli sviluppatori di &kappname; non devono preoccuparsi di estrarre e tradurre i messaggi. Va anche notato, però, che la traduzione funziona solo all'interno dell'infrastruttura di &kde;: &ie; nuove stringhe negli script di terze parti sviluppati al di fuori di &kde; non sarebbero tradotte. Tuttavia prendi in considerazione l'idea di contribuire con i tuoi script a &kate;, in modo che sia possibile una traduzione appropriata. </para>
<variablelist
><varlistentry>
<term
><synopsis
>void i18n(<parameter
>String <replaceable
>testo</replaceable
></parameter
>, <replaceable
>argomento_1</replaceable
>, ... );
</synopsis
></term>
<listitem
><para
>Traduce <replaceable
>testo</replaceable
> nella lingua usata dall'applicazione. Gli argomenti <replaceable
>argomento_1</replaceable
> e seguenti sono facoltativi e vengono usati per sostituire i segnaposti <literal
>%1</literal
>, <literal
>%2</literal
>, &etc;.</para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>void i18nc(<parameter
>String <replaceable
>contesto</replaceable
></parameter
>, <parameter
>String <replaceable
>testo</replaceable
></parameter
>, <replaceable
>argomento_1</replaceable
>, ... );
</synopsis
></term>
<listitem
><para
>Traduce <replaceable
>testo</replaceable
> nella lingua usata dall'applicazione. Inoltre, la stringa <replaceable
>contesto</replaceable
> viene resa visibile ai traduttori, per chiarire eventuali equivoci e produrre una traduzione migliore. Gli argomenti <replaceable
>argomento_1</replaceable
> e seguenti sono facoltativi, e vengono usati per sostituire i segnaposti <literal
>%1</literal
>, <literal
>%2</literal
> &etc;.</para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>void i18np(<parameter
>String <replaceable
>singolare</replaceable
></parameter
>, <parameter
>String <replaceable
>plurale</replaceable
></parameter
>, <parameter
>int <replaceable
>numero</replaceable
></parameter
>, <replaceable
>argomento_1</replaceable
>, ... );
</synopsis
></term>
<listitem
><para
>Traduce <replaceable
>singolare</replaceable
> o <replaceable
>plurale</replaceable
> nella lingua usata dall'applicazione, a seconda del <replaceable
>numero</replaceable
> dato. Gli argomenti <replaceable
>argomento_1</replaceable
> e seguenti sono facoltativi, e vengono usati per sostituire i segnaposti <literal
>%1</literal
>, <literal
>%2</literal
> &etc;.</para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>void i18ncp(<parameter
>String <replaceable
>contesto</replaceable
></parameter
>, <parameter
>String <replaceable
>singolare</replaceable
></parameter
>, <parameter
>String <replaceable
>plurale</replaceable
></parameter
>, <parameter
>int <replaceable
>numero</replaceable
></parameter
>, <replaceable
>argomento_1</replaceable
>, ... );
</synopsis
></term>
<listitem
><para
>Traduce <replaceable
>singolare</replaceable
> o <replaceable
>plurale</replaceable
> nella lingua usata dall'applicazione, a seconda del <replaceable
>numero</replaceable
> dato. Inoltre la stringa <replaceable
>contesto</replaceable
> viene resa visibile ai traduttori, per chiarire eventuali equivoci e produrre una traduzione migliore. Gli argomenti <replaceable
>argomento_1</replaceable
> e seguenti sono facoltativi, e vengono usati per sostituire i segnaposti <literal
>%1</literal
>, <literal
>%2</literal
> &etc;.</para
></listitem>
</varlistentry
></variablelist>
</sect4>
</sect3>
<sect3 id="dev-scripting-api-view">
<title
>API della vista</title>
<para
>Ogni volta che uno script viene eseguito è presente una variabile globale, <quote
><literal
>view</literal
></quote
>, che rappresenta la vista attiva dell'editor. Segue un elenco di tutte le funzioni di vista disponibili. <variablelist>
<varlistentry>
<term
><synopsis
><function
>void view.copy()</function
>
</synopsis
></term>
<listitem>
<para
>Taglia la selezione, se ce n'è una, altrimenti l'intera riga se è stata spuntata l'opzione <userinput
>[ ] Copia o taglia la riga attuale se non c'è una selezione</userinput
>.</para>
<para
>Da: &kde-frameworks; 5.79</para>
</listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
><function
>void view.cut()</function
>
</synopsis
></term>
<listitem>
<para
>Taglia la selezione, se ce n'è una, altrimenti l'intera riga se è stata spuntata l'opzione <userinput
>[ ] Copia o taglia la riga attuale se non c'è una selezione</userinput
>.</para>
<para
>Da: &kde-frameworks; 5.79</para>
</listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
><function
>void view.paste()</function
>
</synopsis
></term>
<listitem>
<para
>Incolla il contenuto degli appunti.</para>
<para
>Da: &kde-frameworks; 5.79</para>
</listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
><function
>Cursor view.cursorPosition()</function
>
</synopsis
></term>
<listitem
><para
>Restituisce la posizione attuale del cursore nella vista.</para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>void view.setCursorPosition(<parameter
>int <replaceable
>riga</replaceable
></parameter
>, <parameter
>int <replaceable
>colonna</replaceable
></parameter
>);
void view.setCursorPosition(<parameter
>Cursor <replaceable
>cursore</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Imposta la posizione attuale del cursore a <literal
>(<replaceable
>riga</replaceable
>, <replaceable
>colonna</replaceable
>)</literal
> o al <replaceable
>cursore</replaceable
> dato. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>Cursor view.virtualCursorPosition();
</synopsis
></term>
<listitem
><para
>Restituisce la posizione virtuale del cursore con ogni tabulazione che conta una quantità di spazi dipendente dall'attuale ampiezza di tabulazione. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>void view.setVirtualCursorPosition(<parameter
>int <replaceable
>riga</replaceable
></parameter
>, <parameter
>int <replaceable
>colonna</replaceable
></parameter
>);
void view.setVirtualCursorPosition(<parameter
>Cursor <replaceable
>cursore</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Imposta la posizione virtuale attuale del cursore a <literal
>(<replaceable
>riga</replaceable
>, <replaceable
>colonna</replaceable
>)</literal
> o al <replaceable
>cursore</replaceable
> dato. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>String view.selectedText();
</synopsis
></term>
<listitem
><para
>Restituisce il testo selezionato. Se non c'è del testo selezionato, la stringa restituita è vuota. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>bool view.hasSelection();
</synopsis
></term>
<listitem
><para
>Restituisce <literal
>true</literal
> se la vista contiene del testo selezionato, altrimenti <literal
>false</literal
>. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>Range view.selection();
</synopsis
></term>
<listitem
><para
>Restituisce l'intervallo di testo selezionato. L'intervallo di testo non è valido se non c'è testo selezionato. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>void view.setSelection(<parameter
>Range <replaceable
>intervallo</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Imposta il testo selezionato all'<replaceable
>intervallo</replaceable
> dato. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>void view.removeSelectedText();
</synopsis
></term>
<listitem
><para
>Rimuove il testo selezionato. Se la vista non ne ha non fa nulla. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>void view.selectAll();
</synopsis
></term>
<listitem
><para
>Seleziona tutto il testo del documento. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>void view.clearSelection();
</synopsis
></term>
<listitem
><para
>Pulisce la selezione di testo senza rimuoverlo. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>void view.setBlockSelection(bool on);
</synopsis
></term>
<listitem
><para
>Attiva o disattiva la modalità di selezione a blocchi. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>bool view.blockSelection();
</synopsis
></term>
<listitem
><para
>Restituisce <literal
>true</literal
> se la modalità di selezione a blocchi è attivata, altrimenti <literal
>false</literal
>. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>void view.align(<parameter
>Range <replaceable
>intervallo</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Fa rientrare nuovamente le righe che si trovano nell'<replaceable
>intervallo</replaceable
> in base alle impostazioni di rientro correnti. </para>
</listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>void view.alignOn(<parameter
>Range <replaceable
>intervallo</replaceable
></parameter
>, <parameter
>String <replaceable
>modello</replaceable
> = ""</parameter
>);
</synopsis
></term>
<listitem
><para
>Allinea le righe in <replaceable
>intervallo</replaceable
> alla colonna data dall'espressione regolare <replaceable
>modello</replaceable
>. Con un <replaceable
>modello</replaceable
> vuoto, per impostazione predefinita allineerà al primo carattere non di spazio. Se il modello ha una cattura, rientrerà </para>
<para
><emphasis
>Esempi:</emphasis
></para>
<para
><literal
>view.alignOn(document.documentRange(), '-');</literal
> inserirà degli spazi prima del primo <literal
>-</literal
> di ogni riga per allinearle nella stessa colonna.</para>
<para
><literal
>view.alignOn(document.documentRange(), ':\\s+(.)');</literal
> inserirà degli spazi prima del primo carattere non di spazio che ricorre dopo i due punti per allinearle nella stessa colonna.</para>
</listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>object view.executeCommand(<parameter
>String <replaceable
>comando</replaceable
></parameter
>,
<parameter
>String <replaceable
>argomenti</replaceable
></parameter
>,
<parameter
> <replaceable
>intervallo</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Esegue il <link linkend="advanced-editing-tools-commandline"
>comando per la riga di comando</link
> <replaceable
>comando</replaceable
> con gli argomenti opzionali <replaceable
>argomenti</replaceable
> e con l'opzionale <replaceable
>intervallo</replaceable
>. L'<replaceable
>oggetto</replaceable
> restituito ha la proprietà booleana <replaceable
>oggetto.ok</replaceable
>, che indica che l'esecuzione del <replaceable
>comando</replaceable
> ha avuto successo. In caso di errori, la stringa <replaceable
>oggetto.status</replaceable
> contiene un messaggio di errore. </para>
<para
>Da: &kde-frameworks; 5.50</para>
</listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>Range view.searchText(<parameter
>Range <replaceable
>intervallo</replaceable
></parameter
>,
<parameter
>String <replaceable
>modello</replaceable
></parameter
>,
<parameter
>bool <replaceable
>backwards</replaceable
> = false</parameter
>);
</synopsis
></term>
<listitem
><para
>Cerca la prima occorrenza di <replaceable
>modello</replaceable
> in <replaceable
>intervallo</replaceable
> e restituisce l'intervallo corrispondente. La ricerca viene eseguita all'indietro se il parametro booleano <replaceable
>backwards</replaceable
> è impostato a <literal
>true</literal
>. </para>
<para
>L'intervallo restituito non è valido (vedi Range.isValid()) se <replaceable
>modello</replaceable
> non viene trovato in <replaceable
>intervallo</replaceable
>. </para>
<para
>Da: &kde-frameworks; 5.97</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</sect3>
<sect3 id="dev-scripting-api-document">
<title
>API del documento</title>
<para
>Ogni volta che uno script viene eseguito è presente una variabile globale, <quote
><literal
>document</literal
></quote
>, che rappresenta il documento attivo. Segue un elenco di tutte le funzioni del documento disponibili. <variablelist>
<varlistentry>
<term
><synopsis
>String document.fileName();
</synopsis
></term>
<listitem
><para
>Restituisce il nome del file del documento o una stringa vuota per i documenti non salvati. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>String document.url();
</synopsis
></term>
<listitem
><para
>Restituisce l'&URL; completo del documento, o una stringa vuota per i documenti non salvati. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>String document.mimeType();
</synopsis
></term>
<listitem
><para
>Restituisce il tipo di file &MIME; del documento, o il tipo &MIME; del file <literal
>application/octet-stream</literal
> se non se ne può trovare uno appropriato. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>String document.encoding();
</synopsis
></term>
<listitem
><para
>Restituisce la codifica attualmente usata per salvare il file. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>String document.highlightingMode();
</synopsis
></term>
<listitem
><para
>Restituisce la modalità di evidenziazione globale usata per tutto il documento. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>String document.highlightingModeAt(<parameter
>Cursor <replaceable
>posizione</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Restituisce la modalità di evidenziazione usata alla <replaceable
>posizione</replaceable
> nel documento. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>Array document.embeddedHighlightingModes();
</synopsis
></term>
<listitem
><para
>Restituisce un array di modalità di evidenziazione incorporate in questo documento. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>bool document.isModified();
</synopsis
></term>
<listitem
><para
>Restituisce <literal
>true</literal
> se il documento ha modifiche non salvate, altrimenti <literal
>false</literal
>. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>String document.text();
</synopsis
></term>
<listitem
><para
>Restituisce tutto il contenuto del documento in una sola stringa di testo. I ritorni a capo sono indicati con il carattere <quote
><literal
>\n</literal
></quote
>. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>String document.text(<parameter
>int <replaceable
>da_riga</replaceable
></parameter
>, <parameter
>int <replaceable
>da_colonna</replaceable
></parameter
>, <parameter
>int <replaceable
>a_riga</replaceable
></parameter
>, <parameter
>int <replaceable
>a_colonna</replaceable
></parameter
>);
String document.text(<parameter
>Cursor <replaceable
>da</replaceable
></parameter
>, <parameter
>Cursor <replaceable
>a</replaceable
></parameter
>);
String document.text(<parameter
>Range <replaceable
>intervallo</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Restituisce il testo nell'intervallo dato. Per migliorare la leggibilità del codice si raccomanda di usare le versioni con cursori o intervalli. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>String document.line(<parameter
>int <replaceable
>riga</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Restituisce la riga di testo richiesta come stringa. La stringa è vuota se la riga richiesta è oltre i limiti. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>String document.wordAt(<parameter
>int <replaceable
>riga</replaceable
></parameter
>, <parameter
>int <replaceable
>colonna</replaceable
></parameter
>);
String document.wordAt(<parameter
>Cursor <replaceable
>cursore</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Restituisce la parola alla posizione del cursore data. </para
></listitem>
</varlistentry>
<varlistentry>
<term>
<synopsis
>Range document.wordRangeAt(<parameter
>int <replaceable
>riga</replaceable
></parameter
>, <parameter
>int <replaceable
>colonna</replaceable
></parameter
>);
Range document.wordRangeAt(<parameter
>Cursor <replaceable
>cursore</replaceable
></parameter
>);
</synopsis>
</term>
<listitem
><para
>Restituisce l'intervallo di una parola alla posizione del cursore data. L'intervallo restituito non è valido (vedi Range.isValid()) se la posizione è oltre la fine di una riga. Se non c'è una parola alla fine del cursore viene restituito un intervallo vuoto. </para>
<para
>Da: &kde; 4.9 </para>
</listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>String document.charAt(<parameter
>int <replaceable
>riga</replaceable
></parameter
>, <parameter
>int <replaceable
>colonna</replaceable
></parameter
>);
String document.charAt(<parameter
>Cursor <replaceable
>cursore</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Restituisce il carattere alla posizione del cursore data. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>String document.firstChar(<parameter
>int <replaceable
>riga</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Restituisce il primo carattere nella <replaceable
>riga</replaceable
> data che non sia uno spazio. Il primo carattere è alla colonna 0. Se la riga è vuota o contiene solo spazi la stringa restituita è vuota. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>String document.lastChar(<parameter
>int <replaceable
>riga</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Restituisce l'ultimo carattere nella <replaceable
>riga</replaceable
> data che non sia uno spazio. Se la riga è vuota o contiene solo spazi la stringa restituita è vuota. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>bool document.isSpace(<parameter
>int <replaceable
>riga</replaceable
></parameter
>, <parameter
>int <replaceable
>colonna</replaceable
></parameter
>);
bool document.isSpace(<parameter
>Cursor <replaceable
>cursore</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Restituisce <literal
>true</literal
> se il carattere alla posizione del cursore data è uno spazio, altrimenti <literal
>false</literal
>. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>bool document.matchesAt(<parameter
>int <replaceable
>riga</replaceable
></parameter
>, <parameter
>int <replaceable
>colonna</replaceable
></parameter
>, <parameter
>String <replaceable
>testo</replaceable
></parameter
>);
bool document.matchesAt(<parameter
>Cursor <replaceable
>cursore</replaceable
></parameter
>, <parameter
>String <replaceable
>testo</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Restituisce <literal
>true</literal
> se il <replaceable
>testo</replaceable
> corrisponde a quello presente alla posizione del cursore, altrimenti <literal
>false</literal
>. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>bool document.startsWith(<parameter
>int <replaceable
>riga</replaceable
></parameter
>, <parameter
>String <replaceable
>testo</replaceable
></parameter
>, <parameter
>bool <replaceable
>salta_spazi</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Restituisce <literal
>true</literal
> se la riga comincia con il <replaceable
>testo</replaceable
>, altrimenti <literal
>false</literal
>. L'argomento <replaceable
>salta_spazi</replaceable
> decide se gli spazi iniziali vanno ignorati. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>bool document.endsWith(<parameter
>int <replaceable
>riga</replaceable
></parameter
>, <parameter
>String <replaceable
>testo</replaceable
></parameter
>, <parameter
>bool <replaceable
>salta_spazi</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Restituisce <literal
>true</literal
> se la riga finisce con il <replaceable
>testo</replaceable
>, altrimenti <literal
>false</literal
>. L'argomento <replaceable
>salta_spazi</replaceable
> decide se gli spazi finali vanno ignorati. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>bool document.setText(<parameter
>String <replaceable
>testo</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Imposta tutto il testo del documento. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>bool document.clear();
</synopsis
></term>
<listitem
><para
>Rimuove tutto il testo del documento. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>bool document.truncate(<parameter
>int <replaceable
>riga</replaceable
></parameter
>, <parameter
>int <replaceable
>colonna</replaceable
></parameter
>);
bool document.truncate(<parameter
>Cursor <replaceable
>cursore</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Tronca la <replaceable
>riga</replaceable
> alla <replaceable
>colonna</replaceable
>. Restituisce <literal
>true</literal
> se funziona, o <literal
>false</literal
> se la <replaceable
>riga</replaceable
> non fa parte dell'intervallo del documento. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>bool document.insertText(<parameter
>int <replaceable
>riga</replaceable
></parameter
>, <parameter
>int <replaceable
>colonna</replaceable
></parameter
>, <parameter
>String <replaceable
>testo</replaceable
></parameter
>);
bool document.insertText(<parameter
>Cursor <replaceable
>cursore</replaceable
></parameter
>, <parameter
>String <replaceable
>testo</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Inserisce il <replaceable
>testo</replaceable
> alla posizione del cursore data. Restituisce <literal
>true</literal
> se funziona, o <literal
>false</literal
> se il documento è in modalità a sola lettura. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>bool document.removeText(<parameter
>int <replaceable
>da_riga</replaceable
></parameter
>, <parameter
>int <replaceable
>da_colonna</replaceable
></parameter
>, <parameter
>int <replaceable
>a_riga</replaceable
></parameter
>, <parameter
>int <replaceable
>a_colonna</replaceable
></parameter
>);
bool document.removeText(<parameter
>Cursor <replaceable
>da</replaceable
></parameter
>, <parameter
>Cursor <replaceable
>a</replaceable
></parameter
>);
bool document.removeText(<parameter
>Range <replaceable
>intervallo</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Rimuove il testo nell'intervallo dato. Restituisce <literal
>true</literal
> se funziona, o <literal
>false</literal
> se il documento è in modalità di sola lettura. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>bool document.insertLine(<parameter
>int <replaceable
>riga</replaceable
></parameter
>, <parameter
>String <replaceable
>testo</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Inserisce il testo nella riga data. Restituisce <literal
>true</literal
> se funziona, o <literal
>false</literal
> se il documento è in modalità di sola lettura oppure la riga non è nell'intervallo del documento. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>bool document.removeLine(<parameter
>int <replaceable
>riga</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Rimuove la riga di testo data. Restituisce <literal
>true</literal
> se funziona, o <literal
>false</literal
> se il documento è in modalità di sola lettura oppure la riga non è nell'intervallo del documento. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>bool document.wrapLine(<parameter
>int <replaceable
>riga</replaceable
></parameter
>, <parameter
>int <replaceable
>colonna</replaceable
></parameter
>);
bool document.wrapLine(<parameter
>Cursor <replaceable
>cursore</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Manda a capo la riga alla posizione del cursore data. Restituisce <literal
>true</literal
> se funziona, altrimenti <literal
>false</literal
>, ⪚ se la riga < 0. </para>
<para
>Da: &kde; 4.9 </para>
</listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>void document.joinLines(<parameter
>int <replaceable
>riga_inizio</replaceable
></parameter
>, <parameter
>int <replaceable
>riga_fine</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Unisce le righe da <replaceable
>riga_inizio</replaceable
> a <replaceable
>riga_fine</replaceable
>. Due righe di testo consecutive sono sempre separate da un solo spazio. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>int document.lines();
</synopsis
></term>
<listitem
><para
>Restituisce il numero di righe nel documento. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>bool document.isLineModified(<parameter
>int <replaceable
>riga</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Restituisce <literal
>true</literal
> se la <replaceable
>riga</replaceable
> attuale contiene dati non salvati. </para>
<para
>Da: &kde; 5.0 </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>bool document.isLineSaved(<parameter
>int <replaceable
>riga</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Restituisce <literal
>true</literal
> se la <replaceable
>riga</replaceable
> è cambiata ma il documento è stato salvato, e quindi la riga corrente non contiene dati non salvati. </para>
<para
>Da: &kde; 5.0 </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>bool document.isLineTouched(<parameter
>int <replaceable
>riga</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Restituisce <literal
>true</literal
> se la <replaceable
>riga</replaceable
> contiene dati non salvati o è stata cambiata in precedenza. </para>
<para
>Da: &kde; 5.0 </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>bool document.findTouchedLine(<parameter
>int <replaceable
>startLine</replaceable
></parameter
>, <parameter
>bool <replaceable
>giù</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Cerca la successiva riga modificata, a partire da <replaceable
>riga</replaceable
>. La ricerca è eseguita verso l'alto o verso il basso, a seconda della direzione specificata in <replaceable
>giù</replaceable
>. </para>
<para
>Da: &kde; 5.0 </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>int document.length();
</synopsis
></term>
<listitem
><para
>Restituisce il numero di caratteri nel documento. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>int document.lineLength(<parameter
>int <replaceable
>riga</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Restituisce la lunghezza della <replaceable
>riga</replaceable
>. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>void document.editBegin();
</synopsis
></term>
<listitem
><para
>Avvia un gruppo di modifica per un raggruppamento di azioni annullabili. Assicurati di chiamare sempre <function
>editEnd()</function
> con la stessa frequenza di <function
>editBegin()</function
>. Chiamando <function
>editBegin</function
> viene usato internamente un contatore di riferimenti, &ie;, questa chiamata può essere annidata. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>void document.editEnd();
</synopsis
></term>
<listitem
><para
>Chiude un gruppo di modifica. L'ultima chiamata di <function
>editEnd()</function
> (&ie; quella corrispondente alla prima chiamata a <function
>editBegin()</function
>) conclude il passo di modifica. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>int document.firstColumn(<parameter
>int <replaceable
>riga</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Restituisce la prima colonna non di spazi nella <replaceable
>riga</replaceable
>. Se nella <replaceable
>riga</replaceable
> ci sono solo spazi, viene restituito <literal
>-1</literal
>. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>int document.lastColumn(<parameter
>int <replaceable
>riga</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Restituisce l'ultima colonna non di spazi nella <replaceable
>riga</replaceable
>. Se nella <replaceable
>riga</replaceable
> ci sono solo spazi, viene restituito <literal
>-1</literal
>. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>int document.prevNonSpaceColumn(<parameter
>int <replaceable
>riga</replaceable
></parameter
>, <parameter
>int <replaceable
>colonna</replaceable
></parameter
>);
int document.prevNonSpaceColumn(<parameter
>Cursor <replaceable
>cursore</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Restituisce la colonna con caratteri non di spaziatura che comincia alla posizione del cursore data, cercando indietro. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>int document.nextNonSpaceColumn(<parameter
>int <replaceable
>riga</replaceable
></parameter
>, <parameter
>int <replaceable
>colonna</replaceable
></parameter
>);
int document.nextNonSpaceColumn(<parameter
>Cursor <replaceable
>cursore</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Restituisce la colonna con caratteri non di spaziatura che comincia alla posizione del cursore data, cercando in avanti. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>int document.prevNonEmptyLine(<parameter
>int <replaceable
>riga</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Restituisce la prossima riga non vuota con caratteri non di spaziatura, cercando indietro. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>int document.nextNonEmptyLine(<parameter
>int <replaceable
>riga</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Restituisce la prossima riga non vuota con caratteri non di spaziatura, cercando in avanti. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>bool document.isInWord(<parameter
>String <replaceable
>carattere</replaceable
></parameter
>, <parameter
>int <replaceable
>attributo</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Restituisce <literal
>true</literal
> se il <replaceable
>carattere</replaceable
> con l'<replaceable
>attributo</replaceable
> può far parte di una parola, altrimenti <literal
>false</literal
>. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>bool document.canBreakAt(<parameter
>String <replaceable
>carattere</replaceable
></parameter
>, <parameter
>int <replaceable
>attributo</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Restituisce <literal
>true</literal
> se il <replaceable
>carattere</replaceable
> con l'<replaceable
>attributo</replaceable
> può essere mandato a capo, altrimenti <literal
>false</literal
>. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>bool document.canComment(<parameter
>int <replaceable
>attributo_inizio</replaceable
></parameter
>, <parameter
>int <replaceable
>attributo_fine</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Restituisce <literal
>true</literal
> se un intervallo che inizia e finisce con gli attributi dati può essere fatto diventare un commento, altrimenti <literal
>false</literal
>. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>String document.commentMarker(<parameter
>int <replaceable
>attributo</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Restituisce l'indicatore di commento per i commenti di una sola riga per un <replaceable
>attributo</replaceable
>. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>String document.commentStart(<parameter
>int <replaceable
>attributo</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Restituisce l'indicatore di commento per l'inizio di commenti multi-riga per un <replaceable
>attributo</replaceable
>. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>String document.commentEnd(<parameter
>int <replaceable
>attributo</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Restituisce l'indicatore di commento per la fine di commenti multi-riga per un <replaceable
>attributo</replaceable
>. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>Range document.documentRange();
</synopsis
></term>
<listitem
><para
>Restituisce un intervallo che comprende tutto il documento. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>Cursor documentEnd();
</synopsis
></term>
<listitem
><para
>Restituisce un cursore posizionato nell'ultima colonna dell'ultima riga del documento. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>bool isValidTextPosition(<parameter
>int <replaceable
>riga</replaceable
></parameter
>, <parameter
>int <replaceable
>colonna</replaceable
></parameter
>);
bool isValidTextPosition(<parameter
>Cursor <replaceable
>cursore</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Restituisce <literal
>true</literal
> se la posizione del cursore ricade in una posizione di testo valida, cioè se è localizzata all'inizio, nel mezzo o alla fine di una riga valida. Una posizione di testo non è valida se si trova in un surrogato Unicode. </para
><para
>Da: &kde; 5.0 </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>int document.attribute(<parameter
>int <replaceable
>riga</replaceable
></parameter
>, <parameter
>int <replaceable
>colonna</replaceable
></parameter
>);
int document.attribute(<parameter
>Cursor <replaceable
>cursore</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Restituisce l'attributo alla posizione del cursore data. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>bool document.isAttribute(<parameter
>int <replaceable
>riga</replaceable
></parameter
>, <parameter
>int <replaceable
>colonna</replaceable
></parameter
>, <parameter
>int <replaceable
>attributo</replaceable
></parameter
>);
bool document.isAttribute(<parameter
>Cursor <replaceable
>cursore</replaceable
></parameter
>, <parameter
>int <replaceable
>attributo</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Restituisce <literal
>true</literal
> se l'attributo alla posizione del cursore data è uguale a <replaceable
>attributo</replaceable
>, altrimenti <literal
>false</literal
>. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>String document.attributeName(<parameter
>int <replaceable
>riga</replaceable
></parameter
>, <parameter
>int <replaceable
>colonna</replaceable
></parameter
>);
String document.attributeName(<parameter
>Cursor <replaceable
>cursore</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Restituisce il nome dell'attributo in testo leggibile. È uguale al nome <literal
>itemData</literal
> nei file di evidenziazione della sintassi. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>bool document.isAttributeName(<parameter
>int <replaceable
>riga</replaceable
></parameter
>, <parameter
>int <replaceable
>colonna</replaceable
></parameter
>, <parameter
>String <replaceable
>nome</replaceable
></parameter
>);
bool document.isAttributeName(<parameter
>Cursor <replaceable
>cursore</replaceable
></parameter
>, <parameter
>String <replaceable
>nome</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Restituisce <literal
>true</literal
> se il nome dell'attributo a una certa posizione del cursore corrisponde al <replaceable
>nome</replaceable
>, altrimenti <literal
>false</literal
>. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>String document.variable(<parameter
>String <replaceable
>chiave</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Restituisce il valore della variabile del documento <replaceable
>chiave</replaceable
>. Se la variabile non esiste il valore restituito è una stringa vuota. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>void document.setVariable(<parameter
>String <replaceable
>chiave</replaceable
></parameter
>, <parameter
>String <replaceable
>valore</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Imposta il valore della variabile del documento richiesta <replaceable
>chiave</replaceable
>. </para>
<para
>Vedi anche: <link linkend="config-variables"
>le variabili nei documenti di Kate</link
>. </para>
<para
>Da: &kde; 4.8 </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>int document.firstVirtualColumn(<parameter
>int <replaceable
>riga</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Restituisce la colonna virtuale del primo carattere non di spaziatura nella riga indicata, o <literal
>-1</literal
> se la riga è vuota oppure contiene solo caratteri di spaziatura. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>int document.lastVirtualColumn(<parameter
>int <replaceable
>riga</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Restituisce la colonna virtuale dell'ultimo carattere non di spaziatura nella riga indicata, o <literal
>-1</literal
> se la riga è vuota oppure contiene solo caratteri di spaziatura. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>int document.toVirtualColumn(<parameter
>int <replaceable
>riga</replaceable
></parameter
>, <parameter
>int <replaceable
>colonna</replaceable
></parameter
>);
int document.toVirtualColumn(<parameter
>Cursor <replaceable
>cursore</replaceable
></parameter
>);
Cursor document.toVirtualCursor(<parameter
>Cursor <replaceable
>cursore</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Converte la posizione <quote
>reale</quote
> del cursore in una virtuale, restituendo un oggetto <classname
>int</classname
> o <classname
>Cursor</classname
>. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>int document.fromVirtualColumn(<parameter
>int <replaceable
>riga</replaceable
></parameter
>, <parameter
>int <replaceable
>colonna_virtuale</replaceable
></parameter
>);
int document.fromVirtualColumn(<parameter
>Cursor <replaceable
>cursore_virtuale</replaceable
></parameter
>);
Cursor document.fromVirtualCursor(<parameter
>Cursor <replaceable
>cursore_virtuale</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Converte la posizione virtuale data del cursore in una <quote
>reale</quote
>, restituendo un oggetto <classname
>int</classname
> o <classname
>Cursor</classname
>. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>Cursor document.anchor(<parameter
>int <replaceable
>riga</replaceable
></parameter
>, <parameter
>int <replaceable
>colonna</replaceable
></parameter
>, <parameter
>Char <replaceable
>carattere</replaceable
></parameter
>);
Cursor document.anchor(<parameter
>Cursor <replaceable
>cursore</replaceable
></parameter
>, <parameter
>Char <replaceable
>carattere</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Cerca indietro il carattere partendo dal cursore dato. Per esempio, se si passa «(» come carattere, la funzione restituirà la posizione dell'apertura «(». Questo conteggio dei riferimenti, &ie; altri «(...)», vengono ignorati. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>Cursor document.rfind(<parameter
>int <replaceable
>riga</replaceable
></parameter
>, <parameter
>int <replaceable
>colonna</replaceable
></parameter
>, <parameter
>String <replaceable
>testo</replaceable
></parameter
>, <parameter
>int <replaceable
>attributo</replaceable
> = -1</parameter
>);
Cursor document.rfind(<parameter
>Cursor <replaceable
>cursore</replaceable
></parameter
>, <parameter
>String <replaceable
>testo</replaceable
></parameter
>, <parameter
>int <replaceable
>attributo</replaceable
> = -1</parameter
>);
</synopsis
></term>
<listitem
><para
>Cerca all'indietro il testo con l'<replaceable
>attributo</replaceable
> appropriato. L'<replaceable
>attributo</replaceable
> viene ignorato se è impostato a <literal
>-1</literal
>. Il cursore restituito non è valido se non si trova il testo. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>int document.defStyleNum(<parameter
>int <replaceable
>riga</replaceable
></parameter
>, <parameter
>int <replaceable
>colonna</replaceable
></parameter
>);
int document.defStyleNum(<parameter
>Cursor <replaceable
>cursore</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Restituisce lo stile predefinito usato alla posizione data del cursore. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>bool document.isCode(<parameter
>int <replaceable
>riga</replaceable
></parameter
>, <parameter
>int <replaceable
>colonna</replaceable
></parameter
>);
bool document.isCode(<parameter
>Cursor <replaceable
>cursore</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Restituisce <literal
>true</literal
> se l'attributo alla posizione data del cursore non è uguale a tutti i seguenti stili: <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
>riga</replaceable
></parameter
>, <parameter
>int <replaceable
>colonna</replaceable
></parameter
>);
bool document.isComment(<parameter
>Cursor <replaceable
>cursore</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Restituisce <literal
>true</literal
> se l'attributo del carattere alla posizione del cursore data è <literal
>dsComment</literal
>, altrimenti <literal
>false</literal
>. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>bool document.isString(<parameter
>int <replaceable
>riga</replaceable
></parameter
>, <parameter
>int <replaceable
>colonna</replaceable
></parameter
>);
bool document.isString(<parameter
>Cursor <replaceable
>cursore</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Restituisce <literal
>true</literal
> se l'attributo del carattere alla posizione del cursore data è <literal
>dsString</literal
>, altrimenti <literal
>false</literal
>. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>bool document.isRegionMarker(<parameter
>int <replaceable
>riga</replaceable
></parameter
>, <parameter
>int <replaceable
>colonna</replaceable
></parameter
>);
bool document.isRegionMarker(<parameter
>Cursor <replaceable
>cursore</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Restituisce <literal
>true</literal
> se l'attributo del carattere alla posizione del cursore data è <literal
>dsRegionMarker</literal
>, altrimenti <literal
>false</literal
>. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>bool document.isChar(<parameter
>int <replaceable
>riga</replaceable
></parameter
>, <parameter
>int <replaceable
>colonna</replaceable
></parameter
>);
bool document.isChar(<parameter
>Cursor <replaceable
>cursore</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Restituisce <literal
>true</literal
> se l'attributo del carattere alla posizione del cursore data è <literal
>dsChar</literal
>, altrimenti <literal
>false</literal
>. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>bool document.isOthers(<parameter
>int <replaceable
>riga</replaceable
></parameter
>, <parameter
>int <replaceable
>colonna</replaceable
></parameter
>);
bool document.isOthers(<parameter
>Cursor <replaceable
>cursore</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Restituisce <literal
>true</literal
> se l'attributo del carattere alla posizione del cursore data è <literal
>dsOthers</literal
>, altrimenti <literal
>false</literal
>. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>void document.indent(<parameter
>Range <replaceable
>intervallo</replaceable
></parameter
>, <parameter
>int <replaceable
>modifica</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Fa rientrare tutte le righe nell'<replaceable
>intervallo</replaceable
> con la <replaceable
>modifica</replaceable
> delle schede o del numero delle volte degli spazi <literal
>tabSize</literal
>, a seconda delle preferenze dell'utente. Il parametro di <replaceable
>modifica</replaceable
> può essere negativo. </para
></listitem>
</varlistentry>
</variablelist>
</para>
</sect3>
<sect3 id="dev-scripting-api-editor">
<title
>L'API dell'editor</title>
<para
>Oltre alle API per documento e vista c'è un'API generale per editor, che fornisce delle funzioni per le funzionalità di script generali per editor. <variablelist>
<varlistentry>
<term
><synopsis
>String editor.clipboardText();
</synopsis
></term>
<listitem
><para
>Restituisce il testo che c'è attualmente negli appunti globali. </para>
<para
>Da: &kde-frameworks; 5.50</para>
</listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>String editor.clipboardHistory();
</synopsis
></term>
<listitem
><para
>L'editor mantiene una cronologia degli appunti che contiene fino a 10 voci di appunti. Questa funzione restituisce tutte le voci che ci sono attualmente nella cronologia degli appunti. </para>
<para
>Da: &kde-frameworks; 5.50</para>
</listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>void editor.setClipboardText(<parameter
>String <replaceable
>testo</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Imposta il contenuto degli appunti a <replaceable
>testo</replaceable
>. il <replaceable
>testo</replaceable
> sarà aggiunto alla cronologia degli appunti. </para>
<para
>Da: &kde-frameworks; 5.50</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</sect3>
</sect2>
</sect1>
</chapter>
Generated by dwww version 1.15 on Thu Jun 27 22:59:31 CEST 2024.