<chapter id="advanced-editing-tools">
<chapterinfo>
<authorgroup>
<author
>&Anders.Lund; &Anders.Lund.mail;</author>
<author
>&Dominik.Haumann; &Dominik.Haumann.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
> 
</authorgroup>
</chapterinfo>
<title
>Strumenti avanzati di modifica</title>

<sect1 id="advanced-editing-tools-comment">

<title
>Commenta/Decommenta</title>

<para
>I comandi Commenta e Decommenta, disponibili nel menu <guimenu
>Strumenti</guimenu
> permettono di aggiungere o rimuovere indicatori di commento alla selezione, o alla riga attuale del testo se non hai selezionato niente, a patto che i commenti facciano parte del formato di testo del documento.</para>

<para
>Le regole su come è applicato il commento sono definite in base alla sintassi del testo che stai scrivendo, quindi se non hai selezionato una modalità di evidenziazione, non potrai usare Commenta/Decommenta. </para>

<para
>Alcuni formati usano indicatori di commento per righe singole, altri usano indicatori per più righe consecutive di commento ed altri ancora entrambi i sistemi. Se i marcatori multiriga non sono disponibili, commentare una selezione che non comprenda completamente la'ultima riga non è possibile.</para>

<para
>Se sono disponibili i marcatori per righe singole  è preferibile usarli ogni volta che è possibile, perché ciò evita i problemi dei commenti nidificati.</para>

<para
>Quando rimuovi gli indicatori di commento devi fare attenzione a non selezionare testo che non fa parte del commento. Quando rimuovi i commenti su più righe da una selezione, gli spazi vuoti al di fuori degli indicatori di commento sono ignorati.</para>

<para
><indexterm
><primary
>commentare</primary
></indexterm
> Per inserire gli indicatori di commento, usa il comando <menuchoice
><guimenu
>Strumenti</guimenu
><guimenuitem
>Commenta</guimenuitem
></menuchoice
> oppure la relativa scorciatoria da tastiera, quella predefinita è <keycombo action="simul"
>&Ctrl;<keycap
>#</keycap
></keycombo
>.</para>

<para
><indexterm
><primary
>decommentare</primary
></indexterm
> Per rimuovere gli indicatori di commento, usa il comando <menuchoice
><guimenu
>Strumenti</guimenu
><guimenuitem
>Decommenta</guimenuitem
></menuchoice
> oppure la relativa scorciatoia da tastiera; quella predefinita è <keycombo action="simul"
>&Ctrl;&Shift;<keycap
>#</keycap
></keycombo
>.</para>

</sect1>

<sect1 id="advanced-editing-tools-commandline">
<title
>La riga di comando per il componente dell'editor</title>

<para
>Il componente editor di &kate; ha una riga di comando interna che permette di effettuare varie azioni da una GUI minima. La riga di comando è una casella di testo nella parte inferiore dell'area di modifica, per mostrarla seleziona <menuchoice
><guimenu
>Visualizza</guimenu
><guimenuitem
>Passa alla riga di comando</guimenuitem
></menuchoice
> o usa la scorciatoia (<keycombo action="simul"
><keycap
>F7</keycap
></keycombo
>). L'editor fornisce l'insieme di comandi documentati di seguito, e comandi aggiuntivi sono forniti con le estensioni.</para>

<para
>Per eseguire un comando, scrivilo e premi il tasto Invio. La riga di comando indicherà se ha avuto successo ed eventualmente mostrerà un messaggio. Se hai attivato la riga di comando premendo <keycap
>F7</keycap
>, verrà nascosta automaticamente dopo qualche secondo. Per pulire la riga ed inserire un nuovo comando, premi di nuovo <keycap
>F7</keycap
>.</para>

<para
>La riga di comando ha un sistema di aiuto integrato, usa il comando <command
>help</command
> per iniziare. Per vedere un elenco di tutti i comandi disponibili usa <command
>help list</command
>, per vedere l'aiuto di un comando specifico usa <command
>help <replaceable
>comando</replaceable
></command
>.</para>

<para
>La riga di comando si ricorda la cronologia dei comandi, per cui puoi riutilizzare i comandi che hai già inserito. Per scorrere la cronologia, usa i tasti <keycap
>Freccia su</keycap
> e <keycap
>Freccia giù</keycap
>. Quando vengono mostrati i comandi della cronologia, la parte degli argomenti del comando è selezionata, in modo da permetterti di sovrascrivere semplicemente gli argomenti.</para>

<sect2 id="advanced-editing-tools-commandline-commands">
<title
>I comandi standard della riga di comando</title>

<sect3 id="advanced-editing-tools-commandline-commands-configure">
<title
>Comandi per la configurazione dell'editor</title>

<para
>Questi comandi sono forniti dal componente editor e permettono di configurare solo il documento attivo e la vista. Sono utili se vuoi usare impostazioni diverse da quelle predefinite, ad esempio per i rientri. </para>

<variablelist>
<title
>Tipi di argomento</title>

<varlistentry>
<term
>BOOLEAN</term>
<listitem
><para
>Questo tipo è usato nei comandi che devono attivare o disattivare una caratteristica. I valori ammessi sono <userinput
>on</userinput
>, <userinput
>off</userinput
>, <userinput
>true</userinput
>, <userinput
>false</userinput
>, <userinput
>1</userinput
> o <userinput
>0</userinput
></para
></listitem>
</varlistentry>

<varlistentry>
<term
>INTEGER</term>
<listitem
><para
>Un numero intero</para
></listitem>
</varlistentry>

<varlistentry>
<term
>STRING</term>
<listitem
><para
>Una stringa</para
></listitem>
</varlistentry>

</variablelist>

<variablelist>

<varlistentry>
<term
><cmdsynopsis
><command
>set-tab-width</command
><arg
>INTEGER ampiezza</arg
></cmdsynopsis
></term>
<listitem
><para
>Imposta l'ampiezza della tabulazione al numero <userinput
>ampiezza</userinput
>.</para
></listitem>
</varlistentry>

<varlistentry>
<term
><cmdsynopsis
><command
>set-indent-width</command
><arg
>INTEGER ampiezza</arg
></cmdsynopsis
></term>
<listitem
><para
>Imposta l'ampiezza del rientro al numero <userinput
>ampiezza</userinput
>. È usata solo se fai rientrare con gli spazi.</para
></listitem>
</varlistentry>

