# Script

## Script con &kile;

La funzionalità per gli script di &kile; permette l'esecuzione di codice ECMAScript, meglio noto come &javascript;. Troverai molte esercitazioni con informazioni su oggetti (variabili), funzioni e proprietà supportate da &javascript;.

Il supporto per gli script può essere abilitato nella finestra di configurazione di &kile;: Impostazioni Configura Kile...Kile Script. Abilitare o disabilitare il supporto per gli script Abilitare o disabilitare il supporto per gli script

Se gli script sono abilitati, è visibile un pannello aggiuntivo apposito nella barra laterale, dove si possono gestire gli script: Pannello degli script nella barra laterale Pannello degli script nella barra laterale

Questo oggetto contiene sei icone, che offrono diverse possibilità:

- Eseguire lo script selezionato.

- Creare un nuovo script.

- Aprire lo script selezionato nell'editor.

- Configurare una sequenza di tasti per lo script selezionato.

- Rimuovere una sequenza di tasti assegnata.

- Aggiornare l'elenco di script disponibili, che sono memorizzati in `$`KDEDIR`/share/apps/kile/scripts/`.

## Eseguire uno script

Puoi eseguire uno script in tre modi diversi:

1. Seleziona lo script desiderato e fai clic sul pulsante Esegui sul lato sinistro dell'oggetto di gestione degli script.

   Script: pulsante di esecuzione
   Script: pulsante di esecuzione

2. Usa una scorciatoia da tastiera.

   Script: scorciatoia da tastiera
   Script: scorciatoia da tastiera

   Puoi assegnare una scorciatoia da tastiera a uno script con il pulsante Configura nell'oggetto di gestione degli script.

   Script: finestra di configurazione delle sequenze
   Script: finestra di configurazione delle sequenze

3. Usa un editor di sequenze di tasti. Lo script verrà eseguito se batti la sequenza di tasti assegnata nell'editor.

   Script: editor delle sequenze di tasti
   Script: editor delle sequenze di tasti

   Questo metodo può essere esteso in un completamento del testo piuttosto sofisticato. Poniamo che hai scritto uno script che semplicemente inserisce il comando &latex; `\textbf{}` nel documento attuale.

       document.insertText("\\textbf{%C}");

   Se ora batti la sequenza di tasti assegnata `bfx` nel documento, questa sequenza verrà rimossa e lo script eseguito. Inserirà `\textbf{}` e il cursore verrà posizionato tra le graffe.

   Script: battere una sequenza di tasti
   Script: battere una sequenza di tasti

   Che modo comodo e flessibile di completare il codice!

## Riferimento API

L'API qui presentata è disponibile in tutti gli script. Prima del caricamento dei contenuti di uno script, &kile; aggiunge diversi prototipi e funzioni al contesto dello script. Questa API di supporto contiene prototipi come cursori e intervalli di testo, ed è localizzata nella cartella ``KILE_APP_DIR`/script-plugins/`.

Gli script di &kile; differiscono leggermente da quelli di &kate;, che usano un altro metodo visto che possono essere avviati anche dalla riga di comando. Però, tutte le funzioni dell'API di &kate; sono disponibili anche nell'API di &kile;, quindi trasferire codice &javascript; da &kate; a &kile; dovrebbe essere molto facile. Essendo però &kile; un editor &latex; con molte funzionalità, la sua API per gli script offre molte più possibilità rispetto a quella di &kate;.

Osservazione: le descrizioni delle chiamate API disponibili anche dagli script di &kate; sono state prese dalla documentazione di &kate;.

### Funzioni globali

Questa sezione elenca le funzioni globali.

    void debug(String testo);

  Stampa il `testo` su `stdout` nella console. Il testo stampato è colorato per differenziarlo dal restante output di debug.

### Il prototipo Cursor

Essendo &kile; un editor di testo, tutta l'API degli script si basa su cursori e intervalli ovunque possibile. Un Cursor è una semplice tupla `(riga, colonna)` che rappresenta una posizione nel testo del documento.

    Cursor();

  Costruttore: restituisce un Cursor alla posizione `(0,0)`.

  Esempio: `var cursore = new Cursor();`

    Cursor(int riga, int colonna);

  Costruttore: restituisce un cursore alla posizione (riga, colonna).

  Esempio: `var cursore = new Cursor(3,42);`

    Cursor(Cursor altro);

  Costruttore di copia. Restituisce una copia dell'`altro` cursore.

  Esempio: `var copia = new Cursor(altro);`

    Cursor Cursor.clone();

  Restituisce un clone del cursore.

  Esempio: `var clone = cursor.clone();`

    bool Cursor.isValid();

  Controlla se il cursore è valido. Non lo è se la riga o la colonna sono impostate a `-1`.

  Esempio: `var valido = cursor.isValid();`

    Cursor Cursor.invalid();

  Restituisce un nuovo cursore non valido posizionato a `(-1,-1)`.

  Esempio: `var cursoreNonValido = cursor.invalid();`

    int Cursor.compareTo(Cursor altro);

  Confronta un cursore con un `altro`. Restituisce:

  - `-1`, se il cursore è posizionato prima dell'`altro`,

  - `0`, se sono uguali, e

  - `+1`, se il cursore è posizionato dopo l'`altro`.

    bool Cursor.equals(Cursor altro);

  Restituisce `true` se il cursore e l'`altro` sono uguali, altrimenti `false`.

    String Cursor.toString();

  Restituisce un cursore sotto forma di stringa nella forma `Cursor(riga, colonna)`.

