1
<chapter id="advanced-editing-tools">
5
>&Anders.Lund; &Anders.Lund.mail;</author>
7
>&Dominik.Haumann; &Dominik.Haumann.mail;</author>
8
<othercredit role="translator"
16
>nicola@nxnt.org</email
20
>Traduzione della documentazione.</contrib
22
><othercredit role="translator"
30
>mikelima@cirulla.net</email
34
>Aggiornamento per Kate 2.5.6</contrib
40
>Strumenti avanzati di modifica</title>
42
<sect1 id="advanced-editing-tools-comment">
45
>Commenta/Decommenta</title>
48
>I comandi Commenta e Decommenta, disponibili nel menu <guimenu
50
> 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>
53
>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>
56
>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>
59
>Se sono disponibili i marcatori per righe singole è preferibile usarli ogni volta che è possibile, perché ciò evita i problemi dei commenti nidificati.</para>
62
>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>
69
> Per inserire gli indicatori di commento, usa il comando <menuchoice
73
>Commenta</guimenuitem
75
> oppure la relativa scorciatoria da tastiera, quella predefinita è <keycombo action="simul"
84
>decommentare</primary
86
> Per rimuovere gli indicatori di commento, usa il comando <menuchoice
90
>Decommenta</guimenuitem
92
> oppure la relativa scorciatoia da tastiera; quella predefinita è <keycombo action="simul"
100
<sect1 id="advanced-editing-tools-commandline">
102
>La riga di comando per il componente dell'editor</title>
105
>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
109
>Passa alla riga di comando</guimenuitem
111
> o usa la scorciatoia (<keycombo action="simul"
115
>). L'editor fornisce l'insieme di comandi documentati di seguito, e comandi aggiuntivi sono forniti con le estensioni.</para>
118
>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
120
>, verrà nascosta automaticamente dopo qualche secondo. Per pulire la riga ed inserire un nuovo comando, premi di nuovo <keycap
125
>La riga di comando ha un sistema di aiuto integrato, usa il comando <command
127
> per iniziare. Per vedere un elenco di tutti i comandi disponibili usa <command
129
>, per vedere l'aiuto di un comando specifico usa <command
131
>comando</replaceable
136
>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
140
>. Quando vengono mostrati i comandi della cronologia, la parte degli argomenti del comando è selezionata, in modo da permetterti di sovrascrivere semplicemente gli argomenti.</para>
142
<sect2 id="advanced-editing-tools-commandline-commands">
144
>I comandi standard della riga di comando</title>
146
<sect3 id="advanced-editing-tools-commandline-commands-configure">
148
>Comandi per la configurazione dell'editor</title>
151
>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>
155
>Tipi di argomento</title>
162
>Questo tipo è usato nei comandi che devono attivare o disattivare una caratteristica. I valori ammessi sono <userinput
183
>Un numero intero</para
204
>set-tab-width</command
206
>INTEGER ampiezza</arg
211
>Imposta l'ampiezza della tabulazione al numero <userinput
221
>set-indent-width</command
223
>INTEGER ampiezza</arg
228
>Imposta l'ampiezza del rientro al numero <userinput
230
>. È usata solo se fai rientrare con gli spazi.</para
238
>set-word-wrap-column</command
240
>INTEGER ampiezza</arg
245
>Imposta l'ampiezza della riga al numero <userinput
247
>. È usata se il testo deve andare a capo automaticamente.</para
255
>set-icon-border</command
257
>BOOLEAN abilitazione</arg
262
>Imposta la visibilità del bordo per le icone.</para
270
>set-folding-markers</command
272
>BOOLEAN abilitazione</arg
277
>Imposta la visibilità del pannello per gli indicatori di raggruppamento.</para
285
>set-line-numbers</command
287
>BOOLEAN abilitazione</arg
292
>Imposta la visibilità del pannello per i numeri di riga.</para
300
>set-replace-tabs</command
302
>BOOLEAN abilitazione</arg
307
>Se è abilitata, le tabulazioni sono sostituiti con spazi durante l'inserimento. </para
315
>set-remove-trailing-space</command
317
>BOOLEAN abilitazione</arg
322
>Se è abilitata, gli spazi in fin di riga vengono rimossi quando il cursore lascia una riga.</para
330
>set-show-tabs</command
332
>BOOLEAN abilitazione</arg
337
>Se è abilitata, le tabulazioni e gli spazi bianchi in fin di riga saranno evidenziati con dei puntini.</para
345
>set-indent-spaces</command
347
>BOOLEAN abilitazione</arg
352
>Se è abilitata, l'editor farà rientrare il testo di <option
353
>indent-width</option
354
> spazi ad ogni livello di rientro, invece che di un carattere di tabulazione.</para
362
>set-mixed-indent</command
364
>BOOLEAN abilitazione</arg
369
>Se abilitato, &kate; userà una miscela di tabulazioni e spazi per i rientri delle righe. Ciascun livello di rientro sarà largo <option
370
>indent-width</option
371
>, e più livelli di rientro saranno ottimizzati usando il maggior numero possibile di tabulazioni.</para>
373
>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
375
> del documento al momento dell'esecuzione.</para
383
>set-word-wrap</command
385
>BOOLEAN abilitazione</arg
390
>Abilita o disabilita l'a capo automatico dinamico a seconda del parametro <userinput
391
>abilitazione</userinput
400
>set-replace-tabs-save</command
402
>BOOLEAN abilitazione</arg
407
>Quando è attiva questa opzione, le tabulazioni verranno sostituite con spazi durante il salvataggio del documento.</para
415
>set-remove-trailing-space-save</command
417
>BOOLEAN abilitazione</arg
422
>Quando è attiva questa opzione, gli spazi alla fine delle righe saranno scartati durante il salvataggio del documento.</para
430
>set-indent-mode</command
437
>Imposta la modalità di autorientro a <userinput
441
> è sconosciuto, la modalità sarà impostata a <literal
443
>. Le modalità valide sono <literal
469
>set-highlight</command
476
>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
480
>Evidenziazione</guisubmenu
482
>. Questo comando fornisce una lista per l'autocompletamento dell'argomento.</para
490
<sect3 id="advanced-editing-tools-commandline-commands-edit">
492
>Comandi per la modifica</title>
495
>Questi comandi servono a modificare il documento corrente.</para>
507
>Fa rientrare le righe selezionate o la riga attuale.</para
520
>Elimina un passo di rientro delle righe selezionate o della riga attuale.</para
528
>cleanindent</command
533
>Riordina il rientro delle righe selezionate o della riga attuale secondo le impostazioni per il rientro del documento. </para
546
>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
559
>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
572
>Elimina la riga attuale.</para
589
>Sostituisce il testo corrispondente a <userinput
592
>sostituzione</userinput
593
>. Se vuoi includere spazi bianchi nel <userinput
595
>, 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
597
> ed il resto come <userinput
598
>sostituzione</userinput
600
>sostituzione</userinput
601
> è vuota, vengono rimosse le corrispondenze con il <userinput
605
>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
606
>replace:opzioni modello sostituzione</userinput
607
>. Le opzioni disponibili sono: <variablelist>
616
>Cerca all'indietro.</para
627
>Cerca dalla posizione del cursore.</para
638
>Cerca solo all'interno della selezione.</para
649
>Esegue la ricerca con un'espressione regolare. Se è impostata, puoi usare <userinput
651
>, dove N è un numero che rappresenta le catture nella stringa di sostituzione.</para
662
>Esegue la ricerca facendo distinzione fra maiuscole e minuscole.</para
673
>Chiede il permesso prima di effettuare la sostituzione.</para
684
>Fa in modo che la ricerca consideri solo parole intere.</para
705
>Inserisce la stringa dell'ora/data come è specificato in <userinput
707
>, o nel formato <quote
708
>yyyy-MM-dd hh:mm:ss</quote
709
> se non ne è specificato nessuno. Le seguenti traduzioni sono effettuate nell'interpretazione di <userinput
720
>Il giorno in forma numerica senza zeri iniziali (1–31).</entry
728
>Il giorno in forma numerica con uno zero iniziale di allineamento (01–31).</entry
736
>Il nome del giorno abbreviato in forma locale (cioè "lun" ... "dom").</entry
744
>Il nome del giorno completo in forma locale (cioè "lunedì" ... "domenica").</entry
752
>Il mese in forma numerica senza zeri iniziali (1–12).</entry
760
>Il mese in forma numerica con uno zero iniziale se necessario (01–12).</entry
768
>Il nome del mese abbreviato in forma locale (cioè "gen" ... "dic").</entry
776
>Le ultime due cifre dell'anno (00–99).</entry
784
>L'anno come numero di quattro cifre (1752–8000).</entry
792
>L'ora senza zero iniziali (0–23 o 1–12 se in modalità AM/PM).</entry
800
>L'ora con zero iniziali (00–23 o 01–12 se in modalità AM/PM).</entry
808
>I minuti senza zero iniziali (0–59).</entry
816
>I minuti con zero iniziali (00–59).</entry
824
>I secondi senza zero iniziali (0–59).</entry
832
>I secondi con zero iniziali (00–59).</entry
840
>I millisecondi senza zeri iniziali (0–999).</entry
848
>I millisecondi con zeri iniziali (000–999).</entry
856
>Usa modalità AM/PM. AP sarà sostituito da "AM" per le ore antimeridiane o "PM" per quelle pomeridiane.</entry
864
>Usa modalità am/pm. ap sarà sostituito da "am" per le ore antimeridiane o "pm" per quelle pomeridiane.</entry
886
>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
887
>char: [numero]</userinput
888
> nel campo di inserimento, quindi fai clic su <guibutton
894
>Esempi con il comando <command
899
>Inserisci: <userinput
903
>Ottieni: <computeroutput
904
>ê</computeroutput
907
>Inserisci: <userinput
908
>char:0x1234</userinput
911
>Ottieni: <computeroutput
912
>ሴ</computeroutput
923
>sostituisci, come in sed</primary>
925
>cerca, come in sed</secondary
935
>Questo comando fa una ricerca/sostituzione nella riga di testo corrente o in tutto il file (<command
937
>) in maniera del tutto simile a sed.</para>
940
>In breve, la ricerca viene effettuata in base a un <emphasis
941
>modello di ricerca</emphasis
942
>, 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
943
>riferimenti all'indietro</emphasis
944
>, 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
946
> per il primo gruppo di parentesi, <userinput
948
> per il secondo e così via.</para>
951
>Per cercare precisamente il simbolo di parentesi <literal
957
> il problema usando la barra rovescia in questo modo: <userinput
962
>Se metti una <userinput
964
> alla fine dell'espressione, la corrispondenza avverrà senza tener far distinzione fra maiuscole o minuscole. Se metti una <userinput
966
>, verranno sostituite tutte le corrispondenze del modello, altrimenti verrà sostituita solo la prima.</para>
971
>Sostituire del testo nella riga corrente</title>
974
>Il tuo caro vecchio compilatore ha appena finito di bloccarsi dicendoti che la classe <classname
976
> che compare nella riga 3902 del tuo file sorgente non è definita.</para>
979
>"Naturale!" pensi, sai benissimo che si scrive <classname
981
>. Vai alla riga 3902 e, invece di provare a cercare la parola nel testo, apri la finestra di dialogo Comando di modifica, inserisci <userinput
982
>s/myclass/MyClass/i</userinput
985
>, salvi il file e lo compili – con successo senza errori.</para>
991
>Sostituire del testo nell'intero file</title>
994
>Immagina di avere un file, nel quale nomini <quote
996
> parecchie volte e arriva qualcuno che ti dice che si è appena sposata con <quote
998
>. Naturalmente tu vuoi sostituire tutti i <quote
1005
>Lancia la finestra di dialogo Comando di modifica, digita nell'apposito campo <userinput
1006
> %s/Miss Jensen/Ms Jones/</userinput
1007
> e premi invio. Il gioco è fatto!</para>
1013
>Un esempio più avanzato</title>
1016
>Questo esempio usa i <emphasis
1017
>riferimenti all'indietro</emphasis
1019
>classi di carattere</emphasis
1020
> (se non sai che cosa sono, leggi la relativa documentazione citata più in basso).</para>
1023
>Immagina di avere la seguente riga: <programlisting
1024
>void MyClass::DoStringOps( String &foo, String &bar String *p, int &a, int &b )</programlisting>
1027
>Ora ti rendi conto che il codice non va bene e decidi di usare la parola chiave <constant
1029
> per tutti gli argomenti <quote
1031
>, quelli caratterizzati dall'operatore & posto davanti al nome dell'argomento. Inoltre vorresti semplificare lo spazio vuoto in modo che ci sia solo uno spazio tra ogni parola.</para>
1034
>Apri la finestra di dialogo Comando di modifica e inserisci: <userinput
1035
>s/\s+(\w+)\s+(&)/ const \1 \2/g</userinput
1036
> e premi il pulsante <guibutton
1040
> 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
1041
>riferimento all'indietro</emphasis
1045
>Ottieni: <computeroutput
1046
>void MyClass::DoStringOps( const String &foo, const String &bar String *p, const int &a, const int &b )</computeroutput
1050
>Missione compiuta! Ora cos'è successo? Abbiamo cercato alcuni spazi vuoti (<literal
1052
>) seguiti da alcuni caratteri alfabetici (<literal
1054
>), seguiti da altri spazi vuoti (<literal
1056
>), 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
1058
>, seguito da un altro spazio vuoto, seguito dalla porzione alfabetica (<literal
1060
>), seguito da uno spazio vuoto e infine seguito dalla e commerciale salvata (<literal
1065
>Ora, in alcuni casi la porzione alfabetica era una <quote
1069
>, quindi se usi <literal
1071
> e il quantificatore <literal
1073
> sarà meglio.</para>
1085
<sect3 id="advanced-editing-tools-commandline-commands-navigation">
1087
>Comandi per gli spostamenti</title>
1102
>Questo comando sposta il cursore alla riga indicata.</para
1117
>Questo comando si sposta alla prima corrispondenza del <userinput
1119
> secondo la configurazione. Le corrispondenze successive possono essere trovate usando <menuchoice
1123
>Trova successivo</guimenuitem
1125
> (la scorciatoia predefinita è <keycap
1129
>Il comando find può essere configurato aggiungendo in fondo un due punti seguito da una o più opzioni, nella forma <userinput
1130
>find:opzioni modello</userinput
1131
>. Le seguenti opzioni sono disponibili: <variablelist>
1140
>Cerca all'indietro.</para
1151
>Cerca dalla posizione del cursore.</para
1162
>Cerca solo all'interno della selezione.</para
1173
>Esegue la ricerca con un'espressione regolare. Se è impostata, puoi usare <userinput
1175
>, dove N è un numero che rappresenta le catture nella stringa di sostituzione.</para
1186
>Esegue la ricerca facendo distinzione fra maiuscole e minuscole.</para
1197
>Fa in modo che la ricerca consideri solo parole intere.</para
1220
>Questo comando fornisce la ricerca <quote
1221
>mentre scrivi</quote
1222
>. Puoi configurarne il comportamento aggiungendo in fondo un due punti seguito da una o più opzioni, nella forma <userinput
1223
>ifind:opzioni modello</userinput
1224
>. Le seguenti opzioni sono disponibili: <variablelist>
1232
>Cerca all'indietro.</para
1243
>Esegue la ricerca di un'espressione regolare.</para
1254
>Esegue la ricerca facendo distinzione fra maiuscole e minuscole.</para
1265
>Cerca dalla posizione del cursore.</para
1282
<sect1 id="advanced-editing-tools-code-folding">
1284
>Uso del raggruppamento del codice</title>
1287
>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
1294
>Per usare la funzione di raggruppamento del codice, attiva gli indicatori di raggruppamento usando la voce <menuchoice
1296
>Visualizza</guimenu
1298
>Mostra segni di raggruppamento</guimenuitem
1300
> 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>
1303
>Sono forniti quattro comandi per manipolare lo stato delle regioni di raggruppamento del codice, vedi la <link linkend="view-code-folding"
1304
>documentazione del menu</link
1308
>Se non vuoi usare la funzione di raggruppamento del codice, puoi disabilitare l'opzione <guilabel
1309
>Mostra segni di raggruppamento (se disponibile)</guilabel
1310
> dalla pagina <link linkend="appearance"
1312
> dalla pagina di configurazione dell'editor.</para>
1316
<sect1 id="advanced-editing-tools-scripting">
1318
>Estensione di &kate; con script</title>
1321
>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>
1323
<sect2 id="advanced-editing-tools-scripting-indentation">
1325
>Script di rientro</title>
1328
>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>
1331
>Le sezioni seguenti descrivono passo-passo come creare la struttura di un semplice rientratore. Come primo passo, crea un nuovo file <literal role="extension"
1333
>, per esempio <filename
1334
>javascript.js</filename
1335
> nella cartella Home locale <filename
1338
>/share/apps/katepart/script</filename
1341
<sect3 id="advanced-editing-tools-scripting-indentation-header">
1343
>L'intestazione dello script di rientro</title>
1345
>L'intestazione del file <filename
1346
>javascript.js</filename
1347
> è incorporata in un commento e ha la forma seguente: <programlisting>
1350
* author: Pippo <pippo@topolinia.it>
1355
* required-syntax-style: javascript
1356
* indent-languages: javascript
1358
* i18n-catalog: mycatalog
1360
* Una riga senza due punti «:» interrompe l'analisi dell'intestazione.
1361
* Puoi quindi aggiungere del testo qui, come il testo di una licenza.
1364
> Ogni voce viene ora spiegata in dettaglio: <itemizedlist>
1368
>kate-script</literal
1369
> [obbligatorio]: questa stringa di testo deve essere nella prima riga del file <literal role="extension"
1371
>, altrimenti &kate; salterà lo script. </para
1377
> [obbligatorio]: questo è il nome del rientratore che appare nel menu <menuchoice
1381
>Rientro</guimenuitem
1383
> e nella finestra di configurazione. </para
1389
> [facoltativo]: il nome dell'autore e informazioni per contattarlo. </para
1395
> [facoltativo]: forma breve della licenza, come BSD o LGPLv3. </para
1401
> [obbligatorio]: la revisione dello script. Questo numero va aumentato a ogni sua modifica. </para
1406
>kate-version</literal
1407
> [obbligatorio]: versione minima di &kate; richiesta. </para
1413
> [obbligatorio]: il tipo deve essere <userinput
1414
>indentation</userinput
1415
>, altrimenti &kate; salterà lo script. </para
1420
>required-syntax-style</literal
1421
> [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
1422
>comportamento non definito</quote
1423
> causato dall'uso del rientratore senza lo schema di evidenziazione atteso. Per esempio, il rientratore di Ruby lo usa nei file <filename
1432
>indent-languages</literal
1433
> [facoltativo]: elenco separato da virgole di stili di sintassi che il rientratore può far rientrare correttamente, per esempio: <userinput
1434
>c++, java</userinput
1441
> [facoltativo]: se ci sono più rientratori che si adattano a un certo file evidenziato, la priorità decide quale viene scelto come predefinito. </para
1446
>i18n-catalog</literal
1447
> [facoltativo]: catalogo di messaggi aggiuntivo (file <literal
1449
>) caricato per la traduzione di rientratori di parti terze.</para
1455
>&kate; legge tutte le coppie nella forma <quote
1457
>chiave</replaceable
1459
>valore</replaceable
1461
> 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>
1465
<sect3 id="advanced-editing-tools-scripting-indentation-body">
1467
>Il codice sorgente del rientratore</title>
1469
>Dopo aver specificato l'intestazione, questa sezione spiega come funziona lo script di rientro vero e proprio. La struttura fondamentale ha questo aspetto:<programlisting>
1470
triggerCharacters = "{}/:;";
1471
function indent(riga, larghezza_rientro, carattere)
1473
// richiamato a ogni ritorno a capo (<varname
1475
> == '\n') e per tutti i caratteri
1476
// specificati nella in variabile globale triggerCharacters. Quando si chiama
1481
>Allinea</guimenuitem
1483
>, la variabile <varname
1485
> è vuota, cioè <varname
1489
// Vedi anche: API di scripting
1493
> La funzione <function
1495
> ha tre argomenti:<itemizedlist
1500
>: la riga da far rientrare;</para
1505
>larghezza_rientro</literal
1506
>: la larghezza del rientro espressa come numero di spazi;</para
1512
>: un carattere di ritorno a capo (<varname
1514
> == '\n'), un carattere di attivazione specificato in <varname
1515
>triggerCharacters</varname
1516
>, o vuota se l'utente ha attivato l'azione <menuchoice
1520
>Allinea</guimenuitem
1525
> Il valore restituito dalla funzione <function
1527
> specifica come far rientrare la riga. Se il valore è un semplice numero intero, viene interpretato come segue: <itemizedlist
1530
>Valore restituito <returnvalue
1532
>: non fare nulla;</para
1536
>Valore restituito <returnvalue
1538
>: mantieni il rientro (cerca una riga non vuota precedente)</para
1542
>Valore restituito <returnvalue
1544
>: I numeri numbers ≥ 0 specificano il rientro in spazi</para
1547
>In alternativa, si può restituire un array di due elementi: <itemizedlist
1551
>return <returnvalue
1552
>[ indent, align ]</returnvalue
1557
> 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
1558
>allineamento</quote
1559
>. 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
1560
>modalità mista</quote
1564
>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 <quote
1566
> uno spazio:<programlisting>
1567
1: <tab><tab>pippo("ciao",
1568
2: <tab><tab>......"mondo");
1570
> Quando si allinea la seconda riga, la funzione <function
1572
> restituisce <returnvalue
1573
>[8, 15]</returnvalue
1574
>. 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>
1577
>Un'installazione predefinita di &kde; include &kate; con diversi rientratori. Il codice JavaScript corrispondente si può trovare in <filename
1580
>/share/apps/katepart/script</filename
1584
>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
1585
>reload-scripts</command
1589
>Se sviluppi degli script utili, per piacere considera la possibilità di contribuirli al progetto &kate; <ulink url="mailto:kwrite-devel@kde.org"
1590
>contattando la lista di distribuzione</ulink
1596
<sect2 id="advanced-editing-tools-scripting-command-line">
1598
>Script dalla riga di comando</title>
1601
>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"
1602
>riga di comando integrata</link
1603
>. Per esempio, il comando <command
1605
> è implementato come uno script. Questa sezione spiega come creare file <literal role="extension"
1607
> per estendere &kate; con script di supporto a piacere. </para>
1610
>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"
1612
> nella cartella Home locale <filename class="directory"
1615
>/share/apps/katepart/script</filename
1618
<sect3 id="advanced-editing-tools-scripting-command-line-header">
1620
>L'intestazione dello script da riga di comando</title>
1622
>L'intestazione di ogni script da riga di comando è incorporata in un commento ed ha la forma seguente: <programlisting>
1624
* author: Pippo <pippo@topolinia.it>
1629
* functions: sort, format-paragraph
1630
* i18n-catalog: mycatalog
1632
* Una riga senza due punti «:» interrompe l'analisi dell'intestazione.
1633
* Puoi quindi aggiungere del testo qui, come il testo di una licenza.
1636
> Ogni voce verrà ora spiegata in dettaglio: <itemizedlist>
1640
>kate-script</literal
1641
> [obbligatorio]: questa stringa di testo deve essere nella prima riga del file <literal role="extension"
1643
>, altrimenti &kate; salterà lo script.</para
1649
> [facoltativo]: il nome dell'autore e informazioni per contattarlo.</para
1655
> [facoltativo]: forma breve della licenza, come BSD o LGPLv3.</para
1661
> [obbligatorio]: la revisione dello script. Questo numero va aumentato a ogni sua modifica.</para
1666
>kate-version</literal
1667
> [obbligatorio]: versione minima di &kate; richiesta.</para
1673
> [obbligatorio]: Il tipo deve essere <userinput
1674
>commands</userinput
1675
>, altrimenti &kate; salterà lo script.</para
1681
> [obbligatorio]: elenco separato da virgole dei comandi nello script.</para
1686
>i18n-catalog</literal
1687
> [facoltativo]: catalogo di messaggi aggiuntivo (file <literal
1689
>) caricato per la traduzione di script di parti terze.</para
1695
>&kate; legge tutte le coppie nella forma <quote
1697
>chiave</replaceable
1699
>valore</replaceable
1701
> 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
1703
> è 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"
1704
>riga di comando incorporata di &kate;</link
1708
<sect3 id="advanced-editing-tools-scripting-command-line-body">
1710
>Il codice sorgente dello script</title>
1713
>Tutte le funzioni specificate nell'intestazione vanno implementate nello script. Lo script nell'esempio sopra deve implementare le due funzioni <command
1716
>format-paragraph</command
1717
>. Tutte le funzioni hanno la sintassi seguente: <programlisting
1718
>function <nome>(argomento_1, argomento_2, ...)
1720
// ... implementazione, vedi anche: API per gli script
1726
>Gli argomenti nella riga di comando vengono passati alla funzione come <parameter
1727
>argomento_1</parameter
1729
>argomento_2</parameter
1730
>, eccetera. Per poter documentare ogni comando, basta implementare la funzione <function
1732
> come segue: <programlisting>
1733
function help(comando)
1735
if (comando == "sort") {
1736
return i18n("Ordina il testo selezionato.");
1737
} else if (comando == "...") {
1742
> Eseguire quindi <command
1744
> nella riga di comando chiamerà questa funzione ausiliaria con l'argomento <parameter
1746
> impostato al comando dato, per esempio <parameter
1747
>comando == "sort"</parameter
1748
>. &kate; presenterà quindi il testo risultante come documentazione per l'utente. Assicurati di <link linkend="advanced-editing-tools-scripting-api-i18n"
1749
>tradurre le stringhe</link
1752
<sect4 id="advanced-editing-tools-scripting-command-line-shortcuts">
1754
>Stabilire le scorciatoie</title>
1756
>Per poter assegnare delle scorciatoie, lo script deve fornire una funzione chiamata <literal
1758
> come la seguente:<programlisting>
1759
function action(cmd)
1761
var a = new Object();
1762
if (cmd == "sort") {
1763
a.text = i18n("Sort Selected Text");
1766
a.interactive = false;
1768
} else if (cmd == "moveLinesDown") {
1769
// stessa cosa per la prossima azione
1774
> Il parametro <literal
1776
> della funzione specifica il comando per cui si richiede una scorciatoia. Ci sono diversi campi che vanno specificati nell'oggetto JavaScript restituito: <itemizedlist>
1781
> [obbligatorio]: il testo che compare nel menu <menuchoice
1787
>. Assicurati di usare <literal
1789
> per le traduzioni dall'inglese.</para
1795
> [facoltativo]: l'icona che appare di fianco al testo nel menu. Qui si possono usare tutti i nomi delle icone di &kde;.</para
1800
>a.category</literal
1801
> [facoltativo]: se si specifica una categoria, lo script compare in un sottomenu. Assicurati di usare <literal
1803
> per le traduzioni dall'inglese.</para
1808
>a.interactive</literal
1809
> [facoltativo]: se allo script serve che l'utente faccia qualcosa, impostalo a <literal
1816
>a.shortcut</literal
1817
> [facoltativo]: la scorciatoia qui data è la predefinita, per esempio <keycombo action="simul"
1821
>. Vedi la <ulink url="http://doc.qt.nokia.com/latest/qt.html#Key-enum"
1822
>documentazione di &Qt;</ulink
1823
> per maggiori dettagli.</para
1830
>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
1831
>reload-scripts</command
1835
>Se sviluppi degli script utili, per piacere considera la possibilità di contribuirli al progetto &kate; <ulink url="mailto:kwrite-devel@kde.org"
1836
>contattando la lista di distribuzione</ulink
1843
<sect2 id="advanced-editing-tools-scripting-api">
1845
>API per gli script</title>
1848
>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
1851
>share/apps/katepart/api</filename
1852
>. Il nome di ogni file JavaScript ivi presente segue il seguente schema: <programlisting>
1853
<numero>_<nome>.js
1855
> Il numero ha due cifre e il nome è un nome a piacere, come per esempio <filename
1856
>mieiprogrammi</filename
1857
>. Con il numero &kate; può controllare l'ordine di esecuzione dell'API: il file <filename
1858
>05_cursor.js</filename
1859
> viene chiamato prima di <filename
1860
>10_range.js</filename
1861
>. Ciò assomiglia al sistema di runlevel/init di Linux. </para>
1864
>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
1867
>/share/apps/katepart/api</filename
1868
>, e assicurarsi che abbia un numero (cioè ordine di esecuzione) maggiore degli altri file <literal role="extension"
1870
> nella cartella globale <filename
1873
>/share/apps/katepart/api</filename
1874
>. &kate; cerca i file <literal role="extension"
1876
> automaticamente in entrambe le cartelle, e li esegue nell'ordine specificato. </para>
1879
>Per estendere i prototipi preesistenti, come <classname
1883
>, il modo raccomandato di procedere <emphasis
1885
> è di modificare i file <literal role="extension"
1887
> globali. Crea piuttosto un file <literal role="extension"
1889
> nella cartella locale da eseguire dopo il file <filename
1890
>05_cursor.js</filename
1891
>, e quindi cambiane il prototipo <classname
1893
> in JavaScript. </para>
1895
<sect3 id="advanced-editing-tools-scripting-api-prototypes">
1897
>Cursori e intervalli</title>
1900
>Essendo &kate; un editor di testo, tutta l'API per gli script si basa su cursori e intervalli ovunque sia possibile. Un cursore (<classname
1902
>) è una semplice tupla del tipo <literal
1903
>(riga, colonna)</literal
1904
> che rappresenta una posizione nel testo del documento. Un intervallo (<classname
1906
>) 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>
1908
<sect4 id="advanced-editing-tools-scripting-api-cursors">
1910
>Il prototipo dei cursori</title>
1921
>Costruttore. Restituisce un cursore alla posizione <literal
1926
>var cursore = new Cursor();</function
1943
>colonna</replaceable
1950
>Costruttore. Restituisce un cursore alla posizione <literal
1951
>(riga, colonna)</literal
1955
>var cursore = new Cursor(3, 42);</function
1967
>Cursor <replaceable
1975
>Costruttore di copia. Restituisce una copia dell'<replaceable
1980
>var copia = new Cursor(altro);</function
1991
>Cursor Cursor.clone();
1996
>Restituisce un clone del cursore.</para>
1999
>var clone = cursor.clone();</function
2010
>bool Cursor.isValid();
2015
>Controlla se il cursore è valido. Non lo è se la riga o la colonna sono impostate a <literal
2020
>var valido = cursor.isValid();</function
2031
>Cursor Cursor.invalid();
2036
>Restituisce un nuovo cursore non valido posizionato a <literal
2041
>var cursoreNonValido = cursor.invalid();</function
2051
>int Cursor.compareTo(<parameter
2052
>Cursor <replaceable
2060
>Confronta un cursore con un <replaceable
2062
>. Restituisce: <itemizedlist>
2067
>, se il cursore è posizionato prima dell'<replaceable
2075
>, se sono uguali, e</para
2081
>, se il cursore è posizionato dopo l'<replaceable
2096
>bool Cursor.equals(<parameter
2097
>Cursor <replaceable
2105
>Restituisce <literal
2107
> se il cursore e l'<replaceable
2109
> sono uguali, altrimenti <literal
2121
>String Cursor.toString();
2126
>Restituisce un cursore sotto forma di stringa nella forma <quote
2128
>Cursor(riga, colonna)</literal
2138
<sect4 id="advanced-editing-tools-scripting-api-ranges">
2140
>Il prototipo degli intervalli</title>
2151
>Costruttore. Chiamare <userinput
2152
>new Range()</userinput
2153
> restituisce un intervallo tra <literal
2168
>Cursor <replaceable
2169
>inizio</replaceable
2172
>Cursor <replaceable
2180
>Costruttore. Chiamare <literal
2181
>new Range(<replaceable
2182
>inizio</replaceable
2186
> restituisce l'intervallo (<replaceable
2187
>inizio</replaceable
2202
>riga_inizio</replaceable
2206
>colonna_inizio</replaceable
2210
>riga_fine</replaceable
2214
>colonna_fine</replaceable
2221
>Costruttore. Chiamare <literal
2222
>new Range(<replaceable
2223
>riga_inizio</replaceable
2225
>colonna_inizio</replaceable
2227
>riga_fine</replaceable
2229
>colonna_fine</replaceable
2231
> restituisce l'intervallo da (<replaceable
2232
>riga_inizio</replaceable
2234
>colonna_inizio</replaceable
2236
>riga_fine</replaceable
2238
>colonna_fine</replaceable
2258
>Costruttore di copia. Restituisce una copia dell'<replaceable
2260
> intervallo. </para
2270
>Range Range.clone();
2275
>Restituisce un clone dell'intervallo. </para>
2278
>var clone = range.clone();</function
2289
>bool Range.isValid();
2294
>Restituisce <literal
2296
> se entrambi i cursori iniziale e finale sono validi, altrimenti <literal
2301
>var valido = range.isValid();</function
2312
>bool Range.invalid();
2317
>Restituisce l'intervallo da <literal
2331
>bool Range.contains(<parameter
2332
>Cursor <replaceable
2333
>cursore</replaceable
2340
>Restituisce <literal
2342
> se l'intervallo contiene la posizione del <replaceable
2343
>cursore</replaceable
2344
>, altrimenti <literal
2356
>bool Range.contains(<parameter
2365
>Restituisce <literal
2367
> se l'intervallo contiene l'<replaceable
2369
>, altrimenti <literal
2381
>bool Range.containsColumn(<parameter
2383
>colonna</replaceable
2390
>Restituisce <literal
2392
> se la <replaceable
2393
>colonna</replaceable
2394
> è nell'intervallo semiaperto <literal
2395
>[inizio.colonna, fine.colonna)</literal
2396
>, altrimenti <literal
2408
>bool Range.containsLine(<parameter
2417
>Restituisce <literal
2419
> se la <replaceable
2421
> è nell'intervallo semiaperto <literal
2422
>[inizio.riga, fine.riga)</literal
2423
>, altrimenti <literal
2435
>bool Range.overlaps(<parameter
2444
>Restituisce <literal
2446
> se l'intervallo e l'<replaceable
2448
> hanno una regione in comune, altrimenti <literal
2460
>bool Range.overlapsLine(<parameter
2469
>Restituisce <literal
2471
> se la <replaceable
2473
> è nell'intervallo <literal
2474
>[inizio.riga, fine.riga]</literal
2475
>, altrimenti <literal
2487
>bool Range.overlapsColumn(<parameter
2489
>colonna</replaceable
2496
>Restituisce <literal
2498
> se la <replaceable
2499
>colonna</replaceable
2500
> è nell'intervallo <literal
2501
>[inizio.colonna, fine.colonna]</literal
2502
>, altrimenti <literal
2514
>bool Range.equals(<parameter
2523
>Restituisce <literal
2525
> se l'intervallo e l'<replaceable
2527
> sono uguali, altrimenti <literal
2539
>String Range.toString();
2544
>Restituisce un intervallo sotto forma di stringa nella forma <quote
2546
>Range(Cursor(riga, colonna), Cursor(riga, colonna))</literal
2556
<sect3 id="advanced-editing-tools-scripting-api-global">
2558
>Funzioni globali</title>
2560
>Questa sezione elenca tutte le funzioni globali.</para>
2562
<sect4 id="advanced-editing-tools-scripting-api-debug">
2570
>void debug(<parameter
2571
>String <replaceable
2579
>Stampa il <replaceable
2583
> nella console che ha avviato l'applicazione. </para
2589
<sect4 id="advanced-editing-tools-scripting-api-i18n">
2594
>Per supportare una localizzazione completa, ci sono diverse funzioni per tradurre le stringhe negli script, cioè <literal
2602
>. Queste funzioni si comportano esattamente come le <ulink url="http://techbase.kde.org/Development/Tutorials/Localization/i18n"
2603
>funzioni di traduzione di &kde;</ulink
2607
>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 &kate; sono automaticamente estratte e traducibili: gli sviluppatori di &kate; non devono preoccuparsi di estrarre e tradurre i messaggi. Tuttavia, nel caso di script di terze parti sviluppati al di fuori di &kde;, i messaggi vanno estratti e tradotti a parte. Assieme ai tuoi script dovrai quindi distribuire un catalogo di traduzioni che includa tutte le stringhe tradotte. Inoltre, l'intestazione dello script dovrà specificare esplicitamente il catalogo da caricare indicandolo con <literal
2608
>i18n-catalog</literal
2615
>void i18n(<parameter
2616
>String <replaceable
2620
>argomento_1</replaceable
2626
>Traduce <replaceable
2628
> nella lingua usata dall'applicazione. Gli argomenti <replaceable
2629
>argomento_1</replaceable
2630
> e seguenti sono facoltativi e vengono usati per sostituire i segnaposti <literal
2634
>, e così via.</para
2643
>void i18nc(<parameter
2644
>String <replaceable
2645
>contesto</replaceable
2648
>String <replaceable
2652
>argomento_1</replaceable
2658
>Traduce <replaceable
2660
> nella lingua usata dall'applicazione. Inoltre, la stringa <replaceable
2661
>contesto</replaceable
2662
> viene resa visibile ai traduttori per chiarire eventuali equivoci e produrre una traduzione migliore. Gli argomenti <replaceable
2663
>argomento_1</replaceable
2664
> e seguenti sono facoltativi e vengono usati per sostituire i segnaposti <literal
2668
>, e così via.</para
2677
>void i18np(<parameter
2678
>String <replaceable
2679
>singolare</replaceable
2682
>String <replaceable
2683
>plurale</replaceable
2687
>numero</replaceable
2690
>argomento_1</replaceable
2696
>Traduce <replaceable
2697
>singolare</replaceable
2699
>plurale</replaceable
2700
> nella lingua usata dall'applicazione, a seconda del <replaceable
2701
>numero</replaceable
2702
> dato. Gli argomenti <replaceable
2703
>argomento_1</replaceable
2704
> e seguenti sono facoltativi e vengono usati per sostituire i segnaposti <literal
2708
>, e così via.</para
2717
>void i18ncp(<parameter
2718
>String <replaceable
2719
>contesto</replaceable
2722
>String <replaceable
2723
>singolare</replaceable
2726
>String <replaceable
2727
>plurale</replaceable
2731
>numero</replaceable
2734
>argomento_1</replaceable
2740
>Traduce <replaceable
2741
>singolare</replaceable
2743
>plurale</replaceable
2744
> nella lingua usata dall'applicazione, a seconda del <replaceable
2745
>numero</replaceable
2746
> dato. Inoltre, la stringa <replaceable
2747
>contesto</replaceable
2748
> viene resa visibile ai traduttori per chiarire eventuali equivoci e produrre una traduzione migliore. Gli argomenti <replaceable
2749
>argomento_1</replaceable
2750
> e seguenti sono facoltativi e vengono usati per sostituire i segnaposti <literal
2754
>, e così via.</para
2762
<sect3 id="advanced-editing-tools-scripting-api-view">
2764
>L'API delle viste</title>
2766
>Ogni volta che uno script viene eseguito è presente una variabile globale, <quote
2770
>, che rappresenta la vista attiva dell'editor. Segue un elenco di tutte le funzioni di vista disponibili. <variablelist
2775
>Cursor view.cursorPosition()</function
2781
>Restituisce la posizione attuale del cursore nella vista.</para
2792
>void view.setCursorPosition(<parameter
2798
>colonna</replaceable
2802
>void view.setCursorPosition(<parameter
2803
>Cursor <replaceable
2804
>cursore</replaceable
2812
>Restituisce la posizione attuale del cursore nella vista.</para
2822
>void view.setCursorPosition(<parameter
2828
>colonna</replaceable
2831
void view.setCursorPosition(<parameter
2832
>Cursor <replaceable
2833
>cursore</replaceable
2840
>Imposta la posizione attuale del cursore a <literal
2844
>colonna</replaceable
2847
>cursore</replaceable
2858
>Cursor view.virtualCursorPosition();
2863
>Restituisce la posizione virtuale del cursore con ogni tabulazione che conta una quantità di spazi dipendente dall'attuale ampiezza di tabulazione. </para
2873
>void view.setVirtualCursorPosition(<parameter
2879
>colonna</replaceable
2882
void view.setVirtualCursorPosition(<parameter
2883
>Cursor <replaceable
2884
>cursore</replaceable
2891
>Imposta la posizione virtuale attuale del cursore a <literal
2895
>colonna</replaceable
2898
>cursore</replaceable
2909
>String view.selectedText();
2914
>Restituisce il testo selezionato. Se non c'è del testo selezionato, la stringa restituita è vuota. </para
2924
>bool view.hasSelection();
2929
>Restituisce <literal
2931
> se la vista contiene del testo selezionato, altrimenti <literal
2943
>Range view.selection();
2948
>Restituisce l'intervallo di testo selezionato. L'intervallo di testo non è valido se non c'è testo selezionato. </para
2958
>void view.setSelection(<parameter
2960
>intervallo</replaceable
2967
>Imposta il testo selezionato all'<replaceable
2968
>intervallo</replaceable
2979
>void view.removeSelectedText();
2984
>Rimuovi il testo selezionato. Se la vista non ne ha, non fa nulla. </para
2994
>void view.selectAll();
2999
>Seleziona tutto il testo del documento. </para
3009
>void view.clearSelection();
3014
>Pulisce la selezione di testo senza rimuoverlo. </para
3021
<sect3 id="advanced-editing-tools-scripting-api-document">
3023
>L'API dei documenti</title>
3025
>Ogni volta che uno script viene eseguito è presente una variabile globale, <quote
3029
>, che rappresenta il documento attivo. Segue un elenco di tutte le funzioni del documento disponibili. <variablelist
3033
>String document.fileName();
3038
>Restituisce il nome del file del documento o una stringa vuota per i documenti non salvati. </para
3048
>String document.url();
3053
>Restituisce l'URL completo del documento, o una stringa vuota per i documenti non salvati. </para
3063
>String document.mimeType();
3068
>Restituisce il tipo di file del documento, o il tipo di file <literal
3069
>application/octet-stream</literal
3070
> se non se ne può trovare uno appropriato. </para
3080
>String document.encoding();
3085
>Restituisce la codifica attualmente usata per salvare il file. </para
3094
>String document.highlightingMode();
3099
>Restituisce la modalità di evidenziazione globale usata per tutto il documento. </para
3108
>String document.highlightingModeAt(<parameter
3109
>Cursor <replaceable
3110
>posizione</replaceable
3117
>Restituisce la modalità di evidenziazione usata alla <replaceable
3118
>posizione</replaceable
3119
> nel documento. </para
3128
>Array document.embeddedHighlightingModes();
3133
>Restituisce un array di modalità di evidenziazione incorporate in questo documento. </para
3142
>bool document.isModified();
3147
>Restituisce <literal
3149
> se il documento ha modifiche non salvate, altrimenti <literal
3161
>String document.text();
3166
>Restituisce tutto il contenuto del documento in una sola stringa di testo. I ritorni a capo sono indicati con il carattere <quote
3180
>String document.text(<parameter
3182
>da_riga</replaceable
3186
>da_colonna</replaceable
3190
>a_riga</replaceable
3194
>a_colonna</replaceable
3197
String document.text(<parameter
3198
>Cursor <replaceable
3202
>Cursor <replaceable
3206
String document.text(<parameter
3208
>intervallo</replaceable
3215
>Restituisce il testo nell'intervallo dato. Si raccomanda di usare le versioni con cursori o intervalli per migliorare la leggibilità del codice. </para
3225
>String document.line(<parameter
3234
>Restituisce la riga di testo richiesta come stringa. La stringa è vuota se la riga richiesta è oltre i limiti. </para
3244
>String document.wordAt(<parameter
3250
>colonna</replaceable
3253
String document.wordAt(<parameter
3254
>Cursor <replaceable
3255
>cursore</replaceable
3262
>Restituisce la parola alla posizione del cursore data. </para
3272
>String document.charAt(<parameter
3278
>colonna</replaceable
3281
String document.charAt(<parameter
3282
>Cursor <replaceable
3283
>cursore</replaceable
3290
>Restituisce il carattere alla posizione del cursore data. </para
3300
>String document.firstChar(<parameter
3309
>Restituisce il primo carattere nella <replaceable
3311
> 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
3321
>String document.lastChar(<parameter
3330
>Restituisce l'ultimo carattere nella <replaceable
3332
> data che non sia uno spazio. Se la riga è vuota o contiene solo spazi, la stringa restituita è vuota. </para
3342
>bool document.isSpace(<parameter
3348
>colonna</replaceable
3351
bool document.isSpace(<parameter
3352
>Cursor <replaceable
3353
>cursore</replaceable
3360
>Restituisce <literal
3362
> se il carattere alla posizione del cursore data è uno spazio, altrimenti <literal
3374
>bool document.matchesAt(<parameter
3380
>colonna</replaceable
3387
>String <replaceable
3391
bool document.matchesAt(<parameter
3392
>Cursor <replaceable
3393
>cursore</replaceable
3396
>String <replaceable
3404
>Restituisce <literal
3406
> se il <replaceable
3408
> corrisponde a quello presente alla posizione del cursore, altrimenti <literal
3420
>bool document.startsWith(<parameter
3425
>String <replaceable
3430
>salta_spazi</replaceable
3437
>Restituisce <literal
3439
> se la riga comincia con il <replaceable
3441
>, altrimenti <literal
3443
>. L'argomento <replaceable
3444
>salta_spazi</replaceable
3445
> decide se gli spazi iniziali vanno ignorati. </para
3455
>bool document.endsWith(<parameter
3460
>String <replaceable
3465
>salta_spazi</replaceable
3472
>Restituisce <literal
3474
> se la riga finisce con il <replaceable
3476
>, altrimenti <literal
3478
>. L'argomento <replaceable
3479
>salta_spazi</replaceable
3480
> decide se gli spazi finali vanno ignorati. </para
3490
>bool document.setText(<parameter
3491
>String <replaceable
3499
>Imposta tutto il testo del documento. </para
3509
>bool document.clear();
3514
>Rimuove tutto il testo del documento. </para
3524
>bool document.truncate(<parameter
3530
>colonna</replaceable
3533
bool document.truncate(<parameter
3534
>Cursor <replaceable
3535
>cursore</replaceable
3542
>Tronca la <replaceable
3545
>colonna</replaceable
3546
>. Restituisce <literal
3548
> se funziona, o <literal
3550
> se la <replaceable
3552
> non fa parte dell'intervallo del documento. </para
3562
>bool document.insertText(<parameter
3568
>colonna</replaceable
3575
>String <replaceable
3579
bool document.insertText(<parameter
3580
>Cursor <replaceable
3581
>cursore</replaceable
3584
>String <replaceable
3592
>Inserisce il <replaceable
3594
> alla posizione del cursore data. Restituisce <literal
3596
> se funziona, o <literal
3598
> se il documento è in modalità a sola lettura. </para
3608
>bool document.removeText(<parameter
3610
>da_riga</replaceable
3614
>da_colonna</replaceable
3618
>a_riga</replaceable
3622
>a_colonna</replaceable
3625
bool document.removeText(<parameter
3626
>Cursor <replaceable
3630
>Cursor <replaceable
3634
bool document.removeText(<parameter
3636
>intervallo</replaceable
3643
>Rimuove il testo nell'intervallo dato. Restituisce <literal
3645
> se funziona, o <literal
3647
> se il documento è in modalità di sola lettura. </para
3657
>bool document.insertLine(<parameter
3662
>String <replaceable
3670
>Inserisce il testo nella riga data. Restituisce <literal
3672
> se funziona, o <literal
3674
> se il documento è in modalità di sola lettura o la riga non è nell'intervallo del documento. </para
3684
>bool document.removeLine(<parameter
3693
>Rimuove la riga di testo data. Restituisce <literal
3695
> se funziona, o <literal
3697
> se il documento è in modalità di sola lettura o la riga non è nell'intervallo del documento. </para
3707
>void document.joinLines(<parameter
3709
>riga_inizio</replaceable
3713
>riga_fine</replaceable
3720
>Unisce le righe da <replaceable
3721
>riga_inizio</replaceable
3723
>riga_fine</replaceable
3724
>. Due righe di testo consecutive sono sempre separate da un solo spazio. </para
3734
>int document.lines();
3739
>Restituisce il numero di righe nel documento. </para
3749
>int document.length();
3754
>Restituisce il numero di caratteri nel documento. </para
3764
>int document.lineLength(<parameter
3773
>Restituisce la lunghezza della <replaceable
3785
>void document.editBegin();
3790
>Avvia un gruppo di modifica per un raggruppamento di azioni annullabili. Assicurati di chiamare sempre <function
3791
>editEnd()</function
3792
> con la stessa frequenza di <function
3793
>editBegin()</function
3794
>. Chiamare <function
3795
>editBegin</function
3796
> usa internamente un contatore di riferimenti, quindi questa chiamata può essere annidata. </para
3806
>void document.editEnd();
3811
>Chiude un gruppo di modifica. L'ultima chiamata di <function
3812
>editEnd()</function
3813
> (cioè quella corrispondente alla prima chiamata a <function
3814
>editBegin()</function
3815
>) conclude il passo di modifica. </para
3825
>int document.firstColumn(<parameter
3834
>Restituisce la prima colonna non di spazi nella <replaceable
3836
>. Se nella <replaceable
3838
> ci sono solo spazi, viene restituito <literal
3850
>int document.lastColumn(<parameter
3859
>Restituisce l'ultima colonna non di spazi nella <replaceable
3861
>. Se nella <replaceable
3863
> ci sono solo spazi, viene restituito <literal
3875
>int document.prevNonSpaceColumn(<parameter
3881
>colonna</replaceable
3884
int document.prevNonSpaceColumn(<parameter
3885
>Cursor <replaceable
3886
>cursore</replaceable
3893
>Restituisce la colonna con caratteri non di spaziatura che comincia alla posizione del cursore data e cercando indietro. </para
3903
>int document.nextNonSpaceColumn(<parameter
3909
>colonna</replaceable
3912
int document.nextNonSpaceColumn(<parameter
3913
>Cursor <replaceable
3914
>cursore</replaceable
3921
>Restituisce la colonna con caratteri non di spaziatura che comincia alla posizione del cursore data e cercando in avanti. </para
3931
>int document.prevNonEmptyLine(<parameter
3940
>Restituisce la prossima riga non vuota con caratteri non di spaziatura cercando indietro. </para
3950
>int document.nextNonEmptyLine(<parameter
3959
>Restituisce la prossima riga non vuota con caratteri non di spaziatura cercando in avanti. </para
3969
>bool document.isInWord(<parameter
3970
>String <replaceable
3971
>carattere</replaceable
3975
>attributo</replaceable
3982
>Restituisce <literal
3984
> se il <replaceable
3985
>carattere</replaceable
3986
> con l'<replaceable
3987
>attributo</replaceable
3988
> può far parte di una parola, altrimenti <literal
4000
>bool document.canBreakAt(<parameter
4001
>String <replaceable
4002
>carattere</replaceable
4006
>attributo</replaceable
4013
>Restituisce <literal
4015
> se il <replaceable
4016
>carattere</replaceable
4017
> con l'<replaceable
4018
>attributo</replaceable
4019
> può essere mandato a capo, altrimenti <literal
4031
>bool document.canComment(<parameter
4033
>attributo_inizio</replaceable
4037
>attributo_fine</replaceable
4044
>Restituisce <literal
4046
> se un intervallo che inizia e finisce con gli attributi dati può essere fatto diventare un commento, altrimenti <literal
4058
>String document.commentMarker(<parameter
4060
>attributo</replaceable
4067
>Restituisce l'indicatore di commento per i commenti di una sola riga per un <replaceable
4068
>attributo</replaceable
4079
>String document.commentStart(<parameter
4081
>attributo</replaceable
4088
>Restituisce l'indicatore di commento per l'inizio di commenti multiriga per un <replaceable
4089
>attributo</replaceable
4100
>String document.commentEnd(<parameter
4102
>attributo</replaceable
4109
>Restituisce l'indicatore di commento per la fine di commenti multiriga per un <replaceable
4110
>attributo</replaceable
4122
>int document.attribute(<parameter
4128
>colonna</replaceable
4131
int document.attribute(<parameter
4132
>Cursor <replaceable
4133
>cursore</replaceable
4140
>Restituisce l'attributo alla posizione del cursore data. </para
4150
>bool document.isAttribute(<parameter
4156
>colonna</replaceable
4160
>attributo</replaceable
4163
bool document.isAttribute(<parameter
4164
>Cursor <replaceable
4165
>cursore</replaceable
4169
>attributo</replaceable
4176
>Restituisce <literal
4178
> se l'attributo alla posizione del cursore data è uguale a <replaceable
4179
>attributo</replaceable
4180
>, altrimenti <literal
4192
>String document.attributeName(<parameter
4198
>colonna</replaceable
4201
String document.attributeName(<parameter
4202
>Cursor <replaceable
4203
>cursore</replaceable
4210
>Restituisce il nome dell'attributo in testo leggibile. È uguale al nome <literal
4212
> nei file di evidenziazione della sintassi. </para
4222
>bool document.isAttributeName(<parameter
4228
>colonna</replaceable
4231
>String <replaceable
4235
bool document.isAttributeName(<parameter
4236
>Cursor <replaceable
4237
>cursore</replaceable
4240
>String <replaceable
4248
>Restituisce <literal
4250
> se il nome dell'attributo a una certa posizione del cursore corrisponde al <replaceable
4252
>, altrimenti <literal
4264
>String document.variable(<parameter
4265
>String <replaceable
4266
>chiave</replaceable
4273
>Restituisce il valore della variabile del documento <replaceable
4274
>chiave</replaceable
4275
>. Se la variabile non esiste, il valore restituito è una stringa vuota. </para
4286
>int document.firstVirtualColumn(<parameter
4295
>Restituisce la colonna virtuale del primo carattere non di spaziatura nella riga indicata, o <literal
4297
> se la riga è vuota o contiene solo caratteri di spaziatura. </para
4307
>int document.lastVirtualColumn(<parameter
4316
>Restituisce la colonna virtuale dell'ultimo carattere non di spaziatura nella riga indicata, o <literal
4318
> se la riga è vuota o contiene solo caratteri di spaziatura. </para
4328
>int document.toVirtualColumn(<parameter
4334
>colonna</replaceable
4337
int document.toVirtualColumn(<parameter
4338
>Cursor <replaceable
4339
>cursore</replaceable
4342
Cursor document.toVirtualCursor(<parameter
4343
>Cursor <replaceable
4344
>cursore</replaceable
4351
>Converte la posizione <quote
4353
> del cursore in una virtuale, restituendo un oggetto <classname
4367
>int document.fromVirtualColumn(<parameter
4373
>colonna_virtuale</replaceable
4376
int document.fromVirtualColumn(<parameter
4377
>Cursor <replaceable
4378
>cursore_virtuale</replaceable
4381
Cursor document.fromVirtualCursor(<parameter
4382
>Cursor <replaceable
4383
>cursore_virtuale</replaceable
4390
>Converte la posizione virtuale data del cursore in una <quote
4392
>, restituendo un oggetto <classname
4406
>Cursor document.anchor(<parameter
4412
>colonna</replaceable
4416
>carattere</replaceable
4419
Cursor document.anchor(<parameter
4420
>Cursor <replaceable
4421
>cursore</replaceable
4425
>carattere</replaceable
4432
>Cerca indietro il <replaceable
4433
>carattere</replaceable
4434
> partendo dal cursore dato. Per esempio, se si passa come carattere <userinput
4436
>, la funzione restituirà la posizione dell'apertura <literal
4438
>. Questo conteggio dei riferimenti, cioè altri <literal
4440
>, vengono ignorati. </para
4450
>Cursor document.rfind(<parameter
4456
>colonna</replaceable
4459
>String <replaceable
4464
>attributo</replaceable
4467
Cursor document.rfind(<parameter
4468
>Cursor <replaceable
4469
>cursore</replaceable
4472
>String <replaceable
4477
>attributo</replaceable
4484
>Trova all'indietro il <replaceable
4486
> con l'<replaceable
4487
>attributo</replaceable
4488
> appropriato. L'<replaceable
4489
>attributo</replaceable
4490
> viene ignorato se è impostato a <literal
4492
>. Il cursore restituito non è valido se non si trova il <replaceable
4504
>int document.defStyleNum(<parameter
4510
>colonna</replaceable
4513
int document.defStyleNum(<parameter
4514
>Cursor <replaceable
4515
>cursore</replaceable
4522
>Restituisce lo stile predefinito usato alla posizione data del cursore. </para
4532
>bool document.isCode(<parameter
4538
>colonna</replaceable
4541
bool document.isCode(<parameter
4542
>Cursor <replaceable
4543
>cursore</replaceable
4550
>Restituisce <literal
4552
> se l'attributo alla posizione data del cursore non è uguale a tutti i seguenti stili: <literal
4557
>dsRegionMarker</literal
4573
>bool document.isComment(<parameter
4579
>colonna</replaceable
4582
bool document.isComment(<parameter
4583
>Cursor <replaceable
4584
>cursore</replaceable
4591
>Restituisce <literal
4593
> se l'attributo del carattere alla posizione del cursore data è <literal
4595
>, altrimenti <literal
4607
>bool document.isString(<parameter
4613
>colonna</replaceable
4616
bool document.isString(<parameter
4617
>Cursor <replaceable
4618
>cursore</replaceable
4625
>Restituisce <literal
4627
> se l'attributo del carattere alla posizione del cursore data è <literal
4629
>, altrimenti <literal
4641
>bool document.isRegionMarker(<parameter
4647
>colonna</replaceable
4650
bool document.isRegionMarker(<parameter
4651
>Cursor <replaceable
4652
>cursore</replaceable
4659
>Restituisce <literal
4661
> se l'attributo del carattere alla posizione del cursore data è <literal
4662
>dsRegionMarker</literal
4663
>, altrimenti <literal
4675
>bool document.isChar(<parameter
4681
>colonna</replaceable
4684
bool document.isChar(<parameter
4685
>Cursor <replaceable
4686
>cursore</replaceable
4693
>Restituisce <literal
4695
> se l'attributo del carattere alla posizione del cursore data è <literal
4697
>, altrimenti <literal
4709
>bool document.isOthers(<parameter
4715
>colonna</replaceable
4718
bool document.isOthers(<parameter
4719
>Cursor <replaceable
4720
>cursore</replaceable
4727
>Restituisce <literal
4729
> se l'attributo del carattere alla posizione del cursore data è <literal
4731
>, altrimenti <literal