<varlistentry>
<term
><cmdsynopsis
><command
>set-word-wrap-column</command
><arg
>INTEGER ampiezza</arg
></cmdsynopsis
></term>
<listitem
><para
>Imposta l'ampiezza della riga al numero <userinput
>ampiezza</userinput
>. È usata se il testo deve andare a capo automaticamente.</para
></listitem>
</varlistentry>

<varlistentry>
<term
><cmdsynopsis
><command
>set-icon-border</command
><arg
>BOOLEAN abilitazione</arg
> </cmdsynopsis
></term>
<listitem
><para
>Imposta la visibilità del bordo per le icone.</para
></listitem>
</varlistentry>

<varlistentry>
<term
><cmdsynopsis
><command
>set-folding-markers</command
><arg
>BOOLEAN abilitazione</arg
></cmdsynopsis
></term>
<listitem
><para
>Imposta la visibilità del pannello per gli indicatori di raggruppamento.</para
></listitem>
</varlistentry>

<varlistentry>
<term
><cmdsynopsis
><command
>set-line-numbers</command
><arg
>BOOLEAN abilitazione</arg
></cmdsynopsis
></term>
<listitem
><para
>Imposta la visibilità del pannello per i numeri di riga.</para
></listitem>
</varlistentry>

<varlistentry>
<term
><cmdsynopsis
><command
>set-replace-tabs</command
><arg
>BOOLEAN abilitazione</arg
></cmdsynopsis
></term>
<listitem
><para
>Se è abilitata, le tabulazioni sono sostituiti con spazi durante l'inserimento. </para
></listitem>
</varlistentry>

<varlistentry>
<term
><cmdsynopsis
><command
>set-remove-trailing-space</command
><arg
>BOOLEAN abilitazione</arg
></cmdsynopsis
></term>
<listitem
><para
>Se è abilitata, gli spazi in fin di riga vengono rimossi quando il cursore lascia una riga.</para
></listitem>
</varlistentry>

<varlistentry>
<term
><cmdsynopsis
><command
>set-show-tabs</command
><arg
>BOOLEAN abilitazione</arg
></cmdsynopsis
></term>
<listitem
><para
>Se è abilitata, le tabulazioni e gli spazi bianchi in fin di riga saranno evidenziati con dei puntini.</para
></listitem>
</varlistentry>

<varlistentry>
<term
><cmdsynopsis
><command
>set-indent-spaces</command
><arg
>BOOLEAN abilitazione</arg
></cmdsynopsis
></term>
<listitem
><para
>Se è abilitata, l'editor farà rientrare il testo di <option
>indent-width</option
> spazi ad ogni livello di rientro, invece che di un carattere di tabulazione.</para
></listitem>
</varlistentry>

<varlistentry>
<term
><cmdsynopsis
><command
>set-mixed-indent</command
><arg
>BOOLEAN abilitazione</arg
></cmdsynopsis
></term>
<listitem
><para
>Se abilitato, &kate; userà una miscela di tabulazioni e spazi per i rientri delle righe. Ciascun livello di rientro sarà largo <option
>indent-width</option
>, e più livelli di rientro saranno ottimizzati usando il maggior numero possibile di tabulazioni.</para>
<para
>Quando viene eseguito, questo comando inoltre abilita i rientri con gli spazi, e se l'ampiezza dei rientri non è specificata, sarà impostata alla metà di <option
>tab-width</option
> del documento al momento dell'esecuzione.</para
></listitem>
</varlistentry>

<varlistentry>
<term
><cmdsynopsis
><command
>set-word-wrap</command
><arg
>BOOLEAN abilitazione</arg
></cmdsynopsis
></term>
<listitem
><para
>Abilita o disabilita l'a capo automatico dinamico a seconda del parametro <userinput
>abilitazione</userinput
>.</para
></listitem>
</varlistentry>

<varlistentry>
<term
><cmdsynopsis
><command
>set-replace-tabs-save</command
><arg
>BOOLEAN abilitazione</arg
></cmdsynopsis
></term>
<listitem
><para
>Quando è attiva questa opzione, le tabulazioni verranno sostituite con spazi durante il salvataggio del documento.</para
></listitem>
</varlistentry>

<varlistentry>
<term
><cmdsynopsis
><command
>set-remove-trailing-space-save</command
><arg
>BOOLEAN abilitazione</arg
></cmdsynopsis
></term>
<listitem
><para
>Quando è attiva questa opzione, gli spazi alla fine delle righe saranno scartati durante il salvataggio del documento.</para
></listitem>
</varlistentry>

<varlistentry>
<term
><cmdsynopsis
><command
>set-indent-mode</command
><arg
>nome</arg
></cmdsynopsis
></term>
<listitem
><para
>Imposta la modalità di autorientro a <userinput
>nome</userinput
>. Se <userinput
>nome</userinput
> è sconosciuto, la modalità sarà impostata a "none". Le modalità valide sono 'cstyle', 'csands', 'xml', 'python', 'varindent' e 'none'.</para
></listitem>
</varlistentry>

<varlistentry>
<term
><cmdsynopsis
><command
>set-highlight</command
><arg
>evidenziazione</arg
></cmdsynopsis
></term>
<listitem
><para
>Seleziona il sistema di evidenziazione della sintassi per il documento. L'argomento deve essere un nome di evidenziazione valido, così come è mostrato nel menu <menuchoice
><guimenu
>Strumenti</guimenu
><guisubmenu
>Evidenziazione</guisubmenu
></menuchoice
>. Questo comando fornisce una lista per l'autocompletamento dell'argomento.</para
></listitem>
</varlistentry>

</variablelist>

</sect3>

<sect3 id="advanced-editing-tools-commandline-commands-edit">
<title
>Comandi per la modifica</title>

<para
>Questi comandi servono a modificare il documento corrente.</para>

<variablelist>
<varlistentry>
<term
><cmdsynopsis
><command
>indent</command
></cmdsynopsis
></term>
<listitem
><para
>Fa rientrare le righe selezionate o la riga attuale.</para
></listitem>
</varlistentry>

<varlistentry>
<term
><cmdsynopsis
><command
>unindent</command
></cmdsynopsis
></term>
<listitem
><para
>Elimina un passo di rientro delle righe selezionate o della riga attuale.</para
></listitem>
</varlistentry>

<varlistentry>
<term
><cmdsynopsis
><command
>cleanindent</command
></cmdsynopsis
></term>
<listitem
><para
>Riordina il rientro delle righe selezionate o della riga attuale secondo le impostazioni per il rientro del documento. </para
></listitem>
</varlistentry>