### Il prototipo Range

Essendo &kile; un editor di testo, tutta l'API per gli script si basa su cursori e intervalli ovunque possibile. Come Cursor è una semplice tupla del tipo `(riga, colonna)` che rappresenta una posizione nel testo del documento, Range si estende sul testo a partire da una posizione del cursore iniziale a una finale.

    Range();

  Costruttore: chiamare `new Range()` restituisce un intervallo `(0, 0) - (0, 0)`.

    Range(Cursor inizio, Cursor fine);

  Costruttore: chiamare `new Range(inizio, fine)` restituisce l'intervallo dal cursore `inizio` al cursore `fine`.

    Range(int riga_inizio, int colonna_inizio, int riga_fine, int colonna_fine);

  Costruttore. Chiamare `new Range(riga_inizio, colonna_inizio, riga_fine, colonna_fine)` restituisce l'intervallo da (`riga_inizio`, `colonna_inizio`) a (`riga_fine`, `colonna_fine`).

    Range(Range altro);

  Costruttore di copia: restituisce una copia dell'`altro` intervallo.

    Range Range.clone();

  Restituisce un clone dell'intervallo.

  Esempio: `var clone = range.clone();`

    bool Range.isValid();

  Restituisce `true` se entrambi i cursori iniziale e finale sono validi, altrimenti `false`.

  Esempio: `var valido = range.isValid();`

    bool Range.invalid();

  Restituisce l'intervallo da `(-1,-1)` a `(-1,-1)`.

    bool Range.contains(Cursor cursore);

  Restituisce `true` se l'intervallo contiene la posizione del cursore, altrimenti `false`.

    bool Range.contains(Range altro);

  Restituisce `true` se l'intervallo contiene l'`altro`, altrimenti `false`.

    bool Range.containsColumn(int colonna);

  Restituisce `true` se la `colonna` è nell'intervallo semiaperto `[inizio.colonna, fine.colonna]`, altrimenti `false`.

    bool Range.containsLine(int riga);

  Restituisce `true` se la `riga` è nell'intervallo semiaperto `[inizio.riga, fine.riga]`, altrimenti `false`.

    bool Range.overlaps(Range altro);

  Restituisce `true` se l'intervallo e l'`altro` hanno una regione in comune, altrimenti `false`.

    bool Range.overlapsLine(int riga);

  Restituisce `true` se la `riga` è nell'intervallo `[inizio.riga, fine.riga]`, altrimenti `false`.

    bool Range.overlapsColumn(int colonna);

  Restituisce `true` se la `colonna` è nell'intervallo `[inizio.colonna, fine.colonna]`, altrimenti `false`.

    bool Range.equals(Range altro);

  Restituisce `true` se l'intervallo e l'`altro` sono uguali, altrimenti `false`.

    String Range.toString();

  Restituisce un intervallo sotto forma di stringa nella forma `Range(Cursor(riga, colonna) - Cursor(riga, colonna))`.

### L'API delle viste

