# Strumenti avanzati di modifica

## Commenta/Decommenta

I comandi Commenta e Decommenta, disponibili nel menu Strumenti 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.

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.

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.

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

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.

Per inserire gli indicatori di commento, usa il comando Strumenti Commenta oppure la relativa scorciatoria da tastiera, quella predefinita è &Ctrl;#.

Per rimuovere gli indicatori di commento, usa il comando Strumenti Decommenta oppure la relativa scorciatoia da tastiera; quella predefinita è &Ctrl;&Shift;#.

## La riga di comando per il componente dell'editor

Il componente dell'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 Visualizza Passa alla riga di comando o usa la scorciatoia (F7). L'editor fornisce l'insieme di comandi documentati di seguito, e comandi aggiuntivi sono forniti con i plugin.

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 F7, verrà nascosta automaticamente dopo qualche secondo. Per pulire la riga ed inserire un nuovo comando, premi di nuovo F7.

La riga di comando ha un sistema di aiuto integrato, usa il comando `help` per iniziare. Per vedere un elenco di tutti i comandi disponibili usa `help list`, per vedere l'aiuto di un comando specifico usa `help `comando``.

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 Freccia su e Freccia giù. Quando vengono mostrati i comandi della cronologia, la parte degli argomenti del comando è selezionata, in modo da permetterti di sovrascrivere semplicemente gli argomenti.

### I comandi standard della riga di comando

#### Comandi per la configurazione dell'editor

Questi comandi sono forniti dal componente dell'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.

#### Tipi di argomento

BOOLEAN

- Questo tipo è usato nei comandi che devono attivare o disattivare una caratteristica. I valori ammessi sono `on`, `off`, `true`, `false`, `1` o `0`

INTEGER

- Un numero intero

STRING

- Una stringa

    set-tab-widthINTEGER ampiezza

- Imposta l'ampiezza della tabulazione al numero `ampiezza`.

    set-indent-widthINTEGER ampiezza

- Imposta l'ampiezza dell'indentazione al numero `ampiezza`. È usata solo se stai indentando con gli spazi.

    set-word-wrap-columnINTEGER ampiezza

- Imposta l'ampiezza della riga al numero `ampiezza`. È usata se il testo deve andare a capo automaticamente.

    set-icon-borderBOOLEAN abilitazione

- Imposta la visibilità del bordo per le icone.

    set-folding-markersBOOLEAN abilitazione

- Imposta la visibilità del pannello per gli indicatori di raggruppamento.

    set-line-numbersBOOLEAN abilitazione

- Imposta la visibilità del pannello per i numeri di riga.

    set-replace-tabsBOOLEAN abilitazione

- Se è abilitata, le tabulazioni sono sostituiti con spazi durante l'inserimento.

    set-remove-trailing-spaceBOOLEAN abilitazione

- Se è abilitata, gli spazi in fin di riga vengono rimossi quando il cursore lascia una riga.

    set-show-tabsBOOLEAN abilitazione

- Se è abilitata, i caratteri Tab e gli spazi bianchi in fin di riga saranno evidenziati con dei puntini.

    set-indent-spacesBOOLEAN abilitazione

- Se è abilitata, l'editor farà rientrare il testo di `indent-width` spazi ad ogni livello di rientro, invece che di un carattere di tabulazione.

    set-mixed-indentBOOLEAN abilitazione

- Se abilitazione vale true, kate userà una miscela di Tab e spazi per i rientri delle righe. Ciascun livello di rientro sarà largo `indent-width`, e più livelli di rientro saranno ottimizzati usando il maggior numero possibile di caratteri Tab.

  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 `tab-width` del documento al momento dell'esecuzione.

    set-word-wrapBOOLEAN abilitazione

- Abilita o disabilita l'a capo automatico dinamico a seconda del parametro `abilitazione`.

    set-replace-tabs-saveBOOLEAN abilitazione

- Quando è attiva questa opzione, le tabulazioni verranno sostituite con spazi durante il salvataggio del documento.

    set-remove-trailing-space-saveBOOLEAN abilitazione

- Quando è attiva questa opzione, gli spazi alla fine delle righe saranno scartati durante il salvataggio del documento.

    set-indent-modenome

- Imposta la modalità di autoindentazione a `nome`. Se `nome` è sconosciuto, la modalità sarà impostata a "none". Le modalità valide sono 'cstyle', 'csands', 'xml', 'python', 'varindent' e 'none'.

    set-highlightevidenziazione