<varlistentry>
<term
><cmdsynopsis
><command
>comment</command
></cmdsynopsis
></term>
<listitem
><para
>Inserisce indicatori di commento per rendere la selezione o le righe selezionate o la riga attuale un commento secondo il formato di testo così com'è definito dalle regole di evidenziazione della sintassi del documento.</para
></listitem>
</varlistentry>

<varlistentry>
<term
><cmdsynopsis
><command
>uncomment</command
></cmdsynopsis
></term>
<listitem
><para
>Rimuove gli indicatori di commento dalla selezione o dalle righe selezionate o dalla riga attuale secondo il formato di testo così com'è definito dalle regole di evidenziazione della sintassi del documento.</para
></listitem>
</varlistentry>

<varlistentry>
<term
><cmdsynopsis
><command
>kill-line</command
></cmdsynopsis
></term>
<listitem
><para
>Elimina la riga attuale.</para
></listitem>
</varlistentry>

<varlistentry>
<term
><cmdsynopsis
><command
>replace</command
><arg
>modello</arg
><arg
>sostituzione</arg
></cmdsynopsis
></term>
<listitem
><para
>Sostituisce il testo corrispondente a <userinput
>modello</userinput
> con <userinput
>sostituzione</userinput
>. Se vuoi includere spazi bianchi nel <userinput
>modello</userinput
>, devi mettere le virgolette single o doppie attorno sia al modello, sia alla sostituzione. Se gli argomenti non sono tra virgolette,la prima parola è usata come <userinput
>modello</userinput
> ed il resto come <userinput
>sostituzione</userinput
>. Se la <userinput
>sostituzione</userinput
> è vuota, vengono rimosse le corrispondenze con il <userinput
>modello</userinput
>.</para>
<para
>Puoi impostare dei modificatori per configurare la ricerca aggiungendo un due punti, seguiti da una o più lettere rappresentanti la configurazione, data nella forma <userinput
>replace:opzioni modello sostituzione</userinput
>. Le opzioni disponibili sono: <variablelist>

<varlistentry>
<term
><userinput
>b</userinput
></term>
<listitem
><para
>Cerca all'indietro.</para
></listitem>
</varlistentry>

<varlistentry>
<term
><userinput
>c</userinput
></term>
<listitem
><para
>Cerca dalla posizione del cursore.</para
></listitem>
</varlistentry>

<varlistentry>
<term
><userinput
>e</userinput
></term>
<listitem
><para
>Cerca solo all'interno della selezione.</para
></listitem>
</varlistentry>

<varlistentry>
<term
><userinput
>r</userinput
></term>
<listitem
><para
>Esegue la ricerca con un'espressione regolare. Se è impostata, puoi usare <userinput
>\N</userinput
>, dove N è un numero che rappresenta le catture nella stringa di sostituzione.</para
></listitem>
</varlistentry>

<varlistentry>
<term
><userinput
>s</userinput
></term>
<listitem
><para
>Esegue la ricerca facendo distinzione fra maiuscole e minuscole.</para
></listitem>
</varlistentry>

<varlistentry>
<term
><userinput
>p</userinput
></term>
<listitem
><para
>Chiede il permesso prima di effettuare la sostituzione.</para
></listitem>
</varlistentry>

<varlistentry>
<term
><userinput
>w</userinput
></term>
<listitem
><para
>Fa in modo che la ricerca consideri solo parole intere.</para
></listitem>
</varlistentry>

</variablelist>

</para>
</listitem>
</varlistentry>

<varlistentry>
<term
><cmdsynopsis
><command
>date</command
><arg
>formato</arg
></cmdsynopsis
></term>
<listitem
><para
>Inserisce la stringa dell'ora/data come è specificato in <userinput
>formato</userinput
>, o nel formato <quote
>yyyy-MM-dd hh:mm:ss</quote
> se non ne è specificato nessuno. Le seguenti traduzioni sono effettuate nell'interpretazione di <userinput
>formato</userinput
>: <informaltable
> <tgroup cols="2"
> <tbody>
<row
><entry
><literal
>d</literal
></entry
><entry
>Il giorno in forma numerica senza zeri iniziali (1&ndash;31).</entry
></row>
<row
><entry
><literal
>dd</literal
></entry
><entry
>Il giorno in forma numerica con uno zero iniziale di allineamento (01&ndash;31).</entry
></row>
<row
><entry
><literal
>ddd</literal
></entry
><entry
>Il nome del giorno abbreviato in forma locale (cioè "lun" ... "dom").</entry
></row>
<row
><entry
><literal
>dddd</literal
></entry
><entry
>Il nome del giorno completo in forma locale (cioè "lunedì" ... "domenica").</entry
></row>
<row
><entry
><literal
>M</literal
></entry
><entry
>Il mese in forma numerica senza zeri iniziali (1&ndash;12).</entry
></row>
<row
><entry
><literal
>MM</literal
></entry
><entry
>Il mese in forma numerica con uno zero iniziale se necessario (01&ndash;12).</entry
></row>
<row
><entry
><literal
>MMM</literal
></entry
><entry
>Il nome del mese abbreviato in forma locale (cioè "gen" ... "dic").</entry
></row>
<row
><entry
><literal
>yy</literal
></entry
><entry
>Le ultime due cifre dell'anno (00&ndash;99).</entry
></row>
<row
><entry
><literal
>yyyy</literal
></entry
><entry
>L'anno come numero di quattro cifre (1752&ndash;8000).</entry
></row>
<row
><entry
><literal
>h</literal
></entry
><entry
>L'ora senza zero iniziali (0&ndash;23 o 1&ndash;12 se in modalità AM/PM).</entry
></row>
<row
><entry
><literal
>hh</literal
></entry
><entry
>L'ora con zero iniziali (00&ndash;23 o 01&ndash;12 se in modalità AM/PM).</entry
></row>
<row
><entry
><literal
>m</literal
></entry
><entry
>I minuti senza zero iniziali (0&ndash;59).</entry
></row>
<row
><entry
><literal
>mm</literal
></entry
><entry
>I minuti con zero iniziali (00&ndash;59).</entry
></row>
<row
><entry
><literal
>s</literal
></entry
><entry
>I secondi senza zero iniziali (0&ndash;59).</entry
></row>
<row
><entry
><literal
>ss</literal
></entry
><entry
>I secondi con zero iniziali (00&ndash;59).</entry
></row>
<row
><entry
><literal
>z</literal
></entry
><entry
>I millisecondi senza zeri iniziali (0&ndash;999).</entry
></row>
<row
><entry
><literal
>zzz</literal
></entry
><entry
>I millisecondi con zeri iniziali (000&ndash;999).</entry
></row>
<row
><entry
><literal
>AP</literal
></entry
><entry
>Usa modalità AM/PM. AP sarà sostituito da "AM" per le ore antimeridiane o "PM" per quelle pomeridiane.</entry
></row>
<row
><entry
><literal
>ap</literal
></entry
><entry
>Usa modalità am/pm. ap sarà sostituito da "am" per le ore antimeridiane o "pm" per quelle pomeridiane.</entry
></row>