Ogni volta che viene eseguito uno script, è presente un oggetto (variabile) globale `view`, che rappresenta l'attuale vista attiva dell'editor. Tutte le funzioni di `view` lavorano con le posizioni del cursore o col testo selezionato. Segue un elenco di tutte le funzioni di `view` disponibili.

    void view.backspace();

  Effettua programmaticamente l'equivalente della pressione del tasto backspace.

    Cursor view.cursorPosition();

  Restituisce la posizione attuale del cursore nella vista.

    void view.setCursorPosition(int riga, int colonna);
    void view.setCursorPosition(Cursor cursore);

  Imposta la posizione attuale del cursore a `riga`, `colonna` o al `cursore` dato.

    void view.cursorLeft();

  Sposta il cursore di una posizione indietro nel testo.

    void view.cursorRight();

  Sposta il cursore di una posizione avanti nel testo.

    void view.cursorUp();

  Sposta il cursore di una riga in su nel documento.

    void view.cursorDown();

  Sposta il cursore di una riga in giù nel documento.

    int view.cursorLine();

  Restituisce la riga sulla quale si trova il cursore.

    int view.cursorColumn();

  Restituisce la colonna sulla quale si trova il cursore.

    void view.setCursorLine(int riga);

  Imposta la riga del cursore alla `riga` data.

    void view.setCursorColumn(int colonna);

  Imposta la colonna del cursore alla `colonna` data.

    Cursor view.virtualCursorPosition();

  Ottieni l'attuale posizione virtuale del cursore. Virtuale vuol dire che il carattere di tabulazione conta più caratteri, come configurato dall'utente (per esempio, una tabulazione può essere otto spazi). La posizione virtuale del cursore dà accesso ai valori visibili dall'utente della posizione attuale del cursore.

    bool view.hasSelection();

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

    String view.selectedText();

  Restituisce il testo selezionato. Se non c'è del testo selezionato, la stringa restituita è vuota.

    Range view.selectionRange();

  Restituisce l'intervallo di testo selezionato. L'intervallo di testo non è valido se non c'è testo selezionato.

    void view.setSelection(Range intervallo);

  Imposta il testo selezionato all'`intervallo` dato.

    void view.selectAll();

  Seleziona tutto il testo del documento.

    void view.clearSelection();

  Pulisce la selezione di testo senza rimuoverlo.

    void view.removeSelectedText();

  Rimuovi il testo selezionato. Se la vista non ne ha, non fa nulla.

    void view.selectLine();

  Seleziona il testo della riga attuale.

    void view.selectLine(int riga);

  Seleziona il testo della `riga` data.

    void view.selectLines(int da, int a);

  Seleziona tutto il testo della riga `da` alla riga `a`.

    void view.selectWord();

  Seleziona la parola attuale. Se non ce n'è una alla posizione attuale del cursore, non fa nulla.

    void view.selectLatexCommand();

  Seleziona il comando &latex; attuale. Se non ce n'è uno alla posizione attuale del cursore, non fa nulla.

    void view.selectEnvironment(bool dentro = false);

  Seleziona tutto il testo dell'ambiente &latex; attuale. Se `dentro` è `false`, sarà selezionato il testo dell'ambiente incluse le etichette &latex; circostanti `\begin{...}...\end{...}`, altrimenti le etichette non saranno incluse. Se non viene dato un valore per il parametro, `dentro` è impostato a `false`.

    void view.selectTexgroup(bool dentro = true);

  Seleziona il testo del gruppo &latex; attuale. Se `dentro` è `true`, sarà selezionato solo il gruppo &tex; senza le graffe circostanti. Se non viene dato un valore per il parametro, `dentro` è impostato a `true`.

    void view.selectMathgroup();

  Seleziona il testo del gruppo matematico attuale.

    void view.selectParagraph(bool bool righeIntere = true);

  Seleziona il testo di tutto il paragrafo &latex; attuale. Se o`righeIntere` è `true`, la prima e l'ultima riga del paragrafo saranno incluse per intero nella selezione (incluso il carattere di fine riga); altrimenti, la selezione conterrà solo caratteri non di spaziatura.

### L'API dei documenti