- Seleziona il sistema di evidenziazione della sintassi per il documento. L'argomento deve essere un nome di evidenziazione valido, così come è mostrato nel menu Strumenti Evidenziazione. Questo comando fornisce una lista per l'autocompletamento dell'argomento.

#### Comandi per la modifica

Questi comandi servono a modificare il documento corrente.

    indent

- Fa rientrare le righe selezionate o la riga attuale.

    unindent

- Elimina un passo di rientro delle righe selezionate o della riga attuale.

    cleanindent

- Riordina l'indentazione delle righe selezionate o della riga attuale secondo le impostazioni per l'indentazione del documento.

    comment

- 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.

    uncomment

- 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.

    kill-line

- Elimina la riga attuale.

    replacemodellosostituzione

- Sostituisce il testo corrispondente a `modello` con `sostituzione`. Se vuoi includere spazi bianchi nel `modello`, 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 `modello` ed il resto come `sostituzione`. Se la `sostituzione` è vuota, vengono rimosse le corrispondenze con il `modello`.

  Puoi impostare dei modificatori per configurare la ricerca aggiungendo un due punti, seguiti da una o più lettere rappresentanti la configurazione, data nella forma `replace:opzioni modello sostituzione`. Le opzioni disponibili sono:

  `b`

- Cerca all'indietro.

`c`

- Cerca dalla posizione del cursore.

`e`

- Cerca solo all'interno della selezione.

`r`

- Esegue la ricerca con un'espressione regolare. Se è impostata, puoi usare `\N`, dove N è un numero che rappresenta le catture nella stringa di sostituzione.

`s`

- Esegue la ricerca facendo distinzione fra maiuscole e minuscole.

`p`

- Chiede il permesso prima di effettuare la sostituzione.

`w`

- Fa in modo che la ricerca consideri solo parole intere.

    dateformato

- Inserisce la stringa dell'ora/data come è specificato in `formato`, o nel formato yyyy-MM-dd hh:mm:ss se non ne è specificato nessuno. Le seguenti traduzioni sono effettuate nell'interpretazione di `formato`:

  `d` | Il giorno in forma numerica senza zeri iniziali (1–31).
  `dd` | Il giorno in forma numerica con uno zero iniziale di allineamento (01–31).
  `ddd` | Il nome del giorno abbreviato in forma locale (cioè "lun" ... "dom").
  `dddd` | Il nome del giorno completo in forma locale (cioè "lunedì" ... "domenica").
  `M` | Il mese in forma numerica senza zeri iniziali (1–12).
  `MM` | Il mese in forma numerica con uno zero iniziale se necessario (01–12).
  `MMM` | Il nome del mese abbreviato in forma locale (cioè "gen" ... "dic").
  `yy` | Le ultime due cifre dell'anno (00–99).
  `yyyy` | L'anno come numero di quattro cifre (1752–8000).
  `h` | L'ora senza zero iniziali (0–23 o 1–12 se in modalità AM/PM).
  `hh` | L'ora con zero iniziali (00–23 o 01–12 se in modalità AM/PM).
  `m` | I minuti senza zero iniziali (0–59).
  `mm` | I minuti con zero iniziali (00–59).
  `s` | I secondi senza zero iniziali (0–59).
  `ss` | I secondi con zero iniziali (00–59).
  `z` | I millisecondi senza zeri iniziali (0–999).
  `zzz` | I millisecondi con zeri iniziali (000–999).
  `AP` | Usa modalità AM/PM. AP sarà sostituito da "AM" per le ore antimeridiane o "PM" per quelle pomeridiane.
  `ap` | Usa modalità am/pm. ap sarà sostituito da "am" per le ore antimeridiane o "pm" per quelle pomeridiane.

    charidentificatore

- 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 `char: [numero]` nel campo di inserimento, quindi fai clic su OK.

  ##### Esempi con il comando `char`

  Inserisci: `char:234`

  Ottieni: `ê`

  Inserisci: `char:0x1234`

  Ottieni: `ሴ`

`s///[ig]` `%s///[ig]`