</tbody>
</tgroup>
</informaltable>

</para
></listitem>
</varlistentry>

<varlistentry>
<term
><cmdsynopsis
><command
>char</command
><arg
>identificatore</arg
></cmdsynopsis
></term>
<listitem>
<para
>Questo comando permette di inserire caratteri indicando il loro identificativo numerico, in decimale, ottale o esadecimale. Per usarlo apri la finestra di dialogo Comando di modifica e digita <userinput
>char: [numero]</userinput
> nel campo di inserimento, quindi fai clic su <guibutton
>OK</guibutton
>.</para>

<example>
<title
>Esempi con il comando <command
>char</command
></title>

<para
>Inserisci: <userinput
>char:234</userinput
></para>
<para
>Ottieni: <computeroutput
>&#234;</computeroutput
></para>
<para
>Inserisci: <userinput
>char:0x1234</userinput
></para>
<para
>Ottieni: <computeroutput
>&#x1234;</computeroutput
></para>
</example>

</listitem>
</varlistentry>

<varlistentry>
<term>
<indexterm
><primary
>sostituisci, come in sed</primary>
<secondary
>cerca, come in sed</secondary
></indexterm>
<command
>s///[ig]</command
> <command
>%s///[ig]</command
></term>

<listitem>
<para
>Questo comando fa una ricerca/sostituzione nella riga di testo corrente o in tutto il file (<command
>%s///</command
>) in maniera del tutto simile a sed.</para>

<para
>In breve, la ricerca viene effettuata in base a un <emphasis
>modello di ricerca</emphasis
>, a una espressione regolare compresa tra la prima e la seconda barra. Quando viene trovata una corrispondenza, la parte che corrisponde viene sostituita con l'espressione compresa tra la seconda e la terza barra. Le parentesi nel modello di ricerca creano dei <emphasis
>riferimenti all'indietro</emphasis
>, vale a dire che il comando ricorda quali parti della stringa di ricerca tra parentesi hanno trovato corrispondenza; queste stringhe possono essere riutilizzate per sostituire pattern riferiti a <userinput
>\1</userinput
> per il primo gruppo di parentesi, <userinput
>\2</userinput
> per il secondo e così via.</para>

<para
>Per cercare precisamente il simbolo di parentesi <literal
>(</literal
> o <literal
>)</literal
>, devi <emphasis
>evitare</emphasis
> il problema usando la barra rovescia in questo modo: <userinput
>\(\)</userinput
></para>

<para
>Se metti una <userinput
>i</userinput
> alla fine dell'espressione, la corrispondenza avverrà senza tener far distinzione fra maiuscole o minuscole. Se metti una <userinput
>g</userinput
>, verranno sostituite tutte le corrispondenze del modello, altrimenti verrà sostituita solo la prima.</para>

<example>

<title
>Sostituire del testo nella riga corrente</title>

<para
>Il tuo caro vecchio compilatore ha appena finito di bloccarsi dicendoti che la classe <classname
>myClass</classname
> che compare nella riga 3902 del tuo file sorgente non è definita.</para>

<para
>&quot;Naturale!&quot; pensi, sai benissimo che si scrive <classname
>MyClass</classname
>. Vai alla riga 3902 e, invece di provare a cercare la parola nel testo, apri la finestra di dialogo Comando di modifica, inserisci <userinput
>s/myclass/MyClass/i</userinput
>, premi <guibutton
>OK</guibutton
>, salvi il file e lo compili &ndash; con successo senza errori.</para>

</example>

<example>
<title
>Sostituire del testo nell'intero file</title>

<para
>Immagina di avere un file, nel quale nomini <quote
>Miss Jensen</quote
> parecchie volte e arriva qualcuno che ti dice che si è appena sposata con <quote
>Mr Jones</quote
>. Naturalmente tu vuoi sostituire tutti i <quote
>Miss Jensen</quote
> con <quote
>Ms Jones</quote
>.</para>

<para
>Lancia la finestra di dialogo Comando di modifica, digita nell'apposito campo <userinput
> %s/Miss Jensen/Ms Jones/</userinput
> e premi invio. Il gioco è fatto!</para>

</example>

<example>
<title
>Un esempio più avanzato</title>

<para
>Questo esempio usa i <emphasis
>riferimenti all'indietro</emphasis
> e le <emphasis
>classi di carattere</emphasis
> (se non sai che cosa sono, leggi la relativa documentazione citata più in basso).</para>

<para
>Immagina di avere la seguente riga: <programlisting
>void MyClass::DoStringOps( String      &amp;foo, String &amp;bar String *p, int  &amp;a, int &amp;b )</programlisting>
</para>
<para
>Ora ti rendi conto che il codice non va bene e decidi di usare la parola chiave <constant
>const</constant
> per tutti gli argomenti <quote
>reference</quote
>, quelli caratterizzati dall'operatore &amp; posto davanti al nome dell'argomento. Inoltre vorresti semplificare lo spazio vuoto in modo che ci sia solo uno spazio tra ogni parola.</para>

<para
>Apri la finestra di dialogo Comando di modifica e inserisci: <userinput
>s/\s+(\w+)\s+(&amp;)/ const \1 \2/g</userinput
> e premi il pulsante <guibutton
>OK</guibutton
>. La <userinput
>g</userinput
> che si trova alla fine dell'espressione fa in modo che si ricompili un'espressione regolare, per ogni corrispondenza, da essere poi salvata come <emphasis
>riferimento all'indietro</emphasis
>.</para>

<para
>Ottieni: <computeroutput
>void MyClass::DoStringOps( const String &amp;foo, const String &amp;bar String *p, const int &amp;a, const int &amp;b )</computeroutput
></para>

<para
>Missione compiuta! Ora cos'è successo? Abbiamo cercato alcuni spazi vuoti (<literal
>\s+</literal
>) seguiti da alcuni caratteri alfabetici (<literal
>\w+</literal
>), seguiti da altri spazi vuoti (<literal
>\s+</literal
>), seguiti da una e commerciale e la porzione alfabetica con la e commerciale salvati nel processo per essere usati nell'operazione di sostituzione. Quindi abbiamo sostituito la parte corrispondente della nostra riga con uno spazio vuoto seguito da <quote
>const</quote
>, seguito da un altro spazio vuoto, seguito dalla porzione alfabetica (<literal
>\1</literal
>), seguito da uno spazio vuoto e infine seguito dalla e commerciale salvata (<literal
>\2</literal
>)</para>