Ogni volta che uno script viene eseguito è presente un oggetto (variabile) globale, `document`, che rappresenta il documento attualmente attivo. Segue un elenco di tutte le funzioni di `document` disponibili.

    void document.insertText(String testo);

  Inserisce il `testo` alla posizione attuale del cursore.

    void document.insertText(int riga, int colonna, String testo);
    void document.insertText(Cursor cursore, String testo);

  Inserisce il `testo` alla posizione data del cursore.

    bool document.removeText(int daRiga, int daColonna, int aRiga, int aColonna);
    bool document.removeText(Cursor da, Cursor a);
    bool document.removeText(Range intervallo);

  Rimuove il testo nell'intervallo dato. Restituisce `true` se funziona, o `false` se il documento è in modalità di sola lettura.

    bool document.replaceText(Range intervallo, String testo);

  Sostituisce il testo dell'`intervallo` dato con il testo specificato.

    int document.lines();

  Restituisce il numero di righe nel documento.

    int document.length();

  Restituisce il numero di caratteri nel documento.

    Range document.documentRange();

  Restituisce un intervallo contenente tutto il documento.

    Cursor document.documentEnd();

  Restituisce la posizione del cursore alla fine del documento.

    String document.text();

  Restituisce tutto il contenuto del documento in una sola stringa di testo. I ritorni a capo sono indicati con il carattere `\n`.

    String document.text(int daRiga, int daColonna, int aRiga, int aColonna);
    String document.text(Cursor da, Cursor a);
    String document.text(Range intervallo);

  Restituisce il testo nell'intervallo dato. Si raccomanda di usare le versioni con cursori o intervalli per migliorare la leggibilità del codice.

    bool document.setText(String testo);

  Imposta tutto il testo del documento.

    bool document.clear();

  Rimuove tutto il testo del documento.

    String document.line();

  Restituisce la riga di testo attuale come stringa.

    String document.line(int riga);

  Restituisce la riga di testo richiesta come stringa. La stringa è vuota se la riga richiesta è oltre i limiti.

    int document.lineLength();

  Restituisce la lunghezza della riga attuale.

    int document.lineLength(int riga);

  Restituisce la lunghezza della riga.

    bool document.insertLine(String text);

  Inserisce del `testo` nella riga attuale. Restituisce `true` se funziona, o `false` se il documento è in modalità di sola lettura o la riga non è nell'intervallo del documento.

    bool document.insertLine(int riga, String testo);

  Inserisce il `testo` nella `riga` data. Restituisce `true` se funziona, o `false` se il documento è in modalità di sola lettura o la riga non è nell'intervallo del documento.

    bool document.removeLine();

  Rimuove la riga di testo attuale. Restituisce `true` se funziona, o `false` se il documento è in modalità di sola lettura.

    bool document.removeLine(int riga);

  Rimuove la `riga` di testo data. Restituisce `true` se funziona, o `false` se il documento è in modalità di sola lettura o la riga non è nell'intervallo del documento.

    bool document.replaceLine(String testo);

  Sostituisce il testo della riga attuale con il testo specificato.

    bool document.replaceLine(int riga, String testo);

  Sostituisce il testo della `riga` data con il testo specificato.

    bool document.truncateLine();

  Tronca la riga attuale alla `colonna` data o al `cursore` dato. Restituisce `true` se funziona, o `false` se la riga non fa parte dell'intervallo del documento.

    bool document.truncate(int riga, int colonna);
    bool document.truncate(Cursor cursore);

  Tronca la `riga` alla `colonna` data o al `cursore` dato. Restituisce `true` se funziona, o `false` se la riga non fa parte dell'intervallo del documento.

    String document.word();

  Restituisce la parola alla posizione attuale del cursore. Se a questa posizione non si trova nessuna parola, la stringa restituita è vuota.

    String document.wordAt(int riga, int colonna);
    String document.wordAt(Cursor cursore);

  Restituisce la parola alla posizione data del `cursore`. Se a questa posizione non si trova nessuna parola, la stringa restituita è vuota.

    Range document.wordRange();

  Restituisce l'intervallo della parola alla posizione attuale del cursore. Se non si trova una parola, viene restituito `Range.invalid()`, che può essere controllato con `Range.isValid()`.

    String document.latexCommand();

  Restituisce il comando &latex; alla posizione attuale del cursore. Se a questa posizione non si trova nessun comando, la stringa restituita è vuota.

    String document.latexCommandAt(int riga, int colonna);
    String document.latexCommandAt(Cursor cursore);

  Restituisce il comando &latex; alla posizione data del `cursore`. Se a questa posizione non si trova nessun comando, la stringa restituita è vuota.

    Range document.latexCommandRange();

  Restituisce l'intervallo del comando &latex; alla posizione data del `cursore`. Se non si trova una parola, viene restituito `Range.invalid()`, che può essere controllato con `Range.isValid()`.

    String document.charAt(int riga, int colonna);
    String document.charAt(Cursor cursore);

  Restituisce il carattere alla posizione del cursore data.

    String document.firstChar(int riga);

  Restituisce il primo carattere nella `riga` data che non sia uno spazio. Il primo carattere è alla colonna 0. Se la riga è vuota o contiene solo spazi, la stringa restituita è vuota.

    String document.lastChar(int riga);

  Restituisce l'ultimo carattere nella `riga` data che non sia uno spazio. Se la riga è vuota o contiene solo spazi, la stringa restituita è vuota.

    bool document.isSpace(int riga, int colonna);
    bool document.isSpace(Cursor cursore);

  Restituisce `true` se il carattere alla posizione del `cursore` data è uno spazio, altrimenti `false`.

    void document.insertBullet();

  Inserisce un punto di &kile;. Ricorda che puoi facilmente passare al punto successivo o precedente. Inoltre, questo evidenzierà questo punto in modo da eliminarlo automaticamente all'inserimento della prima lettera.

    void document.nextBullet();

  Passa al punto successivo, se ce n'è uno.

    void document.previousBullet();

  Passa al punto precedente, se ce n'è uno.

    bool document.hasEnvironment();

  Restituisce `true` se c'è un ambiente &latex; circostante, altrimenti `false`.

    String document.environment(bool dentro = false);

  Restituisce tutto il testo dell'ambiente &latex; circostante. Se `dentro` è `false`, le etichette &latex; `\begin{...}...\end{...}` saranno restituite assieme al testo dell'ambiente, altrimenti verrà restituito solo il testo. Se non viene dato un valore per il parametro, `dentro` verrà considerato `false`. Se non viene rilevato un ambiente, verrà restituita una stringa vuota.

    Range document.environmentRange(bool dentro = false);

  Restituisce l'intervallo dell'ambiente &latex; circostante. Se `dentro` è `false`, sarà restituito l'intervallo incluse le etichette &latex; `\begin{...}...\end{...}`, altrimenti queste verranno escluse. Se non viene dato un valore per il parametro, `dentro` verrà considerato `false`. Se non viene rilevato un ambiente, verrà restituito `Range.invalid()`, che può essere controllato con `Range.isValid()`.

    String document.environmentName();

  Restituisce il nome dell'ambiente &latex; circostante, o una stringa vuota.

    void document.removeEnvironment(bool dentro = false);

  Rimuove il testo dell'ambiente &latex; circostante. Se `dentro` è `false`, sarà rimosso il testo dell'ambiente incluse le etichette &latex; circostanti `\begin{...}...\end{...}`, altrimenti le etichette non saranno rimosse. Se non viene dato un valore per il parametro, `dentro` è impostato a `false`.

    void document.closeEnvironment();

  Inserisci un'etichetta di chiusura di un ambiente, se alla posizione attuale del cursore viene rilevato un ambiente &latex; aperto.

    void document.closeAllEnvironments();

  Inserisci delle etichette di chiusura per tutti gli ambienti &latex; aperti rilevati alla posizione attuale del cursore.

    bool document.hasTexgroup();

  Restituisce `true` se c'è un gruppo &latex; circostante alla posizione attuale del cursore, altrimenti `false`.

    String document.texgroup(bool dentro = true);

  Restituisce il testo del gruppo &latex; circostante. Se `dentro` è `false`, le graffe di questo gruppo &latex; `{...}` saranno restituite assieme al testo, altrimenti verranno escluse. Se non viene dato un valore per il parametro, `dentro` verrà considerato `false`. Se non viene rilevato un gruppo &latex; circostante alla posizione attuale del cursore, verrà restituita una stringa vuota.

    Range document.texgroupRange(bool dentro = true);

  Restituisce l'intervallo del gruppo &latex; circostante Se `dentro` è `false`, sarà restituito l'intervallo incluse le graffe `{...}`, altrimenti queste verranno escluse. Se non viene dato un valore per il parametro, `dentro` verrà considerato `false`. Se non viene rilevato un gruppo, verrà restituito `Range.invalid()`, che può essere controllato con `Range.isValid()`.

    void document.removeTexgroup(bool dentro = true);

  Rimuove il testo del gruppo &latex; circostante Se `dentro` è `false`, sarà rimosso il testo del gruppo incluse le graffe circostanti `{...}`, altrimenti le graffe non saranno rimosse. Se non viene dato un valore per il parametro, `dentro` è impostato a `false`.

    bool document.hasMathgroup();

  Restituisce `true` se c'è un gruppo matematico &latex; circostante alla posizione attuale del cursore, altrimenti `false`.

    String document.mathgroup();

  Restituisce il testo del gruppo matematico &latex; circostante. Se alla posizione attuale del cursore non viene rilevato un gruppo matematico &latex; circostante, viene restituita una stringa vuota.

    Range document.mathgroupRange();

  Restituisce l'intervallo del gruppo matematico &latex; circostante. Se nessun gruppo matematico circostante viene rilevato, viene restituito `Range.invalid()`, che può essere controllato con `Range.isValid()`.

    void document.removeMathgroup();

  Rimuove il testo del gruppo matematico &latex; circostante.

    String document.paragraph();

  Restituisce il testo del paragrafo &latex; attuale.

    Range document.paragraphRange();

  Restituisce l'intervallo del paragrafo &latex; circostante.

    void document.removeParagraph();

  Rimuove il testo del paragrafo &latex; attuale.

    bool document.matchesAt(int riga, int colonna, String testo);
    bool document.matchesAt(Cursor cursore, String testo);

  Restituisce `true` se il `testo` corrisponde a quello presente alla posizione del cursore, altrimenti `false`.

    bool document.startsWith(int riga, String schema, bool salta_spazi = true);

  Restituisce `true` se la riga comincia con lo `schema`, altrimenti `false`. L'argomento `salta_spazi` determina se gli spazi iniziali vanno ignorati.

    bool document.endsWith(int riga, String schema, bool salta_spazi = true);

  Restituisce `true` se la riga finisce con lo `schema`, altrimenti `false`. L'argomento `salta_spazi` determina se gli spazi finali vanno ignorati.

    int document.firstColumn(int riga);

  Restituisce la prima colonna non di spazi nella `riga`. Se nella riga ci sono solo spazi, viene restituito `-1`.

    int document.lastColumn(int riga);

  Restituisce l'ultima colonna non di spazi nella `riga`. Se nella riga ci sono solo spazi, viene restituito `-1`.

    int document.prevNonSpaceColumn(int riga, int colonna);
    int document.prevNonSpaceColumn(Cursor cursore);

  Restituisce la colonna con caratteri non di spaziatura che comincia alla posizione del cursore data e cercando indietro.

    int document.nextNonSpaceColumn(int riga, int colonna);
    int document.nextNonSpaceColumn(Cursor cursore);

  Restituisce la colonna con caratteri non di spaziatura che comincia alla posizione del cursore data e cercando in avanti.

    int document.prevNonEmptyLine(int riga);

  Restituisce la prossima riga non vuota con caratteri non di spaziatura cercando indietro.

    int document.nextNonEmptyLine(int riga);

  Restituisce la prossima riga non vuota con caratteri non di spaziatura cercando in avanti.

    void document.gotoBeginEnv();

  Vai all'inizio di un ambiente &latex; circostante.

    void document.gotoEndEnv();

  Vai alla fine di un ambiente &latex; circostante.

    void document.gotoBeginTexgroup();

  Vai all'inizio di un gruppo &latex; circostante.

    void document.gotoEndTexgroup();

  Vai alla fine di un gruppo &latex; circostante.

    void document.gotoNextParagraph();

  Vai al paragrafo &latex; successivo.

    void document.gotoPrevParagraph();

  Vai al paragrafo &latex; precedente.

    void document.gotoNextSectioning();

  Vai alla prossima sezione &latex;.

    void document.gotoPrevSectioning();

  Vai alla sezione &latex; precedente.

    void document.gotoLine(int riga);

  Vai alla `riga` indicata.

    void document.insertChapter();

  Inserisci un comando `\chapter` (vedi anche `document.insertSection()`).

    void document.insertSection();

  Inserisci un comando `\section`. Come quando si seleziona la voce del menu LaTeX Struttura section, apparirà una finestra in cui si potrà scegliere il titolo e un'etichetta facoltativa per questo comando di struttura. Finestra: inserisci comando di capitolo Finestra: inserisci comando di capitolo

    void document.insertSubsection();

  Inserisci un comando `\subsection` (vedi anche `document.insertSection()`).

    void document.insertSubsubsection();

  Inserisci un comando `\subsubsection` (vedi anche `document.insertSection()`).

    void document.insertParagraph();

  Inserisci un comando `\paragraph` (vedi anche `document.insertSection()`).

    void document.insertSubparagraph();

  Inserisci un comando `\subparagraph` (vedi anche `document.insertSection()`).

    void document.insertLabel();

  Inserisci un comando `\label`.

    void document.insertReference();

  Inserisce un comando `\ref`. Come quando si seleziona la voce del menu LaTeX Riferimenti ref, apparirà una finestra in cui si potrà scegliere tra le etichette già definite, elencate in una casella combinata. Finestra: inserisci comando di riferimento Finestra: inserisci comando di riferimento

    void document.insertPageref();

  Inserisci un comando `\pageref` (vedi anche `document.insertReference()`).

    void document.insertCitation();

  Inserisci un comando `\cite`.

    void document.insertIndex();

  Inserisci un comando `\index`.

    void document.insertFootnote();

  Inserisci un comando `\footnote`.

    void document.comment();

  Inserisce indicatori di commento per rendere la selezione o la riga attuale un commento.

    void document.uncomment();

  Rimuove gli indicatori di commento dalla selezione o dalla riga attuale.

    void document.uppercase();

  Mette il testo selezionato o la lettera dopo il cursore in maiuscolo.

    void document.lowercase();

  Mette il testo selezionato o la lettera dopo il cursore in minuscolo.

    void document.capitalize();

  Mette le iniziali del testo selezionato o della parola attuale in maiuscolo.

    void document.joinLines();

  Unisce le righe della selezione attuale. Due righe di testo consecutive sono sempre separate da un solo spazio.

    void document.insertIntelligentNewline();

  Inserisci un ritorno a capo intelligente (vedi ).

    void document.insertIntelligentTabulator();

  Inserisci un tabulatore intelligente (vedi ).

    void document.editBegin();

  Avvia un gruppo di modifica per un raggruppamento di azioni annullabili. Assicurati di chiamare sempre `editEnd()` con la stessa frequenza di `editBegin()`. Chiamare `editBegin()` usa internamente un contatore di riferimenti, quindi questa chiamata può essere annidata.

    void document.editEnd();

  Chiude un gruppo di modifica. L'ultima chiamata di `editEnd()` (cioè quella corrispondente alla prima chiamata a `editBegin()`) conclude il passo di modifica.

    StringList document.labelList();

  Restituisci tutte le etichette definite come una `Stringlist`, che può essere usata in &javascript; come un array di stringhe.

    StringList document.bibitemList();

  Restituisci tutti gli elementi bibliografici definiti come una `Stringlist`, che può essere usata in &javascript; come un array di stringhe.

    void document.refreshStructure();

  Aggiorna la vista della struttura (vedi ).