- Questo comando fa una ricerca/sostituzione nella riga di testo corrente o in tutto il file (`%s///`) in maniera del tutto simile a sed.

  In breve, la ricerca viene effettuata in base a un modello di ricerca, 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 riferimenti all'indietro, 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 `\1` per il primo gruppo di parentesi, `\2` per il secondo e così via.

  Per cercare precisamente il simbolo di parentesi `(` o `)`, devi evitare il problema usando la barra rovescia in questo modo: `\(\)`

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

  ##### Sostituire del testo nella riga corrente

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

  "Naturale!" pensi, sai benissimo che si scrive `MyClass`. Vai alla riga 3902 e, invece di provare a cercare la parola nel testo, apri la finestra di dialogo Comando di modifica, inserisci `s/myclass/MyClass/i`, premi OK, salvi il file e lo compili – con successo senza errori.

  ##### Sostituire del testo nell'intero file

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

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

  ##### Un esempio più avanzato

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

  Immagina di avere la seguente riga:

      void MyClass::DoStringOps( String      &foo, String &bar String *p, int  &a, int &b )

  Ora ti rendi conto che il codice non va bene e decidi di usare la parola chiave `const` per tutti gli argomenti reference, 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.

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

  Ottieni: `void MyClass::DoStringOps( const String &foo, const String &bar String *p, const int &a, const int &b )`

  Missione compiuta! Ora cos'è successo? Abbiamo cercato alcuni spazi vuoti (`\s+`) seguiti da alcuni caratteri alfabetici (`\w+`), seguiti da altri spazi vuoti (`\s+`), 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 const, seguito da un altro spazio vuoto, seguito dalla porzione alfabetica (`\1`), seguito da uno spazio vuoto e infine seguito dalla e commerciale salvata (`\2`)

  Ora, in alcuni casi la porzione alfabetica era una String. in altri int, quindi se usi `\w` e il quantificatore `+` sarà meglio.

#### Comandi per gli spostamenti

    gotoINT riga

- Questo comando sposta il cursore alla riga indicata.

    findmodello

- Questo comando si sposta alla prima corrispondenza del `modello` secondo la configurazione. Le corrispondenze successive possono essere trovate usando Modifica Trova successivo (la scorciatoia predefinita è F3).

  Il comando find può essere configurato aggiungendo in fondo un due punti seguito da una o più opzioni, nella forma `find:opzioni modello`. Le seguenti opzioni sono disponibili:

  `b`

- Cerca all'indietro.

`c`

- Cerca dalla posizione del cursore.

`e`

- Cerca solo all'interno della selezione.

`r`

- Esegue la ricerca con un'espressione regolare. Se è impostata, puoi usare `\N`, dove N è un numero che rappresenta le catture nella stringa di sostituzione.

`s`

- Esegue la ricerca facendo distinzione fra maiuscole e minuscole.

`w`

- Fa in modo che la ricerca consideri solo parole intere.

    ifindmodello

- Questo comando fornisce la ricerca mentre scrivi. Puoi configurarne il comportamento aggiungendo in fondo un due punti seguito da una o più opzioni, nella forma `ifind:opzioni modello`. Le seguenti opzioni sono disponibili:

  `b`

- Cerca all'indietro.

`r`

- Esegue la ricerca di un'espressione regolare.

`s`

- Esegue la ricerca facendo distinzione fra maiuscole e minuscole.

`c`

- Cerca dalla posizione del cursore.

## Uso del raggruppamento del codice

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 `BEGIN` ed `END`.

Per usare la funzione di raggruppamento del codice, attiva gli indicatori di raggruppamento usando la voce Visualizza Mostra segni di raggruppamento 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 segni +/- indicanti l'operazione possibile su una data regione: Un - indica che la regione è espansa, facendo clic sul - ridurrà la regione ad una sola riga, mentre un + la mostrerà completamente.

Sono forniti quattro comandi per manipolare lo stato delle regioni di raggruppamento del codice, vedi la documentazione del menu.

Se non vuoi usare la funzione di raggruppamento del codice, puoi disabilitare l'opzione Mostra segni di raggruppamento (se disponibile) dalla pagina Aspetto delle configurazioni dell'editor.

## Scripting del componente dell editor con JavaScript

### Introduzione

Dalla versione 2.5, il componente dell'editor di &kate; gestisce gli script con ECMAScript, noto anche come JavaScript.

Gli script possono essere usati con la sola riga di comando integrata. I requisiti sono che lo script sia messo in una cartella dove &kate; possa trovarlo, assieme al file .desktop opzionale che ne definisce le proprietà associate. Le cartelle valide sono chiamate `katepart/scripts` nelle cartelle dei dati di &kde;. Puoi trovare le cartelle dei dati scrivendo `kde-config `--path` `data`` Normalmente c'è almeno una cartella dei dati di sistema ed una personale. Naturalmente gli script nella cartella dei dati di sistema sono utilizzabili da tutti gli utenti, mentre quelli nella cartella personale lo possono essere usati solo da te.