<para
>Ora, in alcuni casi la porzione alfabetica era una <quote
>String</quote
>. in altri <quote
>int</quote
>, quindi se usi <literal
>\w</literal
> e il quantificatore <literal
>+</literal
> sarà meglio.</para>

</example>

</listitem>

</varlistentry>

</variablelist>

</sect3>

<sect3 id="advanced-editing-tools-commandline-commands-navigation">
<title
>Comandi per gli spostamenti</title>

<variablelist>

<varlistentry>
<term
><cmdsynopsis
><command
>goto</command
><arg
>INT riga</arg
></cmdsynopsis
></term>
<listitem
><para
>Questo comando sposta il cursore alla riga indicata.</para
></listitem>
</varlistentry>

<varlistentry>
<term
><cmdsynopsis
><command
>find</command
><arg
>modello</arg
></cmdsynopsis
></term>
<listitem
><para
>Questo comando si sposta alla prima corrispondenza del <userinput
>modello</userinput
> secondo la configurazione. Le corrispondenze successive possono essere trovate usando <menuchoice
><guimenu
>Modifica</guimenu
><guimenuitem
>Trova successivo</guimenuitem
></menuchoice
> (la scorciatoia predefinita è <keycap
>F3</keycap
>).</para>
<para
>Il comando find può essere configurato aggiungendo in fondo un due punti seguito da una o più opzioni, nella forma <userinput
>find:opzioni modello</userinput
>. Le seguenti opzioni sono disponibili: <variablelist>

<varlistentry>
<term
><userinput
>b</userinput
></term>
<listitem
><para
>Cerca all'indietro.</para
></listitem>
</varlistentry>

<varlistentry>
<term
><userinput
>c</userinput
></term>
<listitem
><para
>Cerca dalla posizione del cursore.</para
></listitem>
</varlistentry>

<varlistentry>
<term
><userinput
>e</userinput
></term>
<listitem
><para
>Cerca solo all'interno della selezione.</para
></listitem>
</varlistentry>

<varlistentry>
<term
><userinput
>r</userinput
></term>
<listitem
><para
>Esegue la ricerca con un'espressione regolare. Se è impostata, puoi usare <userinput
>\N</userinput
>, dove N è un numero che rappresenta le catture nella stringa di sostituzione.</para
></listitem>
</varlistentry>

<varlistentry>
<term
><userinput
>s</userinput
></term>
<listitem
><para
>Esegue la ricerca facendo distinzione fra maiuscole e minuscole.</para
></listitem>
</varlistentry>

<varlistentry>
<term
><userinput
>w</userinput
></term>
<listitem
><para
>Fa in modo che la ricerca consideri solo parole intere.</para
></listitem>
</varlistentry>

</variablelist>

</para>

</listitem>

</varlistentry>

<varlistentry>
<term
><cmdsynopsis
><command
>ifind</command
><arg
>modello</arg
></cmdsynopsis
></term>
<listitem
><para
>Questo comando fornisce la ricerca <quote
>mentre scrivi</quote
>. Puoi configurarne il comportamento aggiungendo in fondo un due punti seguito da una o più opzioni, nella forma <userinput
>ifind:opzioni modello</userinput
>. Le seguenti opzioni sono disponibili: <variablelist>
<varlistentry>
<term
><userinput
>b</userinput
></term>
<listitem
><para
>Cerca all'indietro.</para
></listitem>
</varlistentry>

<varlistentry>
<term
><userinput
>r</userinput
></term>
<listitem
><para
>Esegue la ricerca di un'espressione regolare.</para
></listitem>
</varlistentry>

<varlistentry>
<term
><userinput
>s</userinput
></term>
<listitem
><para
>Esegue la ricerca facendo distinzione fra maiuscole e minuscole.</para
></listitem>
</varlistentry>

<varlistentry>
<term
><userinput
>c</userinput
></term>
<listitem
><para
>Cerca dalla posizione del cursore.</para
></listitem>
</varlistentry>

</variablelist>
</para
></listitem>
</varlistentry>

</variablelist>

</sect3>

</sect2>

</sect1>

<sect1 id="advanced-editing-tools-code-folding">
<title
>Uso del raggruppamento del codice</title>

<para
>Il raggruppamento del codice permette di nascondere parti del documento nell'editor, rendendo più facile una panoramica di documenti di grandi dimensioni. In &kate; le regioni raggruppabili sono classificate usando le regole delle definizioni dell'evidenziazione della sintassi, e quindi sono disponibili solo in alcuni formati — tipicamente codice sorgente, annotazioni XML e simili. La maggior parte delle definizioni di evidenziazione che permettono il raggruppamento del codice permettono anche la definizione manuale di regioni raggruppabili, tipicamente con l'uso delle parole chiave <userinput
>BEGIN</userinput
> ed <userinput
>END</userinput
>.</para>

<para
>Per usare la funzione di raggruppamento del codice, attiva gli indicatori di raggruppamento usando la voce <menuchoice
><guimenu
>Visualizza</guimenu
><guimenuitem
>Mostra segni di raggruppamento</guimenuitem
></menuchoice
> del menu se non sono già visibili. Il pannello degli indicatori di raggruppamento sul lato sinistro dello schermo mostra una vista grafica delle regioni raggruppabili, con simbolo di un triangolo indicante l'operazione possibile su una data regione: Un triangolo capovolto indica che la regione è espansa, facendo clic su di esso si ridurrà la regione ad una sola riga e successivamente verrà mostrato come simbolo un triangolo diritto.</para>

<para
>Sono forniti quattro comandi per manipolare lo stato delle regioni di raggruppamento del codice, vedi la <link linkend="view-code-folding"
>documentazione del menu</link
>. </para>

<para
>Se non vuoi usare la funzione di raggruppamento del codice, puoi disabilitare l'opzione <guilabel
>Mostra segni di raggruppamento (se disponibile)</guilabel
> dalla pagina <link linkend="appearance"
>Aspetto</link
> dalla pagina di configurazione dell'editor.</para>

</sect1>

<sect1 id="advanced-editing-tools-scripting">
<title
>Estensione di &kate; con script</title>