### L'API di &kile;

L'oggetto globale (variabile) `kile` è usato per gestire le interazioni di massimo livello con il mondo esterno, i messaggi in ingresso e le interfacce di dialogo. Queste chiamate API si dividono in sotto-oggetti per strutturare questa parte dell'API di scripting. Concettualmente, `kile` è un po' come `window` nell'API di un browser.

- `kile.alert`: riquadri con messaggi

- `kile.input`: ottieni informazioni dall'utente

- `kile.wizard`: richiama uno degli assistenti di &kile;

- `kile.script`: ottieni informazioni su uno script in esecuzione

- `kile.file`: operazioni sui file come lettura e scrittura.

#### Avviso

    void kile.alert.information(String testo, String didascalia);

  Mostra una finestra di Informazione. `testo` è la stringa del messaggio e `didascalia` è il titolo del riquadro. Il titolo predefinito è il nome dello script.

    void kile.alert.sorry(String testo, String didascalia);

  Mostra una finestra di Scusa. `testo` è la stringa del messaggio e `didascalia` è il titolo del riquadro. Il titolo predefinito è il nome dello script.

    void kile.alert.error(String testo, String didascalia);

  Mostra una finestra di Errore. `testo` è la stringa del messaggio e `didascalia` è il titolo del riquadro. Il titolo predefinito è il nome dello script.

    String kile.alert.question(String testo, String didascalia);

  Mostra una semplice finestra di Domanda. `testo` è la stringa del messaggio e `didascalia` è il titolo del riquadro. Il titolo predefinito è il nome dello script. La stringa restituita è `yes` o `no`.

    String kile.alert.warning(String testo, String didascalia);

  Mostra una semplice finestra di Avviso. `testo` è la stringa del messaggio e `didascalia` è il titolo del riquadro. Il titolo predefinito è il nome dello script. La stringa restituita è `continue` o `cancel`.