Questa funzione è sperimentale e probabilmente cambierà durante gli sviluppi futuri.

Sappiamo che molti di voi saranno delusi perché non è possibile aggiungere script al menu o assegnarvi scorciatoie da tastiera. Molto probabilmente sarà possibile in futuro.

Inoltre non è ancora possibile passare degli argomenti agli script. Sii paziente, e anche questo potrebbe essere aggiunto in futuro!

### L'API JavaScript di Kate

Ecco elencata la raccolta completa di funzioni e proprietà disponibili per gli oggetti `document` e `view`. Inoltre sono disponibili naturalmente gli oggetti standard, come `Math`, `String`, `Regexp` e così via.

Quando viene eseguito uno script, l'oggetto `document` è il documento attuale, e l'oggetto `view` è la vista corrente.

I tipi degli argomenti ovviamente non sono usati da JavaScript, al momento. Servono solo ad indicare qhe tipo di valori le funzioni si aspettino.

### Funzioni globali

`debug( ``stringa``) [funzione]`

- ### parametri

  - `stringa` il messaggio da stampare

  Stampa la stringa su STDERR usando la funzione `kdDebug()`. Un'area di output dedicata è usata per l'output, che sarà preceduto da `Kate (KJS Scripts):`.

### L'API di `document`

`document.attribute( ``riga`` , ``colonna`` ); [funzione]`

- ### Parametri

  - `uint riga` La riga della posizione per cui trovare l'attributo.

  - `uint colonna` La colonna della posizione per cui trovare l'attributo.

  Restituisce l'ID numerico dell'attributo per la posizione del documento 0`riga`, `colonna`]. L'attributo rappresenta l'aspetto o lo stile del testo, ed è anche usato per calcolare l'evidenziazione della sintassi per una parte specifica del testo in formati misti come l'HTML e il PHP.

`document.canBreakAt( `Char c`, `uint attributo` ); [funzione]`

- ### Parametri

  - `c` Il carattere da verificare

  - `attributo` L'attributo alla posizione di `c`.

  Restituisce true se è permesso interrompere la riga al carattere c con l'attributo dato. Il risultato è determinato dall'interrogazione dell'evidenziazione che possiede l'attributo per sapere quali caratteri permettono l'interruzione della riga.

`document.canComment( `uint attributo_inizio`, `uint attributo_fine` ); [funzione]`

- ### Parametri

  - `attributo_inizio` L'attributo dell'inizio dell'intervallo da tramutare in commento.

  - `attributo_fine` L'attributo della fine dell'intervallo da tramutare in commento.

  Controlla se attributo_inizio e attributo_fine appartengono allo stesso sistema di evidenziazione della sintassi. Se è così, va tutto bene.

  #### Uso di canComment

      if ( document.canComment( document.attribute(1,0), document.attribute(5,0) ) ) {
          // 1,0 e 5,0 appartengono allo stesso sistema di evidenziazione di sintassi
      }

`document.clear(); [funzione]`

- Svuota il documento.

`document.commentStart( `uint attributo` ); [funzione]`

- ### Parametri

  - `attributo` L'attributo del testo di cui ottenere la stringa di indicazione di inizio commento (commentStart).

  Restituisce la stringa richiesta per avviare un commento su più righe per il testo con l'attributo dato, o una stringa vuota se i commenti su più righe non sono disponibili per quel tipo di testo.

`document.commentMarker( `uint attributo` ); [funzione]`

- ### Parametri

  - `attributo` L'attributo del testo di cui ottenere la stringa di indicazione commento (commentMarker).

  Restituisce la stringa usata per indicare che il resto della riga è un commento per un testo con l'attributo dato o una stringa vuota se i commenti su riga singola non sono disponibili per il testo dato.

`document.commentEnd( `uint attributo` ); [funzione]`

- ### Parametri

  - `attributo` L'attributo del testo di cui ottenere la stringa di indicazione di fine commento (commentEnd).

  Restituisce la stringa richiesta per terminare un commento su più righe per il testo con l'attributo dato, o una stringa vuota se i commenti su più righe non sono disponibili per quel tipo di testo.

`document.editBegin(); [funzione]`

- Inizia un gruppo di modifiche. Tutte le azioni eseguite fino alla chiamata di editEnd() saranno raggruppate in una sola azione di annullamento.

`document.editEnd(); [funzione]`

- Termina un gruppo di modifiche.

`document.highlightMode; [proprietà:sola lettura]`