<para
>Da &kate; 3.4 in KDE 4.4 il componente editor di &kate; è facilmente estendibile attraverso degli script. Il linguaggio di scipt è ECMAScript (comunemente noto come JavaScript). &kate; supporta due tipi di script: rientro e riga di comando. </para>

<sect2 id="advanced-editing-tools-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 &Enter;. </para>

<para
>Le sezioni seguenti descrivono passo-passo come creare la struttura di un semplice rientratore. Come primo passo, crea un nuovo file <literal role="extension"
>.js</literal
>, per esempio <filename
>javascript.js</filename
> nella cartella Home locale <filename
>$<envar
>KDEHOME</envar
>/share/apps/katepart/script</filename
>. </para>

<sect3 id="advanced-editing-tools-scripting-indentation-header">
<title
>L'intestazione dello script di rientro</title>
<para
>L'intestazione del file <filename
>javascript.js</filename
> è incorporata in un commento e ha la forma seguente: <programlisting>
/* kate-script
 * name: JavaScript
 * author: Pippo &lt;pippo@topolinia.it&gt;
 * license: GPL
 * revision: 1
 * kate-version: 3.4
 * type: indentation
 * required-syntax-style: javascript
 * indent-languages: javascript
 * priority: 0
 *
 * Una riga senza due punti «:» interrompe l'analisi dell'intestazione.
 * Puoi quindi aggiungere del testo qui, come il testo di una licenza.
 */
</programlisting
> Ogni voce viene ora spiegata in dettaglio: <itemizedlist>
<listitem
><para
><literal
>kate-script</literal
> [obbligatorio]: questa stringa di testo deve essere nella prima riga del file <literal role="extension"
>.js</literal
>, altrimenti &kate; salterà lo script. </para
></listitem>
<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 BSD o LGPLv3. </para
></listitem>
<listitem
><para
><literal
>revision</literal
> [obbligatorio]: la revisione dello script. Questo numero va aumentato a ogni sua modifica. </para
></listitem>
<listitem
><para
><literal
>kate-version</literal
> [obbligatorio]: versione minima di &kate; richiesta. </para
></listitem>
<listitem
><para
><literal
>type</literal
> [obbligatorio]: il tipo deve essere <userinput
>indentation</userinput
>, altrimenti &kate; salterà lo script. </para
></listitem>
<listitem
><para
><literal
>required-syntax-style</literal
> [facoltativo]: elenco separato da virgole di stili richiesti 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 separato da virgole di stili di sintassi che il rientratore può far rientrare correttamente, per esempio: <userinput
>c++, java</userinput
>. </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>

<para
>&kate; legge tutte le coppie nella forma <quote
><replaceable
>chiave</replaceable
>:<replaceable
>valore</replaceable
></quote
> finché non trova più virgole. Ciò vuol dire che l'intestazione può contenere del testo a piacere, come una licenza, come mostrato nell'esempio. </para>

</sect3>

<sect3 id="advanced-editing-tools-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>
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
>Allinea</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
>Allinea</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, &lt;tab&gt; indica una tabulazione e <quote
>.</quote
> uno spazio:<programlisting>
1: &lt;tab&gt;&lt;tab&gt;pippo("ciao",
2: &lt;tab&gt;&lt;tab&gt;......"mondo");
</programlisting
> Quando si allinea 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 &kate; con diversi rientratori. Il codice JavaScript corrispondente si può trovare in <filename
>$<envar
>KDEDIR</envar
>/share/apps/katepart/script</filename
>. </para>

<para
>Sviluppare un rientratore richiede ricaricare gli script per vedere se le modifiche funzionano correttamente. Invece di riavviare l'applicazione, basta 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 &kate; <ulink url="mailto:kwrite-devel@kde.org"
>contattando la lista di distribuzione</ulink
>. </para>

</sect3>
</sect2>

<sect2 id="advanced-editing-tools-scripting-command-line">
<title
>Script dalla riga di comando</title>

<para
>Essendo difficile soddisfare le necessità di tutti, &kate; 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 &kate; con script di supporto a piacere. </para>

<para
>Gli script dalla riga di comando si trovano nella stessa cartella degli script di rientro. Come primo passo, crea un nuovo file <literal role="extension"
>*.js</literal
> nella cartella Home locale <filename class="directory"
>$<envar
>KDEHOME</envar
>/share/apps/katepart/script</filename
>. </para>

<sect3 id="advanced-editing-tools-scripting-command-line-header">
<title
>L'intestazione dello script da riga di comando</title>
<para
>L'intestazione di ogni script da riga di comando è incorporata in un commento ed ha la forma seguente: <programlisting>
/* kate-script
 * author: Pippo &lt;pippo@topolinia.it&gt;
 * license: BSD
 * revision: 1
 * kate-version: 3.4
 * type: commands
 * functions: sort, format-paragraph
 *
 * Una riga senza due punti «:» interrompe l'analisi dell'intestazione.
 * Puoi quindi aggiungere del testo qui, come il testo di una licenza.
 */
</programlisting
> Ogni voce verrà ora spiegata in dettaglio: <itemizedlist>
<listitem
><para
><literal
>kate-script</literal
> [obbligatorio]: questa stringa di testo deve essere nella prima riga del file <literal role="extension"
>.js</literal
>, altrimenti &kate; salterà lo script.</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 BSD o LGPLv3.</para
></listitem>
<listitem
><para
><literal
>revision</literal
> [obbligatorio]: la revisione dello script. Questo numero va aumentato a ogni sua modifica.</para
></listitem>
<listitem
><para
><literal
>kate-version</literal
> [obbligatorio]: versione minima di &kate; richiesta.</para
></listitem>
<listitem
><para
><literal
>type</literal
> [obbligatorio]: Il tipo deve essere <userinput
>commands</userinput
>, altrimenti &kate; salterà lo script.</para
></listitem>
<listitem
><para
><literal
>functions</literal
> [obbligatorio]: elenco separato da virgole dei comandi nello script.</para
></listitem>
</itemizedlist>
</para>

<para
>&kate; legge tutte le coppie nella forma <quote
><replaceable
>chiave</replaceable
>:<replaceable
>valore</replaceable
></quote
> finché non riesce a trovare più un carattere di due punti. Ciò vuol dire che l'intestazione può contenere caratteri a piacere, come nell'esempio una licenza. Il valore della chiave <literal
>functions</literal
> è un elenco separato da virgole di comandi da riga di comando. Ciò vuol dire che un solo script contiene un numero a piacere di questi comandi. Ogni funzione è disponibile attraverso la <link linkend="advanced-editing-tools-commandline"
>riga di comando incorporata di &kate;</link
>. </para>
</sect3>