#### Immissione

    String kile.input.getListboxItem(String didascalia, String etichetta, StringList elenco);

  Funzione per permettere all'utente di selezionare un elemento da un elenco mostrato come una casella a cascata. `didascalia` è il testo visualizzato nella barra del titolo, `etichetta` è il testo usato come etichetta per l'elenco ed `elenco` è l'elenco di stringhe inserito nell'elenco.

    String kile.input.getComboboxItem(String didascalia, String etichetta, StringList elenco);

  Funzione per permettere all'utente di selezionare un elemento da un elenco mostrato come una casella combinata `didascalia` è il testo visualizzato nella barra del titolo, `etichetta` è il testo usato come etichetta per l'elenco ed `elenco` è l'elenco di stringhe inserito nell'elenco.

    String kile.input.getText(String didascalia, String etichetta);

  Funzione per ottenere una stringa dall'utente. `didascalia` è il testo visualizzato nella barra del titolo e `etichetta` è il testo usato come etichetta per la casella di immissione.

    String kile.input.getLatexCommand(String didascalia, String etichetta);

  Funzione per ottenere un comando &latex; dall'utente. Ciò vuol dire che sono ammesse solo maiuscole e minuscole. `didascalia` è il testo visualizzato nella barra del titolo e `etichetta` è il testo usato come etichetta per la casella di immissione.

    int kile.input.getInteger(String didascalia, String etichetta, int min = INT_MIN, int max = INT_MAX);

  Funzione per ottenere un numero intero dall'utente. `didascalia` è il testo visualizzato nella barra del titolo. `etichetta` è il testo usato come etichetta per la casella numerica. `min` e `max` sono i valori minimo e massimo ammissibili che l'utente può selezionare; i valori predefiniti sono `INT_MIN` e `INT_MAX`.

    int kile.input.getPosInteger(String didascalia, String etichetta, int min = 1, int max = INT_MAX);

  Funzione per ottenere un numero intero positivo dall'utente. `didascalia` è il testo visualizzato nella barra del titolo. `etichetta` è il testo usato come etichetta per la casella numerica. `min` e `max` sono i valori minimo e massimo ammissibili che l'utente può selezionare; i valori predefiniti sono `1` e `INT_MAX`.