- IL nome dellla modalità di evidenziazione del documento, come JavaScript o C++. Se non è impostata nessuna modalità di evidenziazione per il documento, il valore è None. Nota che è necessario usare il nome inglese nei casi in cui sia diverso da quello tradotto.

`document.indentMode; [proprietà:sola lettura]`

- Il nome della modalità di indentazione del documento, come `normal` o `cstyle`. Ricorda che se non è impostata una modalità di indentazione, il valore è `none`.

`document.indentWidth; [proprietà:sola lettura]`

- L'ampiezza del rientro impostata per il dcumento. È usata se è attiva l'indentazione con gli spazi.

`document.insertLine( `uint riga`, `string testo` ); [funzione]`

- ### Parametri

  - `riga` numero della riga del documento

  - `testo` testo da inserire

  Inserisce una nuova riga di testo `testo` alla riga `riga`.

`document.insertText( `uint riga`, `uint colonna`, `string testo` ); [funzione]`

- ### Parametri

  - `riga` numero della riga

  - `colonna` il numero della colonna

  - `testo` il testo da inserire

  Inserisce il testo `testo` alla riga `riga` e alla colonna `colonna`.

document.length(); [funzione]

- Restituisce la dimensione del documento in byte.

`document.lines(); [funzione]`

- Restituisce il numero di righe del documento.

document.mixedIndent; [proprietà:sola lettura]

- Un valore booleano che indica se la modalità mixed-indent è abilitata per il documento. Se è così, l'indentazione è ottimizzata per contenere una miscela di caratteri di tabulazione e spazi come fa l'editor Emacs.

document.removeLine( `uint numeroriga` ); [funzione]

- ### Parametri

  - `riga` numero di riga

  Rimuove la riga numeroriga dal documento.

`document.removeText( `uint rigaIniziale`, `uint colonnaIniziale`, `uint rigaFinale`, `uint colonnaFinale` ); [funzione]`

- ### Parametri

  - `rigaIniziale` indica la riga d'inizio

  - `colonnaIniziale` indica la colonna d'inizio

  - `rigaFinale` indica la riga di fine

  - `colonnaFinale` indica la colonna di fine

  Rimuove la sezione di testo che inizia da riga `rigaIniziale` e colonna `colonnaIniziale` fino a `rigaFinale` e colonna `colonnaFinale`.

`document.setText( `string testo` ); [funzione]`

- ### Parametri

  - `testo` testo del documento

  Sostituisce il testo dell'intero documento con `testo`.

`document.spaceIndent; [proprietà:sola lettura]`

- Un valore booleano che indica se è abilitata l'indentazione con gli spazi per il documento. Se è così, il documento è indentato con indentWidth spazi per livello, altrimenti è di una tabulazione per livello.

`document.textFull(); [funzione]`

- Restituisce il testo completo del documento. Se il testo continua su più righe il carattere di separazione delle righe è `\n`.

`document.textLine( uint numeroRiga ); [funzione]`

- ### Parametri

  - `numeroRiga` il numero della riga

  Restituisce il testo della riga `numeroRiga`.

`document.textRange( `uint rigaIniziale`, `uint colonnaIniziale`, `uint rigaFinale`, `uint colonnaFinale` ); [funzione]`

- ### Parametri

  - `rigaIniziale` indica la riga d'inizio

  - `colonnaIniziale` indica la colonna d'inizio

  - `rigaFinale` indica la riga di fine

  - `colonnaFinale` indica la colonna di fine

  Restituisce il testo dell'intervallo selezionato. Se il testo continua su più righe il carattere di separazione delle righe è `\n`.

### L'API di `view`

`view.clearSelection(); [funzione]`

- Deseleziona tutto il testo.

`view.cursorColumn(); [funzione]`

- Restituisce la colonna su cui si trova il cursore (i caratteri di tabulazione sono espansi).

`view.cursorColumnReal(); [funzione]`

- Restituisce la colonna su cui si trova il cursore (i caratteri di tabulazione contano come uno).

`view.cursorLine(); [funzione]`

- Restituisce il numero di riga attuale del cursore.

`view.hasSelection(); [funzione]`

- Restituisce `true` se la vista contiene del testo selezionato, altrimenti `false`.

`view.removeSelectedText(); [funzione]`

- Elimina il testo selezionato, se c'è una selezione nella vista.

`view.selectAll(); [funzione]`

- Seleziona tutto il testo.

`view.selection(); [funzione]`

- Restituisce il testo selezionato. Se la selezione è composta da più righe, il carattere di separazione delle righe è `\n`.