<sect3 id="advanced-editing-tools-scripting-command-line-body">
<title
>Il codice sorgente dello script</title>

<para
>Tutte le funzioni specificate nell'intestazione vanno implementate nello script. Lo script nell'esempio sopra deve implementare le due funzioni <command
>sort</command
> e <command
>format-paragraph</command
>. Tutte le funzioni hanno la sintassi seguente: <programlisting
>function &lt;nome&gt;(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
>, eccetera. Per poter documentare ogni comando, basta implementare la funzione <function
>help</function
> come segue: <programlisting>
function help(comando)
{
    if (comando == "sort") {
        return "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, per esempio <parameter
>comando == "sort"</parameter
>. &kate; presenterà quindi il testo risultante come documentazione per l'utente. </para>

<para
>Sviluppare uno script da riga di comando richiede di ricaricarlo per vedere se le modifiche si funzionano correttamente. Invece di riavviare l'applicazione, basta passare alla riga di comando e lanciare il comando <command
>reload-scripts</command
>. </para>

<para
>Se sviluppi degli script utili, per piacere considera la possibilità di contribuirli al progetto &kate; <ulink url="mailto:kwrite-devel@kde.org"
>contattando la lista di distribuzione</ulink
>. </para>
</sect3>
</sect2>

<sect2 id="advanced-editing-tools-scripting-api">
<title
>API per gli script</title>

<para
>L'API per gli script qui presentata è disponibile in tutti gli script, cioè script di rientro e comandi da riga di comando. Prima di caricare i contenuti di uno script, &kate; aggiunge diversi prototipi e funzioni contestuali. Questa API contiene prototipi come cursori e intervalli di testo, e si trova nella cartella <filename
>$<envar
>KDEDIR</envar
>share/apps/katepart/api</filename
>. Il nome di ogni file JavaScript ivi presente segue il seguente schema: <programlisting>
&lt;numero&gt;_&lt;nome&gt;.js
</programlisting
> Il numero ha due cifre e il nome è un nome a piacere, come per esempio <filename
>mieiprogrammi</filename
>. Con il numero &kate; può controllare l'ordine di esecuzione dell'API: il file <filename
>05_cursor.js</filename
> viene chiamato prima di <filename
>10_range.js</filename
>. Ciò assomiglia al sistema di runlevel/init di Linux. </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
>KDEHOME</envar
>/share/apps/katepart/api</filename
>, e assicurarsi che abbia un numero (cioè ordine di esecuzione) maggiore degli altri file <literal role="extension"
>*.js</literal
> nella cartella globale <filename
>$<envar
>KDEDIR</envar
>/share/apps/katepart/api</filename
>. &kate; cerca i file <literal role="extension"
>*.js</literal
> automaticamente in entrambe le cartelle, e li esegue nell'ordine specificato. </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. Crea piuttosto un file <literal role="extension"
>*.js</literal
> nella cartella locale da eseguire dopo il file <filename
>05_cursor.js</filename
>, e quindi cambiane il prototipo <classname
>Cursor</classname
> in JavaScript. </para>

<sect3 id="advanced-editing-tools-scripting-api-global">
<title
>Cursori e intervalli</title>

<para
>Essendo &kate; un editor di testo, tutta l'API per gli script si basa su cursori e intervalli ovunque sia possibile. 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="advanced-editing-tools-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
></variablelist>


<variablelist
><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
></variablelist>


<variablelist
><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
></variablelist>


<variablelist
><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
></variablelist>


<variablelist
><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
></variablelist>


<variablelist
><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
></variablelist>

<variablelist
><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
></variablelist>


<variablelist
><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
></variablelist>


<variablelist
><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="advanced-editing-tools-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
></variablelist>


<variablelist
><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
></variablelist>


<variablelist
><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
></variablelist>


<variablelist
><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
></variablelist>


<variablelist
><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
></variablelist>


<variablelist
><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
></variablelist>


<variablelist
><varlistentry>
<term
><synopsis
>bool Range.invalid();
</synopsis
></term>
<listitem
><para
>Restituisce l'intervallo da <literal
>(-1, -1)</literal
> a <literal
>(-1, -1)</literal
>. </para
></listitem>
</varlistentry
></variablelist>


<variablelist
><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 <replaceable
>cursore</replaceable
>, altrimenti <literal
>false</literal
>. </para
></listitem>
</varlistentry
></variablelist>


<variablelist
><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
></variablelist>


<variablelist
><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
></variablelist>


<variablelist
><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
></variablelist>


<variablelist
><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
></variablelist>


<variablelist
><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
></variablelist>


<variablelist
><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
></variablelist>


<variablelist
><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
></variablelist>


<variablelist
><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="advanced-editing-tools-scripting-api-debug">
<title
>Funzioni globali</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>


</sect3>

<sect3 id="advanced-editing-tools-scripting-api-view">
<title
>L'API delle viste</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
>Cursor view.cursorPosition()</function
>
</synopsis
></term>
<listitem
><para
>Restituisce la posizione attuale del cursore nella vista.</para
></listitem>
</varlistentry
></variablelist>


<variablelist
><varlistentry>
<term
><synopsis
><function
>void view.setCursorPosition(<parameter
>int <replaceable
>riga</replaceable
></parameter
>, <parameter
>int <replaceable
>colonna</replaceable
></parameter
>)</function>
<function
>void view.setCursorPosition(<parameter
>Cursor <replaceable
>cursore</replaceable
></parameter
>)</function
>
</synopsis
></term>
<listitem
><para
>Restituisce la posizione attuale del cursore nella vista.</para
></listitem>
</varlistentry
></variablelist>


<variablelist
><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
></variablelist>


<variablelist
><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
></variablelist>


<variablelist
><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
></variablelist>


<variablelist
><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
></variablelist>


<variablelist
><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
></variablelist>


<variablelist
><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
></variablelist>


<variablelist
><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
></variablelist>


<variablelist
><varlistentry>
<term
><synopsis
>void view.removeSelectedText();
</synopsis
></term>
<listitem
><para
>Rimuovi il testo selezionato. Se la vista non ne ha, non fa nulla. </para
></listitem>
</varlistentry
></variablelist>


<variablelist
><varlistentry>
<term
><synopsis
>void view.selectAll();
</synopsis
></term>
<listitem
><para
>Seleziona tutto il testo del documento. </para
></listitem>
</varlistentry
></variablelist>


<variablelist
><varlistentry>
<term
><synopsis
>void view.clearSelection();
</synopsis
></term>
<listitem
><para
>Pulisce la selezione di testo senza rimuoverlo. </para
></listitem>
</varlistentry
></variablelist>
</para>
</sect3>

<sect3 id="advanced-editing-tools-scripting-api-document">
<title
>L'API dei documenti</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
></variablelist>


<variablelist
><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
></variablelist>


<variablelist
><varlistentry>
<term
><synopsis
>String document.mimeType();
</synopsis
></term>
<listitem
><para
>Restituisce il tipo di file del documento, o il tipo di file <literal
>application/octet-stream</literal
> se non se ne può trovare uno appropriato. </para
></listitem>
</varlistentry
></variablelist>


<variablelist
><varlistentry>
<term
><synopsis
>String document.encoding();
</synopsis
></term>
<listitem
><para
>Restituisce la codifica attualmente usata per salvare il file. </para
></listitem>
</varlistentry
></variablelist>

<variablelist
><varlistentry>
<term
><synopsis
>String document.highlightingMode();
</synopsis
></term>
<listitem
><para
>Restituisce la modalità di evidenziazione globale usata per tutto il documento. </para
></listitem>
</varlistentry
></variablelist>

<variablelist
><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
></variablelist>

<variablelist
><varlistentry>
<term
><synopsis
>Array document.embeddedHighlightingModes();
</synopsis
></term>
<listitem
><para
>Restituisce un array di modalità di evidenziazione incorporate in questo documento. </para
></listitem>
</varlistentry
></variablelist>

<variablelist
><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
></variablelist>


<variablelist
><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
></variablelist>


<variablelist
><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. Si raccomanda di usare le versioni con cursori o intervalli per migliorare la leggibilità del codice. </para
></listitem>
</varlistentry
></variablelist>


<variablelist
><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
></variablelist>


<variablelist
><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
></variablelist>


<variablelist
><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
></variablelist>


<variablelist
><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
></variablelist>


<variablelist
><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
></variablelist>


<variablelist
><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
></variablelist>


<variablelist
><varlistentry>
<term
><synopsis
>bool document.matchesAt(<parameter
>int <replaceable
>riga</replaceable
></parameter
>, <parameter
>int <replaceable
>colonna</replaceable
></parameter
>, <parameter
>int <replaceable
>riga</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
></variablelist>


<variablelist
><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
></variablelist>


<variablelist
><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
></variablelist>


<variablelist
><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
></variablelist>


<variablelist
><varlistentry>
<term
><synopsis
>bool document.clear();
</synopsis
></term>
<listitem
><para
>Rimuove tutto il testo del documento. </para
></listitem>
</varlistentry
></variablelist>


<variablelist
><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
></variablelist>


<variablelist
><varlistentry>
<term
><synopsis
>bool document.insertText(<parameter
>int <replaceable
>riga</replaceable
></parameter
>, <parameter
>int <replaceable
>colonna</replaceable
></parameter
>, <parameter
>int <replaceable
>riga</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
></variablelist>


<variablelist
><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
></variablelist>


<variablelist
><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 o la riga non è nell'intervallo del documento. </para
></listitem>
</varlistentry
></variablelist>


<variablelist
><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 o la riga non è nell'intervallo del documento. </para
></listitem>
</varlistentry
></variablelist>


<variablelist
><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
></variablelist>


<variablelist
><varlistentry>
<term
><synopsis
>int document.lines();
</synopsis
></term>
<listitem
><para
>Restituisce il numero di righe nel documento. </para
></listitem>
</varlistentry
></variablelist>


<variablelist
><varlistentry>
<term
><synopsis
>int document.length();
</synopsis
></term>
<listitem
><para
>Restituisce il numero di caratteri nel documento. </para
></listitem>
</varlistentry
></variablelist>


<variablelist
><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
></variablelist>


<variablelist
><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
>. Chiamare <function
>editBegin</function
> usa internamente un contatore di riferimenti, quindi questa chiamata può essere annidata. </para
></listitem>
</varlistentry
></variablelist>


<variablelist
><varlistentry>
<term
><synopsis
>void document.editEnd();
</synopsis
></term>
<listitem
><para
>Chiude un gruppo di modifica. L'ultima chiamata di <function
>editEnd()</function
> (cioè quella corrispondente alla prima chiamata a <function
>editBegin()</function
>) conclude il passo di modifica. </para
></listitem>
</varlistentry
></variablelist>


<variablelist
><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
></variablelist>


<variablelist
><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
></variablelist>


<variablelist
><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 e cercando indietro. </para
></listitem>
</varlistentry
></variablelist>


<variablelist
><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 e cercando in avanti. </para
></listitem>
</varlistentry
></variablelist>


<variablelist
><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
></variablelist>


<variablelist
><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
></variablelist>


<variablelist
><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
></variablelist>


<variablelist
><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
></variablelist>


<variablelist
><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
></variablelist>


<variablelist
><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
></variablelist>


<variablelist
><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 multiriga per un <replaceable
>attributo</replaceable
>. </para
></listitem>
</varlistentry
></variablelist>


<variablelist
><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 multiriga per un <replaceable
>attributo</replaceable
>. </para
></listitem>
</varlistentry
></variablelist>



<variablelist
><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
></variablelist>


<variablelist
><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
></variablelist>


<variablelist
><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
></variablelist>


<variablelist
><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
></variablelist>


<variablelist
><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
></variablelist>



<variablelist
><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 o contiene solo caratteri di spaziatura. </para
></listitem>
</varlistentry
></variablelist>


<variablelist
><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 o contiene solo caratteri di spaziatura. </para
></listitem>
</varlistentry
></variablelist>


<variablelist
><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
></variablelist>


<variablelist
><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
></variablelist>


<variablelist
><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 <replaceable
>carattere</replaceable
> partendo dal cursore dato. Per esempio, se si passa come carattere <userinput
>(</userinput
>, la funzione restituirà la posizione dell'apertura <literal
>(</literal
>. Questo conteggio dei riferimenti, cioè altri <literal
>(...)</literal
>, vengono ignorati. </para
></listitem>
</varlistentry
></variablelist>


<variablelist
><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
>Trova all'indietro il <replaceable
>testo</replaceable
> 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 <replaceable
>testo</replaceable
>. </para
></listitem>
</varlistentry
></variablelist>


<variablelist
><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
></variablelist>


<variablelist
><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
></variablelist>



<variablelist
><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
></variablelist>


<variablelist
><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
></variablelist>


<variablelist
><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
></variablelist>


<variablelist
><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
></variablelist>


<variablelist
><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
></variablelist>
</para>

</sect3>
</sect2>
</sect1>
</chapter>