#### Assistente

    void kile.wizard.tabular();

  Richiama l'assistente per tabelle, che aiuta a scrivere un ambiente tabular (vedi ).

    void kile.wizard.array();

  Richiama l'assistente per matrici, che aiuta a scrivere un ambiente array (vedi ).

    void kile.wizard.tabbing();

  Richiama l'assistente per tabulazioni, che aiuta a scrivere un ambiente tabbing (vedi ).

    void kile.wizard.floatEnvironment();

  Richiama l'assistente per flottanti, che aiuta a inserire elementi flottanti (vedi ).

    void kile.wizard.mathEnvironment();

  Richiama l'assistente matematico, che aiuta a inserire elementi matematic (vedi ).

    void kile.wizard.postscript();

  Richiama l'assistente per gli strumenti PostScript, che aiuta a manipolare o ridisporre i documenti PostScript (vedi ).

#### Script

    String kile.script.name();

  Restituisce il nome base di uno script in esecuzione (senza percorso ed estensione).

    String kile.script.caption();

  Restituisce una stringa utilizzabile come didascalia nei riquadri d'avviso. Ha l'aspetto di `Script: nome_script.js`.

#### File

    Object kile.file.read(String nome_file);

  Legge i contenuti di un file di testo. Si usa come:

  Esempio: `var ris = kile.file.read("percorso/al/file.txt");`

  Il valore restituito `ris` è un oggetto (o meglio, una mappa) con tre proprietà:

  - status:: presenta il codice di stato dell'operazione, che può essere 0 (nessun errore), 1 (accesso non riuscito), o 2 (accesso negato). Se nessun errore si è verificato, il valore di `ris.status` o `ris["status"]` sarà 0.

  - result:: contiene il testo del file indicato.

  - message:: contiene un messaggio d'errore, se si è verificato un errore.

    Object kile.file.read();

  Lo stesso che `read(nome_file)`, ma non viene dato un nome di file. Apparirà una finestra per selezionare il file da leggere.

    Object kile.file.write(String nome_file, String testo);

  Scrivi il testo dato in un file. Si usa come:

  Esempio: `var ris = kile.file.write("percorso/al/file.txt", "Del testo...");`

  Il valore restituito `ris` è un oggetto (o meglio, una mappa) con due proprietà: `status` e `message` (vedi `read()` per maggiori informazioni).

    Object kile.file.write(String testo);

  Lo stesso che `write(nome_file, testo)`, ma non viene dato un nome di file. Apparirà una finestra per scegliere il nome del file.

    String kile.file.getOpenFileName(String cartella_iniziale, String filtro);

  Crea una finestra modale di selezione dei file e restituisce il nome del file selezionato, o una stringa vuota se non ne è stato selezionato nessuno. Nota che con questo metodo l'utente deve selezionare il nome di un file esistente.

  Parametri:

  - cartella_iniziale:: cartella in cui è inizialmente aperta la finestra di selezione dei file.

  - filtro: un'espressione con caratteri jolly o un tipo MIME che specifica quali file visualizzare. Riferisciti alla documentazione di `KFileDialog` per maggiori informazioni su questo parametro.

  Entrambi i parametri sono facoltativi. Se ometti filtro, saranno visualizzati tutti i file. Se è omessa cartella_iniziale, la finestra userà la cartella del documento attuale come punto di partenza.

    String kile.file.getSaveFileName(String cartella_iniziale, String filtro);

  Crea una finestra modale di selezione dei file e restituisce il nome del file selezionato, o una stringa vuota se non ne è stato selezionato nessuno. Nota che con questo metodo l'utente non deve necessariamente selezionare il nome di un file esistente. Vedi `getOpenFileName()` per una spiegazione dei parametri.