`view.selectionEndColumn; [proprietà:sola lettura]`

- Restituisce il numero di colonna della fine della selezione.

`view.selectionEndLine; [proprietà:sola lettura]`

- Restituisce il numero di riga della fine della selezione.

`view.selectionStartColumn; [proprietà:sola lettura]`

- Restituisce la colonna iniziale della selezione.

`view.selectionStartLine; [proprietà:sola lettura]`

- Restituisce la riga iniziale della selezione.

`view.setCursorPosition( `uint riga`, `uint colonna` ); [funzione]`

- ### Parametri

  - `riga` Specifica la riga del cursore.

  - `colonna` Specifica la colonna del cursore.

  Sposta la posizione del cursore nella vista a [`riga`, `colonna`]. La posizione del cursore è calcolata in modo visuale, cioè i caratteri di tabulazione contano per `tabwidth` spazi, a seconda della posizione all'interno della riga. La posizione del cursore è resa visibile. Sia la riga che la colonna sono contate partendo da zero.

`view.setCursorPositionReal( `uint riga`, `uint colonna` ); [funzione]`

- ### Parametri

  - `riga` Specifica la riga del cursore.

  - `colonna` Specifica la colonna del cursore.

  Sposta la posizione del cursore nella vista a [`riga`, `colonna`]. Questa funzione imposta la posizione nella stringa di caratterim cioè un carattere di tabulazione conta per uno. Sia la riga che la colonna sono contate partendo da zero.

`view.setSelection( `uint rigaIniziale`, `uint colonnaIniziale`, `uint rigaFinale`, `uint colonnaFinale` ); [funzione]`

- ### Parametri

  - `rigaIniziale` indica la riga d'inizio

  - `colonnaIniziale` indica la colonna d'inizio

  - `rigaFinale` indica la riga di fine

  - `colonnaFinale` indica la colonna di fine

  Seleziona il testo da riga `rigaIniziale` e colonna `colonnaIniziale` fino a riga `rigaFinale` e colonna `colonnaFinale`.

#### Uno script di esempio

Come esempio, prepareremo un breve script che rende maiuscole tutte le lettere della selezione. È ovvio che dovremo prima controllare se esiste una selezione, quindi ottenere il testo, rendere ogni lettera maiuscola ed infine sostituire il vecchio testo col nuovo. Un'implementazione potrebbe essere questa:

    if ( view.hasSelection() )
    {
      // uppercase selection
      column = view.selectionStartColumn;
      line = view.selectionStartLine;

      selection = view.selection().toUpperCase();

      document.editBegin();
      view.removeSelectedText();
      document.insertText( line, column, selection );
      document.editEnd();
    }

Per raggruppare queste azioni assieme i modo che siano annullate con una singola attivazione di Annulla, incapsuliamo le righe

    view.removeSelectedText()

e

    document.insertText()

con un

    document.editBegin()

ed un

    document.editEnd()

.

#### Un esempio di file `.desktop`

Ecco un esempio di file .desktop da associare allo script summenzionato.

    # Example of a .desktop file
    [Desktop Entry]
    Encoding=UTF-8
    Name=Kate Part JavaScript Uppercase
    Comment=Script to uppercase the selection
    X-Kate-Command=uppercase-selection
    X-Kate-Help=<p>Usage: <code>uppercase-selection</code></p>

Come puoi vedere è possibile definire la codifica, il nome, un commento, un testo di aiuto usando X-Kate-Help ed il nome per la riga di comando usando X-Kate-Command. Le voci Name, Comment e X-Kate-Help sono tradotte automaticamente in altre lingue dalle squadre di traduzione di KDE, se i file risiedono nel deposito SVN di KDE.

#### Mettere tutto assieme

&kate; cercherà i file `*.js` nelle cartelle degli script (vedi sopra). Per ciascun file controlla se è presente un file `.desktop`; ad esempio, per `uppercase.js` cercherebbe un file `uppercase.desktop`.

Se un file `.desktop` non è presente, lo script sarà registrato nella riga di comando di KatePart con il nome del file senza l'estensione .js, quindi nell'esempio, questo vuol dire `uppercase`. Se il nome del comando va bene e non ti servono le altre caratteristiche fornite dai file `.desktop`, non è affatto necessario creare il file.

Se esiste un file `.desktop`, KatePart leggerà il nome sotto cui lo script sarà registrato dalla voce X-Kate-Command del file .desktop, ad esempio X-Kate-Command=uppercase-selection.