## Esempi

Alcuni esempi potrebbero aiutare a capire come usare l'API di scripting. Questi esempi e altri ancora sono presenti nella cartella di scripting di &kile;: `KILE_APP_DIR/scripts/`. Ogni script contiene una breve descrizione.

### Esempio 1: sostituire il nome dell'ambiente

Sostituisci un ambiente &latex; circostante con un altro, senza cambiare la posizione del cursore. Per esempio, `\begin{abc}...\end{abc}` verrà cambiato in `\begin{xyz}...\end{xyz}`.

    var range = document.environmentRange(false);
    if ( range.isValid() ) {
            var envname = kile.input.getLatexCommand("Inserisci ambiente","Nuovo nome dell'ambiente:");
            if ( envname != '' ) {
                    replaceEnvCommand(envname,range);
            }
    }
    else {
            kile.alert.sorry("Nessun ambiente LaTeX circostante rilevato.");
    }

    function replaceEnvCommand(newEnv,r)
    {
            var c = view.cursorPosition();

            var envname = document.environmentName();

            if ( envname != "" ) {
                    var beginRange = new Range(r.start,new Cursor(r.start.line,r.start.column+8+envname.length));
                    var endRange = new Range(new Cursor(r.end.line,r.end.column-6-envname.length),r.end);

                    document.editBegin();
                    document.replaceText(endRange,"\\end{"+newEnv+"}");
                    document.replaceText(beginRange,"\\begin{"+newEnv+"}");
                    document.editEnd();
            }
    }

### Esempio 2: sostituire un comando &latex; di carattere

Sostituisci un comando &latex; per il carattere con un altro, quando il cursore è posizionato nel gruppo TeX. La posizione relativa del cursore non verrà modificata. Per esempio `\textbf{abc}` verrà cambiato in `\textit{abc}`.

    var fontCommands = new Array("\\textbf","\\textit","\\textsl","\\texttt",
                                 "\\textsc","\\textrm","\\textsf","\\emph");

    var range = document.texgroupRange(false);
    if ( range.isValid() ) {
            replaceFontCommand(range);
    }
    else {
            kile.alert.sorry("Nessun gruppo TeX circostante rilevato.");
    }

    function replaceFontCommand(r)
    {
            var c = view.cursorPosition();

            document.editBegin();
            view.setCursorPosition(r.start);
            var cmd = document.latexCommand();
            var index = fontCommands.indexOf(cmd);
            if ( index
    >= 0 ) {
                    var cmdRange = document.latexCommandRange();
                    if ( cmdRange.isValid() ) {
                            var newcommand = kile.input.getListboxItem("Choose",
                                                        "Scegli comando di carattere:",buildCmdList(cmd));
                            if ( newcommand != "" ) {
                                    document.replaceText(cmdRange,newcommand);
                                    c.column = c.column - (cmd.length - newcommand.length);
                            }
                    }
    /                view.setCursorPosition(c);
            }
            else {
                    kile.alert.sorry("Nessun comando di carattere circostante rilevato.");
            }
            document.editEnd();
    }

    function buildCmdList(current)
    {
            var result = new Array();
            for ( i=0; i<fontCommands.length; ++i ) {
                    if ( fontCommands[i] != current ) {
                            result.push(fontCommands[i]);
                    }
            }
            return result;
    }

### Esempio 3: circonda il testo selezionato

Circonda il testo selezionato con un comando TeX, senza cambiare la posizione relativa del cursore. Per esempio, `abc` verrà modificato in `\textcommand{abc}`.

    var range = view.selectionRange();

    if ( range.isValid() ) {
            var cmd = kile.input.getLatexCommand("Scegli","Scegli il comando LaTeX circostante:");
            if ( cmd != "" ) {
                    surroundTexCommand("\\"+cmd,range);
            }
    }
    else {
            kile.alert.sorry("Nessuna selezione rilevata.");
    }

    function surroundTexCommand(cmd,r)
    {
            var c = view.cursorPosition();

            document.editBegin();
            view.clearSelection();
            document.insertText(r.end,"}");
            document.insertText(r.start,cmd+"{");

            c.column = c.column + cmd.length + 2;
            view.setCursorPosition(c);
            document.editEnd();
    }